Understanding Windows CE Device Drivers | Native Driver Architecture Overview

1. Chapter 7: Understanding Device Drivers

2. Overview • Device Driver Architecture • Native Device Drivers • Device Driver Memory Management • Device Driver Interrupt Handling • Stream Device Drivers • Display Driver Architecture • Primer on GDI Programming • Inside Display Drivers

3. Device Driver Architecture • Windows CE Architecture • Device Power Management

4. RemoteConnectivity WindowsCEShellServices WIN32APIs COREDLL, WINSOCK, OLE, COMMCTRL, COMMDLG, WININET, TAPI Windows CE Architecture OEM ISV,OEM Microsoft Applications EmbeddedShell IrDA Kernel Library TCP/IP GWES File Manager Device Manager Filedrivers Drivers Devicedrivers OAL Bootloader Network drivers OEMHardware

5. Device Power Management • Power status notification function • Shutdown operations • Save device state to preallocated storage • Issue commands to the device that is shutting down • Set a flag within the driver to note that it has been shut down • Do not call Win32 API functions during a shutdown sequence

6. Native Device Drivers • Overview of Native Device Drivers • Programming Model • MDD/PDD Layers • Battery and Notification LED Device Drivers • PC Card Socket Device Drivers • Keyboard Device Drivers

7. Overview of Native Device Drivers • Designed to drive built-in devices • Provided by OEMs • Supports custom interfaces • Loaded by GWES • Device Driver Interface (DDI) • Interface between the OS and device drivers is called DDI • DDI functions are defined for each device driver class • DDI functions are defined by Microsoft and cannot be changed

8. Programming Model GWES DDI functions DDI functions Monolithic device driver Device Driver MDD layer DDSI functions PDD layer Hardware

9. MDD/PDD Layers • Model Device Driver (MDD) Layer • Provided by Microsoft • Platform-independent code • Communicates with GWES and Kernel • Handles interrupts • Platform-Dependent Driver (PDD) Layer • Provided by OEMs • Focus only on specific platform porting issue • Communicates with the hardware

10. MDD/PDD Layers (continued) • MDD layer handles the DDI interface • Interface between MDD and PDD is the Device Driver Service-Provider Interface (DDSI) • DDSI interfaces may be redefined by OEMs with corresponding changes in the MDD layer • When performance is an issue, the PDD layer can be bypassed - all processing can be done in MDD layer • MDD code is provided as source code and as libraries

11. Battery and Notification LED Device Drivers • Battery device driver • Provides information about power level of main and backup batteries • Library statically linked with GWES • Monolithic; uses only DDI functions • Notification LED driver • Library statically linked with GWES • Handles all requests to turn the system notification LED on or off

12. PC Card Socket Device Drivers • Manages any PC Card sockets • Abstracts hardware specifics so that a PC Card driver can run unchanged on any platform • The MDD Layer exposes functions that can be used when developing a stream interface device driver for individual PC Cards • MDD functions constitute the Card Services library • PPD layer exposes low-level functions that constitute the Socket Services library

13. Keyboard Device Drivers • MDD Layer • Maps scan code to virtual key code • Generates character data associated with VK code • Packages keyboard messages and puts them in the system message queue • PDD Layer • Retrieves scan code from hardware

14. Device Driver Memory Management • Memory Management Functions • Windows CE Address Space • Drivers and Pointer Data • Driver Memory Access • Memory Access in Drivers

15. Memory Management Functions • Device drivers are user-mode modules - it is necessary to map physical memory to virtual memory • VirtualAlloc, VirtualFree: reserve, free virtual memory • MEM_RESERVE • VirtualCopy: maps a physical memory range to a virtual memory range • PAGE_NOCACHE • PAGE_PHYSICAL

16. Memory Management Functions (continued) • MapPtrToProcess • GetCurrentProcess • GetOwnerProcess • UnMapPtr • SetProcPermissions • Volatile qualifier

17. 512M Non-Cached 512M Cached Windows CE Address Space 4 GB Not Used Accessable via MmMapiIoSpace 3 GB Above 2G-3G Mapped to physical memory 0xA0000000 Virtual address space 0x80000000 2 GB Memory mapped files Slot 32 Slot 32 64 MB Slot 1 32 MB Slot 0 64 KB NULL pointers

18. Drivers and Pointer data • OS manages pointers passed directly as parameters • Driver must map All pointers contained in structs • DeviceIOControl buffers often are structs that contain data, some of which may be pointers. • Use MapPtrToProcess( SomePtr, GetOwnerProcess()) • GetOwnerProcess() is used only in the context of a driver and cannot be used by Apps.

