Fix and Extend Code for xHCI DbC Data Transmission
Budget: $30 – $250 USD
Short description:
Repair broken code which uses xHCI’s Debug Capability (DbC) to transmit and receive data via USB3 from two physical machines. Existing code is provided, along with working code to compare against. End result is repaired C code which enables DbC on an xHC, and transmits + receives some simple data between machines. Build mechanism to create an example UEFI runtime driver on Windows via EDK2 is also provided in the existing code. Both machines are Windows 10/11 machines connected via a USB host-to-host/type A-to-A cable. Should be a very easy project for those familiar with USB programming constructs.
Long description:
I am creating a library which utilizes an xHCI controller’s Debug Capability (DbC) to transmit binary and textual data from one physical machine to another. This library is intended to be as simple and minimal as possible (all completed examples are around 1,000 LOC, our library is around 500 LOC). This library currently uses only one function to enter an xHCI controller into DbC operation, and should be fixed from its broken state and extended to have a simple set of functions to check for incoming data, read incoming data, and write outgoing data.
Given that code is already provided to you—with all of the OS-specific functions completed—and that several working examples are also provided (all minimal code bases at around 1,000 LOC or less as standalone source files), this should be an easy project; especially for someone with knowledge of xHCI/USB3’s programming constructs, such as TRB rings, interfacing with controller MMIO registers, and so on.
A current code base already exists for you to work off of, which would be preferable, but this code currently does not properly enter the Debug Target xHCI controller into DbC operation (and also does not contain the routines to transmit or receive data). I don’t know why the DbC setup code isn’t working, but several resources–all of which are also minimal and standard (Xen/Linux/etc.)–have been included so that you can draw comparisons between our code and existing, working code; with one independent project included, which I can confirm does correctly initialize DbC operation. This independent project is called Xue, and linked below, but know I have not been able to use it to transmit or receive data as of yet.
The programming language used for this library is C, and the code should be designed to run in environments with extremely minimal reliance on the underlying operating system; as in some cases, this code may be used in custom/hobby operating systems, or systems without an underlying operating system (such as hypervisor microkernels). In the existing code base, all of the functions in the `mem.h/c`, `io.h/asm`, `mmio.h/c`, and `pci.h/c` files provide an existing means of performing all of the memory/io/mmio/pci operations you would need. If these routines need to be modified in any way, or new ones need to be added, approval should be sought beforehand. The style of the code submitted should also, ideally, match the existing code base. The final code does not need to be commented, as the existing code is, but should be extremely minimal, and again, match the style of the existing code. In the existing code base, the xHCI interfacing code, along with the DbC interfacing/setup code can be found in the `xhci_dbc.c` file. Our code base builds a UEFI runtime driver with EDK2 for testing on bare metal. Scripts are provided to build this `*.efi` binary for testing (assuming a Windows build machine). For such testing on bare metal, one requires a USB host-to-host cable, or type A-to-A cable, for communication between two machines with SuperSpeed-capable ports, with the Debug Target containing an xHCI controller that supports DbC. The Debug Host machines up to now have been Windows 10/11 machines.
Transmitting and receiving data should use polling and NOT use any interrupts generated from the xHCI controller (the controller should never be configured this way).
The final product of your code ***must work as expected*** on our bare metal testing machine (Windows 11, standard xHCI controller (vendor ID: 8086, device ID: 7A60, subsystem ID: 88821043, revision: 11)), which entails entering the xHCI controller into DbC operation, and transmitting + receiving simple data. For transmitting/receiving data on the Debug Host side of things, you don’t have to write a USB driver or implement this from scratch. A Xue-style Zadig USB driver using pyusb is perfectly acceptable (and this script file can be used directly from Xue’s source code if you wish).
Understand that, because of the sensitive nature of the data that lies on our testing machine, binary-only submissions are not acceptable; even just for testing. Source code with build instructions—if the build system or core code base is modified—must be shared in order for the binary to be rebuilt, tested, and for your work to be validated.
Here is our current code, along with additional resources you can use to learn more about DbC (or view other implementations of this xHCI DbC interface).
Our code, along with a custom version of Xue that works with EDK2 and the xHCI/DbC specification PDFs:
https://github.com/LuminousTrout/xhci-dbc-lib
Slides on DbC:
https://people.allbsd.org/~hrs/FreeBSD/udbc/sato-20240531-usbdbc.pdf
The Xue project, which has--what *seems* to be--a working DbC implementation, but does not align in the slightest with our project's code style:
https://github.com/cjams/xue/blob/master/include/xue.h
https://github.com/cjams/xue/blob/master/README.md
Xen's port of Xue, which is much cleaner and contains directions for setup and consuming logs on the Debug Host:
https://github.com/xen-project/xen/blob/f29cc14de1d195bcd8312dcab2b5f8e634b57288/xen/drivers/char/xhci-dbc.c
Minimal example of Xen's Xue port + the Linux DbC driver built into one:
https://github.com/tomtzook/xhci-dbc-tryout/blob/3f73aa35c5366a618c79551183fcf8c731d5b54c/xdbc/xdbc/xdbc.c
Linux's DbC driver:
https://github.com/torvalds/linux/blob/master/drivers/usb/early/xhci-dbc.c
A FreeBSD implementation of a DbC driver by the same guy who did the slides above:
https://github.com/hrs-allbsd/freebsd-src/commit/1d96d494dc295a397cbd717ca4279b6f7f3baecd#diff-097e81690c5052b693a27fd6d173c896de2f0da24d6362da045f50bbdac3f5eb
Repair broken code which uses xHCI’s Debug Capability (DbC) to transmit and receive data via USB3 from two physical machines. Existing code is provided, along with working code to compare against. End result is repaired C code which enables DbC on an xHC, and transmits + receives some simple data between machines. Build mechanism to create an example UEFI runtime driver on Windows via EDK2 is also provided in the existing code. Both machines are Windows 10/11 machines connected via a USB host-to-host/type A-to-A cable. Should be a very easy project for those familiar with USB programming constructs.
Long description:
I am creating a library which utilizes an xHCI controller’s Debug Capability (DbC) to transmit binary and textual data from one physical machine to another. This library is intended to be as simple and minimal as possible (all completed examples are around 1,000 LOC, our library is around 500 LOC). This library currently uses only one function to enter an xHCI controller into DbC operation, and should be fixed from its broken state and extended to have a simple set of functions to check for incoming data, read incoming data, and write outgoing data.
Given that code is already provided to you—with all of the OS-specific functions completed—and that several working examples are also provided (all minimal code bases at around 1,000 LOC or less as standalone source files), this should be an easy project; especially for someone with knowledge of xHCI/USB3’s programming constructs, such as TRB rings, interfacing with controller MMIO registers, and so on.
A current code base already exists for you to work off of, which would be preferable, but this code currently does not properly enter the Debug Target xHCI controller into DbC operation (and also does not contain the routines to transmit or receive data). I don’t know why the DbC setup code isn’t working, but several resources–all of which are also minimal and standard (Xen/Linux/etc.)–have been included so that you can draw comparisons between our code and existing, working code; with one independent project included, which I can confirm does correctly initialize DbC operation. This independent project is called Xue, and linked below, but know I have not been able to use it to transmit or receive data as of yet.
The programming language used for this library is C, and the code should be designed to run in environments with extremely minimal reliance on the underlying operating system; as in some cases, this code may be used in custom/hobby operating systems, or systems without an underlying operating system (such as hypervisor microkernels). In the existing code base, all of the functions in the `mem.h/c`, `io.h/asm`, `mmio.h/c`, and `pci.h/c` files provide an existing means of performing all of the memory/io/mmio/pci operations you would need. If these routines need to be modified in any way, or new ones need to be added, approval should be sought beforehand. The style of the code submitted should also, ideally, match the existing code base. The final code does not need to be commented, as the existing code is, but should be extremely minimal, and again, match the style of the existing code. In the existing code base, the xHCI interfacing code, along with the DbC interfacing/setup code can be found in the `xhci_dbc.c` file. Our code base builds a UEFI runtime driver with EDK2 for testing on bare metal. Scripts are provided to build this `*.efi` binary for testing (assuming a Windows build machine). For such testing on bare metal, one requires a USB host-to-host cable, or type A-to-A cable, for communication between two machines with SuperSpeed-capable ports, with the Debug Target containing an xHCI controller that supports DbC. The Debug Host machines up to now have been Windows 10/11 machines.
Transmitting and receiving data should use polling and NOT use any interrupts generated from the xHCI controller (the controller should never be configured this way).
The final product of your code ***must work as expected*** on our bare metal testing machine (Windows 11, standard xHCI controller (vendor ID: 8086, device ID: 7A60, subsystem ID: 88821043, revision: 11)), which entails entering the xHCI controller into DbC operation, and transmitting + receiving simple data. For transmitting/receiving data on the Debug Host side of things, you don’t have to write a USB driver or implement this from scratch. A Xue-style Zadig USB driver using pyusb is perfectly acceptable (and this script file can be used directly from Xue’s source code if you wish).
Understand that, because of the sensitive nature of the data that lies on our testing machine, binary-only submissions are not acceptable; even just for testing. Source code with build instructions—if the build system or core code base is modified—must be shared in order for the binary to be rebuilt, tested, and for your work to be validated.
Here is our current code, along with additional resources you can use to learn more about DbC (or view other implementations of this xHCI DbC interface).
Our code, along with a custom version of Xue that works with EDK2 and the xHCI/DbC specification PDFs:
https://github.com/LuminousTrout/xhci-dbc-lib
Slides on DbC:
https://people.allbsd.org/~hrs/FreeBSD/udbc/sato-20240531-usbdbc.pdf
The Xue project, which has--what *seems* to be--a working DbC implementation, but does not align in the slightest with our project's code style:
https://github.com/cjams/xue/blob/master/include/xue.h
https://github.com/cjams/xue/blob/master/README.md
Xen's port of Xue, which is much cleaner and contains directions for setup and consuming logs on the Debug Host:
https://github.com/xen-project/xen/blob/f29cc14de1d195bcd8312dcab2b5f8e634b57288/xen/drivers/char/xhci-dbc.c
Minimal example of Xen's Xue port + the Linux DbC driver built into one:
https://github.com/tomtzook/xhci-dbc-tryout/blob/3f73aa35c5366a618c79551183fcf8c731d5b54c/xdbc/xdbc/xdbc.c
Linux's DbC driver:
https://github.com/torvalds/linux/blob/master/drivers/usb/early/xhci-dbc.c
A FreeBSD implementation of a DbC driver by the same guy who did the slides above:
https://github.com/hrs-allbsd/freebsd-src/commit/1d96d494dc295a397cbd717ca4279b6f7f3baecd#diff-097e81690c5052b693a27fd6d173c896de2f0da24d6362da045f50bbdac3f5eb