{"id":20149802,"url":"https://github.com/cjams/xue","last_synced_at":"2025-04-09T20:10:57.751Z","repository":{"id":252578547,"uuid":"192415813","full_name":"cjams/xue","owner":"cjams","description":"Cross-platform driver for the USB 3 xHCI Debug Capability","archived":false,"fork":false,"pushed_at":"2021-10-21T17:06:54.000Z","size":188,"stargazers_count":19,"open_issues_count":1,"forks_count":8,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-09T20:10:52.024Z","etag":null,"topics":["bareflank","dbc","debug","efi","linux","usb3","xen","xhci"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cjams.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-17T20:41:25.000Z","updated_at":"2025-02-19T09:35:38.000Z","dependencies_parsed_at":"2024-08-10T22:42:36.295Z","dependency_job_id":null,"html_url":"https://github.com/cjams/xue","commit_stats":null,"previous_names":["cjams/xue"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjams%2Fxue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjams%2Fxue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjams%2Fxue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjams%2Fxue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cjams","download_url":"https://codeload.github.com/cjams/xue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103872,"owners_count":21048245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bareflank","dbc","debug","efi","linux","usb3","xen","xhci"],"created_at":"2024-11-13T22:46:56.402Z","updated_at":"2025-04-09T20:10:57.728Z","avatar_url":"https://github.com/cjams.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xue USB 3 Debugger\n\nXue is a cross-platform driver for the USB 3 Debug Capability (DbC). It is a\nheader-only library so that it may be easily included into various\nenvironments. The goal of Xue is to provide a high-bandwidth debugger that can\nbe used with two standard mobile/laptop devices without the need for legacy\nUART hardware.\n\n### Hardware Requirements\n\nTo use xue, you need two machines: a target and a host. The target (the one\nyou're debugging) must have a USB 3 xHCI host controller that\nimplements the Debug Capability as described in the xHCI\n[specification](https://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/extensible-host-controler-interface-usb-xhci.pdf).\nSo far the following Intel (PCI vendor 0x8086) host controllers have been\ntested to work:\n\n  - Z370 (PCI device 0xA2AF)\n  - Z390 (PCI device 0xA36D)\n  - Wildcat Point-LP (PCI device 0x9CB1)\n  - Sunrise Point-LP (PCI device 0x9D2F)\n  - Cannon Point-LP (PCI device 0x9DED)\n\nDevices not listed here will likely work after you add the appropriate `#define\nXUE_XHC_DEV_*` to `xue.h`. If you have a device not listed above, and/or it\ndoes not work after adding the `#define`, please open a merge request so\nsupport can be added.\n\nThe host (the machine you're viewing the target output from) only needs one\nSuper-Speed port. The debug cable that connects the target to the host is an\nA/A crossover cable that can be purchased\n[here](https://www.datapro.net/products/usb-3-0-super-speed-a-a-debugging-cable.html).\nThe final requirement is that the cable must be connected directly to a root\nSuper-Speed port on the target, i.e., it will not work through a hub.\n\n### Debug Targets\n\nXue is officially supported to run from the following environments:\n\n  - UEFI [applications](test/test_efi.c) (based on gnuefi)\n  - Linux kernel [modules](https://github.com/connojd/hypervisor/blob/xue/bfdriver/src/common.c#L373)\n  - Bareflank [hypervisor](https://github.com/connojd/hypervisor/blob/xue/bfvmm/src/debug/unistd.cpp#L53)\n  - Xen [hypervisor](https://github.com/connojd/xen/blob/xue/xen/drivers/char/xue.c)\n\n\u003e **NOTE:** To use the Xen example above, pass 'console=dbgp dbgp=xue' on the Xen command line\n\nXue requires a set of operations to properly communicate with the DbC hardware.\nThese operations are defined in `struct xue_ops` in `xue.h`. Xue provides default\nimplementations of these operations for each of the four systems above. However,\nyou may override each of these defaults in order to adapt xue to your target system.\nTo use xue in your own project, follow these steps:\n\n  1. Ensure `include/xue.h` is in your include path\n  2. Allocate and clear a `struct xue` and `struct xue_ops`\n  3. If needed, implement system-specific `xue_ops` and initialize the previously allocated `struct xue_ops` with them\n  4. Optionally allocate a structure for storing system-specific state. This may be used in conjunction with the operations defined in 3\n  5. Open xue by passing the addresses of the above structures to `xue_open`\n  6. Write data to xue with `xue_write`\n\nAny NULL members of the `struct xue_ops` passed to `xue_open` will be set\nto the xue_sys_* defaults defined for that system. If a member is not NULL,\nthen xue assumes it is a user-defined override and will simply call it.\n\n### Debug Hosts\n\nXue itself runs on the target machine and sends any data provided to\n`xue_write` to the debug host, which can be either Linux or Windows.\nEach host platform has its own instructions outlined below you should\nfollow in order to read data from xue.\n\n#### Linux\n\nXue presents itself as the xhci_dbc device over USB. This means that Linux\nwill bind the xhci_dbc driver to the device and will create\na /dev/ttyUSBx file that can be read. You can read this file like any other\nserial device, however the `scripts/read.sh` is provided and recommended as\nit handles common things like disconnects that may occur during development.\n\n#### Windows 10\n\nIf your debug host is Windows 10, then you can run `python scripts/read.py`\nfrom a terminal to read the target's output, but there are a few steps you need\nto do before the script will work:\n  - Install [zadig](https://zadig.akeo.ie)\n  - Run zadig as admin\n  - Click 'Device' -\u003e 'Create New Device'\n  - Enter 'Xue DbC Device' in the top text box\n  - Enter '1D6B' in the left text box of USB ID\n  - Enter '0010' in the middle text box of USB ID\n  - Click 'Install Driver'\n\nThis will install the WinUSB driver and bind the DbC device to it whenever\nthe debug cable is connected and the DbC enabled.\n\n\u003e **NOTE:** The DbC is considered 'enabled' after a successful call to `xue_open`.\n\nAfter WinUSB is installed, setup the python environment:\n  - Install the latest **64-bit** python for Windows\n    - Select \"Add Python to PATH\"\n    - Select \"Install Now\"\n  - Install [7zip](https://www.7-zip.org/download.html) and [libusb](https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z)\n  - Extract libusb with 7zip\n  - Copy `\u003cpath\\to\\extracted\\libusb\u003e\\MS64\\dll\\libusb-1.0.dll` to `C:\\Windows\\System32\\`\n  - Run `pip install pyusb`\n\nNow you should be able to run `python scripts\\read.py` from a terminal to read the\noutput from the debug target.\n\n### Known Limitations\n\n  - Does not run from Windows 10. Based on earlier experiments, Windows\n    does not allow multiple drivers to map in a given PCI MMIO region\n    simultaneously. This prevents Xue from mapping in the DbC's registers\n    because Window's xHCI driver already owns the mapping. If anyone\n    knows a workaround for this, please share.\n\n  - The DbC is subject to USB host controller resets. This means if any other\n    code resets the host controller, the DbC is reset as well. This means that\n    if you `xue_open` from EFI, the DbC will be reset. Xue checks if this\n    occured before each write, and will re-initialize the device if it has been\n    reset, but this could lead to data loss depending on when the host\n    controller was reset.\n\n  - The DbC is subject to DMA remapping. If the USB host controller is being\n    remapped by an IOMMU, then the default xue_sys_* functions provided in\n    `xue.h` may not work.\n\n### Testing\n\nTo run the unit tests, pass -DBUILD_TESTS=ON to `cmake`. Then run `make test`.\nThis runs the actual test and performs static analysis of the resulting binary\nwith `clang-tidy`.\n\n### Documentation\n\nThe portion of the code intended to be \"public\" is documented with doxygen.\nYou can generate the docs with `doxygen .doxygen.txt` from the source root.\nThat said, most of the \"internal\" code is documented in `xue.h` as well.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjams%2Fxue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcjams%2Fxue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjams%2Fxue/lists"}