Module 6: Device Driver Architecture

Transcription

1 Module 6: Device Driver Architecture Contents Overview 1 Built-In Vs. Installable Drivers 2 Device Manager 23 Device Manager (continued) 24 ActivateDeviceEx 25 Registry Enumerator 27 Services 32 Bus Drivers 42 DMA 46 Resource Manager 51 Interrupt Model 54 Device Driver Power Management 70 CETK 79 Lab 6: Implementing a Stream Interface Driver 82 Review 83

2 Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, address, logo, person, places or events is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property Microsoft Corporation. All rights reserved. Microsoft, MS-DOS, Windows, Windows NT, Visual Studio are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries. The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

3 Module 6: Device Driver Architecture iii Instructor Notes Presentation: 120 Minutes Lab: 60 Minutes This module provides students with an overview of what drivers are in Windows CE.NET and how to provide system resources for them. After completing this module, students will be able to: Explain the differences between built-in and installable drivers. Identify the role of Device Manager in Windows CE.NET. Describe the ActivateDeviceEx function. Describe Registry Enumerator. Describe the Services.exe module. Explain Bus drivers. Identify direct memory access (DMA) in Windows CE.NET. Identify the role of Resource Manager in Windows CE.NET. Describe the interrupt model. Explain power management. Describe CE Test Kit (CETK). Materials and Preparation This section provides the materials and preparation tasks that you need to teach this module. Required Materials To teach this module, you need the following materials: Microsoft PowerPoint file 2535a_06.ppt Preparation Tasks To prepare for this module: Read all of the materials for this module including instructor notes. Complete the lab. Review the demonstration of the CETK. Review all relevant Platform Builder help files.

4 iv Module 6: Device Driver Architecture Demonstration This section provides demonstration procedures that will not fit in the margin notes or are not appropriate for the student notes. Run the CETK 1. Run the CETK. 2. Run the User Defined Test Wizard. 3. Run a test. 4. Show the logging Engine.

5 Module 6: Device Driver Architecture v Module Strategy Use the following strategy to present this module: Built-in Vs Installable Drivers There are two distinct driver models in Windows CE.NET. This topic is used to acquaint the students with these models. Device Manager Show the students the process space which controls all streams drivers. Also, demonstrate the registry keys and the process device uses to load drivers. ActivateDeviceEx Show the students the main function used to load drivers in the Device process space. Registry Enumerator Introduce a new device driver model element. The Registry Enumerator loads all bus drivers and handles the enumeration of the ISA bus itself. Services Another new component to Windows CE.NET is the service module and its manager. This module is used to offload tasks from the Device manager. Bus Drivers Explain how to attach to busses in CE. Explain how these drivers are used to load other device drivers related to its specific bus. DMA Discuss the methods used in Windows CE.NET to implement DMA from device drivers. Resource Manager Introduce a new component of Windows CE.NET which handles the assigning of resources on a system from a predefined set of resources listed in the registry. Interrupt Model Describe how the interrupt model works in Windows CE.NET. This process is more indirect then in other operating systems and requires some detail to explain. Device Driver Power Management Summarize how to use the new calls and IOCTLs in Windows CE.NET from the perspective of a driver. CETK The CETK is provided with a Platform Builder installation. This topic discusses how to utilize this tool to test the device drivers of a platform.

6 Module 6: Device Driver Architecture 1 Overview To provide an overview of the module topics and objectives. In this module, you will learn about device driver architecture. Built-In Vs. Installable Drivers Device Manager ActivateDeviceEx Registry Enumerator Services Bus Drivers DMA Resource Manager Interrupt Model Device Driver Power Management CETK In this module, you will learn about device driver architecture. After completing this module, you will be able to understand the following: Explain the differences between built-in and installable drivers. Identify the role of Device Manager in Windows CE.NET. Describe the ActivateDeviceEx function. Describe Registry Enumerator. Describe the Services.exe module. Explain Bus drivers. Identify direct memory access (DMA) in Windows CE.NET. Identify the role of Resource Manager in Windows CE.NET. Describe the interrupt model. Explain power management. Describe CE Test Kit (CETK).

7 2 Module 6: Device Driver Architecture Built-In Vs. Installable Drivers To explain the differences between built-in and installable drivers. In this section, you will learn about the built-in and installable drivers. Built-in Drivers Also referred to as native device drivers Loaded in the GWES process space at system boot Generally for devices that are hardwired or must be loaded at system boot up Uses a custom interface Installable Drivers Also referred to as streams device drivers Dynamically loaded by the Device Manager either at boot or on insertion notification Exist as standalone DLLs Uses the streams interface driver architecture Hybrid Drivers Expose both a custom-purpose interface and a stream interface Windows CE device drivers are either user mode dynamic-link libraries (DLLs), or are statically linked to the operating system as object files. Built-In Drivers Built-in drivers are also refereed to as native device drivers. Some examples of the built-in drivers are the battery driver and the notification LED driver. These drivers are statically linked to GWES, so that means that they do not exist as a standalone DLL. The notification led driver is linked via the nleddrv.lib and the battery driver is linked via the battery.lib. Other examples of Native Drivers are Display and keyboard. These are stand alone DLLs that are loaded in the GWES process space and have a custom interface exposed to the operating system. Installable Drivers Installable drivers are also refereed to as streams device drivers. Installable drivers are user mode DLLs that are loaded dynamically by the Device Manger, device.exe. Installable drivers use the streams interface driver architecture to get commands from the Device Manager and from applications by means of file system calls. Examples of installable device drivers are: PCMCIA driver (PCMCIA.DLL) Serial driver (SERIAL.DLL) ATAFLASH driver (ATA.DLL) Ethernet driver (NE2000.DLL, SMSC100FD.DLL)

