Microsoft Windows Embedded CE 6.0 Exam Preparation Kit

Drivers, applications, and OEM adaptation layer (OAL) code impact system and real­time performance. Although Windows Embedded CE may be used in real-time and non-real-time configurations, it is important to note that using non-real-time components and applications can decrease system performance in a real-time operating system (OS) configuration. For example, you should keep in mind that demand paging, device input/output (I/O), and power management are not designed for real-time devices. Use these features carefully.

Demand Paging

Demand paging facilitates memory sharing between multiple processes on devices with limited RAM capacity. When demand paging is enabled, Windows Embedded CE discards and removes memory pages from active processes under low-memory conditions. However, to keep the code of all active processes in memory, disable demand paging for the entire operating system or for a specific module, such as a dynamic-link library (DLL) or device driver.

You can disable demand paging by using the following methods:

■ Operating system Edit the Config.bib file and set the ROMFLAGS option in the CONFIG section.

■ DLLs Use the LoadDriver function instead of the LoadLibrary function to load the DLL into memory.

■ Device drivers Add the DEVFLAGS_LOADLIBRARY flag to the Flags registry entry for the driver. This flag causes Device Manager to use the LoadLibrary function instead of the LoadDriver function to load the driver.

Windows Embedded CE allocates and uses memory as usual, but does not discard it automatically when you disable demand paging.

System Timer

The system timer is a hardware timer that generates system ticks at a frequency of one tick per millisecond. The system scheduler uses this timer to determine which threads should run at what time on the system. A thread is the smallest executable unit within a process that is allocated processor time to execute instructions in the operating system. You can stop a thread for an amount of time by using the Sleep function. The minimum value that you can pass to the Sleep function is 1 (Sleep(1)), which stops the thread for approximately 1 millisecond. However, the sleep time is not exactly 1 millisecond because the sleep time includes the current system timer tick plus the remainder of the previous tick. The sleep time is also linked to the priority of the thread. The thread priority determines the order in which the operating system schedules the threads to run on the processor. For those reasons, you should not use the Sleep function if you need accurate timers for real-time applications. Use dedicated timers with interrupts or multimedia timers for real-time purposes.

Power Management

Power management can affect system performance. When the processor enters the Idle power state, any interrupt generated by a peripheral or the system scheduler causes the processor to exit this state, restore the previous context, and invoke the scheduler. Power context switching is a time-consuming process. For detailed information about the power management features of Windows Embedded CE, see the section "Power Management" in the Windows Embedded CE 6.0 documentation available on the Microsoft MSDN® website at http://msdn2.microsoft.com/en-us/library/aa923906.aspx.

System Memory

The kernel allocates and manages system memory for heaps, processes, critical sections, mutexes, events, and semaphores. Yet, the kernel does not completely free the system memory when releasing these kernel objects. Instead, the kernel holds on to the system memory to reuse it for the next allocation. Because it is faster to reuse allocated memory, the kernel initializes the system memory pool during the startup process and allocates further memory only if no more memory is available in the pool. System performance can decrease depending how processes use virtual memory, heap objects, and the stack.

Non-Real-Time APIs

When calling system APIs, or Graphical Windows Event System (GWES) APIs, be aware that some APIs rely on non-real-time features, such as for window drawing. Forwarding calls to non-real-time APIs may dramatically decrease system performance. Consequently, you should make sure that your APIs in real-time applications are real-time compliant. Other APIs, such as ones used for accessing a file system or hardware, can have an impact on performance because these APIs may use blocking mechanisms, such as mutexes or critical sections, to protect resources.

Windows Embedded CE includes many performance monitoring and troubleshooting tools that can be used to measure the impact of Win32 APIs on system performance. These tools are helpful when identifying inefficient memory use, such as an application not releasing the system memory it allocates.

The following Windows Embedded CE tools are particularly useful to measure the real-time performance of your system components and applications:

■ ILTiming Measures Interrupt Service Routine (ISR) and Interrupt Service Thread (IST) latencies.

■ OSBench Measures system performance by tracking the time the kernel spends managing kernel objects.

■ Remote Performance Monitor Measures system performance, including memory usage, network throughput, and other aspects.

Interrupt Latency Timing (ILTiming)

The ILTiming tool is particularly useful for Original Equipment Manufacturers (OEMs) who want to measure ISR and IST latencies. Specifically, ILTiming enables you to measure the time it takes to invoke an ISR after an interrupt occurred (ISR latency) and the time between when the ISR exits and the IST actually starts (IST latency). This tool uses a system hardware tick timer by default, but it is also possible to use alternative timers (high-performance counters).

The ILTiming tool relies on the OALTimerIntrHandler function in the OAL to implement the ISR for managing the system tick interrupt. The timer interrupt handler stores the current time and returns a SYSINTR_TIMING interrupt event, which an ILTiming application thread waits to receive. This thread is the IST. The time elapsed between the reception of the interrupt in the ISR and the reception of the SYSINTR_TIMING event in the IST is the IST latency that the ILTiming tool measures.

You can find the ILTiming tool's source code in the %_WINCEROOT%\Public\Common\Oak\Utils folder on your development computer if you have installed Microsoft Platform Builder for Windows Embedded CE 6.0 R2. The ILTiming tool supports several command-line parameters that you can use to set the IST priority and type according to the following syntax:

