Skeleton I2C Sample Driver

  • Code Sample
Browse code

The SkeletonI2C sample demonstrates how to design a KMDF controller driver for Windows that conforms to the simple peripheral bus (SPB) device driver interface (DDI). SPB is an abstraction for low-speed serial buses (for example, I2C and SPI) that allows peripheral drivers to be developed for cross-platform use without any knowledge of the underlying bus hardware or device connections. While this sample implements an empty I2C driver, it could just as easily be the starting point for an SPI driver with only minor modifications.

Note that the SkeletonI2C sample is simplified to show the overall structure of an SPB controller, but contains only the code that the driver requires to communicate with the SPB framework extension (SpbCx) and KMDF. The SkeletonI2C sample driver omits all hardware-specific code. It does not simulate data transfers or implement request completion asynchronously. Pay close attention to code comments marked with "TODO" that refer to blocks of code that must be removed or updated.

The simplified structure of the SkeletonI2C sample driver makes it a convenient starting point for development of a real SPB controller driver that manages the hardware functions in an SPB controller.

Modifying the sample

Here are some high-level points to consider when modifying the SkeletonI2C sample for use on real hardware:

  • Edit (and likely rename) Skeletoni2c.h to describe your hardware's register set.

  • Modify Controller.cpp and Device.cpp to translate the SPB DDI and primitives into I2C or SPI protocol for your hardware. This includes initialization, I/O configuration, and interrupt processing.

  • Address any comments marked with "TODO" in the sample, especially those that short circuit the I/O path to complete requests synchronously.

  • Modify the HWID (ACPI\skeletoni2c) in Skeletoni2c.inf to match the device node in your firmware.

  • Generate and specify a unique trace GUID in I2ctrace.h.

  • Refactor the driver name, functions, comments, etc., to better describe your implementation.

Code tour

Implementing the SPB DDI

The following are relevant functions in the SkeletonI2C driver for implementing the SPB DDI.

INITIALIZATION

OnDeviceAdd

Within OnDeviceAdd, the driver makes several configuration calls for SPB.

SpbDeviceInitConfig must be called before creating the WDFDEVICE. Note that SpbCx sets a default security descriptor on the device object, but the controller driver can override it by calling WdfDeviceInitAssignSDDLString after SpbDeviceInitConfig.

After creating the WDFDEVICE, the driver configures it appropriately for SPB by calling SpbDeviceInitialize. Here the driver also sets the target and request attributes.

Finally the driver configures a WDF system-managed idle time-out.

TARGET CONNECTION

OnTargetConnect

Invoked when a client opens a handle to the specified SPB target. Queries the I2C connection parameters from the resource hub (via SPB) and initializes the target context.

SPB I/O CALLBACKS

OnRead

SPB read callback. Invokes the PbcConfigureForNonSequence function to set up the transfer.

OnWrite

SPB write callback. Invokes the PbcConfigureForNonSequence function to set up the transfer.

OnSequence

SPB sequence callback. Configures the controller for an atomic transfer*.

OnControllerLock

SPB lock controller callback. Configures to handle subsequent I/O as an atomic transfer*. For I2C the controller should place a start bit on the bus. For SPI the controller should assert the chip-select line. The driver may choose to carry this out as part of this callback or defer until the first I/O operation is received (the next call to OnRead or OnWrite).

OnControllerUnlock

SPB unlock controller callback. Marks the end of an atomic transfer*. For I2C, the controller should place a stop bit on the bus. For SPI, the controller should de-assert the chip-select line.

SPB HELPER METHODS

PbcConfigureForIndex

Configures the request context for the specified transfer index. This could be a single I/O or part of a sequence.

PbcRequestComplete

Sets the number of bytes completed for a request and invokes the SpbRequestComplete method.

*An atomic transfer in SPB is implemented using Sequence or a Lock/Unlock pair. For I2C, this means a set of reads and writes with restarts in between. For SPI, this means a set of reads and writes with the chip select-line asserted throughout.

Implementing controller-specific I2C protocol

The following are relevant functions in the SkeletonI2C driver for implementing controller-specific I2C protocol. For the most part, these are placeholders and must be filled in appropriately.

INITIALIZATION (controller-specific)

ControllerInitialize

One-time controller initialization. Prepare FIFOs, clocks, interrupts, etc.

ControllerConfigureForTransfer

Per-I/O controller configuration. Depending on the type of I/O (and whether its part of an ongoing atomic transfer), the driver may need to configure direction, set interrupts, etc.

Additionally, for I2C, the driver may need to insert a start, restart, or stop bit as necessary, and for SPI the driver may need to assert or de-assert the chip select line.

I/O PROCESSING

OnInterruptIsr

Interrupt callback. Acknowledges interrupts and saves state as necessary. Queues a DPC for processing.

OnInterruptDpc

DPC callback. Processes saved interrupts. If necessary the request is completed.

ControllerProcessInterrupts

Handles processing for both normal and error condition interrupts. Invokes ControllerCompleteTransfer() as appropriate.

ControllerCompleteTransfer

Invoked when an I/O completes or an error is detected. If this I/O is part of a sequence, PbcRequestConfigureForIndex() is called to prepare the next I/O; otherwise, the request is marked for completion.