8 Module 6: Device Driver Architecture 3 Hybrid Drivers While most of the sample drivers included in the Windows CE Platform Builder are clearly either native device drivers or stream interface drivers, some are hybrid in the sense that they expose both a custom-purpose interface and a stream interface to the rest of the system. Hybrid device drivers are ones that primarily need to expose a custom-purpose interface, but also need to interact with specific parts of the operating system in ways that are only allowed for stream interface drivers. For example, the PC card socket has both native and streams interfaces.

9 4 Module 6: Device Driver Architecture Monolithic Vs. Layered Device Drivers To describe two types of drivers. In this section, you will learn about the system architecture for native device drivers. DDI functions Layered Device Driver MDD DDSI functions PDD GWES DDI functions Monolithic Device Driver Hardware There are two types of sample device drivers provided in Platform Builder: Layered Device Driver Monolithic Device Driver Layered Device Driver The Layered device drivers split the code into an upper layer called the Model Device Driver (MDD) and a lower layer called the Platform Dependent Driver (PDD). The MDD layer contains code that is common to all drivers of a given type. The PDD layer consists of the code that is specific to a given hardware device or platform. The MDD calls specific PDD routines to access the hardware or hardware specific information. When using a layered driver, you can reuse the common MDD code provided by Microsoft, and only write new PDD code that is specific to the your hardware. Or, if porting one of the sample drivers to a new hardware, you only need to port the PDD layer, and the MDD layer can be used directly from the sample driver. The layered driver style is not required and may not be appropriate for all drivers. In particular, splitting device driver code into two layers imposes additional function call overhead in the operation of device driver. For performance critical situations, a monolithic driver may be more appropriate. In general, Microsoft provides the MDD for a layered driver. The MDD is common to all platforms and functions, both as source code and as a library. It performs the following tasks: Links to the PDD layer and defines the DDSI functions it expects to call in that layer Exposes DDI functions to the operating system Handles complex tasks such as interrupt processing

10 Module 6: Device Driver Architecture 5 Each MDD handles a specific set of devices, such as audio hardware or touch screens. The device driver interface (DDI) is a set of functions exposed by an MDD layer or monolithic driver and called by other OS modules. The device driver service provider interface (DDSI) is a set of functions exposed by the PDD layer of a layered device driver and called by the MDD. Classes of related device drivers can share the same DDI. In general, the MDD requires no changes. If you choose to modify the MDD, be aware that Microsoft does not test, warrant, or support custom MDDs. You are responsible for all further MDD maintenance if Microsoft supplies an updated MDD in order to fix bugs or to support later versions of Windows CE. Unlike the MDD layer, the PDD layer must be written specifically to your target platform. The PDD generally consists of functions that perform specific discrete tasks. These functions serve to isolate the MDD from the specifics of the hardware. Because the PDD is hardware-dependent, you must create a customized PDD for your platform hardware, or port one of Microsoft's sample PDD layers to your hardware. To assist you, Microsoft provides several sample PDD layers for various built-in devices. The sample code for the Wavedev drivers is a good example of the layered, streams-interface driver provided by Microsoft. The sample driver is located in %WINCEROOT%\public\common\oak\drivers\WAVEDEV. This code is provided as a convenience and does not imply any restrictions in the way that audio hardware for Windows CE must function. An audio driver could be implemented that is monolithic, is polled, and that drives a peripheral device, if a user wants to do so. The sample audio driver MDD layer implements a single audio device capable of playing and/or recording pulse code modulation (PCM) waveform audio. The sample supports simultaneous recording and playing but may also be used with audio devices that can perform only one of those functions at a time. The PDD layer is responsible for communicating with the audio hardware to start and stop playing and recording and to initialize and deinitialize the hardware. Monolithic Device Driver You can forego the MDD and PDD layers by implementing your device driver as a monolithic driver. Source code for a monolithic driver consists of both interrupt service thread code and platform specific code. For example, if performance is a critical factor, a monolithic driver might be a better choice than a layered driver because a monolithic driver avoids the overhead associated with the function calls that take place between the MDD and PDD layers. You might also choose to implement a monolithic driver if the capabilities of the device in question are well matched to the tasks that the functions in the MDD layer perform. In such a case, implementing a monolithic driver might be simpler and more efficient than implementing a layered driver. However, regardless of whether you implement a monolithic driver or a layered driver, you can base your implementation on the source code for any of the sample drivers. Note The provided MDD sources are simplistic and should be treated as driver templates. You are encouraged to modify these sources to fit their needs.

