253 lines
No EOL
11 KiB
Text
253 lines
No EOL
11 KiB
Text
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|
|
|
+-------------------+ |