BLCOMMON Code Library

Article
06/30/2006

The BLCOMMON library, located in %_WINCEROOT%\Public\Common\Oak\Drivers\Ethdbg\Blcommon, implements the basic framework of a boot loader. It handles relocating the boot loader to RAM for faster execution, decoding the .bin file contents, verifying checksums, and keeping track of load progress. The library calls well-defined OEM functions throughout the process to handle platform or solution-specific customizations.

The BLCOMMON library entry point is the BootloaderMain function, which is called by the boot loader startup code as part of the platform power-on/reset (POR) process. For more information about BootloaderMain and how it is used when developing a boot loader, see Ethernet Boot Loader Code Implementation.

The following list details the OEM functions called by the BLCOMMON library. The definitions for these functions live in the OEM code and are typically customized to the platform or solution.

Control Flow Functions

The control flow functions provide a way to plug into the loader at various points in the process. Each function is called in the context of a particular part of the setup or download process and enables the OEM to define the operation.

The following table shows the control flow functions.

Function	Description
OEMDebugInit	The first function called when the boot loader is started. Typically, debug output hardware (serial UARTs) are initialized during this call. The OEM often chooses to call the OEMInitDebugSerial function to initialize a serial UART for debug messages.
OEMPlatformInit	An OEM platform initialization function. You should perform platform-specific initialization, such as clock, driver, and transport, in this function. OEMPlatformInit can be customized to prompt for user feedback, such as network options.
OEMPreDownload	Call this function before downloading an OS image. It can be customized to prompt for user feedback. The download begins at this time.
OEMLaunch	The final function called to start the OS, and it is never returned.

Debug Functions

The debug functions provide a way for the BLCOMMON library to send error and status information to the user. It also provides a way to capture user input.

The following table shows the debug-related function.

Function	Description
OEMWriteDebugByte	Outputs a byte to the debug port, which is usually the serial port.
OEMInitDebugSerial	Initializes the debug serial port (UART).
OEMWriteDebugString	Writes a text string to the debug port, which is usually the serial port.
OEMReadDebugByte	Reads a byte from the debug port, which is usually the serial port.

Download Functions

The following table shows the download-related functions.

Function	Description
OEMReadData	The BLCOMMON framework calls this function to read data from the transport during the download process. A sample for Ethernet transport is provided in Public\Common\Oak\Ethdbg\Eboot\Ebsimp.c.
OEMShowProgress	The BLCOMMON framework calls this function as the download is progressing. An OEM can use this function to show information on an LED; for example, to let users know that the download is in progress.
OEMMapMemAddr	If the platform supports downloading a flash-based OS image, this function needs to be implemented. It translates a flash address into a temporary RAM address (used for file caching) until the download operation completes. This allows the download to proceed while a slower flashing operation takes place.

Flash Functions

The following table shows the FLASH-related functions.

Function	Description
OEMIsFlashAddr	Returns TRUE if an address is a FLASH address. Otherwise, the function returns FALSE.
OEMStartEraseFlash	The BLCOMMON framework calls this function as soon as it knows how much flash memory is needed. An OEM can start the flash erasing process.
OEMContinueEraseFlash	The BLCOMMON framework calls this function while downloading the OS image. It provides a context for the OEM to continue the flash erase operation.
OEMFinishEraseFlash	The BLCOMMON framework calls this function when it is about to write the OS image to flash. An OEM should make sure that all the flash memory needed is completely erased.
OEMWriteFlash	The BLCOMMON framework calls this function to write the OS image in FLASH_CACHE to flash memory.

The following table shows the variables, which are defined in Loader.h, that you must implement to support flash memory.

Variable	Description
FLASH_END	Specifies the ending address of flash memory.
FLASH_START	Specifies the starting address of flash memory.

Timer Function

The following table shows the timer-related function.

Function	Description
OEMEthGetSecs	Returns the current time in seconds. Only the relative value is important; that is, the difference between two calls to OEMEthGetSecs must reflect the number of seconds passed between the calls.

Share via