19. Driver Memory Access APP APP APP App is mapped into Slot 0 Mapped pointer App Calls DeviceIOControl DM mapped into Slot 0 DM DM Sets permissions to App space DM Calls xxx_IoControl APP APP DM Driver Calls MapPtrToProcess Original pointer Slot 0 Driver returns from xxx_IoControl DM Re-Sets permissions to App space App is mapped into Slot 0

20. Memory Access in Drivers • If driver creates a thread to do the work. MapPtrToProcess() will not work without some help • You must use GetCurrentPermissions() and SetProcPermissions() to capture and reset the process permissions.

21. Device Driver Interrupt Handling • Interrupt Run Time • Interrupt Service Thread • Interrupt Management Functions • Typical IST Start • Typical IST • Typical Stop

22. Driver Kernel Exception Handler Interrupt Support Handler IST ISR OAL routines I/O Routines OAL OEM Hardware Interrupt Run Time 6 5 8 4 7 2 3 9 1

23. Interrupt Service Thread • Uses user-mode thread of device drivers for built-in devices • Does the actual processing of the interrupt • Creates an event object associated with the logical interrupt • IST remains idle most of the time, awakened when the kernel signals the event object • IST usually runs at above-normal priority

24. Interrupt Service Thread (continued) • Boost IST priority with CeSetThreadPriority function • Create an event object with CreateEvent function • Associate event object with SYSINTR_ by calling InterruptInitialize function • Code a loop whose first operation is WaitForSingleObject • The kernel signals the event object, which causes WaitForSingleObject to return • Perform I/O in the device and process data • Call InterruptDone to signal interrupt handling completion

25. Interrupt Management Functions • ISR • HookInterrupt • UnhookInterrupt • IST • InterruptInitialize • InterruptDone • InterruptDisable

26. Typical IST Start struct ISTData // Declare the Strucure to pass to the IST { HANDLE hThread; // IST Handle DWORD sysIntr; // Logical ID HANDLE hEvent; // handle to the event to wait for interrupt volatile BOOL abort; // flag to test to exit the IST }; ISTData g_KeypadISTData; // Create event to link to IST g_KeypadISTData.hEvent = CreateEvent(NULL, FALSE, FALSE, NULL); // Translate IRQ to an logical ID (x86 CEPC) g_KeypadISTData.sysIntr =Mapirq2Sysintr(5); // start the thread g_KeypadISTData.hThread = CreateThread(NULL,0,&KeypadIST, &g_KeypadISTData, 0, NULL);

27. TypicalISTStart (Continued) //Change the threads priority CeSetThreadPriority(g_KeypadISTData.hThread,0); //disconnect any previous event from logical ID InterruptDisable(g_KeypadISTData.sysIntr); // Connect Logical ID with Event InterruptInitialize(g_KeypadISTData.sysIntr, g_KeypadISTData. hEvent,NULL,0);