iltiming [-i0] [-i1] [-i2] [-i3] [-i4] [-p priority] [-ni] [-t interval] [-n interrupt] [-all] [-o file_name] [-h]

Table 3-1 describes the individual ILTiming command-line parameters in more detail.

Table 3-1 ILTiming parameters

Operating System Benchmark (OSBench)

The OSBench tool can help you measure system performance by identifying the time that the kernel spends managing kernel objects. Based on the scheduler, OSBench collects timing measurements by means of scheduler performance-timing tests. A scheduler performance-timing test measures how much time basic kernel operations, such as thread synchronization, require.

OSBench enables you to track timing information for the following kernel operations:

■ Acquiring or releasing a critical section.

■ Waiting for or signaling an event.

■ Creating a semaphore or mutex.

■ Yielding a thread.

■ Calling system APIs.

The OSBench tool supports several command-line parameters that you can use according to the following syntax to collect timing samples for kernel operations:

osbench [-all] [-t test_case] [-list] [-v] [-n number] [-m address] [-o file_name] [-h]

Table 3-2 describes the individual OSBench command-line parameters in more detail.

Table 3-2 OSBench parameters

Check out the OSBench source code to identify the test content. You can find the source code at the following locations:

■ %_WINCEROOT%\Public\Common\Oak\Utils\Osbench

■ %_WINCEROOT%\Public\Common\Oak\Utils\Ob_load

Test results are by default sent to the debug output, but can be redirected to a CSV file.

Remote Performance Monitor

The Remote Performance Monitor application can track the real-time performance of the operating system as well as memory usage, network latencies, and other elements. Each system element is associated with a set of indicators that provide information on usage, queue length, and delays. Remote Performance Monitor can analyze log files generated on a target device.

As the name suggests, the Remote Performance Monitor application is a remote tool. The application monitors devices both under development and out in the field, as long as you have a way to connect to the device and deploy the application.

The Remote Performance Monitor monitors the following objects:

■ Remote Access Server (RAS).

■ Internet Control Message Protocol (ICMP).

■ Transport Control Protocol (TCP).

■ Internet Protocol (IP).

■ User Datagram Protocol (UDP).

■ Memory.

■ Battery.

■ System.

■ Process.

■ Thread.

This list is extended by implementing your own Remote Performance Monitor extension DLL. For sample code, look in the %COMMONPROGRAMFILES%\Microsoft Shared\Windows CE Tools\Platman\Sdk\WCE600\Samples\CEPerf folder.

Similar to the Performance tool on a Windows workstation, Remote Performance Monitor can create performance charts, configure alerts triggered at specified thresholds, write raw log files, and compile performance reports based on the performance objects available on the target device. Figure 3-1 shows a performance chart example.

Figure 3-1 A performance chart in Remote Performance Monitor

Hardware Validation

ILTiming tool, OSBench, and Remote Performance Monitor cover most performance monitoring needs. However, some cases may require other methods of gathering system performance information. For example, if you want to obtain exact interrupt latency timings, or if your hardware platform does not provide the required timer support for the ILTiming tool, you must use hardware-based performance measuring methods based on the General Purpose Input/Output (GPIO) interface of the processor and a waveform generator.

By using a waveform generator on a GPIO, it is possible to generate interrupts that are handled through ISRs and ISTs. These ISRs and ISTs then use another GPIO to generate a waveform in response to the received interrupt. The time elapsed between the two waveforms — the input waveform from the generator and the output waveform from the ISR or IST — is the latency time of the interrupt.

You can configure applications to start automatically as part of the Windows Embedded CE initialization process. This feature can be set in several ways, depending on whether you want to run the applications before or after Windows Embedded CE loads the shell user interface (UI). One method is to manipulate several registry settings that control the application startup behavior. Another common method is to place a shortcut to the application in the Startup folder so that the standard shell can start the application.

HKEY_LOCAL_MACHINE\INIT Registry Key

The Windows Embedded CE registry includes several registry entries to start operating system components and applications at startup time, such as Device Manager and Graphical Windows Event System (GWES). These registry entries are located under the HKEY_LOCAL_MACHINE\INIT registry key, as illustrated in Figure 3-2. You can create additional entries at this location to run your own applications included in the run-time image without having to load and run these applications manually on your target device. Among other things, automatically starting an application can facilitate debugging activities during software development.

Figure 3-2 The HKEY_LOCAL_MACHINE\INIT registry key

Table 3-3 lists three examples of registry entries to start typical Windows Embedded CE components when the run-time image starts.

Table 3-3 Startup registry parameter examples

If you look at the Launch50 registry entry in Table 3-3, you can see that the Windows Embedded CE standard shell (Explorer.exe), will not run until process 0x14 (20) and process 0x1E (30) have started successfully, which happen to be Device Manager and GWES. The hexadecimal values in the DependXX entry refer to decimal launch numbers XX, specified in the name of the LaunchXX entries.

Implementing the SignalStarted API helps the kernel manage process dependencies between all applications registered under the HKEY_LOCAL_MACHINE\INIT registry key. The application can then use the SignalStarted function to inform the kernel that the application has started and initialization is complete, as illustrated in the following code snippet.

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,

