pbatard
Wrong information in the Wiki
Hello
You wrote an excellent Wiki of very high quality. But there is an error:
IMPORTANT NOTE 1: There is a bug/limitation in WinUSB that will force the wIndex of any Interface Request to the interface number. This means that, if you are using WinUSB to verify the content of your Extended Properties Feature Descriptor, you won't be able to retrieve it (unless it is only defined for interface #5).
This is not a bug. It means only that you did not understand how Microsoft has designed WinUSB. Please read my posting how to get WinUSB sending a SETUP request to any interface:
https://github.com/libusb/libusb/issues/1675
I can send a SETUP request in my code to any interface of a Multi-Interface USB device without problems.
What's being described there is how the WinUSB DLL forces/rewrites the wIndex behind the user's back, as pointed to you in https://github.com/libusb/libusb/issues/1675#issuecomment-3172917184. This is unexpected behaviour from a DLL, and we use the "bug/limitation" terminology to alert users to that (because in most case, people will not get the result they expect due to WinUSB interfering with the value they set for wIndex).
Unless you want to provide better wording that lets users know that wIndex will be modified behind their back while allowing them to verify the content of their Extended Properties Feature Descriptor, I'm not planning to change the wording.
Microsoft broke the Principle of least astonishment in how they designed WinUSB, which, IMO, does qualify as a bug/limitation of WinUSB.
Hello
It is definitely not a bug. So at least your heading is not correct. This leads many people in internet, who read this, to the conclusion that they CAN NOT send a SETUP with their desired value in wIndex to another interface. I'am not inventing this. I have read in several places that people think that it is not possible with WinUSB because Microsoft is limiting us. They can but not the way that would be intuitive.
1.) Therefore is indispensable that a detailed Wiki, like yours, explains this unexpected and un-intuitive behavior of WinUSB.dll. It is important to explain that WinUSB treats each interface as if it was a separate USB device completely independent of all the other interfaces in the same USB device. The same you see in Device Manager: Each interface of a USB device has it's own icon and name. And each interface may have a driver installed or not. You never install only one driver for the entire USB device. You install one driver for each interface and you may need another driver for interface 0 than for interface 1.
2.) And a consequence of this is that you cannot send a SETUP packet to another interface than the one that you have opened with CreateFile().
3.) Another consequence I have described in the same issue 1675: Microsoft did even go one step further: I found that Microsoft did a lot of work to make working with different interfaces easy for the developer. When I request the configuration descriptor I get different results depending on the interface for which I open WinUSB. When I use the DeviceID for interface 0 Microsoft removes the descriptor for the interface 1 and the DFU descriptor from the returned data. When I use the DeviceID for interface 1 Microsoft removes the descriptor for the interface 0 and the 2 endpoint descriptos from the returned data. So WinUSB behaves really as if I was working with 2 completely independent devices.
Also this information should not be missing in a detailed Wiki like yours.
Software developers must understand that they CAN send SETUP packets through WinUSB to ANY interface in a USB device if: 1.) The WinUSB driver has been installed for this interface 2.) They have obtained the correct DevicePath and passed it to CreateFile() 3.) After having this handle they can ONLY communicate with this ONE interface. 4.) If they want to communicate with 2 interfaces they need 2 handles.
To find an interface with SetupDiEnumDeviceInterfaces() it is fundamental to know the GUID that is stored in the registry under "Device Parameters" --> DeviceInterfaceGUIDs. If you only know the VID and PID of a device it is not possible to find the interfaces except you analyze the registry.
Unless you want to provide better wording that lets users know that wIndex will be modified behind their back while allowing them to verify the content of their Extended Properties Feature Descriptor, I'm not planning to change the wording.
The MS OS descriptor has nothing to do with what I wrote! What I wrote applies to ANY communication with an interface. The Extended Properties Feature Descriptor is only one example that you cannot obtain using the wrong handle.
The mechanism is very simple and I already explained in detail in issue 1675: If you get a WinUSB handle from CreateFile() and then WinUsb_Initialize() you can only send SETUP packets to that interface. If you set wIndex = 1 and send the SETUP packet to interface 0 Microsoft will change wIndex to be zero if your WinUSB handle has been opened for interface 0. If you set wIndex = 0 and send the SETUP packet to interface 1 Microsoft will change wIndex to be one if your WinUSB handle has been opened for interface 1.
This applies to ANY communication with an interface not only to getting the Extended Properties Feature Descriptor.
Again, I'll be happy to accept direct suggestions on the alterations you want to see for the Wiki (i.e. replace ABC with XYZ).
Otherwise, the best you'll see from me, since it seems to annoy you, is that I will change "bug/limitation" with "limitation".
Hello
since it seems to annoy you, is
This is absolutely not about me! I already know all this! I write this only for other people who come to your page and may get confused. I'am only offering help to all those who are new to WinUSB programming. I dont need a change in your wiki for me. My code is already running perfectly.
Can you put yourself in the place of a developer who finds out that the wIndex value in his SETUP packet has been modified by Windows ? What will he do next?
Obviously he will google for this. And he may come to your wiki which says that this is a bug. But this is not a bug. He may then search for alternative libraries to WinUSB and waste a lot of time. He may even completely give up because he finds the same wrong information also in other places in internet and he doesn't want to invest more time into this.
So what information does he need? 1.) Why is this happening ? 2.) What is the solution ?
Currently you write:
There is a bug/limitation in WinUSB that will force the wIndex of any Interface Request to the interface number.
This is not wrong but insufficient because it does not explain how to solve this. I would write: Working with multi-interface USB devices is a special case with WinUSB. Microsoft has designed WinUSB in a way that sees each interface in a USB device as if it was completely separate from the other interfaces. This means if you open a handle with CreateFile() and then WinUSB_Initialize() to one interface, you will be limited to use this handle only for this one interface. If you send a SETUP request with destination Interface and set wIndex to the value of another interface, Windows will modify your wIndex and replace it with the interface number for which you have opened the handle. If you want to send a SETUP to another interface of the same device you must open another handle to this interface
This is absolutely not about me!
I was just talking about using the terminology "bug/limitation", for which the two parts are important and intentional, but which you appear to simply interpret as "bug". In other words, it should be read as "limitation that can be interpreted as a bug" rather than simply "bug".
So, once again, you are misinterpreting what I said (in no way am I stating that changes to the Wiki should be for you), and rolling to a direction that is completely opposite of what I am actually stating and wrote.
Please bear in mind that it's not because someone isn't saying "you're right, let me fix that" right away that they are against you or think that there is some selfish motivation behind what you do (because, of course I do not think that, and have not thought so a single second from when you posted the issue).
However, when you constantly appear to focus on some misinterpreted element of what one writes, it makes it A LOT more difficult to want to deal with your request, which is precisely why I asked you to just post how you would like the Wiki altered, which you did at last, but not before going on another fictitious tangent...
I would write:
Thank you. This is really all I wanted here, and what I will take it into consideration (instead of all the surrounding extra noise) to alter the Wiki.