Windows CE Kernel

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.

Windows CE: Number of Processes and Threads

Bruce Eitman — Thu, 07 Aug 2008 02:37:42 GMT

Once in a while I am asked how many processes can run at any time in a Windows CE system. It is also one of my interview questions when interviewing a candidate with Windows CE experience, and the follow on question is how many threads can run at one time?

Number of Processes:

Then number of processes is controlled by the kernel and was changed for Windows CE 6.0 to be 32K processes. Pretty impressive, but I suspect that the limit is much smaller because on most, if not all, Windows CE systems you will run out of physical memory long before creating even close to 32K processes (I suppose that there is another post topic in that sentence.) Each process has up to 2GB of virtual address space available to it. As a result, Microsoft lifted the artificial limits on number of processes and virtual address space, now the limit is hardware.

The number of processes that can run at simultaneously in Windows CE 5.0 and earlier versions is 32. Each process has 32MB of virtual address space available to it. The reason for these limits is that the address space for processes is divided into 33 slots each having 32MB of virtual address space available to it. The slots are numbered 0 through 32, with slot 0 being the currently running process.

There was a significant change to the slot architecture in Windows CE 4.0. Slot 1, which was where the kernel ran in prior versions, was reserved for loading DLLs that were specifically fixed up to run in slot 1. The kernel moved out of the slots altogether, so this change didn’t reduce the number of processes that could run. This change was significant because in previous versions all DLLs loaded in slot 0, which meant that the DLLs reduced the amount of available virtual address space available to the running process. That is if any process loaded a DLL, all processes suffered the loss of virtual address space. This was still true for Windows CE 4.x and 5.0, but only if the DLL was not fixed up to run in slot 1, but most of the DLLs that are loaded are included in the OS and are fixed up to run in slot 1.

Number of Threads

The number of threads is only limited by the available system resources. That is a fancy way of saying that when the system runs out of physical RAM, no more threads can be started.

	Number of Processes	Number of Threads	Virtual Address Space per Process
Windows CE 5.0 and before	32	Limited by System Resources	32 MB
Windows CE 6.0	32K	Limited By System Resources	2 GB

Tags: Kernel

Platform Builder: Clone Public Code

Bruce Eitman — Wed, 02 Jul 2008 18:32:13 GMT

I recently wrote an article about modifying the behavior of KernelIoControl when called by User Mode code. In that article, I stated that you need to clone the Public oemioctl code to your platform. Sounds so simple doesn’t it, and really it isn’t that difficult if you know what you are doing, but for the rest of you I thought that I would walk through the process of cloning code.

Many of us use the term “clone code” but what does it really mean? Cloning code means to copy the code to another build tree and modify the build environment to build the code under the new tree. In the old days of Windows CE development, that meant reverse engineering how Microsoft builds the code to apply your knowledge of the build system to it. Today we have sysgen_capture.bat to do most of the hard work for us.

Here is how I would clone oemioctl:

1. Create a new folder in my platform to build oemoctl.dll, I will call mine OALIoctlDir. This folder will be a holding place for two new folders; one will build the lib that is built in Public\Common\OAK\oalioctl, and the other will link the lib to create the dll. You certainly can create the dll with one folder, but that is more involved that the discussion here.

2. Copy the %_WINCEROOT%\Public\Common\OAK\OEMICTL folder and paste it as a new subfolder of OALIoctlDir. This is the folder that creates OALIoctl.lib.

3. Create an new folder in OALIoctlDir named BuildDll; this is the folder that will do the linking to create OALIoctl.dll.

4. Create a dirs file OALIoctlDir that contains

DIRS=oalicotl BuildDll
This tells build to go into OALIoctl first to build the lib, then go to BuildDll to link the dll.

5. Add OEMIocltDir to its parent folder’s dirs file, which tells build to build our clone of OALIoctl.dll.

6. Modify OALIoctlDir\OALIoctl\sources to add RELEASETYPE=PLATFORM, this tells build to put the lib in the platform build tree

7. Open a build window and change directories to OALIocltDir\BuildDll

8. Run “sysgen_capture OALIoctl” which will create a file named sources.OALIoctl. This new file contains the information that Microsoft uses to link OALIoctl.lib to create OALIoctl.dll, we need that information to build.