11 6 Module 6: Device Driver Architecture Native Device Drivers To describe native drivers. In this section, you will learn about native drivers. Used for built-in devices Custom interfaces but a standard set of functionality Statically linked to an executable, while other are DLLs Sample native device exist for: Display, Battery, Keyboard, Touch, LED Some types of devices such as keyboards and displays have a custom interface to the operating system. The drivers for these types of devices are called native device drivers because the interfaces they use are specific to Windows CE. In general, native device drivers are of interest only to original equipment manufacturers (OEMs) who build Windows CE based platforms. Independent hardware vendors (IHVs) who develop drivers for add-on hardware have no need to design or customize native device drivers. Therefore, the following sections regarding native device drivers are directed primarily to OEMs. Microsoft defines custom interfaces for each type of native device driver. However, although each type of native device driver has a custom interface, native device drivers present a standard set of functionality for all devices of a particular class. This enables the Windows CE operating system to treat all instances of a particular device class alike, despite any physical differences. For example, many Windows CE based platforms use some type of LCD panel as a display. However, there is a wide variety of these panels on the market that have different operating characteristics, such as resolution, bit depth, memory interleaving, and so on. By making all display drivers conform to the same interface, Windows CE can treat all display devices the same, regardless of the physical differences between the devices themselves. Microsoft Windows CE Platform Builder provides sample native device drivers: Display Battery Keyboard Touch screen Notification LED

12 Module 6: Device Driver Architecture 7 If your target platform contains devices not listed above, you need to create your own native device drivers for the devices. However, if your platform includes devices from the list, consider porting the sample native device drivers to your platform, rather than developing your own native device drivers. By porting the tested device drivers, you can save time and avoid bugs. Even so, it is not mandatory to use the sample code provided with the Platform Builder for the native device driver or for any other driver model. The Platform Builder supplies driver samples solely as a convenience to help you develop your drivers rapidly.

13 8 Module 6: Device Driver Architecture Streams Drivers To describe stream drivers. In this section, you will learn about stream drivers. What is a Stream Driver? Common interface and functions to all Streams drivers Ideal for I/O devices that are a data source or data sink Interface functions similar to file system APIs such as ReadFile, IOControl Streams drivers are used to access, from the application level, the physical peripheral device as if it was a file. A stream interface driver is any driver that exposes the stream interface functions, regardless of the type of device controlled by the driver. The stream interface drivers all use the same interface and expose a common set of functions the stream interface functions. This is in contrast to native device drivers, which each use special, single-purpose interfaces. The stream interface is appropriate for any I/O device that can be thought of logically as a data source or a data sink. That is, any peripheral that produces or consumes streams of data as its primary function is a good candidate to expose the stream interface. An example is a serial port device. An example of a device that does not produce or consume data in the traditional sense would be a display device, and indeed, the stream interface is not exposed for controlling display hardware The stream interface functions themselves are designed to closely match the semantics of the normal file system APIs such as ReadFile, IOControl. As a side effect of this design, devices that are managed by stream interface drivers are exposed to applications through the file system; applications interact with the driver by opening special files in the file system. This metaphor of treating devices as special files is common to many operating systems, including the desktop versions of Microsoft Windows and most Unixlike operating systems as well. For example, in the desktop versions of Microsoft Windows, printer devices have traditionally been represented by the LPTx: special file names, serial ports by the COMx: special file names, etc. Note In very general terms, a Streams interface driver is a mechanism of turning a piece of hardware into a file.

14 Module 6: Device Driver Architecture 9 Streams Drivers Architecture To describe stream drivers. In this section, you will learn about stream drivers. The diagram on the slide illustrates the architecture of stream interface drivers for built-in devices that are loaded by the Device Manager at boot time. As you can see, applications communicate with the hardware via the stream interface driver and device manager using the file system APIs. A stream interface driver receives commands from the Device Manager and from applications by means of file system calls. The driver encapsulates all of the information that is necessary to translate those commands into appropriate actions on the devices that it controls. All stream interface drivers, whether they manage built-in devices or installable devices; or whether they are loaded at boot time or loaded dynamically, have similar interactions with other system components.

15 10 Module 6: Device Driver Architecture Implementing Streams Drivers To describe the steps to create a basic Stream Interface Driver. In this section, you will learn how to create a basic Stream Interface Driver. How do you implement a Stream Driver? Select a device file name prefix Implement the required entry points Create the *.DEF file Create the registry values for your driver To illustrate implementing streams drivers, let us use an example from platform builder. For the following instructions, you will be referring to WINCE400\PLATFORM\SA11X0BD\DRIVERS\PWRBUTTON directory as the example. This driver is a power button driver for the SA110XBD platform. The basic steps on how to create a stream driver: 1. The first step in creating a streams driver is figuring what prefix name to call it. The prefix name refers to the XXX in the entry-point names. For example, if your device file name prefix is PWR, you will implement PWR_Close, PWR_Init, and so on. 2. Next, you will need to implement the required entry points. These entry points are the standard file I/O functions that are used by the kernel. The entry points are summarized below: Function Description XXX_Close XXX_Deinit XXX_Init XXX_IOControl XXX_Open XXX_PowerDown XXX_PowerUp Closes the device context identified by hopencontext. Called by the Device Manager to deinitialize a device. Called by the Device Manager to initialize a device. Sends a command to a device. Opens a device for reading, writing, or both. An application indirectly invokes this function when it calls CreateFile to open special device file names. Ends power to the device. It is useful only with devices that can be shut off under software control. Restores power to a device.

