Windows CE Bootloader

Platform Builder: Understanding the Serial Debug Port

Bruce Eitman — Tue, 09 Sep 2008 01:32:51 GMT

Recently, there have been a few questions in the newsgroups about the serial debug port. The questions were along the lines of:

· Which COM port do I use for debug output?

· How do I change the COM port that is used for debug output?

These are actually quite common questions, so I thought I would address these. Every CPU and/or UART is different so I won’t give you a how to lesson, but I will provide you with enough information to look inside your BSP to figure it out for yourself.

First, let’s address the term COM port. COM is a special name used in device drivers to indicate that the driver is manageable through special COM APIs for controlling the communications through a UART. The term doesn’t apply to the debug serial port because:

1. No device driver. The serial debug port must be available before the device manager is even running. The serial debug port is available in the single threaded bootloader and is available early in the kernel initialization.

2. No run time API support for baud rate, parity, stop bit…

3. The debug serial port is not manageable by the COM APIs.

Getting the Serial Debug Port Started

On the most base level, the serial debug port can be initialized and written to in the assembly code that starts your bootloader. This is not the focus of this article, but I mention it because you may need to delve into the assembly code to change the serial debug port.

Talking C though, the serial debug port is initialized in OEMInitDebugSerial(). OEMInitDebugSerial() should initialize the UART. It should set the baud rate, parity and stop bits, may need to turn on power to external hardware and may need to start a clock to run the UART. OEMInitDebugSerial() may select different UARTs or even disable the serial output depending on platform specific features.

Outputting on the Serial Debug Port

OEMWriteDebugString() and OEMWriteDebugByte() provide the functionality of outputting on the serial debug port. OEMWriteDebugByte () usually implements putting a byte on the output FIFO of the UART and OEMWriteDebugString () usually processes a string and calls OEMWriteDebugByte () for each character to be output.

Reading Input on the Serial Debug Port

OEMReadDebugByte() implements reading a byte from the UART input FIFO. OEMReadDebugByte() is non-blocking, so if a character isn’t available or an error occurs it returns with a status code of either OEM_DEBUG_COM_ERROR, OEM_DEBUG_READ_NODATA. I have provided a code sample of reading from the serial debug port in Windows CE: Using the debug serial port for input.

Answering the Questions

How would you answer the questions about the serial debug port? Every BSP is different, so I the only concrete advice that I can give is to look for the serial debug port functions in your code. But in more generic terms, these functions are often implemented in both the bootloader and the OAL or Kernel, so you may need to look in both. The functions are sometimes implemented in a file named debug.c. If you look at CEPC, you will find that it actually has three implementations of these functions in eboot, sboot and the kernel uses an implementation in Platform\Common.

Platform Builder: Building a Bootloader

Bruce Eitman — Thu, 05 Jun 2008 20:39:11 GMT

Building a bootloader isn't much different than building a driver or an application. In fact, if you have already built your project more than likely your bootloader has already been built. But what if you want to make a change to the bootloader? Then knowing how to build it, and more important what happens when you build it, will help get from changing code to testing faster.

The first step is to find the source code. The source code may be in different places depending on the version of Windows CE that you are targeting and the BSP that you are using. The following are some locations to look:

Windows CE 4.2 and earlier:

%_WINCEROOT%\Platform\<BSP Name>\eboot

%_WINCEROOT%\Platform\<BSP Name>\sboot

Windows CE 5.0 and 6.0:

%_WINCEROOT%\Platform\<BSP Name>\src\Bootloader

If you have received your BSP from a third party, the location could be different.

The next step is to identify what your bootloader will be named when it is built. The bib file for the bootloader will tell you the name of the file. The bib file will be you the bootlaoder folder usually.

Let's look at the relevant lines in both C:\WINCE600\PLATFORM\CEPC\SRC\BOOTLOADER\EBOOT\boot.bib and

C:\WINCE600\PLATFORM\CEPC\SRC\BOOTLOADER\SBOOT\boot.bib and see how they are different:

eboot.bib

;   Name     Start     Size      Type

;   ------- -------- -------- ----

    EBOOT   00130000 00020000 RAMIMAGE

sboot.bib

;   Name     Start     Size      Type

;   ------- -------- -------- ----

    SBOOT    00130000 00010000 RAMIMAGE

The "Name" column for "Type" RAMIMAGE determines the file names that are created. In this case, eboot will create eboot.bin and eboot.nb0 while sboot will create sboot.bin and sboot.nb0. These files will be created and put in the appropriate sub folders in your platform's Target folder.