9. Rename souces.OALIoctl to sources, so that build.exe can use it.

10. Modify OALIoctlDir\BuildDll\sources to

a. change $(_PUBLICROOT)\common\oak\lib\$(_CPUINDPATH)\OALIoctl.lib to $(_TARGETPLATROOT)\lib\$(_CPUINDPATH)\OALIoctl.lib

b. Change the DEFFILE to DEFFILE=OALIoctl.def

11. Copy OALIoctl.def from OALIoctlDir\oalioclt to OALIoctlDir\BuildDll, this is necessary so that when BuildDll is built it can find the def file. There are alternative solutions for this, but this one is easy.

12. Copy a makefile from one another folder to BuildDll, this is necessary because build.exe needs the makefile when it calls nmake.

13. Change directories to OALIocltDir and run build

14. Now you have an OALIoctl.dll in your Platform’s Target folder. When you run buildrel, this OALIoctl.dll will overwrite the one created in the Public folder.

Now you have a clone of OALIoctl that you can modify to suit the needs of your platform.

Tags: Sysgen_Capture, Clone

Windows CE 6.0: User Mode KernelIoControl

Bruce Eitman — Tue, 01 Jul 2008 06:21:06 GMT

Windows CE 6.0 introduces some new security features including new meaning for User Mode and Kernel Mode. Loosely speaking, Kernel Mode has access to the system’s resources and User Mode is greatly restricted. One of the new restrictions on User Mode code is that calls to KernelIoControl are limited to the following OEMIoControl IOCTLs:

IOCTL_HAL_GET_CACHE_INFO

IOCTL_HAL_GET_DEVICE_INFO

IOCTL_HAL_GET_DEVICEID

IOCTL_HAL_GET_UUID

IOCTL_PROCESSOR_INFORMATION

As an OEM you can change this to allow access to other IOCTLs. The default restriction makes a lot of sense for consumer devices, but for closed systems or systems that the OEM wants to provide more functionality, there is a need to provide more IOCTLs for use from User Mode code.

User Mode code accesses these IOCTLS through a new oalioctl.dll. The code for oalioctl.dll is available in %_WINCEROOT%\Public\Common\Oak\Oalioctl, so I won’t publish the code here. But basically it has an IoControl function that has a switch statement which limits access to OEMIoControl(). So to add more IOCTLs, we need to clone the code and change the switch statement.

Windows CE: Why does my system halt for 20 minutes?

Bruce Eitman — Mon, 12 May 2008 22:26:26 GMT

I don't know how many systems are affected by this problem, but apparently there are still some. I do know that the reference BSP for the Intel PXA25x processor boards has a problem. This problem is still biting people because there have recently been questions about it in the Platform Builder newsgroup.

The cause is really quite simple. A shared resource with nothing to protect it from interrupts during read-modify-write operations.

In this case, there are two sets of code that access the time match register. One is in OEMIdle() which is called when the scheduler doesn't have any threads to run. The other is in the system timer Interrupt Service Routine (ISR).

The timer match register (OSMR0) is used with the timer counter register (OSCR) to cause an interrupt to occur when a certain time is reached. When the two registers contain the same value the interrupt is fired. The counter register increments with the CPU ocsilator. Both registers roll over in just under 20 minutes. Anyone see a coorilation between that rollover and the amount of time that the system halts?

So what is happening in the reference BSP? The code in OEMIdle is setting the match register by:

1. Reading the OSCR value
2. Adding something to it
3. Then writing it to OSMR0

That makes sense, unless you consider that the interrupts are still enabled. Imagine that the time interrupt fires just after reading the OSCR and before writing it back. And maybe we have one or more other interrupts. If everything goes wrong for us, by the time we write OSMR0, OSCR has incremented past OSMR0. That means that we must wait until OSCR rolls over to reach a match with OSMR0 and the next system tick occurs.

How can you know if this is happening? A simple application that outputs the current time and the current tick count can tell you. If the output indicates that 20 minutes past and the current tick count didn't increment, you have this problem.

How can you fix it? Disable interrupts while modifying the counter register.