16 Module 6: Device Driver Architecture 11 XXX_Read XXX_Seek XXX_Write Reads data from the device identified by the open context. Moves the data pointer in the device. Writes data to the device. In WINCE400\PLATFORM\SA11X0BD\DRIVERS\PWRBUTTON\pwrbutto npdd.c, you can see actual code examples of the above entry points. 3. Next, you will need to create the *.DEF file. For our example, the *.DEF file is named PWRBUTTON.DEF. This is the definition file that is passed to the linker. This file contains the exported function names. Note You need to name the *.DLL and the *.DEF the same names. Note You should use a C declspec here as well. Here is an example copy of the PWRBUTTON.DEF file: ; ; Copyright (c) Microsoft Corporation. All rights reserved. ; /* Copyright 1999 Intel Corp. */ LIBRARY PWRBUTTON EXPORTS PWR_Init PWR_Deinit PWR_Open PWR_Close PWR_Read PWR_Write PWR_Seek PWR_IOControl PWR_PowerDown PWR_PowerUp PWR_PowerHandler PWR_DllEntry 4. Next, you will need to create the registry entries for this driver so that the driver can be loaded by Device.exe. Here is an example of the registry needed for the power button driver. [HKEY_LOCAL_MACHINE\Drivers\BuiltIn\PWRBUTTON] "Prefix"="PWR" "Dll"="PwrButton.Dll" "Order"=dword:2 "Ioctl"=dword:4 In addition, you can store any driver specific information in the registry that can be used later by the driver. The Dll entry is what device.exe looks for when loading the driver. Note the Prefix setting. In this case, the prefix is PWR. This PWR corresponds to the same 3 letter in each entry point. Also, the registry key named IOCTL is check by device.exe and if present

17 12 Module 6: Device Driver Architecture device.exe calls PWR_IOControl with the dwcode parameter set. That value in this case is 4. The ORDER is the load order of this driver.

18 Module 6: Device Driver Architecture 13 Streams Entry Points: Open and Close To describe the stream interface driver required entry points. In this section, you will learn about stream interface driver required entry points. XXX_Open -Opens a device for reading and/or writing. -An application indirectly invokes this function when it calls CreateFile to open special device file names. -When this function is called, your device should allocate the resources that it needs for each open context and prepare for operation XXX_Close -In response to CloseHandle, the operating system invokes this function. Here are details on each required stream driver entry point function. Syntax XXX_Open DWORD XXX_Open( DWORD hdevicecontext, DWORD AccessCode, DWORD ShareMode ); Parameters hdevicecontext Handle to the device context. The XXX_Init function creates and returns this handle. AccessCode Specifies the requested access code of the device. The access is a combination of read and write. ShareMode Specifies the requested file share mode of the PC Card device. The share mode is a combination of file read and write sharing. This function opens a device for reading and/or writing. An application indirectly invokes this function when it calls CreateFile to open special device file names. When this function is called, your device should allocate the resources that it needs for each open context and prepare for operation. This might involve preparing the device for reading or writing and initializing data structures it uses for operation. Note A device context is a graphics device interface (GDI) structure containing information that governs the display of text and graphics on a particular output device. A device context stores, retrieves, and modifies the attributes of graphic objects and specifies graphic modes. The graphic objects stored in a device context include a pen for line drawing, a brush for painting

19 14 Module 6: Device Driver Architecture and filling, a font for text output, a bitmap for copying or scrolling, a palette for defining the available colors, and a region for clipping. Syntax XXX_Close BOOL XXX_Close( DWORD hopencontext ); Parameters hopencontext Handle returned by the XXX_Open function, used to identify the open context of the device. An application calls CloseHandle to stop using a stream interface driver. The hfile parameter specifies the handle associated with the device context. In response to CloseHandle, the operating system invokes this function. The file handle specified for hopencontext is no longer valid after this function returns; if an application tries to perform stream I/O operations on that handle after calling CloseHandle, those operations fail.

20 Module 6: Device Driver Architecture 15 Streams Entry Points: Init and Deinit To describe the stream interface driver required entry points. In this section, you will learn about stream interface driver required entry points. XXX_Init Called when Device Manager loads the driver Initializes resources that are to be used Memory mapping XXX_Deinit Called when Device Manager unloads the driver Frees allocated resources, stops the IST Here are details on each required stream driver entry point function. Syntax XXX_Init DWORD XXX_Init( DWORD dwcontext ); Parameters dwcontext Specifies a pointer to a string containing the registry path to the active key for the stream interface driver The Device Manager calls this function as a result of a call to the ActivateDeviceEx function. When the user starts using a device, such as when a PC Card is inserted, the Device Manager calls this function to initialize the device. This function is not called by applications. Stream interface drivers that support multiple instances of the same type of special device file name, such as sample serial port driver of Microsoft, which supports multiple COMx: device filenames should expect their XXX_Init function to be called once for each instance. For such drivers, this function should return separate handles each time it is called. Stream interface drivers that only support a single special device file name then this function can return any non-zero value After this function returns, the Device Manager checks the registry for a key named Ioctl for the driver, and if such a key is present, the Device Manager calls XXX_IOControl, passing the value specified by Ioctl as the dwcode parameter. Your driver can use this function to finish initializing itself after it has been installed. Syntax XXX_Deinit BOOL XXX_Deinit( DWORD hdevicecontext ); Parameters hdevicecontext

