kdusb.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602
  1. /*++
  2. Copyright (c) 2014 Minoca Corp. All Rights Reserved
  3. Module Name:
  4. kdusb.h
  5. Abstract:
  6. This header contains definitions for USB debug devices.
  7. Author:
  8. Evan Green 26-Mar-2014
  9. --*/
  10. //
  11. // ------------------------------------------------------------------- Includes
  12. //
  13. //
  14. // ---------------------------------------------------------------- Definitions
  15. //
  16. #define DEBUG_USB_HOST_DESCRIPTION_VERSION 1
  17. //
  18. // Define USB port status bits.
  19. //
  20. #define DEBUG_USB_PORT_STATUS_CONNECTED 0x00000001
  21. #define DEBUG_USB_PORT_STATUS_ENABLED 0x00000002
  22. #define DEBUG_USB_PORT_STATUS_SUSPENDED 0x00000004
  23. #define DEBUG_USB_PORT_STATUS_OVER_CURRENT 0x00000008
  24. #define DEBUG_USB_PORT_STATUS_RESET 0x00000010
  25. #define DEBUG_USB_PORT_STATUS_LOW_SPEED 0x00000100
  26. #define DEBUG_USB_PORT_STATUS_FULL_SPEED 0x00000200
  27. #define DEBUG_USB_PORT_STATUS_HIGH_SPEED 0x00000400
  28. #define DEBUG_USB_PORT_STATUS_SUPER_SPEED 0x00000800
  29. #define DEBUG_USB_SETUP_PACKET_SIZE 8
  30. #define DEBUG_USB_ENDPOINT_ADDRESS_MASK 0x0F
  31. //
  32. // ------------------------------------------------------ Data Type Definitions
  33. //
  34. typedef enum _DEBUG_USB_DEVICE_SPEED {
  35. DebugUsbDeviceSpeedInvalid,
  36. DebugUsbDeviceSpeedLow,
  37. DebugUsbDeviceSpeedFull,
  38. DebugUsbDeviceSpeedHigh,
  39. DebugUsbDeviceSpeedSuper,
  40. } DEBUG_USB_DEVICE_SPEED, *PDEBUG_USB_DEVICE_SPEED;
  41. typedef enum _DEBUG_USB_TRANSFER_TYPE {
  42. DebugUsbTransferTypeInvalid,
  43. DebugUsbTransferTypeControl,
  44. DebugUsbTransferTypeInterrupt,
  45. DebugUsbTransferTypeBulk,
  46. DebugUsbTransferTypeIsochronous,
  47. DebugUsbTransferTypeCount
  48. } DEBUG_USB_TRANSFER_TYPE, *PDEBUG_USB_TRANSFER_TYPE;
  49. typedef enum _DEBUG_USB_TRANSFER_DIRECTION {
  50. DebugUsbTransferDirectionInvalid,
  51. DebugUsbTransferDirectionIn,
  52. DebugUsbTransferDirectionOut,
  53. DebugUsbTransferBidirectional,
  54. DebugUsbTransferDirectionCount
  55. } DEBUG_USB_TRANSFER_DIRECTION, *PDEBUG_USB_TRANSFER_DIRECTION;
  56. /*++
  57. Structure Description:
  58. This structure stores information about a debug USB transfer request.
  59. Members:
  60. Type - Stores the type of USB request that this transfer is.
  61. Direction - Stores the direction of the USB endpoint.
  62. Speed - Stores the speed of the destination device.
  63. HubAddress - Stores the address of the hub this device is connected to.
  64. This is only required for full or low speed devices on a high speed
  65. bus.
  66. HubPort - Stores the one-based port number of the hub this device is
  67. connected to. This is only required for full or low speed devices on a
  68. high speed bus.
  69. EndpointNumber - Stores the endpoint number, including the high 0x80 bit.
  70. DeviceAddress - Stores the device address of the device that owns this
  71. endpoint.
  72. DataToggle - Stores the data toggle value of the next transfer descriptor
  73. to be filled out.
  74. Halted - Stores a boolean indicating if the endpoint is halted.
  75. MaxPacketSize - Stores the maximum packet size of this endpoint.
  76. --*/
  77. typedef struct _DEBUG_USB_ENDPOINT {
  78. DEBUG_USB_TRANSFER_TYPE Type;
  79. DEBUG_USB_TRANSFER_DIRECTION Direction;
  80. DEBUG_USB_DEVICE_SPEED Speed;
  81. UCHAR HubAddress;
  82. UCHAR HubPort;
  83. UCHAR EndpointNumber;
  84. UCHAR DeviceAddress;
  85. BOOL DataToggle;
  86. BOOL Halted;
  87. ULONG MaxPacketSize;
  88. } DEBUG_USB_ENDPOINT, *PDEBUG_USB_ENDPOINT;
  89. /*++
  90. Structure Description:
  91. This structure stores information about a debug USB transfer request.
  92. Members:
  93. Endpoint - Stores a pointer to the endpoint this transfer is associated
  94. with.
  95. Direction - Stores the direction of the USB transfer. This must be
  96. consistent with the endpoint being sent to.
  97. Length - Stores the length of the request, in bytes.
  98. LengthTransferred - Stores the number of bytes that have actually been
  99. transferred.
  100. Buffer - Stores a pointer to the data buffer.
  101. BufferPhysicalAddress - Stores the physical address of the data buffer.
  102. HostContext - Stores a pointer of context for the host controller.
  103. HostDescriptorCount - Stores a value used optionally and internally by the
  104. host controller. Consumers should not use this value.
  105. Status - Stores the completion status of the request.
  106. --*/
  107. typedef struct _DEBUG_USB_TRANSFER {
  108. PDEBUG_USB_ENDPOINT Endpoint;
  109. DEBUG_USB_TRANSFER_DIRECTION Direction;
  110. ULONG Length;
  111. ULONG LengthTransferred;
  112. PVOID Buffer;
  113. PHYSICAL_ADDRESS BufferPhysicalAddress;
  114. PVOID HostContext;
  115. ULONG HostDescriptorCount;
  116. KSTATUS Status;
  117. } DEBUG_USB_TRANSFER, *PDEBUG_USB_TRANSFER;
  118. typedef
  119. KSTATUS
  120. (*PDEBUG_USB_HOST_INITIALIZE) (
  121. PVOID Context
  122. );
  123. /*++
  124. Routine Description:
  125. This routine initializes a USB debug device, preparing it to return the
  126. root hub status and ultimately send and receive transfers.
  127. Arguments:
  128. Context - Supplies a pointer to the device context.
  129. Return Value:
  130. Status code.
  131. --*/
  132. typedef
  133. KSTATUS
  134. (*PDEBUG_USB_HOST_GET_ROOT_HUB_STATUS) (
  135. PVOID Context,
  136. ULONG PortIndex,
  137. PULONG PortStatus
  138. );
  139. /*++
  140. Routine Description:
  141. This routine queries the host controller for the status of a root hub port.
  142. Arguments:
  143. Context - Supplies a pointer to the device context.
  144. PortIndex - Supplies the zero-based port number to query.
  145. PortStatus - Supplies a pointer where the port status is returned.
  146. Return Value:
  147. STATUS_SUCCESS if the hub status was successfully queried.
  148. STATUS_OUT_OF_BOUNDS if the controller port index is out of range.
  149. STATUS_DEVICE_IO_ERROR if a device error occurred.
  150. --*/
  151. typedef
  152. KSTATUS
  153. (*PDEBUG_USB_HOST_SET_ROOT_HUB_STATUS) (
  154. PVOID Context,
  155. ULONG PortIndex,
  156. ULONG PortStatus
  157. );
  158. /*++
  159. Routine Description:
  160. This routine sets the host controller for the status of a root hub port.
  161. Arguments:
  162. Context - Supplies a pointer to the device context.
  163. PortIndex - Supplies the zero-based port number to set.
  164. PortStatus - Supplies the port status to set.
  165. Return Value:
  166. STATUS_SUCCESS if the hub status was successfully queried.
  167. STATUS_OUT_OF_BOUNDS if the controller port index is out of range.
  168. STATUS_DEVICE_IO_ERROR if a device error occurred.
  169. --*/
  170. typedef
  171. KSTATUS
  172. (*PDEBUG_USB_HOST_SETUP_TRANSFER) (
  173. PVOID Context,
  174. PDEBUG_USB_TRANSFER Transfer
  175. );
  176. /*++
  177. Routine Description:
  178. This routine allocates a buffer and initializes the given USB transfer.
  179. Arguments:
  180. Context - Supplies a pointer to the device context.
  181. Transfer - Supplies a pointer to the transfer to initialize to. The caller
  182. must have filled out the endpoint, direction, and length members. This
  183. routine will allocate buffer space for the transfer data.
  184. Return Value:
  185. STATUS_SUCCESS if the hub status was successfully queried.
  186. STATUS_INVALID_PARAMETER if the given transfer was not filled out correctly.
  187. STATUS_INSUFFICIENT_RESOURCES if a buffer for the transfer could not be
  188. allocated.
  189. STATUS_DEVICE_IO_ERROR if a device error occurred.
  190. --*/
  191. typedef
  192. KSTATUS
  193. (*PDEBUG_USB_HOST_SUBMIT_TRANSFER) (
  194. PVOID Context,
  195. PDEBUG_USB_TRANSFER Transfer,
  196. BOOL WaitForCompletion
  197. );
  198. /*++
  199. Routine Description:
  200. This routine submits a previously set up USB transfer.
  201. Arguments:
  202. Context - Supplies a pointer to the device context.
  203. Transfer - Supplies a pointer to the transfer to submit.
  204. WaitForCompletion - Supplies a boolean indicating if the routine should
  205. block until the transfer completes.
  206. Return Value:
  207. STATUS_SUCCESS if the hub status was successfully queried.
  208. STATUS_INVALID_PARAMETER if the given transfer was not initialized
  209. correctly.
  210. STATUS_DEVICE_IO_ERROR if a device error occurred.
  211. STATUS_TIMEOUT if the caller wanted to wait for the transfer but it
  212. never completed.
  213. --*/
  214. typedef
  215. KSTATUS
  216. (*PDEBUG_USB_HOST_CHECK_TRANSFER) (
  217. PVOID Context,
  218. PDEBUG_USB_TRANSFER Transfer
  219. );
  220. /*++
  221. Routine Description:
  222. This routine checks on the completion status of a transfer.
  223. Arguments:
  224. Context - Supplies a pointer to the device context.
  225. Transfer - Supplies a pointer to the transfer to check.
  226. Return Value:
  227. STATUS_SUCCESS if the hub status was successfully queried.
  228. STATUS_INVALID_PARAMETER if the given transfer was not initialized
  229. correctly.
  230. STATUS_DEVICE_IO_ERROR if a device error occurred.
  231. STATUS_MORE_PROCESSING_REQUIRED if the transfer is still in progress.
  232. --*/
  233. typedef
  234. KSTATUS
  235. (*PDEBUG_USB_HOST_RETIRE_TRANSFER) (
  236. PVOID Context,
  237. PDEBUG_USB_TRANSFER Transfer
  238. );
  239. /*++
  240. Routine Description:
  241. This routine retires an EHCI. This frees the buffer allocated during setup.
  242. Arguments:
  243. Context - Supplies a pointer to the device context.
  244. Transfer - Supplies a pointer to the transfer to retire.
  245. Return Value:
  246. STATUS_SUCCESS if the hub status was successfully queried.
  247. STATUS_INVALID_PARAMETER if the given transfer was not initialized
  248. correctly.
  249. STATUS_DEVICE_IO_ERROR if a device error occurred.
  250. --*/
  251. typedef
  252. KSTATUS
  253. (*PDEBUG_USB_HOST_STALL) (
  254. PVOID Context,
  255. ULONG Milliseconds
  256. );
  257. /*++
  258. Routine Description:
  259. This routine burns time using the frame index register to mark time.
  260. Arguments:
  261. Context - Supplies a pointer to the device context.
  262. Milliseconds - Supplies the number of milliseconds to stall for.
  263. Return Value:
  264. STATUS_SUCCESS if the hub status was successfully queried.
  265. STATUS_DEVICE_IO_ERROR if a device error occurred.
  266. --*/
  267. typedef
  268. KSTATUS
  269. (*PDEBUG_USB_HOST_GET_HANDOFF_DATA) (
  270. PVOID Context,
  271. PDEBUG_USB_HANDOFF_DATA HandoffData
  272. );
  273. /*++
  274. Routine Description:
  275. This routine returns the controller specific handoff data in preparation
  276. for the real USB driver taking over primary functionality.
  277. Arguments:
  278. Context - Supplies a pointer to the device context.
  279. HandoffData - Supplies a pointer to the handoff data. The controller should
  280. fill in the host controller specific data and size fields.
  281. Return Value:
  282. Status code.
  283. --*/
  284. /*++
  285. Structure Description:
  286. This structure contains the function table for a debug USB host device.
  287. Members:
  288. Initialize - Stores a pointer to a function used to initialize the USB
  289. host controller.
  290. GetRootHubStatus - Stores a pointer to a function used to get the status
  291. of a port on the root hub of the USB host controller.
  292. SetRootHubStatus - Stores a pointer to a function used to set the status
  293. of a port on the root hub of the USB host controller.
  294. SetupTransfer - Stores a pointer to a function used to allocate and
  295. initialize a transfer that will be submitted to the USB host controller.
  296. SubmitTransfer - Stores a pointer to a function use to submit a transfer
  297. to the USB host controller.
  298. CheckTransfer - Stores a pointer to a function used to check the completion
  299. status of a submitted transfer.
  300. RetireTransfer - Stores a pointer to a function used to deschedule and
  301. deallocate a previously set up usb transfer.
  302. Stall - Stores a pointer to a function that provides time-based busy
  303. spinning using the USB host controller's frame counter.
  304. GetHandoffData - Stores a pointer to a function used to get the handoff
  305. data in preparation for the official USB host controller driver taking
  306. over.
  307. --*/
  308. typedef struct _DEBUG_USB_HOST_FUNCTION_TABLE {
  309. PDEBUG_USB_HOST_INITIALIZE Initialize;
  310. PDEBUG_USB_HOST_GET_ROOT_HUB_STATUS GetRootHubStatus;
  311. PDEBUG_USB_HOST_SET_ROOT_HUB_STATUS SetRootHubStatus;
  312. PDEBUG_USB_HOST_SETUP_TRANSFER SetupTransfer;
  313. PDEBUG_USB_HOST_SUBMIT_TRANSFER SubmitTransfer;
  314. PDEBUG_USB_HOST_CHECK_TRANSFER CheckTransfer;
  315. PDEBUG_USB_HOST_RETIRE_TRANSFER RetireTransfer;
  316. PDEBUG_USB_HOST_STALL Stall;
  317. PDEBUG_USB_HOST_GET_HANDOFF_DATA GetHandoffData;
  318. } DEBUG_USB_HOST_FUNCTION_TABLE, *PDEBUG_USB_HOST_FUNCTION_TABLE;
  319. /*++
  320. Structure Description:
  321. This structure is used to describe a USB host controller implementation
  322. that can be used for kernel debugging.
  323. Members:
  324. TableVersion - Stores the version of the USB host controller description
  325. table as understood by the hardware module. Set this to
  326. DEBUG_USB_HOST_DESCRIPTION_VERSION.
  327. FunctionTable - Stores the table of pointers to the hardware module's
  328. functions.
  329. Context - Stores a pointer's worth of data specific to this instance. This
  330. pointer will be passed back to the hardware module on each call.
  331. Identifier - Stores the unique identifier of the controller.
  332. PortSubType - Stores the host controller sub-type, as defined by the Debug
  333. Port Table 2 specification.
  334. --*/
  335. typedef struct _DEBUG_USB_HOST_DESCRIPTION {
  336. ULONG TableVersion;
  337. DEBUG_USB_HOST_FUNCTION_TABLE FunctionTable;
  338. PVOID Context;
  339. ULONGLONG Identifier;
  340. USHORT PortSubType;
  341. } DEBUG_USB_HOST_DESCRIPTION, *PDEBUG_USB_HOST_DESCRIPTION;
  342. /*++
  343. Structure Description:
  344. This structure stores the information about a USB debug device.
  345. Members:
  346. Host - Stores a pointer to the host controller.
  347. --*/
  348. typedef struct _HARDWARE_USB_DEBUG_DEVICE {
  349. PDEBUG_USB_HOST_DESCRIPTION Host;
  350. } HARDWARE_USB_DEBUG_DEVICE, *PHARDWARE_USB_DEBUG_DEVICE;
  351. //
  352. // -------------------------------------------------------------------- Globals
  353. //
  354. //
  355. // -------------------------------------------------------- Function Prototypes
  356. //
  357. KSTATUS
  358. KdUsbInitialize (
  359. PDEBUG_USB_HOST_DESCRIPTION Host,
  360. BOOL TestInterface
  361. );
  362. /*++
  363. Routine Description:
  364. This routine initializes a USB debug based transport.
  365. Arguments:
  366. Host - Supplies a pointer to the host controller.
  367. TestInterface - Supplies a boolean indicating if the interface test should
  368. be run. This is only true under debugging scenarios where the USB
  369. debug transport itself is being debugged.
  370. Return Value:
  371. Status code.
  372. --*/
  373. //
  374. // Host controller module initialization functions.
  375. //
  376. VOID
  377. KdEhciModuleEntry (
  378. VOID
  379. );
  380. /*++
  381. Routine Description:
  382. This routine is the entry point for a hardware module. Its role is to
  383. detect the prescense of any of the hardware modules it contains
  384. implementations for and instantiate them with the kernel.
  385. Arguments:
  386. None.
  387. Return Value:
  388. None.
  389. --*/