LPTSTR lpCmdLine, int nCmdShow) {

 // Perform initialization here...

 // Initialization complete,

 // call SignalStarted...

 SignalStarted(_wtol(lpCmdLine));

 // Perform application work and eventually exit.

 return 0;

}

Dependency handling is straightforward. The kernel determines the launch number from the Launch registry entry, uses it as a sequence identifier, and passes it as a startup parameter in lpCmdLine to the WinMain entry point. The application performs any required initialization work and then informs the kernel that it has finished this part by calling the SignalStarted function. The call to the _wtol function in the SignalStarted code line performs a conversion of the launch number from a string to a long integer value because the SignalStarted function expects a DWORD parameter. For example, Device Manager must pass a SignalStarted value of 20 and GWES must pass a value of 30 back to the kernel for the kernel to start Explorer.exe.

The Startup Folder

If you are using the standard shell on your target device, you can drop the application or a shortcut to the application into the Windows\Startup folder of the device. Explorer.exe examines this folder and starts all found applications.

The Windows Embedded CE standard shell can handle executable and shortcut files. Windows Embedded CE shortcut files differ from the shortcut files of Windows XP, but provide similar functionality. CE shortcut files are text files with an .lnk file-name extension. They contain the command-line parameters for the linked target according to the following syntax:

nn# command [optional parameters]