21 16 Module 6: Device Driver Architecture Handle to the device context. The XXX_Init function creates and returns this identifier. The Device Manager calls the XXX_Deinit function of a driver as a result of a call to the DeactivateDevice function. Your stream interface driver should free any resources it has allocated and terminate.

22 Module 6: Device Driver Architecture 17 Streams Entry Points: Read, Write and Seek To describe the stream interface driver required entry points. In this section, you will learn about stream interface driver required entry points. 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 Here are details on each required stream driver entry point function. Syntax XXX_Read DWORD XXX_Read( DWORD hopencontext, LPVOID pbuffer, DWORD Count ); Parameters hopencontext Handle to the open context of the device. The XXX_Open function creates and returns this identifier. pbuffer Pointer to the buffer that stores the data read from the device. This buffer should be at least Count bytes long. Count Specifies the number of bytes to read from the device into pbuffer This function reads data from the device identified by the open context. An application calls the ReadFile function to read from the device. The operating system, in turn, invokes this function. The hfile parameter is a handle to your device. The pdata parameter points to the buffer that contains the data read from the device. The Size parameter indicates the number of bytes that the application wants to read from the device. The psizeread parameter is a pointer to a value where this function can store the number of bytes actually read from the device. The value returned from this function is equal to the value contained in psizeread, unless this function returns 1 for an error. If this function returns an error, psizeread contains 0. Syntax XXX_Write

23 18 Module 6: Device Driver Architecture DWORD XXX_Write( DWORD hopencontext, LPCVOID pbuffer, DWORD Count ); Parameters hopencontext Handle to the open context of the device. The call to the XXX_Open function returns this identifier. pbuffer Pointer to the buffer that contains the data to write Count Specifies the number of bytes to write from the psourcebytes buffer into the device This function writes data to the device. An application uses the WriteFile function to write to the device. The operating system, in turn, invokes this function. Syntax XXX_Seek DWORD XXX_Seek( DWORD hopencontext, long Amount, WORD Type ); Parameters hopencontext Handle to the open context of the device. The XXX_Open function creates and returns this identifier. Amount Specifies the number of bytes to move the data pointer in the device. A positive value moves the data pointer toward the end of the file, and a negative value moves it toward the beginning. Type Specifies the starting point for the data pointer: An application calls the SetFilePointer function to move the data pointer in the device. The operating system, in turn, invokes this function. If your device is capable of being opened multiple times, this function modifies only the data pointer for the instance specified by hopencontext.

24 Module 6: Device Driver Architecture 19 Streams Entry Points: IOControl To introduce the last of the streams entry points Streams drivers have an IOControl function to handle miscellaneous requests. 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 Streams drivers have an IOControl function to handle miscellaneous requests: Syntax XXX_IOControl BOOL XXX_IOControl( DWORD hopencontext, DWORD dwcode, PBYTE pbufin, DWORD dwlenin, PBYTE pbufout, DWORD dwlenout, PDWORD pdwactualout ); Parameters hopencontext Handle to the open context of the device. The XXX_Open function creates and returns this identifier. dwcode Specifies a value indicating the I/O control operation to perform. These codes are device-specific and are usually exposed to programmers by means of a header file. pbufin Pointer to the buffer containing data to be transferred to the device dwlenin Specifies the number of bytes of data in the buffer specified for pbufin pbufout Pointer to the buffer used to transfer the output data from the device dwlenout Specifies the maximum number of bytes in the buffer specified by pbufout pdwactualout Pointer to the DWORD buffer that this function uses to return the actual number of bytes received from the device

25 20 Module 6: Device Driver Architecture This function sends a command to a device. An application uses the DeviceIOControl function to specify an operation to be performed. The operating system, in turn, invokes this XXX_IOControl. The dwcode parameter contains the input or output operation to be performed; these codes are usually specific to each device driver and are exposed to application programmers by means of a header file that the device driver programmer makes available. If the HKEY_LOCAL_MACHINE\Drivers\BuiltIn\YourDevice\Ioctl registry key is defined for your device driver, the Device Manager will invoke your device driver's XXX_IOControl function when it loads and initializes your device driver. It uses the Ioctl registry value for the dwcode parameter and NULL for the pbufin and pbufout parameters. Your device might use this option to load other modules that require the installation of the basic device driver, or as a trigger to perform any other actions that are not suited to being part of your device driver's XXX_Init function. The actual sequence of calls made to a device driver in this scenario is XXX_Init, XXX_Open, XXX_IOControl, and XXX_Close. The XXX_Open call is necessary for the Device Manager to get a valid context handle, and XXX_Close is necessary to leave the device driver available to serve applications.

