GumstixIII Windows CE 6.0 BSP documentation

For application developers you only need to download and install the SDK. Everything you need (i.e. the prebuilt image, boot loader and many (C#) example projects) are included within.
Only if you plan on regenerating the image with Platform Builder do you need the actual PLATFORM BSP and OSDESIGN files.

Note: The example NK.BIN included with the SDK is for educational, demonstration and development purposes only!
It is not legal to base a commercial product off of this NK.bin image.
See the MIcrosoft Windows CE and Platform Builder license for terms and conditions.
The author assumes no responsibility for use (or misuse as the case may be).
For commercial use you must regenerate the image yourself and use your runtime licenses.

Boot Loader:

BootLoadertxt.bmp
EBOOT is the Windows CE boot loader. The EBOOT loader must be flashed over U-BOOT as the first step to bringing up Windows CE on the Gumstix platform.
This action will remove U-BOOT so if you wish to go back it is a good idea to save off the U-BOOT bits. This can be done using the "saves" U-BOOT command.
This command can be used to save off a range of memory via the serial port in S-Record format. EBOOT understands S-Records also so this is the hook to reloading
U-BOOT should you desire. U-BOOT is stored in the first two blocks of flash memory so be sure to save at least this much. U-BOOT uses the first block as the U-BOOT
program and the second block as a parameter block, EBOOT uses the first two block as program and the third block as parameters.

There are other tecniques to load/reload U-BOOT or EBOOT including JTAG and returning the motherboard to Gumstix for a "ReFlash".
Botom line: As long as you are carefull and follow directions you will not have any problems and will always be able to go back to the original factory configuration.

Note: You probably also want to make note of the MAC address assigned in U-BOOT before flashing as this can also be used in EBOOT.

Follow the step-by-step procedures outlined below for loading/reloading EBOOT/U-BOOT.


EBOOT boot loader are unique for the XM4 and XL6 Gumstix Verdex platform because of the different RAM and Flash configurations.
Be sure to use the correct boot loader version for the target you are using.
There are no other restrictions on the CE image, the same image can be used on ether platform as long as there is enought available memory to support the image size.
Because of space reserved for persistent registry and the odd parameter block sizes of the P30T Flash parts, the largest flashable image for the XM4 is ~14MB
and for the XL6 ~30MB.

The boot loader supports launching a CE image from on-board Flash, Compact Flash or MMC/SD card.
Images stored and launched from a Compact Flash or MMC/SD card are not restricted to the size of the motherboards flash memory but do require slightly longer time to boot.
The images can be downloaded to the motherboards RAM or Flash via an Ethernet, USB or serial port connection.

Platform Builder is the Windows CE image development enviroment and the prefered image loading mechanism. That being said, I have included tools that allow loading both
the boot loader and prebuilt images without the need for Platform Builder. I understand not everybody wants to be an OS construction expert, some are much more interested
in developing applications. I have tried to support both worlds with these tools.

CAUTION: Read and understand procedure completely before attempting the following procedure. Failure to follow procedure may result in an unbootable unit!


CAUTION: There are very likely new BSP to boot loader dependencies introduced with each new BSP release.
It is highly recommend you upgrade the boot loader to the matching BSP release before you load the OS.

Step by step procedure for loading eboot boot loader over u-boot.

1. Connect Hyperterminal to the FF uart port.

2. Set to 115200 N,8,1.

3. Bring up u-boot.

4. Issue the following u-boot command "loadb"

5. Use Hyperterminal's Transfer->send file and select the Kermit protocol.

6. Browse and select the eboot.nb0 file.

7. This will do a binary image load of the eboot boot loader into Gumstix RAM at A2000000.

8. Issue the following u-boot commands to flash the image into Gumstix at 0:

a. protect off all

b. era 1:0-2

c. cp.b a2000000 0 40000

d. Reset

Step by step procedure for re-loading u-boot boot loader over eboot

1. Connect HyperTerminal to the FF uart port.

2. Set to 115200 N,8,1.

3. Bring up eboot.

4. 9 :edit memory

5. f a2000000 ffffffff 98304 :fill 98304 DWORDS (3 blocks) at address a2000000 with ffffffff (flash erased value)

6. x :quit

7. 6 :select the FFUART (SRecord) as the primary download device

8. d :download image now

9. >A2000000 :offset of A2000000 when added to the base address of 00000000 (examine the u-boot.srec file to verify base address, you may need different numbers here.
Addresses are in the 5th - 12th character positions of the S3 records) wraps to become a destination load address of A2000000 which is the RAM buffer

10. Hit return and you should see:

Download SRecord file with offset A2000000

Waiting for SRecord file...

Error com timeout.

Waiting for SRecord file...

Select "Transfer" and "Send Text File..." from the Hyperterminal menu bar.

Select the . file type, browse and select the u-boot.srec file.

File should load printing "." across the screen.

When finished:

11. u :Unlock boot blocks (3.1 and up)

12. 9 :edit memory

13. e 0 3 :erase first 3 flash blocks

14. p 0 a2000000 768 :program 768 sectors (512 bytes/sector which is 3 blocks or 393216 bytes) starting at sector 0 (reset location) using buffer at a2000000

15. x :quit

16. r :reset


Step by step procedure for upgrading eboot:

Option A: Via serial port

Be sure the boot loader was built with "Write run-time image to Flash Memory" build option checked (i.e. IMAGEFLASH=1 set) this generates a S-record file with a base address BCA00000.

Note the hardware configuration DWORD and other configuration parameters as they will be erased by the upgrade process.

1. Connect HyperTerminal to the FF uart port (Stuart little or other).

2. Set to 115200 N,8,1.

3. Bring up eboot.

4. 9 :edit memory

5. f a2000000 ffffffff 98304 :fill 98304 DWORDS (3 blocks) at address a2000000 with ffffffff (flash erased value)

6. x :quit

7. 6 :select the FFUART (SRecord) as the primary download device

8. d :download image now

9. >e5600000 :offset of e5600000 when added to the base address of BCA00000 wraps to become a destination load address of A2000000 which is the RAM buffer.

10. Hit return and you should see:

Download SRecord file with offset e5600000

Waiting for SRecord file...

Error com timeout.

Waiting for SRecord file...

Select "Transfer" and "Send Text File..." from the HyperTerminal menu bar.

Select the . file type, browse and select the eboot.sre (or we-bootXX.sre) file.

File should load printing "." across the screen.

When finished:

11. u :Unlock boot blocks (3.1 and up)

12. 9 :edit memory

13. e 0 3 :erase first 3 flash blocks

14. p 0 a2000000 768 :program 768 sectors (512 bytes/sector which is 3 blocks or 393216 bytes) starting at sector 0 (reset location) using buffer at a2000000

15. x :quit

16. s :store and relock boot blocks

17. r :reset

18. Press space bar on restart to break into the boot loader.

Note:If you get a lot of communication errors you may be over driving the Gumstix UART, this usually happens when using very fast host PC's.
Inserting a 1ms line delay or charater tx delay (See Hyperterminal's parameter settings) will usually fix the problem.


Option B: Via Ethernet connection using Visual Studio and Platform Builder.

1. Copy the prebuilt eboot.bin file into the FLATRELEASE directory of your Platform Builder's OSDesign folder.

2. Under the Project settings properties Configuration Properties->General->Target File Name for Debugger select "eboot.bin".

3. If using one of the native Ethernet Gumstix peripherals (netCF, netMicro) make sure the Hardware configuration, IP configuration and MAC address are set correctly.

4. Set the Primary download device to the proper Ethernet device. If using a NE2000 compatible Ethernet CF card, set Primary download device to CF.

6 U : unlock boot blocks

7. D : download image now

8. Within Platform Builder select the Target->Connectivity options and set as per Platform Builders instructions.

9. Select Target->Attach device.

10. Boot loader will download, re-flash and reset automatically.

11. Press space bar on restart to break into the boot loader.

12. S : store and relock boot blocks


Option C: Via Ethernet connection using EShell utility.

1. Follow steps 1-7 above.

2. Launch eshell.exe in the tools directory.

3. On the Options menu select Download Only on Command.

4. On the Files->Select image file menu select the xxx.bin file for download.

5. On the Tools->Manage device list select the requesting device.

6. On the Files menu select download image.

7. Boot loader will download, re-flash and reset automatically.

8. Press space bar on restart to break into the boot loader.

9. S : store and relock boot blocks

Platform configuration

After booting eboot for the first time, be sure to initially set the hardware configuration word, store it ("S" command) and reset ("R" command).

Note:It is very important for correct operation that this word be set correctly and accurately reflects the current hardware/software platform configuration!

The following configuration bits are defined:

Feature Bit Comment
GUMCFG_XM4 0x00000001
GUMCFG_XL6 0x00000002
GUMCFG_BLUETOOTH 0x00000008 PBA31308 Bluetooth module support
GUMCFG_NETCF 0x00000010
GUMCFG_NETMICROSD 0x00000040
GUMCFG_WIFI 0x00000080 DRCM-81 WiFi module support
GUMCFG_AUDIOSTIX 0x00000100
GUMCFG_AUDIOSTIX_USBH 0x00000200 1=USB host, 0=USB client
GUMCFG_AUDIOSTIX_TOUCH 0x00000400 UCB1400 touch support
GUMCFG_CONSOLE 0x00001000
GUMCFG_CONSOLE_USBH 0x00002000 1=USB host, 0=USB client
GUMCFG_CONSOLE_LCD 0x00004000 Samsung LCD w/touch support
GUMCFG_CONSOLE_16BIT 0x00008000 1=16Bit, 0=18Bit color module
GUMCFG_BREAKOUT 0x00010000
GUMCFG_BREAKOUT_USBH 0x00020000 USB host, 0=USB client
GUMCFG_LED 0x00100000
GUMCFG_RAMFILE 0x20000000 ram file (XL6)
GUMCFG_FLASHFILE 0x40000000 flash file (XL6)
GUMCFG_PERREG 0x80000000 persistent registry


Unused bits are reserved and should be set to zero.

If you were using a Verdex XM4-BT motherboard, for example, with a netCF-vx expanision board and an AudiostixII board with the USB port configured as a host the hardware word would be:
  • Hardware configuration: 0x00000319

A full up configuration consisting of an XL6, NetMicroSD-WiFi, ConsoleLCD-vx, with a Samsung display and USB port configured as a host and persistent registry support would be:
  • Hardware configuration: 0x800070C2

There is also a a "SetGumstixHardwareWord" utility in the tools directory. This utility helps with calculating the Hardware Configuration setting.

Hardware configuration

The prefered hardware stack is the following:
  • XL6
  • NetMicroSD-WiFi
  • ConsoleLCD-vx
  • Samsung display
With this hardware configuration you can have a "PDA" like experiance complete with touch screen and power managment support.
The default prebuilt image and the associated OSDesign "GUMSTIXIII_BIN_1" fully supports this configuration.
Other hardware permutations, including "headless" operation, are possible with the same prebuilt nk.bin image by just changing
the hardware configuration word in the boot loader.

Of course, greater flexibility is offered if you chose to construct your own image. Building your own OS allows you the option to "tune" the image for
best performance, operation and size. You can add or delete software components as needed for your application. You can also remove extra
drivers that may not be needed in your final hardware configuration thus making the image smaller and faster.

Using the prebuilt sample image bypasses the need to know or install Platform Builder (see restrictions above).

Sample application programs included with the SDK will run on this hardware configuration with the prebuilt image.
The samples are in source code form and will require Visual Studio 2005 to recompile and run. The free "Visual Studio Express"
version does not support device development so I believe you need, at minimum, Visual Studio 2005 Standard.

Touch screen modification:
Some ConsoleLCD-vx boards were shipped with a missing a connection between the interrupt line of the touch screen controller
and the low speed bus connector. Here is the modification that may be needed:
ConsoleLCD touch mod.gif
Later revisions of the board may have this problem corrected.

Notification LED modification:
There is one free GPIO that can be used for the notification LED.
GPIO101 is pinned out on the Breakout-vx and Console-vx and can be used for this purpose.
GPIO101LED.gif
The Breakout-vx also has 4 spare LEDs that can be utilized.

Power button modification:
A normally open (NO) push button can also be added to support external suspend/resume operation.
GPIO9 (CLK32) is available on the low speed bus and is pined out on the Breakout-vx and the Console-vx.
GPIO9PB.gif
Most local 3.3 volt regulators are shut down when the processor enters sleep mode so a 3.3 volt supply may not
be available for pull-up. You can instead pull-up to VBAT with a large enought resistor.
You should protect the GPIO input from overvoltage with a zener. You may be
able to get away without using the zener if you keep the resistor high enough and let the PXA270's internal
protection diodes do the clamping. This is not good practice and is not recommended.

Reset button:
A normally open (NO) push button from the nReset signal to ground is all that is needed for external reset.

Auxiliary USB host:
The 24 pin connector available on Verdex motherboards brings out the signals need for the
port 1 USB host. Also available are the I2C, BTUART and GPIO0 signals. GPIO0 is a better signal
to use for the power button. The hope would be for a small breakout board to support these additional features.

These pictures show an XL6 with a netMicroWiFi-sd and a ConsoleLCD-vx setup.
Samsung LCD display along with the notification LED, power button (RED) and reset button (Black) mounted on
a Plexiglass form.
Gumstix platform2.bmp Gumstix platform1.bmp

Persistent registry

Persistent registry is enabled by setting the upper bit of the plarform configuration word (0x8XXXXXXX).
After setting and storing this bit, set the "Clean registry boot" flag in the boot loader to "NEXT LAUNCH" and launch the image.
This will initially "prime" the registry with the default registry values from the generated image.
You should see the following messages on the debug terminal upon startup:
...
INFO: Using persistent registry
INFO: Booting clean registry
...

Next, you should "flush" the registry to flash. This will persistently store the registry settings to the reserved sectors in flash memory.
This is done by executing the "RegistryFlush.exe" utility. This utility is prepopulated in the Most Recently Used (MRU) cache under
the "Start->Run.." menu from the CE Windows desktop. You should see these messages on the debug terminal:
...
INFO: OALPerRegWrite: Registry write start
INFO: OALPerRegWrite: Registry store erase start
INFO: OALPerRegWrite: Registry store erase done
INFO: OALPerRegWrite: Registry write done
...

Note: You can also programmatically flush the registry. See the Windows CE API reference for more information.

After this operation, subsequent reboot will load the registry from flash instead of from the image.
Fresh reboots should result in the following messages:
...
INFO: Using persistent registry
INFO: OALPerRegRead: Registry read start
INFO: OALPerRegRead: Registry read start
INFO: OALPerRegRead: Registry read done (0)
...

Any time after altering the registry (you can use ActiveSync and the Remote Registry Editor) you should "flush" the settings to save
them persistently.

As an example, say you wish to flip your display 180 degrees. Here you would:
  • Enable and setup persistent registry as outlined above.
  • Connect ActiveSync.
  • Connect Remote Registry Editor.
  • Alter the registry key: [HKEY_LOCAL_MACHINE\System\GDI\Rotation]
  • Change the "Angle" value from "0" to "180".
  • Flush the registry using "RegistryFlush" utility.
  • Reboot.

Flash drive

The flash drive option (0x4XXXXXXX) and ram drive option (0x2XXXXXXX) applies only to XL6 motherboards
as this board has expanded flash (32mb) and ram (128mb) support.
The flash drive carves off 8mb from the local flash and makes it into a persistent flash drive.
The drive can be used to persistently store program files or other types of files. If a startup folder is
created any program placed in this folder will launch on powerup.

Caution: Upon initial startup the drive will be auto partitioned and formated. This could take several minutes.
The unit will appear to be sluggish while this operation completes. Be patient! Subsequent reboots will not have this delay!

Ram drive

The ram drive option creates a 16mb ram drive. The ram drive will have very fast access times but files stored within will
not be persistent over power cycles. Ram drives are great for temporary or cache files etc. The ram drive contents
should be preserved over suspend/resume cycles.

Tools

There are several utilities in the tools directory.

ESHELL

ESHELL is a utility that allows downloading .bin files to the device via an Ethernet connection.

This utility can be used to load nk.bin image files or eboot.bin boot loader files into on-board flash.
Use this utility as an alternative to loading with Platform Builder.
This utility works best over an Ethernet connection.

bin2srec

bintosrec can be used to convert a raw binary files (*.nb0) to a S-Record formatted file.

srec2bin

srec2bin converts a S-Record file to raw binary.

cerhost_AS

cerhost_AS is the CE remote display desktop client that runs over USB ActiveSync.

cerhost_IP

cerhost_IP is the CE remote display destop client that runs over Ethernet IP.

JFlashmm

JTAG programming utility.

JFlashmm is a modified JTAG utility first published by Intel.
This utility can be used with JTAG-vx board to program EBOOT or U-BOOT (or anything else for that matter) into onboard flash.
Can also be used to recover unbootable motherboards.
The program accepts raw binary files and you will also need a "Wiggler" like adaptor connected to your PCs parallel port.
A Wiggler is a parrallel port to JTAG adaptor available from Macraigor Systems http://www.macraigor.com/.
You can purchase one or you can make one yourself. There are schematics online and there are also a lot of knockoffs around.

The syntax for JFLASHMM use would be:
jflashmm dbgum270c5 eboot.nb0
See jflash documentation for more information.

Note:This utility is included with the source code package and is not available with the binary BSP release.

TouchCalibrate

TouchCalibrate is a standalone utility that can be used to force a calibration sequence on a touch screen display.

Place this utility in a \Startup folder on a storage card and if the AutoLaunch project was included in the OSDesign this utility will be run on device startup.
Touch screen calibration parameters are stored in the registry so this most likely will be used when the persestent registry option is enabled.
I do not have a large population of Samsung displays to draw from but it appears the default touch screen values prepopulated in the registry
are adequate for this display. Most cases recalibration may not be necessary.

SetGumstixHardwareWord

The SetGumstixHardwareWord utility helps calculate the correct hex number needed for entry into the Hardware Configuration setting in the boot loader.
It takes into account most all dependencies so it’s very hard to come up with an invalid setting.
SetHardware.jpg


Managed code development

Step by step procedure for setting up managed code development (C# or VB)

The following components are needed:
  • Visual Studio 2005 Standard edition (or higher)
  • ActiveSync 4.5 (or higher)
  • Gumstix platform with USB client support

Note: It is best to start with the default image supplied with the SDK. This image was built with the proper components included for managed code development.
These components include the Compact Framework, Smart Device Framework, Gumstix Managed API and ActiveSync support etc.

1. Install the latest Gumstix SDK on the host PC.
You can download from the releases tab.

2. Install ActiveSync 4.5 if not already installed on host PC.
You can download from Microsoft's Windows Mobile site

3. Install Gumstix EBOOT boot loader as outlined above.

4. Configure hardware configuration word in boot loader. Be sure USB client support is set.
You can use SetGumstixHardwareWord utility if you need help

5. Copy default image to SD or CF card (or flash if size permits).

6. Configure boot loader to launch image from storage card (or flash).

7. Reset and launch. Verify image launches correctly.

8. Run "GumstixManagedInfo.exe" from the start menu.
RunManagedInfo.bmp

9. Verify something like the following information screen appears.
ManagedInfo.bmp

10. Connect USB cable from PC to Gumstix USB client connector.

11. Verify ActiveSync autolaunches and connects.

12. Launch Visual Studio 2005.

13. Load Gumstix sample application solutions from "<sdk install location>\Samples\Managed apps".
Typically "C:\Program Files\Windows CE Tools\wce600\GumstixIII_BIN SDK VX_X"

14. Set target device and rebuild.

15. Deploy and run.


Other notes:

If you develop your own project you probably want to include references to the GumstixManagedAPI dlls as well as other dlls.
Important dlls can be found in the "<sdk install location>\Managed" directory.


Emulator development

Many times it is possible to do the majority of the development (native or managed) on the PC based emulator.
An emulator image can be constructed that parallels the same components used on the actual device.
The emulator SDK that can be downloaded from this site integerates with Visual Studio and operates much like
the Windows Mobile emulators.
It is possible to emulate the serial ports on the Gumstix through the host PC's serial ports. Its also possible to emulate
a GPS receiver like on the GPSStix, an Ethernet card and even a phone module.
You can establish a local ActiveSync connection, deploy, debug single step just like you were connected to the real device.
The emulator is great for debugging form based Compact Framework applications.
Most times you can just drop the debugged emulator executable onto the device and it will run unaltered.
Managed code is great!














Last edited Oct 3, 2008 at 4:16 PM by dvescovi, version 79

Comments

No comments yet.