Windows System Software -- Consulting, Training, Development -- Unique Expertise, Guaranteed Results
The free OSR Learning Library has more than 50 articles on a wide variety of topics about writing and debugging device drivers and Minifilters. From introductory level to advanced. All the articles have been recently reviewed and updated, and are written using the clear and definitive style you've come to expect from OSR over the years.
Check out The OSR Learning Library at: https://www.osr.com/osr-learning-library/
We have a product here which is a PCIe to I2C/SPI bridge. We are required to write a Windows Driver to control the I2C controller present inside the PCIe chip.
The hardware connection looks like this:
| HostPC | ------- > PCIe to I2C bridge Device connected to PCIe slot---> I2C slave device
I went through the Simple Peripheral Bus (SPB) framework for this I2C controller. But the documentation is mainly concentrated on the I2C controller that are part of the SOC platform. For example, the documentation says that the information about the SPB controller or SPB peripheral device should be present as a part of the ACPI table.
My device here is not statically connected to any system. This PCIe switch can be connected by the customer whenever he needs and he just does a reboot of the PC to get that enumerated by the OS. So we cannot define this as part of the ACPI table.
Also it says that the application cannot directly send data to and from the SPB controller driver. We need to have a SPB peripheral driver also that bridges the application and the SPB controller.
My use case is like this:
Provide the I2C controller driver for the PCIe to I2C bridge. I will provide specific IOCTLs to send Write or Read commands from the application. Let the customer connect whatever I2C device they want to be connected to the I2C controller. Let them drive that peripheral from the application without the need for a peripheral driver in between.
I like my device to be acting as a USB to I2C bridge. Something like this:
Is there a Windows device driver framework to support my use case?
Or to better frame my question, How can I go about this?
P.S: I am pretty new to WIndows drivers. I have a fair knowledge on Linux drivers though.
|Upcoming OSR Seminars|
|OSR has suspended in-person seminars due to the Covid-19 outbreak. But, don't miss your training! Attend via the internet instead!|
|Internals & Software Drivers||19-23 June 2023||Live, Online|
|Writing WDF Drivers||10-14 July 2023||Live, Online|
|Kernel Debugging||16-20 October 2023||Live, Online|
|Developing Minifilters||13-17 November 2023||Live, Online|
Welcome to the forum, and thanks for taking the time to write such a clear and complete description of what you are trying to accomplish.
Because of your specific use case, you simply would write an ordinary PCI device driver that controls your I2C controller at the bottom edge, and that takes whatever Reads, Writes, and a Ioctls that you wish to define from your user app at the top edge.
There’s no need for you to fit your driver (or your I2C controller) into the Windows SPB framework, because of your use case: Specifically, you do not want or need Windows PnP to enumerate the Client Device that’s attached to your I2C controller, find the “best” driver for it, and load that driver. Rather, you want Windows to match your driver to your PCIe Controller board, and then you’ll provide a generic interface (probably accessed via a nice user-mode DLL) that user apps use to access the various registers on the I2C client device that’s connected to your controller.
So, that’s pretty easy! You get to ignore everything in Windows about I2C because Windows does not get involved in the management of your I2C bus or the device that’s connected to it.
Sounds like a fun project! Good,luck,
As Peter said, this is not a hard driver to write, but I have to wonder why you would do so. I2C and SPI are slow busses, thousands of times slower than PCIe. Why would you go to the expense of developing and certifying a PCIe board, when there are (as you mentioned) USB-to-SPI chips that already exist off the shelf?
Tim Roberts, [email protected]
Providenza & Boekelheide, Inc.
yes there are chips which do that. I have dealt recently with MCP2221A which is exactly that - USB-to-I2c.
Microchip company does not provide a good native Windows 10 driver for MCP2221A, there is only legacy DLL with proprietary functions to read and write to i2c. I.e. when used in Windows 10 the MCP2221A chip when plugged in into USB will not appear as any particular class device. One has to call some function in DLL to find out if it was connected and if i2c controller is alive.
So, in general using USB-to-i2c chips works in Windows 10 but cumbersome, and is subject to vendor support.
I can see that someone may wish to have a well formed i2c controllers (perhaps many of those) on single PCIe card recognized by Windows 10 as proper class devices. Since if you don't then Windows 10 has no idea your system has i2c controller.
RIght, because there IS no pre-defined device class for I2C adapters. Any driver you write for this will be a custom device with a custom API. That's true for many devices. That shouldn't be an impediment for you.
The point of having pre-defined device classes is so Windows can provide an abstraction API. There is no I2C device class, so there is no I2C abstraction API. This is not the fault of the vendors. There is not much call for I2C devices in the corporate world, which is where Windows is king. Look, I2C is slow and uncomplicated. You need Detect, Read, and Write. As long as the DLL provides that, what's the problem?
Tim Roberts, [email protected]
Providenza & Boekelheide, Inc.
Except in the land of Windows IoT, where (a) I2C is much more likely to be used as Mr. Roberts alludes, and (b) there’s a very complete abstraction available in C# (at least).
Thanks for the detailed and quick explanation. Really appreciate that I have few more doubts.
There is another use case to the one I mentioned in my description. There could be a need wherein, instead of the application directly sending command to the controller to control the peripheral beneath, there could be a KMDF or UMDF peripheral driver present for that peripheral device in the OS. So in this case, the application will not directly talk to controller driver. but talks to the peripheral driver.
This could be achieved using the SPB framework if we are static and using the ACPI table to define the devices and the connections. But unfortunately we are not.
Is there anyway to use the SPB framework and escape from using the ACPI table for Controller and peripheral binding? From the documentation I could see that, there are too much dependencies on the ACPI table. For example, to get the target connection settings, the controller driver needs to call SpbTargetGetConnectionParameters. This API is inturn reading through the ACPI table to obtain the device's settings.
I am thinking if I can somehow achieve the I2C/SPI controller to device binding without ACPI and through some other means, I can reuse the SPB framework and achieve both the use cases.
IS there a way out here??
Well, that's almost 100% different from your first use case... And it changes the design COMPLETELY. This is a MUCH harder ask.
If your goal is to allow "standard" WDF drivers to be recognized and loaded for devices that are attached to your controller, I don't see any reasonable way of avoiding having the device described in the ACPI BIOS. The Client Driver is going to try to open a Remote I/O Target connection to the Controller Driver via the Resource Hub (ACPIEX). ACPIEX is going to try to determine which Controller the Client device is attached to by looking through the ACPI BIOS tables.
If you wanted to be really fancy and complex, I suppose you could:
Write a bus driver that enumerates the device(s) connected to your controller. Because there's no standard way to dynamically enumerate the I2C bus, you'd have to create some method that users specify the device(s) connected to your I2C Controller's bus (as well as the Client IDs associated with each of those devices). You'll also need to be clever enough to "fake" a Connection ID for the Client driver to use when it enumerates its resources and attempt to open the connection to the Resource Hub.
Write a filter driver that intercepts Open requests that are sent to the Resource Hub, and redirect the open (via STATUS_REPARSE) to your Controller Driver.
Ensure your Controller Driver takes into account (that is, effectively "emulates") the behavior that the Client Driver would expect if it were talking to a Controller Driver via the SPBCx. So, you'll need to support the "standard" IOCTLs.
I think you'll be able to avoid actual use of the SPB Controller Extensions entirely if you do the above. They don't really provide any advantage or help in your case... and I suspect that once the Client Driver gets his Connection ID and has opened a Remote I/O Target to your Controller Driver, it'll start sending you those standard IOCTLs.
The above ignores the case where the Client device has some other resources other than the I2C Connection. For example, this doesn't allow you support for connections from the I2C device to a GPIO controller for interrupts (which is pretty common). I really don't see how you could support interrupts on the Client devices you enumerate... GPIO controller isn't under your control, after all.
ANYhow... having to load the standard driver (and not just allow an app to do write and read) really turns this from a simple project into what is basically a research project. You're waaaay out of the standard ways of doing things.
And here comes the PCIe interface. PCIe is very good with interrupts.
PCI(e) is also more reliable than USB (TL;DR) so it can be preferred for unattended systems (servers, industrial...) even if cost is higher.
From an I2C device that expects to be connected via a GPIO controller?
So, now you’re telling me the OP has also neglected to tell us about the other 50% of his project in which his PCIe card has a GPIO controller on it, and he needs to write control that as well?
I suspect that the OP still holds some interesting details up his sleeve...
Same logic on the PCIe device that drives I2C can also receive interrupt requests. Not any "GPIO controller. As you and Mr. Roberts wrote previously it can be a simple PCI device, or a custom bus parent . It now depends on the class of the I2C devices - should they use in-box drivers or can be custom as well.
Let my bits go on the wire!
The OPs board supports “ordinary” I2C Client devices, which connect to an I2C bus and (perhaps, depending on the device) one or more interrupts. On the interrupt side, Client device expects to talk to a GPIO controller. It’s simple for you to write “ Same logic on the PCIe device that drives I2C can also receive interrupt requests” — but it’s not so simple in the hardware. You need to match logic levels and timing. You need to accommodate the potential for multiple interrupts in the same way you’d accommodate multiple GPIOs... if you’re going to pipe these to multiple MSIs there needs to be some logic involved, right?
I really don’t think it’s as simple as you seem to think. You can’t just wire one or more lines that are designed to pull high or low (depending on the device) to generate an interrupt to your PCIe interface chip. You have an FPGA out there to do all this matching and mapping?
Exactly right Peter ! In fact as I recall the entire spbclx is now a part of OneCore, not just for Windows IoT. Therefore a PCIe card with a proprietary ic2 host controller could be nicely supported by a proper driver into a well formed i2c class device on Windows 10. Moverover, shall one such exist I may even be interested to order it for future designs.
Mr. Roberts, i2c is a bit slow, yes, but still very important, in some areas in fact is the key for the instrument, such as Tektronix analyzer. One of our systems has five(5) i2c host controllers, since there are many components to communicate with. Yes on Windows 10.
i2c host controller is not a custom device in Windows 10. i2c host controller is a supported type of device.
SPB Framework Extension (SpbCx)
For example Intel implemented i2c host controller connected to PCIe on Core-i5 based board.
00:15.0 Signal processing controller: Intel Corporation Sunrise Point-LP Serial IO I2C Controller #0 (rev 21)
Subsystem: Intel Corporation Device 7270
Control: I/O- Mem- BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR- FastB2B- DisINTx+
Status: Cap+ 66MHz- UDF- FastB2B- ParErr- DEVSEL=fast >TAbort- SERR- <PERR- INTx-
Interrupt: pin A routed to IRQ 16
Yes, well... that’s true. I2C controllers, in general, are backplane bus type devices (supported by PCI.SYS).
However, the issue is that... regardless of how the Controller is interfaced, the Client devices still need to be listed in the ACPI BIOS, because the I2C bus is not dynamically enumerable.
And, as I said earlier... it’s not typically a matter of JUST I2C. I2C (and SPI) connected devices are often designed to connect to one or more GPIOs to allow them to signal conditions.
Anyhow... your project is turning into something that’s feeling far too complicated to reasonably design via forum posts.
Good luck with your project. It’s an interesting one, for sure.
Hi Peter and others,
Thanks for spending time in helping me out here. Looks like I triggered a ruckus here . I am still a fair bit away from understanding the entire Windows driver architecture. I will go through the suggestions and comments from everyone here and try to progress. I will keep you guys updated in case I break through this.
Thanks again for your time
I am back
We had a discussion with marketing and finally we agreed that our I2C/SPI drivers need to be compliant to SPB framework and thus it was also agreed to have the ACPI table of the system to be updated to add our device.
Now that this is fixed and done, I have another query. We have a SPI controller on one of the PCIe endpoint as I pointed out earlier. There are 2 instances of the controller in the same PCIe endpoint. So logically it should be 2 SPB controller driver instances with 2 separate set of registers. So I thought of calling the WDFDeviceCreate and SPB related functions twice in the OnDeviceAdd callback function to create 2 separate instances of SPI controller. But the 2nd WDFDeviceCreate is failing since the FxDeviceInit object is not free.
Since this is a PCIe device, we hit the OnDeviceAdd only once upon the device detection but the requirement is to have 2 SPI controller instances registered to the SPB framework.
Is there a simple way to achieve this?
Thanks in advance,
Hmmmm... so, you have a PCIe device, that provides TWO SPI controllers, with separate sets of registers... but ONE PCIe function? Who designed THAT device? Cuz it’s not PCIe compliant. Does the device do anything ELSE?
Simple? No. Can it be done? Yes, and it’s not TOO difficult.
You need to write a bus driver that enumerates each of the SPI controllers, and creates one PDO for each. As a result of reporting these PDO during normal PnP processing, the function driver for the controller will be instantiated on each PDO. Hence EvtDriverDeciceAdd in the function driver will be called twice, once for each controller.
With all due respect, if your company’s major goal is for all this to work properly on Windows, I strongly suggest you hire a consultant who understands how all these pieces fit together... before you design and build hardware and try to write drivers that make life difficult. You’ll likely save yourself a ton of time and effort. You don’t know what you don’t know.
Something around mf.sys with a resource map? Is this still supported on win10?
What I don't understand at all... if SPB devices must have ACPI descriptors - who enumerates them: ACPI or PCI? Or PCI with ACPI as upper filter?
It's not clear to me how it is possible to have an SPB device on a PCI bus. SPB is supposed to include I2C, SPI, MIPI, and UART devices, none of which have any PnP capabilities at all, so ACPI is the only way to expose those devices. I'm not convinced that the PCI bus driver knows how to expose an SPB-like device.
Tim Roberts, [email protected]
Providenza & Boekelheide, Inc.
I am not sure if this is PCIe compliant or not but, I have seen similar posts w.r.t many UARTs being shared in the same PCIe function. Isn't this similar to that?
Yes this device also has a I2C and UART in separate endpoints. So as a whole this is a PCIe multifunction device considering UART, I2C, SPI being present in the same endpoint but having their own config spaces.
So you mean to say its similar to using the mf.sys? Can I use mf.sys here to take care of creating the PDOs for me?
I can certainly convey this message but i think the ship sailed beyond that point.
So you are saying that I can use the default mf.sys itself for my device?
The documentation regarding the resource map is not that clear. This is my understanding till now:
1. Provide an inf for mf.sys which contains the actual PCIe HW IDs, MSI interrupts.
2. Allocate resources to each of the child some resources of the parent in the parent inf. Like BAR0 - 0 - 200 -> SPI1, BAR0 200 - 400 SPI2.
3. Create two child infs for each of the SPI controller. I am not sure what to put in these INFs apart from the pointers to .sys and cat files.
here comes my doubt, we will have only one .sys file, should i create 2 INFs for 2 SPI controllers?
Is my understanding correct?
My understanding is that the enumeration will be done by the PCI driver and the logical connections between SPB controller and SPB peripherals will be maintained by the ACPI.
Well, it doesn’t. The OP said in his most recent post that his card has SPB controllers which are typically just standard PCIE backplane bus architecture devices.
Here, we’re talking about the client devices I assume. The system developer manually creates entries... one per device... is the SSDT. The entries are enumerated by ACPI — ACPI is the enumerator and bus driver for all things SPB. Because devices on the buses are not dynamically discoverable.
Forget about it. Just write a bus driver using KMDF. Enumerate each of the devices on your card. Then the function driver will load for each of those devices. If the I2C and SPI controllers are “standard” controllers, you could use the in-box drivers for those. Which would be good, because writing drivers for those won’t be easy.
This design still isn’t a “done deal.” I’m not sure how you’re going to describe the controllers in the ACPI SSDT. Remember, they need to be described, too.
I’m really not sure how or if this whole project will work... at all. I’m sure there’s a lot that you haven’t told us. If what you’re trying to do is build an add-in card to allow random users to attach I2C or SPI devices to a Windows machine... forget it: That’s not supported by the OS at this point (it should be, but it’s not). I you’re trying to create an add-in card that OEMs would use, say, in a laptop or an embedded system to attach I2C and SPI devices, you might have a chance. But, as I said, I don’t know how you make that work in ACPI — you’ll need someone who knows a lot more about ACPI than I do, that’s for sure, to tell you how to do this.
Ok. I am yet to go through Windows documentation for writing a bus driver. Any pointers?
Yes. I thought of doing it this way:
DefinitionBlock ("", "SSDT", 2, "OEMID", "SPBSSDT ", 0x00)
//PCI port below which our PCIe controller resides
//0x00010003 -> device, function number of the PCIe
Name (_ADR, 0x00010003)
Won't this work? This was before this multiple instance issue came up. Will this require a change if we introduce a bus driver in between?
Sorry I forgot to add one more point. we spoke to Marketing team and they conveyed that this PCIe device cannot be a pluggable module. Its present by default in a system upon bootup. So that's one less problem. Let me give a gist of the product without revealing too much. Its a PCIe device that has one multi-function endpoint where we have UART,SPI,I2C and GPIO controllers. Each of these is an independent function. i.e. they have their own config space. Here in case of SPI alone, there are 2 SPI controller instances shared in the same function.
Also there are cases where we need user apps to directly interact with our controller drivers to control the peripherals beneath I2C/SPI without a peripheral driver. I went through this link which says its feasible through a RHProxy driver:
Understood that even this needs ACPI entry beneath a RHProxy node. Anyway we are fine to go with editing the ACPI table.
What do you think?
Well, that makes all the difference, actually. That makes this “just another I2C and SPI controller”... which is no big thing.
Wait. One multifunction endpoint? That means it surfaces separate devices for each of the controllers, and this will be automatically handled by the PCI bus driver.
You therefore have no work to do.
As someone who's done a fair amount of hooking up strange devices to PC's, its looking like you're starting to drift into the weeds a bit (actually your first post was the most clear). I would take a step back and determine
a) what is the target hardware (commercial off the shelf, like a laptop) or customizable (you'll order something from Wistron or WiPro)
b) what exactly are you trying to accomplish ... you've mentioned a lot of things here: on the I2C network are you trying to be a master, a slave or a monitor? Same on SPI; master, slave or monitor? GPIO are you trying to read from a GPIO expander (which would mean I2C) or are you really going to have some wires that you can toggle? For UART is this RS232, RS485 or something else and are you going to be a master, a slave or a monitor?
c) what is the end user going to be ... is this targeted for a system integrator (who will likely want to interact with this at the device level) or at a user level (something similar to ReadWriteEverything, or the SIV64 display?
d) what is the timeframe that you're looking at, hours/ days/ weeks/ months?
Generally, I have found that letting a PC be a PC, Windows be Windows and keeping everything at arms length works best. You've got several technologies here (I2C, SPI and GPIO) which really aren't found on regular hardware and you're asking Windows to do some things that it's really not designed to do (such as directly accessing hardware) ... that all spells trouble, especially when a new version of Windows comes out every six months and you get to retest everything
If I had a similar request (I2C/ SPI/ GPIO/ UART on the back end) I would spec out a PCIe card which would be plugged into an m2 connector (which most motherboards and laptops have) and have two FPGA's on that: one FPGA for the PCIe IP and one FPGA to handle all of the strange stuff. Write a single KMDF PCIe function driver which can interact with that card and you're done ... that way all of the I2C/ SPI/ GPIO/ UART stuff is handled by the back end FPGA (which is programmed by the front end FPGA, so you can customize it as you wish), the front end FPGA handles the PCIe stuff and all you need to do is expose some BAR's and interrupts for the KMDF driver to handle as needed ...
But again, a clear idea of what you're wanting to do, what it's running on and who's going to be using it will help you immeasurably ...
But he still has two SPIs in one PCIe function. However if ACPI can describe SPB devices as children of given PCI bus/device/function then the ACPI patch is all what is remaining. No tinkering with mf.sys.
That’s not clear. Nothing the OP writes is definitively clear, at least to me.
@craig_howard: The OPs requirements seem to have evolved very dramatically since his initial post. Last we heard, he now had a multifunction PCIe endpoint that was permanently attached to the main board that provided one SPI, one I2C, one UART and one GPIO controller. Or, that’s what I understand at least. I can’t exactly envision what that would look like, or how it would get permanently attached, but perhaps that’s from my lack of experience as a system builder.
Sorry for not being clear. I think I dint have the clarity when I first started this thread. But right now I have more clarity on what is needed. Let me list it down by answering @craig_howard's questionnaire
Ours is a PCIe switch that's going to be plugged into embedded board like imx.8 which has PCIe slot (M.2 I think). So most likely Windows IoT could be flavor. It has one PCIe Downstream Port and one PCIe multifunction endpoint which has 4 separate functions (4 separate config space for each function).
DS Port 0 : PCIe DS port
DS Port 1: 4 Functions
Function 1: one UART
Function 2: one I2C controller
Function 3: two SPI controllers
Function 4: GPIO controller.
I2C -> Master controller
SPI -> Master controller
UART -> I guess its RS485
GPIO -> Generic GPIO controller that exposes around 60 GPIOs.
There are 2 use cases:
1. There can be other kernel peripheral drivers that can use our Master Controllers to control their peripherals. example: connecting a I2C temperature sensor or a SPI based LCD display.
2. There will be no kernel peripheral drivers. The user space application will directly send commands to our controller drivers to control anything that is connected. Example : Connecting a I2C eeprom and sending commands from user space to program that EEPROM. We know that native SPBCx doesn't allow that but we came across this below link that helps us achieve this.
May be next 3 months
I dont have an answer for this.
W.r.t I2C, UART, GPIO controllers we are not using the Mf.sys for the multifunction devices even though we are compliant at this level to PCI multi-function standard. I don't see any advantage of using Mf.sys for the UART,I2C, SPI, GPIO controllers. What's the need to use Mf.sys at this level? Can't we live without that?
With respect to the I2C, UART, GPIO controllers I dont have any issues since these are one instance and I can register them as normal drivers.
So the trouble I have here is with the SPI controller. Since there are 2 SPI controllers on a single config space, I am finding it difficult to enable these 2 SPI controllers upon a single EvtDriverDeviceAdd callback.
Suggestion from Peter was to write a bus driver on top this SPI controller and enumerate each of the SPI controller.
Suggestion from Pavel was to use the mf.sys and use Varying resource map as mentioned in
With this description in mind, is there a clear pointer for me?
Is there anymore ambiguity? I can explain specific things better if needed.
MUCH more clear. Thank you.
Yay for supporting the i.MX SoC! Long live NXP! Do they (NXP) even still support Windows IoT core?
Forget about my.sys, which is old junk... just write a bus driver for the SPI function. It should be reasonably simple, relative to everything else you’re doing, and assuming the register sets are separate.
If you have to write your own controller drivers for these devices, that will be a bit difficult. I’m not aware of any examples available.
But as I said: If the SPI, I2C, and GPIO controllers use standard register layouts.... there’s probably already a driver written for them... and you won’t have to write it yourself.
Thank you for pointing me in the right direction. I am pretty new to Windows so have little to no experience w.r.t bus drivers. From my understanding following are the responsibilities of the bus driver:
1. Since this is a PCIe device, the bus driver's EvtDeviceAdd would be called upon device attach.
2. Need to create PDOs for the 2 SPI controllers.
3. I would get the PCIe BAR resources in the bus driver.
4. Need to allocate some part of the BAR to SPI controller 1 and another part to SPI controller 2.
5. Similarly interrupts MSI interrupts need to be allocated.
Following are my questions:
1. How and when does the child devices' EvtDeviceAdd would be called?
2. How the linkage between the bus driver and the child driver occurs.
3. Also I have little confusion how the INFs of the bus driver and the SPI child devices would be.
Is there a sample driver that I can refer for this? That would be really helpful.
You would need to do this allocation internally. You should not be reporting these as hardware resource requirements to pnp,
PDOs do not have EvtDeviceAdd called. If you are using a static WDFCHILDLIST (you should) you create and initialize them whenver is appropriate. You can do this in the parent's EvtDeviceAdd
The linkage occurs naturally by creating the child WDFDEVICEs