26 Module 6: Device Driver Architecture 21 Streams Entry Points: PowerUp and PowerDown To describe the stream interface driver required entry points. In this section, you will learn about stream interface driver required entry points. XXX_PowerDown Restores power to a device XXX_PowerUp Suspends power to the device Useful only with devices that can be shut off under software control Here are details on each required entry point function: Syntax XXX_PowerDown void XXX_PowerDown( DWORD hdevicecontext ); Parameters hdevicecontext Handle to the device context. The call to the XXX_Init function returns this identifier. This function suspends power to the device. It is useful only with devices that can be shut off under software control. Such devices are typically, but not exclusively, PC Card devices. This function is required by the stream driver interface and is called in the power path of the kernel. IOCTL_POWER_XXX is separate and is not called in the power path of the kernel. The operating system invokes this function to suspend power to the device. The operating system might call this function when it is about to enter the powersave mode. This function should not call any functions that might cause it to block, and it should return as quickly as possible. One strategy for returning quickly is to have this function set a global variable to indicate that a power loss occurred and to defer any complicated processing until later, when the driver's XXX_PowerUp function is called. Syntax XXX_PowerUp void XXX_PowerUp( DWORD hdevicecontext ); Parameters hdevicecontext

27 22 Module 6: Device Driver Architecture Handle to the device context. The call to the XXX_Init function returns this identifier. This function restores power to a device. This function is required by the stream driver interface and is called in the power path of the kernel. IOCTL_POWER_XXX is separate and is not called in the power path of the kernel. The operating system invokes this function to restore power to a device. The operating system might call this function as it is leaving its power-save mode. This function should not call any functions that may cause it to block, and it should return as quickly as possible. This function should set a global variable to indicate that power was restored and perform any necessary processing later.

28 Module 6: Device Driver Architecture 23 Device Manager To describe device manager. In this section, you will learn about the Device Manager. Device Manager implemented as Device.exe User-level process that runs continously Not part of the Kernel but launch via Kernel HKEY_LOCAL_MACHINE\Init] "Launch20"= Device.exe" Separate application that interacts with the kernel, the registry and stream interface driver DLLs Provides ActivateDeviceEx and DeactivateDeviceEx APIs The Device Manager is the user-level process that is launched by the kernel early in the boot process. It is implemented as Device.exe. Device Manager performs the following tasks: Detects that a user has attached a peripheral to the Windows CE based platform, and attempts to load a device driver for the peripheral. For example, when a user inserts a PC Card, the Device Manager attempts to locate and load a device driver for that PC Card. Registers special file names with the kernel that map the stream I/O functions that are used by applications to the implementations of those functions within a stream interface driver. Finds the appropriate device driver for a peripheral by obtaining a Plug and Play identifier from the peripheral device or by invoking a detection routine to find a driver that can handle the device. Loads and tracks drivers by reading and writing registry values. Unloads drivers when their devices are no longer needed. For example, the Device Manager unloads a PC Card device driver when a user removes the card. Tracks the following boot phases.

29 24 Module 6: Device Driver Architecture Device Manager (continued) To describe the device driver loading process. In this section, you will learn about the device driver loading process. Device Driver Loading Process Kernel loads DEVICE.EXE (I/O Resource Manager) loads REGENUM.DLL loads Registry enumerator is re-entrant REGENUM.DLL (for ISA busses) PCIBUS.DLL The device driver loading process involves: At OEMInit time in the OAL, debugging services such as Ethernet debugging, serial debugging, or both, need to be started. The OAL may need to configure and enumerate a bus, such as the PCI bus, to the extent needed in order to operate a device used for debugging services The OAL is responsible for putting this resource information in a registry key and making it accessible to the driver Then, Device.exe is loaded and started. It loads the Resource Manager to read a list of available resources from the registry. Device.exe loads the registry enumerator from HKEY_LOCAL_MACHINE\Drivers\RootKey. The registry enumerator starts the process of scanning the registry for more buses and devices to be loaded for sub-keys of the root key. The Registry Enumerator is used in place of an ISA bus driver. The OEM or user may use an ISA PnP bus driver is desired. All ISA resources must be allocated through the registry. RegEnum.dll can be used again to enumerate the registry for ISA devices. One of the Drivers subkeys may be PCI. Normally, the DLL listed under the PCI key is the PCI bus driver (PCIBUS.DLL), which is loaded by the registry enumerator. Registry entries for the PCI bus driver include resources available to the PCI bus. The HKEY_LOCAL_MACHINE\Drivers\RootKey\Order value is set so that the PCI bus driver is usually loaded last. This is so all of the fixed resources are allocated before the flexible resources of the PCI devices are configured. Driver registry entries are listed under the PCI key, which represent devices that reside on the PCI bus.

