USB Development Kit (UsbDk) Design and Architecture ============================================================= USB Development Kit is a set of software modules meant to provide user mode applications with direct and exclusive access to USB devices by detaching those from Windows PNP manager and device drivers and providing user mode with API for USB-specific operations on the device. Original intention of the kit is USB device redirection support for spice remote desktop application however it may be used for any other purpose directly or via libusb (there is a libusb backend for UsbDk). USB Development Kit software consists of following modules: 1. UsbDk.sys - USB bus filter driver for acquisition of exclusive access to USB devices. 2. UsbDkHelper.dll - Helper DLL to install, uninstall and configure the driver and forward USB requests to USB devices. 3. UsbDkController.exe - Simple command line application for system API usage demonstration and verification. Using USB Development Kit for USB devices redirection (exclusive access aquisition) USB Development Kit software is used by virt-viewer for USB devices discovery and access as required for redirection purposes. Overall system architecture --------------------------- +---------------------------+ +---------------------+ | | | UsbDkController.exe | | virt-viewer | +---------------------+ | | ^ | +------------+--------------+ | | | libusb | libusbredir | | | +------------+--------------+ | | ^ | | | |----------------------------+ | | |<---------------------------+ Notifications like: | | High-level API like: Device inserted | | InstallDriver/UninstallDriver Device removed | | RedirectDevice | | WritePipe, ReadPipe | | | V +-----------------+ | UsbDkHelper.dll |<--+ +-----------------+ | ^ | | | User Mode ----------------------+------------+--------------------------- | | Kernel Mode Control channel | | | | Data channel for redirected V | device Tx/Rx transfers Control device o | | | +-----------+ +-----------+ V |PNP Manager|<->| UsbDk.sys |------o Generic USB device +-----------+ +-----------+ ^ ^ | | | Tx/Rx passthrough Filter and patch | | done by UsbDk.sys device discovery | | messages | | | | V | +-------+ V |USB hub|--------o Redirected USB device +-------+ ^ | V +-------------------+ |USB host controller| +-------------------+ Kernel mode component (UsbDk.sys) design and functionality ---------------------------------------------------------- UsbDk.sys is both USB filter driver and generic USB device driver. On installation it is being registered as USB filter driver and system invokes it for each new USB device being discovered including USB hubs. On invocation UsbDk.sys checks type of underlying device and creates filter instances for USB hubs only. Being a filter of USB hub UsbDk.sys receives all requests from upper part of USB stack including enumeration requests that originated by PNP manager (IRP_MJ_PNP/IRP_MN_QUERY_DEVICE_RELATIONS). Upon enumeration request completion by USB hub driver UsbDk.sys scans array of child devices returned and in case there are devices to be redirected (according to current configuration) it attaches as filter to those devices as well. As a result all PNP manager requests pass via UsbDk.sys callbacks and the latter patches device ID properties as needed to make PNP manager recognize the device as a generic USB device. Besides that UsbDk.sys marks underlying device object as raw PDO so the system assigns the driver who created it (UsbDk.sys) to be the device driver as well. At this stage any request to this vendor specific device will be forwarded to UsbDk.sys which in turn will patch and pass requests to/from original device created by USB hub as needed. There is also a separate API provided by UsbDkHelper.dll intended to detach USB device from USB stack without acquiring actual access to the device (hider API). This API may be useful for security applications that need to deny access to USB devices according to security policy or to prevent Windows from showing "New Hardware" pop-ups for devices solely managed by UsbDk. When UsbDk.sys discovers device to be hidden during enumeration phase (IRP_MJ_PNP/IRP_MN_QUERY_DEVICE_RELATIONS) it wipes corresponding PDO from device array returned by underlying USB bus driver, this effectively hides given device from PNP manager and OS driver stack. Device stack after UsbDk.sys installation ------------------------------------ +-----------+ |PNP Manager| +-----------+ ^ | V +-----------+ | UsbDk.sys | as filter driver of USB Root Hub +-----------+ ^ | V +-------+ |USB hub| +-------+ ^ | V +-------------------+ |USB host controller| +-------------------+ QUERY_DEVICE_RELATIONS request flow ---------------------------------------------------------------- PNP Manager UsbDk driver USB Root Hub | | | | | | | enumerate devices | | |------------------------------>| | | | enumerate devices | | |------------------------------>| | | array of child devices | | |<------------------------------| | attach filters | | and save the device list | | | | | array of devices | | |<------------------------------| | Device access acquisition flow -------------------------------------- UsbDkHelper.dll UsbDk.sys Specific PDO (Mouse, Keyboard, Storage) | | | | | | | GetDeviceList | | |------------------------------>| | | | | | Array of devices | | |(include VID, PID, Serial Number) | |<------------------------------| | | | | | Redirect specific device | | | (VID, PID, Serial Number) | | |------------------------------>| | | | | | set state for device (redirected) | | | | | | Reset device | | |------------------------------>| ~ ~ ~ ~ ~ ~ | Stop redirect | | |------------------------------>| | | | | | reset state for device | | | | | | Reset device | | |------------------------------>| QUERY_DEVICE_RELATIONS flow with redirected device ---------------------------------------------------- PNP Manager UsbDk driver USB Root Hub | | | | | | | enumerate devices | | |------------------------------>| | | | enumerate devices | | |------------------------------>| | | array of child devices | | |<------------------------------| | attach as filter | | to the PDO being redirected | | | | | | | | | | | array of child devices | | |<------------------------------| | Device stack after redirection initiation ------------------------ +-----------------+ | UsbDkHelper.dll | +-----------------+ ^ | User Mode ----------------------+---------------------------------------- | Kernel Mode | | | +---------------+ | Filter DO | | UsbDk.sys | +---------------+ ^ | V +-----------------------+ | Specific device PDO | | (Mouse, Storage etc.) | +-----------------------+ ^ | V +-------+ |USB hub| +-------+ ^ | V +-------------------+ |USB host controller| +-------------------+