Now we know what to build to create the bootloader, what is created, and where the files end up after building. Let's build the bootloader.

Open a build window, which I discussed in << Platform Builder: Build Tools, Opening a Build Window >> and change directories to the bootloader folder. Then run build.exe << Platform Builder: Using Build.exe >>, and you are done.

So how did it do it? The following discussion will look at C:\WINCE600\PLATFORM\CEPC\SRC\BOOTLOADER\EBOOT:

1. Build processed the sources file and then ran nmake to build the source files

2. Nmake linked the object files and pre-built libraries to create eboot.exe (yes, I know that nmake doesn't actually do the linking)

3. In the sources file, WINCETARGETFILES is defined to be equal to RomImage. WINCETARGETFILES tells build to process the target RomImage after building the target defined in the sources file.

4. Build "knows" that the rule for WINCETARGETFILES is defined in makefile.inc.

5.      The rule for WINCETARGETFILES is:

RomImage:
!IF "$(NOLINK)" == ""
      romimage boot.bib
!ENDIF
!IF "$(WINCEREL)"=="1"
      copy $(_TARGETPLATROOT)\target\$(_TGTCPU)\$(WINCEDEBUG)\eboot.* $(_FLATRELEASEDIR)
!ENDIF

which says:

i. When building target RomImage, if the environment variable NOLINK is not set to some value, then run "romimage boot.bib" which creates the ROM images

ii. When building target RomImage, if the environment variable WINCEREL is set to 1, then copy the ROM images from the Target folder to the _FLATRELEASEDIR

Go to Summary of Building Windows CE

Windows CE: Bootloader Splash Screen

Bruce Eitman — Wed, 14 May 2008 14:50:51 GMT

I am sitting here at my desk experiencing some local network problems and thought I would take this time to discuss creating and using a splash screen in a bootloader. My target OS is Windows CE, but this applies to any code that needs to draw to a display without the use of an OS since this is a bootloader.

What is a bootloader splash screen? The bootloader is a small peice of code that runs when the reset vector is processed. This code's primary purpose is the initialize some hardware and look for OS updates. This shouldn't take much time, but if you include the time that it takes for the OS to boot to the desktop there is a long pause before the user sees activity. A long pause in user time can be one second or more. So it is nice to show the user that the device is doing something. To do this many devices show a graphic on the display, this is commonly known as a splash screen.

I am going to keep this as generic as I can. So that means no code and nothing specific to any CPU, Display Controller or anything else. But instead I hope to inspire you to think about a splash screen for your device and give you enough information to do some research and get a splash screen working.

What needs to be done to add a splash screen:

Find a good place in your existing code to add splash screen support
This can be anyplace that works. Probably best to do it after you get out of the assembly code and after you have done some basic initialization of other hardware and software.
Initialize your Display Controller
The most common question that I see asked about this is how do I do that? The good news is that in most cases you probably already have some code doing it in your display driver. So it is a matter of porting that code to build and run in your bootloader. If you don't have that code, then hopefully you have a datasheet for your display controller and can figure out from it how to initialize the display controller. Just keep in mind that what you don't have is an operating system, so no threads, no events, not syncronization objects, no interrupts.
Add a graphic to your system
This one can be fun. Of course the first thing to do is figure out which graphic you will be able to decode to display from your bootloader. I suggest keeping it simple. A Windows Bitmap (BMP) or a just a blob of data works well. Here are some thoughts on what you can do:
- Add a structure to your code that includes the binarly data. Of course creating the binary data can be challenging and may require that you write a desktop application to do it.
- Add a file to your system. This can be done by putting the file in an unused region of your ROM, on a CompactFlash or SD card, or in your persistent flash file system. But, it will require that you have some way to read it from your bootloader.
- Add the file to your bootloader .bib file. You will need to figure out how to get it from the bootloader image then.
Draw a graphic and maybe a background color
By now you have initalized the display controller and should have a frame buffer that you will write to. So the rest is down hill. You will need to write some code to read the graphic, this is where keeping it simple will come in handy. A quick internet search for "file format bmp" should yeild enough information to decode a Windows Bitmap file.
Turn on the backlight
Only you know how to do this.
Modify your display controller so that it doesn't clear the splash screen
If you have a splash screen, you will now notice that the display driver probably will clear the screen. This can cause a blank screen for short time before the desktop or your application starts. If you remove the clearing of the display it will make it a smoother transition.