30 Module 6: Device Driver Architecture 25 ActivateDeviceEx To describe the ActivateDeviceEx function. In this section, you will learn about the ActivateDeviceEx function. What is ActivateDeviceEx? A function used by Device.exe to load a device driver A function used by the Registry Enumerator on each subkey it finds (to load driver) ActivateDeviceEx uses the Dll, Prefix, Index and Flags fields of registry. Use ActivateDeviceEx to load drivers. You can useactivatedevice, but it simply calls ActivateDeviceEx. The ActivateDeviceEx function is used to load a device driver. It reads the registry key specified in its lpszdevkey parameter (which is the first parameter) to get the DLL name, device prefix, index, and other values. Note This function replaces ActivateDevice and RegisterDevice. For example here is a sample registry entry: [HKEY_LOCAL_MACHINE\Drivers\BuiltIn\PM] "Prefix"="PWR" "Dll"="pm.dll" "Order"=dword:0 "Ioctl"=dword:4 "Index"=dword:0 "IClass"=multi_sz:"{A32942B7-920C-486b-B0E6-92A702A99B35}" The function in the case call would be ActivateDeviceEx( \\HKEY_LOCAL_MACHINE\\Drivers\\BuiltIn\\PM, ) The function would then read the registry and get the DLL name, pwr.dll, the device prefix PWR, the index 0, and other values. Note The Index value indicates port numbering with stream interface drivers, such as COM0: or COM1:. If there is no Index value, one will be generated. Next, it adds the device to the active device list, and stores the relevant values there. If no device index was specified in the key named in lpszdevkey, then it assigns a free index. Then, it loads the device driver DLL in the process space of the Device Manager. Here is the detailed definition of this function:

31 26 Module 6: Device Driver Architecture HANDLE ActivateDeviceEx( LPCWSTR lpszdevkey, LPCVOID lpregents, DWORD cregents, LPVOID lpvparam ); Parameters lpszdevkey A pointer to a string containing the registry path of the device driver's key. This key contains the driver's DLL name, prefix, and other data. lpregents Points to an array of REGINI structures, each of which defines a registry value to be added to the device's instance key before its driver is loaded. This value is usually set to NULL. cregents A count of the number of REGINI structures to which lpregents points. This affects a generalization of ActivateDevice. lpvparam An opaque pointer to a driver-specific data structure. It can be used to pass parameters to the loaded driver without having to write them through the registry. lpvparam will be passed to the XXX_Init function as the second parameter.

32 Module 6: Device Driver Architecture 27 Registry Enumerator To describe Registry enumerator. In this section, you will learn about Registry enumerator. What is a Registry Enumerator? Loaded by Device Manager (Device.exe) Finds new devices by reading registry entries Re-entrant Implemented as REGENUM.DLL Code located at WINCE400\public\common\oak\DRIVERS\REGENUM The Registry enumerator is part of the new device driver loading model. It is loaded early on by device.exe during the driver loading process. It finds new devices by reading entries from the registry. It is re-entrant, can be called again while a previous invocation is still active, and supports hierarchical usage so it can load itself over a different registry key. When it gets unloaded, it unloads anything it directly loaded. It is implemented as REGENUM.DLL. The code is located at WINCE400\public\common\oak\DRIVERS\REGENUM

33 28 Module 6: Device Driver Architecture Registry Enumerator (continued) To describe how Registry enumerator works. Let s look at how Registry enumerator works. How does the Registry Enumerator work? Device.exe loads Registry Enumerator checking HKLM\Drivers\RootKey Init function is called with the HKLM\Drivers\RootKey key Registry Enumerator examines key below HKLM\Drivers\RootKey based on Order value Registry Enumerator traverses subkeys of HKLM\Drivers\RootKey and initializes a driver for each entry. The Registry Enumerator works in the following manner: First in the registry you will notice the following settings. This settings overrides the default RootKey value. The RootKey value is usually defaulted to Drivers. In this case, the value is defaulted to Drivers\Builtin. [HKEY_LOCAL_MACHINE\Drivers] "RootKey"="Drivers\\BuiltIn" [HKEY_LOCAL_MACHINE\Drivers\BuiltIn] "Dll"="RegEnum.dll" 1. The Device Manager loads the Registry Enumerator by checking HKLM\Drivers\RootKey, where RootKey is set to Drivers\Builtin by default in the registry. It examines the Dll value for RegEnum.dll and invokes it. This is the root enumerator DLL. 2. The Registry Enumerator s entry point, Init, not the stream interface function, is called with the HKLM\Drivers\Builtin key. 3. The Registry Enumerator examines the first level of keys just below the key passed to it (HKLM\Drivers\Builtin) according to Order. 4. It traverses the subkeys of HKEY_LOCAL_MACHINE\Drivers\BuiltIn (or where ever the HKLM\Drivers\RootKey value points) one by one, and initializes a driver for each entry. 5. It loads the DLL indicated by the DLL value, and then creates a subkey for the driver under HKLM\Drivers\Active. Then it calls the Init function or the driver's entry point and passes in a string containing that subkey. During registry enumeration, the subkeys are defined as given in the following table:

34 Module 6: Device Driver Architecture 29 Subkey Type Description Order DWORD Smallest value gets loaded first. Dll SZCHAR Which DLL to load for registry enumerator to load via ActiveDevice. Only the Dll key is required. If there is no Order value, the driver will get loaded after drivers with defined Orders. Index DWORD Identifier when multiple instances are present, between 0 and 9, inclusively. The Index value indicates port numbering with stream interface drivers, such as COM0: or COM1:. If there is no Index value, one will be generated. Flags DWORD Modifies the default behavior of the enumerator. The Flags value is a set of bits to modify the behavior of ActivateDevice; this value is optional and is set to zero if there is no value present. Bits 3 through 23 are reserved and must be set to zero. The driver being loaded may use bits 24 through 31 of the Flags value Flags are defined as described in the following table. Flag Value Description DEVFLAGS_NONE 0x No flags defined. DEVFLAGS_UNLOAD 0x Unload driver after call to entry point returns, XXX_Init, or Init. DEVFLAGS_LOADLIBRARY 0x Use LoadLibrary instead of LoadDriver. DEVFLAGS_NOLOAD 0x Do not load DLL.

35 30 Module 6: Device Driver Architecture Registry Enumerator (continued) To describe the Registry Enumerator loading example. Let s look at the Registry Enumerator loading example. Registry Enumerator Example (Simplified) [HKLM\Drivers] "RootKey"="Drivers" [HKLM\Drivers\Virtual\NDIS] "Dll"="RegEnum.dll "Dll"="NDIS.dll" "Order"=dword:1 [HKLM\Drivers\Debug] "Prefix"="NDS "Dll"="RegEnum.dll" "Order"=dword:0 [HKLM\Drivers\PCI] "Flags"=dword:1 "Dll"="PCIbus.dll" "Order"=dword:4 [HKLM\Drivers\Debug\EDBG] "Flags"=dword:1 "Flags"=dword:4 [HKLM\Drivers\Virtual] "Dll"="RegEnum.dll" "Order"=dword:1 "Flags"=dword:1 Here is a very simple example to illustrate how the registry enumerator works: 1. When Device.exe is loaded, it examines the HKEY_LOCAL_MACHINE\Drivers key for the RootKey value. It then examines the key pointed to by RootKey, in this case Drivers, for a DLL to load. In this example, it is the Registry Enumerator (RegEnum.dll). The Registry Enumerator s entry point, Init, not the stream interface function, is called with the HKEY_LOCAL_MACHINE\Drivers key. The Registry Enumerator examines the first level of keys just below the key passed to it according to Order. In this example, the Drivers\Debug key has Order of 0, so it is examined first. 2. Next, the DLL loaded for Drivers\Debug is again the Registry Enumerator; it is re-entrant. The Flags value is set to 1, meaning that RegEnum.dll is unloaded, or its reference count is decremented. Its reference count is decremented in this example. Init is called with the Drivers\Debug key. It examines the immediate subkeys for ordering information. In this example, Drivers\Debug\EDBG has the lowest and only Order key. The Flags value for Drivers\Debug\EDBG is 0x0004, which indicates that the DLL is not loaded because the Ethernet debugging adapter driver has already been loaded by the OAL. 3. The next key under the Drivers key is Drivers\Virtual with Order equal to 1. The Registry Enumerator is activated through a call to its Init function with the parameter Drivers\Virtual. Init examines the immediate subkeys for ordering information. In this example, Drivers\Virtual\NDIS has the lowest and only Order key. The Dll value is examined and NDIS.dll is loaded. The entry point, NDS_Init, is called with driver s Active key due the properties of the stream interface, which contains a Key value equal to Drivers\Virtual\NDIS. There are no more keys under Drivers\Virtual, so the Registry Enumerator's Init function returns.

36 Module 6: Device Driver Architecture The last key examined is Drivers\PCI. In this example, the Drivers\PCI key has Order of 4. The DLL is PCIbus.dll, a PCI bus driver and enumerator. This driver is explained more in detail later. This driver is then loaded. This driver takes care of configuring and enumerating the PCI bus, allocating resources to the devices it finds on the bus, and populating the registry with device instances.

37 32 Module 6: Device Driver Architecture Services To describe the Services.exe module. In this section, you will learn about the services.exe module. Purpose of a Service Services.exe Vs. Device.exe Activating / Controlling a Service Registering a Service Programmatically Stopping a Running Service Services.exe at System Startup Services API s In this section, you will learn about the service module. You will learn the differences between services.exe and device.exe. You will learn how to activate/control a service. You will also learn how to register a service programmatically. Then, you will learn how to stop a running service. You will learn about services.exe at system startup and services APIs.

38 Module 6: Device Driver Architecture 33 Purpose of a Service To describe the Services.exe module. In this section, you will learn about the services.exe module. Supplements existing device.exe Hosts services that do not require direct access to the system Isolates those services from the system services Enhances device stability in a service failure and decreases the likelihood of a system crash Provides a super service Services.exe is a process that supplements the existing Device.exe process in loading system services. It expands the Device.exe functionality by hosting services that do not require direct access to the system and isolating those services from the system services. In the event of a service failure, separating the services protects a system service from failing as well. This functionality allows for enhanced device stability in a service failure and decreases the likelihood of a crash of the system. A super service is an enhanced standard service designed to allow all ports to be monitored by Services.exe itself. The super service is notified when it is required to handle any network traffic. Use of a super server can be advantageous, because the accept threads for all services being handled by a super service total only 1. Without a super service, each service must create its own thread, resulting in additional system overhead. Note Services.exe is launched via the registry. [HKEY_LOCAL_MACHINE\init] "Launch60"="services.exe" "Depend60"=hex:14,00