The placeholder nn stands for the number of characters followed by a pound sign (#), and the actual command, such as 27#\Windows\iexplore.exe -home to start Internet Explorer® and open the home page. After creating and adding the desired .lnk file to the run-time image, edit the Platform.dat or Project.dat file to map the .lnk file to the Startup folder, similar to the following .dat file entry:

Directory("\Windows\Startup"):-File("Home Page.lnk", "\Windows\homepage.lnk")

Chapter 2 covers these configuration tasks in more detail.

Delayed Startup

Another interesting option to start applications automatically is to leverage the services host process (Services.exe). Although Windows Embedded CE does not include a full-featured Service Control Manager (SCM), it does include built-in services and also comes with a sample service called Svcstart that can be used to start applications.

Svcstart is particularly useful for applications with dependencies on system components and services that are not immediately available after the startup process finishes. For example, it might take a few seconds to obtain an Internet Protocol (IP) address from a Dynamic Host Configuration Protocol (DHCP) server for a network interface card (NIC) or initialize a file system. To accommodate these scenarios, the Svcstart service supports a Delay parameter that specifies the time to wait before starting an application. You can find the Svcstart sample code in the %_WINCEROOT%\Public\Servers\SDK\Samples\Services\Svcstart folder. Compile the sample code into Svcstart.dll, add this DLL to your run-time image, and then run the sysgen -p servers svcstart command to register the Svcstart service with the operating system. Load it by using Services.exe.

Table 3-4 lists the registry settings that the Svcstart service supports to start applications.

Table 3-4 Svcstart registry parameters

By default, Platform Builder provides three shells to implement the interface between the target device and the user: the command processor shell, the standard shell, and a thin client shell. Each shell supports different features to interact with the target device.

Command Processor Shell

The command processor shell provides console input and output with a limited set of commands. This shell is available for both display-enabled devices and headless devices without keyboard and display screen. For display-enabled devices, include the Console Window component (Cmd.exe) so that the command processor shell can handle input and output through a command-prompt window. Headless devices, on the other hand, typically use a serial port for input and output.

Table 3-5 lists registry settings that you must configure on the target device to use a serial port in conjunction with the command processor shell.

Table 3-5 Console registry parameters

Windows Embedded CE Standard Shell

The standard shell provides a graphical user interface (GUI) similar to the Windows XP desktop. The primary purpose of the standard shell is to start and run user applications on the target device. This shell includes a desktop with Start menu and taskbar that enables the user to switch between applications, from one window to another. The standard shell also includes a system notification area to display additional information, such as the status of network interfaces and the current system time.

Windows Embedded CE Standard Shell is a required catalog item if you select the Enterprise Terminal design template when creating an OS design project in Visual Studio by using the OS Design Wizard. If you want to clone and customize this shell, you can find the source code in the %_WINCEROOT\Public\Shell\OAK\HPC folder. Chapter 1 explains how to clone catalog items and add them to an OS design.

Thin Client Shell

The thin client shell, also called the Windows-based Terminal (WBT) shell in the product documentation, is a GUI shell for thin-client devices that do not run user applications locally. You can add Internet Explorer to a thin-client OS design, yet all other user applications must run on a Terminal server in the network. The thin client shell uses the Remote Desktop Protocol (RDP) to connect to the server and display the remote Windows desktop. By default, the thin client shell displays the remote desktop in full-screen mode.

Taskman

You can also implement your own shell by cloning and customizing the Windows Task Manager (TaskMan) shell application. The source code in the %_WINCEROOT%\Public\Wceshellfe\Oak\Taskman folder is a good starting point.

The Control Panel is a special repository for central access to system and application configuration tools. The product documentation refers to these configuration tools as applets, to indicate the fact that they are embedded in the Control Panel. Each applet serves a specific and targeted purpose and does not depend on other applets. You can customize the content of the Control Panel by adding your own applets or by removing existing Control Panel applets included with Windows Embedded CE.

Control Panel Components

The Control Panel is a configuration system that relies on the following three key components:

■ Front-End (Control.exe) This application displays the user interface and facilitates starting Control Panel applets.

■ Host Application (Ctlpnl.exe) This application loads and runs the Control Panel applets.

■ Applets These are the individual configuration tools, implemented in form of .cpl files listed with icon and name in the Control Panel user interface.

For details regarding the implementation of the Windows Embedded CE Control Panel, check out the source code in the %_WINCEROOT%\Public\Wceshellfe\Oak\Ctlpnl folder. You can clone the Control Panel code and customize it to implement your own Control Panel version

Implementing Control Panel Applets

As mentioned, a Control Panel applet is a configuration tool for a system component or user application implemented in form of a .cpl file and located in the Windows folder on the target device. Essentially, a .cpl file is a DLL that implements the CPlApplet API. A single .cpl file can contain multiple Control Panel applications, yet a single applet cannot span multiple .cpl files. Because all .cpl files implement the CPlApplet API, it is a straightforward process for Control.exe to obtain detailed info about the implemented applets at startup in order to display the set of available applets in the user interface. Control.exe only needs to enumerate all .cpl files in the Windows folder and to call the CPlApplet function in each file.

According to the DLL nature and CPlApplet API requirements, .cpl files must implement the following two public entry points:

■ BOOL APIENTRY DllMain(HANDLE hModule, DWORD ul_reason_for_call, LPVOID lpReserved) Used to initialize the DLL. The system calls DllMain to load the DLL. The DLL returns true if initialization succeeded or false if initialization failed.

■ LONG CALLBACK CPlApplet(HWND hwndCPL, UINT message, LPARAM lParam1, LPARAM lParam2) A callback function that serves as the entry point for the Control Panel to perform actions on the applet.

The Control Panel calls the CPlApplet function to initialize the applet, obtain information, provide information about user actions, and to unload the applet. The applet must support several Control Panel messages, listed in Table 3-6, to implement a fully functional CPlApplet interface:

Table 3-6 Control Panel messages

Building Control Panel Applets

To build a Control Panel applet and generate the corresponding .cpl file, find the source code folder of the applet subproject and add the following CPL build directive on a new line at the end of the Sources file:

CPL=1

You also must add the path to the Control Panel header file to the Include Directories entry on the C/C++ tab in the applet subproject settings in Visual Studio, as illustrated in Figure 3-3:

$(_PROJECTROOT)\CESysgen\Oak\Inc

Figure 3-3 Include Directories entry for a Control Panel applet

Each process has at least one thread called the primary thread. This is the main thread of the process, which means that exiting or terminating this thread also ends the process. The primary thread can also create additional threads, such as worker threads, to perform parallel calculations or accomplish other processing tasks. These additional threads can create more threads if necessary by using the core Win32 API. Table 3-9 lists the most important functions to use in applications that work with threads on Windows Embedded CE.

Table 3-9 Thread management functions

Creating, Exiting, and Terminating Threads

The CreateThread function used to create a new thread expects several parameters that control how the system creates the thread and the instructions that the thread runs. Although it is possible to set most of these parameters to null or zero, it is necessary to provide at least a pointer to an application-defined function that the thread is supposed to execute. This function typically defines the core processing instructions for the thread, although you can also call other functions from within this function. It is important to pass the core function as a static reference to CreateThread because the linker must be able to determine the core function's starting address at compile time. Passing a non-static function pointer does not work.

The following code listing is copied from the Explorer.cpp file that you can find in the %_WINCEROOT%\Public\Shell\OAK\HPC\Explorer\Main folder. It illustrates how to create a thread.

void DoStartupTasks() {

 HANDLE hThread = NULL;

 // Spin off the thread which registers and watches the font dirs

 hThread = CreateThread(NULL, NULL, FontThread, NULL, 0, NULL);

 if (hThread) {

 CloseHandle(hThread);

 }

 // Launch all applications in the startup folder

 ProcessStartupFolder();

}

This code specifies FontThread as the new thread's core function. It immediately closes the returned thread handle because the current thread does not need it. The new thread runs parallel to the current thread and implicitly exits upon returning from the core function. This is the preferred way to exit threads because it enables C++ function cleanup to occur. It is not necessary to explicitly call ExitThread.

However, it is possible to explicitly call the ExitThread function within a thread routine to end processing without reaching the end of the core function. ExitThread invokes the entry point of all attached DLLs with a value indicating that the current thread is detaching, and then deallocates the current thread's stack to terminate the current thread. The application process exits if the current thread happens to be the primary thread. Because ExitThread acts on the current thread, it is not necessary to specify a thread handle. However, you must pass a numeric exit code, which other threads can retrieve by using the GetExitCodeThread function. This process is useful to identify errors and reasons for the thread exiting. If ExitThread is not explicitly called, the exit code corresponds to the return value of the thread function. If GetExitCodeThread returns the value STILL_ACTIVE, the thread is still active and running.

Although you should avoid it, there can be rare situations that leave you no other way to terminate a thread except for calling the TerminateThread function. A malfunctioning thread destroying file records might require this function. Formatting a file system might need you to call TerminateThread in debugging sessions while your code is still under development. You need to pass the handle to the thread to be terminated and an exit code, which you can retrieve later by using the GetExitCodeThread function. Calling the TerminateThread function should never be part of normal processing. It leaves the thread stack and attached DLLs behind, abandons critical sections and mutexes owned by the terminated thread, and leads to memory leaks and instability. Do not use TerminateThread as part of the process shutdown procedure. Threads within the process can exit implicitly or explicitly by using the ExitThread function.

Managing Thread Priority

Each thread has a priority value ranging from zero to 255, which determines how the system schedules the thread to run in relationship to all other threads within the process and between processes. On Windows Embedded CE, the core Win32 API includes four thread management functions that set the priority of a thread as follows.

■ Base priority levels Use the SetThreadPriority and SetThreadPriority functions to manage the thread priority at levels compatible with early versions of Windows Embedded CE (zero through seven).

■ All priority levels Use the CeSetThreadPriority and CeGetThreadPriority functions to manage the thread priority at all levels (zero through 255).

It is important to keep in mind that thread priorities define a relationship between threads. Assigning a high thread priority can be detrimental to the system if other important threads run with lower priority. You might achieve better application behavior by using a lower priority value. Performance testing with different priority values is a reliable manner of identifying the best priority level for a thread in an application or driver. However, testing 256 different priority values is not efficient. Choose an appropriate priority range for your threads according to the purpose of your driver or application as listed in Table 3-10.

Table 3-10 Thread priority ranges

Suspending and Resuming Threads

It can help system performance to delay certain conditional tasks that depend on time-consuming initialization routines or other factors. After all, it is not efficient to enter a loop and check 10,000 times if a required component is finally ready for use. A better approach is to put the worker thread to sleep for an appropriate amount of time, such as 10 milliseconds, check the state of the dependencies after that time, and go back to sleep for another 10 milliseconds or continue processing when conditions permit. Use the Sleep function from within the thread itself to suspend and resume a thread. You can also use the SuspendThread and ResumeThread functions to control a thread through another thread.

The Sleep function accepts a numeric value that specifies the sleep interval in milliseconds. It is important to remember that the actual sleep interval will likely exceed this value. The Sleep function relinquishes the remainder of the current thread's quantum and the scheduler will not give this thread another time slice until the specified interval has passed and there are no other threads with higher priority. For example, the function call

sleep(0)

sleep(0)

Similar to the

sleep(0)

The WaitForSingleObject or WaitForMultipleObjects functions suspend a thread until another thread or a synchronization object is signaled. For example, a thread can wait for another thread to exit without having to enter a loop with repeated Sleep and GetExitCodeThread calls if the WaitForSingleObject function is enabled instead. This approach results in a better use of resources and improves code readability. It is possible to pass a timeout value in milliseconds to the WaitForSingleObject or WaitForMultipleObjects functions.

Thread Management Sample Code

The following code snippet illustrates how to create a thread in suspended mode, specify a thread function and parameters, change the thread priority, resume the thread, and wait for the thread to finish its processing and exit. In the last step, the following code snippet demonstrates how to check the error code returned from the thread function.

// Structure used to pass parameters to the thread.

typedef struct {

 BOOL bStop;

} THREAD_PARAM_T

// Thread function

DWORD WINAPI ThreadProc(LPVOID lpParameter) {

 // Perform thread actions...

 // Exit the thread.

 return ERROR_SUCCESS;

}

BOOL bRet = FALSE;

THREAD_PARAM_T threadParams;

threadParams.bStop = FALSE;

DWORD dwExitCodeValue = 0;

// Create the thread in suspended mode.

HANDLE hThread = CreateThread(NULL, 0, ThreadProc,

 (LPVOID) &threadParams, CREATE_SUSPENDED, NULL);

if (hThread == NULL) {

 // Manage the error...

} else {

 // Change the Thread priority.

 CeSetThreadPriority(hThread, 200);

 // Resume the thread, the new thread will run now.

 ResumeThread(hThread);

 // Perform parallel actions with the current thread...

 // Wait until the new thread exits.

 WaitForSingleObject(hThread, INFINITE);

 // Get the thread exit code

 // to identify the reason for the thread exiting

 // and potentially detect errors

 // if the return value is an error code value.

 bRet = GetExitCodeThread(hThread, &dwExitCodeValue);

 if (bRet && (ERROR_SUCCESS == dwExitCodeValue)) {

 // Thread exited without errors.

 } else {

 // Thread exited with an error.

 }

 // Don't forget to close the thread handle

 CloseHandle(hThread);

}

The real art of multithreaded programming lies in avoiding deadlocks, protecting access to resources, and ensuring thread synchronization. Windows Embedded CE provides several kernel objects to synchronize resource access for threads in drivers or applications, such as critical sections, mutexes, semaphores, events, and interlocks functions. Yet, the choice of the object depends on the task that you want to accomplish.

Critical Sections

Critical sections are objects that synchronize threads and guard access to resources within a single process. A critical section cannot be shared between processes. To access a resource protected by a critical section, a thread calls the EnterCriticalSection function. This function blocks the thread until the critical section is available.

In some situations, blocking the thread execution might not be efficient. For example, if you want to use an optional resource that might never be available, calling the EnterCriticalSection function blocks your thread and consumes kernel resources without performing any processing on the optional resource. It is more efficient in this case to use a critical section without blocking by calling the TryEnterCriticalSection function. This function attempts to grab the critical section and returns immediately if the critical section cannot be used. The thread can then continue along an alternative code path, such as to prompt the user for input or to plug in a missing device.

Having obtained the critical section object through EnterCriticalSection or TryEnterCriticalSection, the thread enjoys exclusive access to the resource. No other thread can access this resource until the current thread calls the LeaveCriticalSection function to release the critical section object. Among other things, this mechanism highlights why you should not use the TerminateThread function to terminate threads. TerminateThread does not perform cleanup. If the terminated thread owned a critical section, the protected resource becomes unusable until the user restarts the application.

Table 3-11 lists the most important functions that you can use to work with critical section objects for thread synchronization purposes.

Table 3-11 Critical Section API

Mutexes

Whereas critical sections are limited to a single process, mutexes can coordinate mutually exclusive access to resources shared between multiple processes. A mutex is a kernel object that facilitates inter-process synchronization. Call the CreateMutex function to create a mutex. The creating thread can specify a name for the mutex object at creation time, although it is possible to create an unnamed mutex. Threads in other processes can also call CreateMutex and specify the same name. However, these subsequent calls do not create new kernel objects, but instead return a handle to the existing mutex. At this point, the threads in the separate processes can use the mutex object to synchronize access to the protected shared resource.

The state of a mutex object is signaled when no thread owns it and non-signaled when one thread has ownership. A thread must use one of the wait functions, WaitForSingleObject or WaitForMultipleObjects, to request ownership. You can specify a timeout value to resume thread processing along an alternative code path if the mutex does not become available during the wait interval. On the other hand, if the mutex becomes available and ownership is granted to the current thread, do not forget to call ReleaseMutex for each time that the mutex satisfied a wait in order to release the mutex object for other threads. This is important because a thread can call a wait function multiple times, such as in a loop, without blocking its own execution. The system does not block the owning thread to avoid a deadlock situation, but the thread must still call ReleaseMutex as many times as the wait function to release the mutex.

Table 3-12 lists the most important functions that you can use to work with mutex objects for thread synchronization purposes.

Table 3-12 Mutex API

Semaphores

Apart from kernel objects that enable you to provide mutually exclusive access to resources within a process and between processes, Windows Embedded CE also provides semaphore objects that enable concurrent access to a resource by one or multiple threads. These semaphore objects maintain a counter between zero and a maximum value to control the number of threads accessing the resource. The maximum value amount is specified in the CreateSemaphore function call.

The semaphore counter limits the number of threads that can access the synchronization object concurrently. The system will keep decrementing the counter every time a thread completes a wait for the semaphore object until the counter reaches zero and enters the nonsignaled state. The counter cannot decrement past zero. No further thread can gain access to the resource until an owning thread releases the semaphore by calling the ReleaseSemaphore function, which increments the counter by a specified value and again switches the semaphore object back into signaled state.

Similar to mutexes, multiple processes can open handles of the same semaphore object to access resources shared between processes. The first call to the CreateSemaphore function creates the semaphore object with a specified name. You can also construct unnamed semaphores, but these objects are not available for interprocess synchronization. Subsequent calls to the CreateSemaphore function with the same semaphore name do not create new objects, but open a new handle of the same semaphore.

Table 3-13 lists the most important functions that work with semaphore objects for thread synchronization purposes.

Table 3-13 Semaphore API

Events

The Event object is another kernel object that synchronizes threads. This object enables applications to signal other threads when a task is finished or when data is available to potential readers. Each event has signaled/non-signaled state information used by the API to identify the state of the event. Two types of events, manual events and auto-reset events, are created according to the behavior expected by the event.

The creating thread specifies a name for the event object at creation time, although it is also possible to create an unnamed event. It is possible for threads in other processes to call CreateMutex and specify the same name, but these subsequent calls do not create new kernel objects.

Table 3-14 lists the most important functions for event objects for thread synchronization purposes.

Table 3-14 Event API

The behavior of the events API is different according to the type of events. When you use SetEvent on a manual event object, the event will stay signaled until ResetEvent is explicitly called. Auto-reset events only stay signaled until a single waiting thread is released. At most, one waiting thread is released when using the PulseEvent function on auto-reset events before it immediately transitions back to the non-signaled state. In the case of manual threads, all waiting threads are released and immediately transition back to a non-signaled state.

Interlocked Functions

In multithread environments, threads can be interrupted at any time and resumed later by the scheduler. Portions of code or applications resources can be protected using semaphores, events, or critical sections. In some applications, it could be too time consuming to use those kinds of system objects to protect only one line of code like this:

// Increment variable

dwMyVariable = dwMyVariable + 1;

The sample source code above in C is one single instruction, but in assembly it could be more than that. In this particular example, the thread can be suspended in the middle of the operation and resumed later, but errors can potentially be encountered in the case of another thread using the same variable. The operation is not atomic. Fortunately, it is possible in Windows Embedded CE 6.0 R2 to increment, decrement, and add values in multithreading-safe, atomic operations without using synchronization objects. This is done by using interlocked functions.

Table 3-15 lists the most important interlocked functions that are used to atomically manipulate variables.

Table 3-15 Interlock API

Exceptions are events resulting from error conditions. These conditions can arise when the processor, operating system, and applications are executing instructions outside the normal flow of control in kernel mode and user mode. By catching and handling exceptions, you can increase the robustness of your applications and ensure a positive user experience. Strictly speaking, however, you are not required to implement exception handlers in your code because structured exception handling is an integral part of Windows Embedded CE.

The operating system catches all exceptions and forwards them to the application processes that caused the events. If a process does not handle its exception event, the system forwards the exception to a postmortem debugger and eventually terminates the process in an effort to protect the system from malfunctioning hardware or software. Dr. Watson is a common postmortem debugger that creates a memory dump file for Windows Embedded CE.

Exception Handling and Kernel Debugging

Exception handling is also the basis for kernel debugging. When you enable kernel debugging in an operating system design, Platform Builder includes the kernel debugging stub (KdStub) in the run-time image to enable components that raise exceptions to break into the debugger. Now you can analyze the situation, step through the code, resume processing, or terminate the application process manually. However, you need a KITL connection to a development workstation in order to interact with the target device. Without a KITL connection, the debugger ignores the exception and lets the application continue to run so that the operating system can use another exception handler as if no debugger was active. If the application does not handle the exception, then the operating system gives the kernel debugger a second chance to perform postmortem debugging. In this context, it is often called just in time (JIT) debugging. The debugger must now accept the exception and waits for a KITL connection to become available for the debug output. Windows Embedded CE waits until you establish the KITL connection and start debugging the target device. Developer documentation often uses the terms first-chance exception and second-chance exception because the kernel debugger has two chances to handle an exception in this scenario, but they are, in fact, referring to the same exception event. For more information about debugging and system testing, read Chapter 5, "Debugging and Testing the System."

Hardware and Software Exceptions

Windows Embedded CE uses the same structured exception handling (SEH) approach for all hardware and software exceptions. The central processing unit (CPU) can raise hardware exceptions in response to invalid instruction sequences, such as division by zero or an access violation caused by an attempt to access an invalid memory address. Drivers, system applications, and user applications, on the other hand, can raise software exceptions to invoke the operating system's SEH mechanisms by using the RaiseException function. For example, you can raise an exception if a required device is not accessible (such as a USB camera or a database connection), if the user specified an invalid command-line parameter, or for any other reason that requires you to run special instructions outside the normal code path. You can specify several parameters in the RaiseException function call to specify information that describes the exception. This specification can then be used in the filter expression of an exception handler.

On Windows Embedded CE, Power Manager (PM.dll) is a kernel component that integrates with the Device Manager (Device.exe) to implement power management features. Essentially, Power Manager acts as a mediator between the kernel, OEM adaptation layer (OAL), and drivers for peripheral devices and applications. By separating the kernel and OAL from drivers and applications, drivers and applications can manage their own power state separately from the system state. Drivers and applications interface with Power Manager to receive notifications about power events and to perform power management functions. Power Manager has the ability to set the system power state in response to events and timers, control driver power states, and respond to OAL events that require a power state change, such as when the battery power state is critical.

Power Manager Components and Architecture

Power Manager exposes a notification interface, an application interface, and a device interface according to its tasks. The notification interface enables applications to receive information about power management events, such as when the system state or a device power state changes. In response to these events, power management-enabled applications use the application interface to interact with Power Manager to communicate their power management requirements or change the system power state. The device interface, on the other hand, provides a mechanism to control the power level of device drivers. Power Manager can set device power states separately from the system power state. Similar to applications, device drivers may use the driver interface to communicate their power requirements back to Power Manager. The important point is that Power Manager and the Power Manager APIs centralize power management on Windows Embedded CE, as illustrated in Figure 3-7.

Figure 3-7 Power Manager and power management interaction

Power Manager Source Code

Windows Embedded CE comes with source code for Power Manager, which is found in the %_WINCEROOT%\Public\Common\Oak\Drivers\Pm folder on your development computer. Customizing this code provides personalized power handling mechanisms on a target device. For example, an Original Equipment Manufacturer (OEM) can implement additional logic to shut down special components before calling the PowerOffSystem function. See Chapter 1, "Customizing the Operating System Design" for techniques to clone and customize standard Windows Embedded CE components.

As mentioned earlier in this lesson, Power Manager exposes three interfaces to enable applications and drives for power management: notification interface, driver interface, and application interface.

Notification Interface

The notification interface provides two functions that applications can use to register and deregister for power notifications through message queues, as listed in Table 3-17. It is important to note that power notifications are multicast messages, which means that Power Manager sends these notification messages only to registered processes. In this way, power management-enabled applications can seamlessly coexist on Windows Embedded CE with applications that do not implement the Power Management API.

Table 3-17 Power Management notification interface

The following sample code illustrates how to use power notifications:

// Size of a POWER_BROADCAST message.

DWORD cbPowerMsgSize =

 sizeof POWER_BROADCAST + (MAX_PATH * sizeof TCHAR);

// Initialize a MSGQUEUEOPTIONS structure.

MSGQUEUEOPTIONS mqo;

mqo.dwSize = sizeof(MSGQUEUEOPTIONS);

mqo.dwFlags = MSGQUEUE_NOPRECOMMIT;

mqo.dwMaxMessages = 4;

mqo.cbMaxMessage = cbPowerMsgSize;

mqo.bReadAccess = TRUE;

//Create a message queue to receive power notifications.

HANDLE hPowerMsgQ = CreateMsgQueue(NULL, &mqo);

if (NULL == hPowerMsgQ) {

 RETAILMSG(1, (L"CreateMsgQueue failed: %x\n", GetLastError()));

 return ERROR;

}

// Request power notifications.

HANDLE hPowerNotifications = RequestPowerNotifications(hPowerMsgQ,

 PBT_TRANSITION | PBT_RESUME | PBT_POWERINFOCHANGE);

// Wait for a power notification or for the app to exit.

while(WaitForSingleObject(hPowerMsgQ, FALSE, INFINITE) == WAIT_OBJECT_0) {

 DWORD cbRead;

 DWORD dwFlags;

 POWER_BROADCAST *ppb = (POWER_BROADCAST*) new BYTE[cbPowerMsgSize];

 // Loop through in case there is more than 1 msg.

 while(ReadMsgQueue(hPowerMsgQ, ppb, cbPowerMsgSize, &cbRead, 0, &dwFlags)) {

 // Perform action according to the message type.

 }

}

Device Driver Interface

In order to integrate with the Power Manager, device drivers must support a set of I/O controls (IOCTLs). Power Manager uses these to query device-specific power capabilities as well as to set and change the device's power state, as illustrated in Figure 3-10. Based on the Power Manager IOCTLs, the device driver should put the hardware device into a corresponding power configuration.

Figure 3-10 Power Manager and device driver interaction

Power Manager uses the following IOCTLs to interact with device drivers:

■ IOCTL_POWER_CAPABILITIES Power Manager checks the power management capabilities of the device driver. The returned information should reflect the capabilities of the hardware and the driver managing the hardware device. The driver must return only supported Dx states.

■ IOCTL_POWER_SET Power Manager forces the driver to switch to a specified Dx state. The driver must perform the power transition.

■ IOCTL_POWER_QUERY Power Manger checks to see if the driver is able to change the state of the device.

■ IOCTL_POWER_GET Power Manager wants to determine the current power state of the device.

■ IOCTL_REGISTER_POWER_RELATIONSHIP Power Manager notifies a parent driver to register all child devices that it controls. Power Manager sends this IOCTL only to devices that include the POWER_CAP_PARENT flag in the Flags member of the POWER_CAPABILITIES structure.

Application Interface

The application interface provides functions that applications can use to manage the power state of the system and of individual devices through Power Manager. Table 3-18 summarizes these power management functions.

Table 3-18 Application interface

As illustrated in Figure 3-8, Power Manager associates system power states with device power states to keep system and devices synchronized. Unless configured otherwise, Power Manager enforces the following default system-state-to-device-state mappings: On = D0, UserIdle = D1, SystemIdle = D2, and Suspend = D3. Overriding this association for individual devices and device classes can be accomplished by means of explicit registry settings.

Overriding the Power State Configuration for an Individual Device

The default Power Manager implementation maintains system-state-to-device-state mappings in the registry under the HKEY_LOCAL_MACHINE\System\CurrentControlSet\State key. Each system power state corresponds to a separate subkey and you can create additional subkeys for OEM-specific power states.

Table 3-19 shows a sample configuration for the system power state On. This configuration causes Power Manager to switch all devices, except the backlight driver BLK1: driver, into the D0 device power state. The backlight driver BLK1: can only go to the D2 state.

Table 3-19 Default and driver-specific power state definitions for system power state On

Overriding the Power State Configuration for Device Classes

Defining device power state for multiple system power states individually can be a tedious task. Power Manager facilitates the configuration by supporting device classes based on IClass values, which can be used to define the power management rules. The following three default class definitions are found under the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Power\Interfaces registry key.

■ {A3292B7-920C-486b-B0E6-92A702A99B35} Generic power management-enabled devices.

■ {8DD679CE-8AB4-43c8-A14A-EA4963FAA715} Power-management-enabled block devices.

■ {98C5250D-C29A-4985-AE5F-AFE5367E5006} Power-management-enabled Network Driver Interface Specification (NDIS) miniport drivers.

Table 3-20 shows a sample configuration for the NDIS device class, which specifies that NDIS drivers only go as high as the D4 state.

Table 3-20 Sample power state definition for NDIS device class

Complete the following tasks to help you successfully master the exam objectives presented in this chapter:

Use the ILTiming and OSBench Tools

Use Iltiming and OSBench on the emulator device to examine the emulated ARMV4 processor's performance.

Implement a Custom Shell

Customize the look and feel of the target device by using Task Manager, included in Windows Embedded CE with source code, to replace the shell.

Experiment with Multithreaded Applications and Critical Sections

Use critical section objects in a multithreaded application to protect access to a global variable. Complete the following tasks:

1. Create two threads in the main code of the applications and in the thread functions wait two seconds (Sleep(2000)) and three seconds (Sleep(3000)) in an infinite loop. The primary thread of the application should wait until both threads exit by using the WaitForMultipleObjects function.

2. Create a global variable and access it from both threads. One thread should write to the variable and the other thread should read the variable. By accessing the variable before and after the first Sleep and displaying the values, you should be able visualize concurrent access.

3. Protect access to the variable by using a CriticalSection object shared between both threads. Grab the critical section at the beginnings of the loops and release it at the ends of the loops. Compare the results with the previous output.