SpbCx Device Driver Interface (DDI)
The SpbCx device driver interface (DDI) consists of methods that are implemented by the SPB framework extension module, Spbcx.sys, and event callback functions that the SPB controller driver implements. The SPB controller driver registers its callback functions with SpbCx during the initialization of the DDI.
To request services from SpbCx, the SPB controller driver calls the SpbCx driver support methods. For example, the SPB controller driver calls these methods to set driver configuration options for the SPB controller, or to obtain additional information about an I/O request.
To notify the SPB controller driver of an event (for example, the arrival of an I/O request from a client), SpbCx calls an event callback function that is implemented by the SPB controller driver.
During callbacks from SpbCx, the SPB controller driver code runs in an arbitrary thread context. After receiving an I/O request that requires processing by the SPB controller driver, SpbCx does any required preprocessing of the request before SpbCx calls an EvtSpbXxx function to perform the requested operation. For example, to make a user-mode buffer available to a callback function, SpbCx might need to run in the context of the thread that originated the I/O request. (The EvtIoInCallerContext function is the only callback function that cannot rely on SpbCx to preprocess requests.)
To register a set of EvtSpbXxx callback functions, the SPB controller driver calls the SpbDeviceInitialize method. This driver calls the SpbControllerSetIoOtherCallback method to register an EvtIoInCallerContext callback function.
The SpbCx DDI uses the WDFDEVICE object handle type to represent the device object for an SPB controller. Include the Wdf.h header file to define WDFDEVICE and the other KMDF object handle types. In addition, the DDI uses two SPB-specific object handle types, SPBREQUEST and SPBTARGET, which are similar to the WDFREQUEST and WDFTARGET object handle types that are defined by KMDF. An SPBREQUEST handle represents an I/O request. An SPBTARGET handle represents a logical connection to a peripheral device on the bus that has been opened for I/O operations.
Simple peripheral buses such as I²C and SPI are typically used by System on a Chip (SoC) modules, for which low pin counts are important. SoC modules are frequently used as processors in handheld devices that require low power consumption. Because SPB controller circuits consume relatively little power, the power management code in SpbCx can be relatively simple. By default, SpbCx ensures that power to the SPB controller is turned on before it calls any of the event callback methods in the SPB controller driver. For more information, see the description of the PowerManaged member in SPB_CONTROLLER_CONFIG.
If necessary, the SPB controller driver can explicitly turn power to the controller on and off by calling the WdfDeviceStopIdle and WdfDeviceResumeIdle methods.
Because the SPB controller driver is a kernel-mode driver, it should assign an appropriate security descriptor to its file objects. This descriptor prevents unauthorized access from user mode to the peripheral devices on the SPB. For example, the sample SPB controller drivers in the WDK use the following SDDL string, which provides a default level of security that is suitable for a typical SPB controller driver:
"D:P(A;;GA;;;SY)(A;;GA;;;BA)(A;;GA;;;UD)"
This SDDL string restricts access to the operating system (and its user-mode components), members of the Administrators group, and User-Mode Driver Framework (UMDF) drivers. For more information about SDDL strings, see SDDL for Device Objects.
In addition, the EvtSpbControllerIoOther function must validate all parameters in the custom I/O control requests that it receives from user-mode clients. For all other EvtSpbXxx functions, SpbCx validates the parameters in I/O requests from user-mode clients before these parameters are passed to the SPB controller driver. For more information about device security, see Securing Device Objects.
All methods and callback functions in the SpbCx DDI that return status codes return NTSTATUS values. The driver-support methods in this DDI follow the usual conventions for KMDF interfaces, and all objects that are used by SpbCx follow the usual conventions for KMDF objects. For more information, see Introduction to Framework Objects.