28. TypicalIST DWORD KeypadIST(void *dat) { ISTData* pData= (ISTData*)dat; // loop until told to stop While(!pData->abort) { // wait for the interrupt event... WaitForSingleObject(pData->hEvent, INFINITE) if(pData->abort) break; // Handle the interrupt... // Let OS know the interrupt processing is done InterruptDone(pData->sysIntr); } Return 0; }

29. TypicalISTStop //disconnect event from logical ID InterruptDisable(g_KeypadISTData.sysIntr); // set abort flag to true to let thread know // that it should exit g_KeypadISTData.abort =TRUE; // manually set the event to break thread // out of wait call SetEvent(g_KeypadISTData.hEvent); //wait for thread to exit WaitForSingleObject(g_KeypadISTData.hEvent,INFINITE); CloseHandle(g_KeypadISTData.hEvent); CloseHandle(g_KeypadISTData.hThread);

30. Stream Device Drivers • Overview of Stream Interface Device Drivers • Device Manager • Programming Model • Loading Mechanism • Entry Points • Programming Considerations • Audio Device Drivers • File System Drivers

31. Overview of Stream Interface Device Drivers • Designed to support installable devices • Common interface for all device drivers • Expose device services through Win32 File I/O API functions • Loaded, controlled, and unloaded by the Device Manager • Can also be loaded directly by an application • Often uses services from underlying native drivers • Modem driver using the native serial driver

32. Device Manager The goal of a user-level process is to: • Load device drivers either at startup or on connection notifications • Register special file names in the system • Locate device drivers by obtaining PnP ID or by executing detection routines • Track device drivers by reading and writing registry values • Unload device drivers

33. Device Manager (continued) • Device file name • All operations on device files are redirected to their respective drivers • Device file name format is XXXY: where • XXX is the prefix and consists of three letters in uppercase • Y is the index and allows several devices to be handled by the same driver • The names of the stream interface functions always begin with the device file name as a prefix

34. User application Stream interface driver File system code Device manager Native device driver Kernel Windows CE-based platform Peripheral device Programming Model

35. Loading Mechanism • Load Drivers Listed in HKLM\Drivers\BuiltIn • Required values : Dll, Prefix • Useful values : Index, Order • Load PCMCIA drivers when detected • HKLM\Drivers\PCMCIA\Plug and Play ID • HKLM\Drivers\PCMCIA\Detect • HKLM\Drivers\PCMCIA\Driver

36. Loading Mechanism (continued) • Application can load a driver dynamically by calling the RegisterDevice function • For each loaded device driver, the Device Manager creates a key under HKLM\Drivers\Active • Argument passed to the initialization function • Hnd : the device handle • Name : the device file name • Key : the registry path to the device key under HKLM

37. Entry Points • XXX_Init • Called when Device Manager loads the driver • Initializes resources that are to be used: memory mapping, etc. • XXX_Deinit • Called when Device Manager unloads the driver • Frees allocated resources, stops the IST

38. Entry Points (continued) • XXX_Open • Invoked when applications call CreateFile(XXX, …) • Returns a context handle that will be used in subsequent calls to XXX_Read, XXX_Write, XXX_Seek, XXX_IOControl, and XXX_Close • XXX_Close • Invoked when applications call CloseHandle function

39. Entry Points (continued) • XXX_Read • Invoked when application calls ReadFile function • XXX_Write • Invoked when application calls WriteFile function • XXX_Seek • Allows moving the current I/O pointer

40. Entry Points (continued) • XXX_IOControl • Allows performing custom operations that do not necessarily apply to files • I/O control code identifies the operation • I/O control code is device-specific • XXX_PowerXXXX • PowerUp and PowerDown notifications • Should complete execution as quickly as possible

41. Programming Considerations • Single or multiple access to a device • Multiple: XXX_Open always returns a unique context handle • Single: XXX_Open returns one context handle on the first call and NULL for subsequent calls • For unusual operations on files, use the XXX_IOControl function • Read-only or write-only device

42. Audio Device Drivers • Sample PCM Waveform Audio Driver • WAV prefix • Relies mostly on XXX_IOControl • You can use wavemdd.lib to build your own wavepdd.lib and link the two together to form the wavedev.dll • Audio Compression Manager driver • ACM prefix • Codec, Converter, Filter • You can refer to Windows NT ACM documentation

43. File System Drivers • Designed for drivers that allow data to be read or written in blocks of fixed size • Block device functionality • Extend the size of the Object Store • Store code and data • Interoperability between operating systems • Registry storage • Database storage

44. File System Drivers (continued) • ATA flash memory • Emulates the behavior of an ATA-style hard drive with a chip • Linear memory flash • Uses a software layer called flash translation layer (FTL) to emulate a disk drive • Block device prefix is DSK • All I/O are handled by the DSK_IOControl function with the same I/O control codes as the ones used by the FAT file system driver

45. Lab A: Developing a Stream Interface Device Driver

46. Display Driver Architecture • Windows CE Graphic Pipeline • GPE Driver Pipeline • Key Display Driver Source Files

47. Windows CE Graphic Pipeline Windows CE Graphic Pipeline DRAWPROG.EXE GWES.EXE DDI.DLL COREDLL.DLL HARDWARE

48. GPE Driver Architecture GWES.EXE DDI.DLL DrvEnableDriver GPE.LIB DrvEnableDriver Hardware Acceleration EMUL.LIB HARDWARE – DIB-Compatible Video Buffer

49. Key Display Driver Source Files • In ..\public\common\oak\inc: • WINDDI.H – Driver interface definitions • EMUL.H – Drawing helpers for raster drawing • GPE.H – Basic set of data structures & defines • GPE Source Files • In ..\private\winceos\ coreos\gwe\mgdi\gpe

50. Primer on GDI Programming • Families of Drawing Functions • Drawing Coordinates • GDI Drawing Functions • Drawing Text • Drawing Raster Data • Drawing Vector Objects • Window Drawing: WM_PAINT • MINGDI Display Drawing