2 EFI_USB_HC_PROTOCOL as defined in EFI 1.10.
4 The USB Host Controller Protocol is used by code, typically USB bus drivers,
5 running in the EFI boot services environment, to perform data transactions
6 over a USB bus. In addition, it provides an abstraction for the root hub of the USB bus.
8 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
9 SPDX-License-Identifier: BSD-2-Clause-Patent
13 #ifndef _USB_HOSTCONTROLLER_H_
14 #define _USB_HOSTCONTROLLER_H_
16 #include <Protocol/Usb2HostController.h>
18 #define EFI_USB_HC_PROTOCOL_GUID \
20 0xf5089266, 0x1aa0, 0x4953, {0x97, 0xd8, 0x56, 0x2f, 0x8a, 0x73, 0xb5, 0x19 } \
24 /// Forward reference for pure ANSI compatability
26 typedef struct _EFI_USB_HC_PROTOCOL EFI_USB_HC_PROTOCOL
;
29 // Protocol definitions
33 Provides software reset for the USB host controller.
35 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
36 @param Attributes A bit mask of the reset operation to perform.
38 @retval EFI_SUCCESS The reset operation succeeded.
39 @retval EFI_UNSUPPORTED The type of reset specified by Attributes is not currently supported
40 by the host controller hardware.
41 @retval EFI_INVALID_PARAMETER Attributes is not valid.
42 @retval EFI_DEVICE_ERROR An error was encountered while attempting to perform the reset operation.
47 (EFIAPI
*EFI_USB_HC_PROTOCOL_RESET
)(
48 IN EFI_USB_HC_PROTOCOL
*This
,
53 Retrieves current state of the USB host controller.
55 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
56 @param State A pointer to the EFI_USB_HC_STATE data structure that
57 indicates current state of the USB host controller.
59 @retval EFI_SUCCESS The state information of the host controller was returned in State.
60 @retval EFI_INVALID_PARAMETER State is NULL.
61 @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the host controller's
67 (EFIAPI
*EFI_USB_HC_PROTOCOL_GET_STATE
)(
68 IN EFI_USB_HC_PROTOCOL
*This
,
69 OUT EFI_USB_HC_STATE
*State
73 Sets the USB host controller to a specific state.
75 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
76 @param State Indicates the state of the host controller that will be set.
78 @retval EFI_SUCCESS The USB host controller was successfully placed in the state specified by
80 @retval EFI_INVALID_PARAMETER State is NULL.
81 @retval EFI_DEVICE_ERROR Failed to set the state specified by State due to device error.
86 (EFIAPI
*EFI_USB_HC_PROTOCOL_SET_STATE
)(
87 IN EFI_USB_HC_PROTOCOL
*This
,
88 IN EFI_USB_HC_STATE State
92 Submits control transfer to a target USB device.
94 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
95 @param DeviceAddress Represents the address of the target device on the USB, which is
96 assigned during USB enumeration.
97 @param IsSlowDevice Indicates whether the target device is slow device or full-speed
99 @param MaximumPacketLength Indicates the maximum packet size that the default control
100 transfer endpoint is capable of sending or receiving.
101 @param Request A pointer to the USB device request that will be sent to the USB
103 @param TransferDirection Specifies the data direction for the transfer. There are three
104 values available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData.
105 @param Data A pointer to the buffer of data that will be transmitted to USB
106 device or received from USB device.
107 @param DataLength On input, indicates the size, in bytes, of the data buffer specified
108 by Data. On output, indicates the amount of data actually
110 @param TimeOut Indicates the maximum time, in milliseconds, which the transfer
111 is allowed to complete.
112 @param TransferResult A pointer to the detailed result information generated by this
115 @retval EFI_SUCCESS The control transfer was completed successfully.
116 @retval EFI_OUT_OF_RESOURCES The control transfer could not be completed due to a lack of resources.
117 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
118 @retval EFI_TIMEOUT The control transfer failed due to timeout.
119 @retval EFI_DEVICE_ERROR The control transfer failed due to host controller or device error.
124 (EFIAPI
*EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER
)(
125 IN EFI_USB_HC_PROTOCOL
*This
,
126 IN UINT8 DeviceAddress
,
127 IN BOOLEAN IsSlowDevice
,
128 IN UINT8 MaximumPacketLength
,
129 IN EFI_USB_DEVICE_REQUEST
*Request
,
130 IN EFI_USB_DATA_DIRECTION TransferDirection
,
131 IN OUT VOID
*Data OPTIONAL
,
132 IN OUT UINTN
*DataLength OPTIONAL
,
134 OUT UINT32
*TransferResult
138 Submits bulk transfer to a bulk endpoint of a USB device.
140 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
141 @param DeviceAddress Represents the address of the target device on the USB, which is
142 assigned during USB enumeration.
143 @param EndPointAddress The combination of an endpoint number and an endpoint
144 direction of the target USB device. Each endpoint address
145 supports data transfer in one direction except the control
146 endpoint (whose default endpoint address is 0). It is the
147 caller's responsibility to make sure that the EndPointAddress
148 represents a bulk endpoint.
149 @param MaximumPacketLength Indicates the maximum packet size that the default control
150 transfer endpoint is capable of sending or receiving.
151 @param Data A pointer to the buffer of data that will be transmitted to USB
152 device or received from USB device.
153 @param DataLength On input, indicates the size, in bytes, of the data buffer specified
154 by Data. On output, indicates the amount of data actually
156 @param DataToggle A pointer to the data toggle value.
157 @param TimeOut Indicates the maximum time, in milliseconds, which the transfer
158 is allowed to complete.
159 @param TransferResult A pointer to the detailed result information of the bulk transfer.
161 @retval EFI_SUCCESS The bulk transfer was completed successfully.
162 @retval EFI_OUT_OF_RESOURCES The bulk transfer could not be completed due to a lack of resources.
163 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
164 @retval EFI_TIMEOUT The bulk transfer failed due to timeout.
165 @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error.
170 (EFIAPI
*EFI_USB_HC_PROTOCOL_BULK_TRANSFER
)(
171 IN EFI_USB_HC_PROTOCOL
*This
,
172 IN UINT8 DeviceAddress
,
173 IN UINT8 EndPointAddress
,
174 IN UINT8 MaximumPacketLength
,
176 IN OUT UINTN
*DataLength
,
177 IN OUT UINT8
*DataToggle
,
179 OUT UINT32
*TransferResult
183 Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
185 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
186 @param DeviceAddress Represents the address of the target device on the USB, which is
187 assigned during USB enumeration.
188 @param EndPointAddress The combination of an endpoint number and an endpoint
189 direction of the target USB device. Each endpoint address
190 supports data transfer in one direction except the control
191 endpoint (whose default endpoint address is zero). It is the
192 caller's responsibility to make sure that the
193 EndPointAddress represents an interrupt endpoint.
194 @param IsSlowDevice Indicates whether the target device is slow device or full-speed
196 @param MaximumPacketLength Indicates the maximum packet size that the default control
197 transfer endpoint is capable of sending or receiving.
198 @param IsNewTransfer If TRUE, an asynchronous interrupt pipe is built between the host
199 and the target interrupt endpoint. If FALSE, the specified asynchronous
200 interrupt pipe is canceled. If TRUE, and an interrupt transfer exists
201 for the target end point, then EFI_INVALID_PARAMETER is returned.
202 @param DataToggle A pointer to the data toggle value. On input, it is valid when
203 IsNewTransfer is TRUE, and it indicates the initial data toggle
204 value the asynchronous interrupt transfer should adopt. On output,
205 it is valid when IsNewTransfer is FALSE, and it is updated to indicate
206 the data toggle value of the subsequent asynchronous interrupt transfer.
207 @param PollingInterval Indicates the interval, in milliseconds, that the asynchronous
208 interrupt transfer is polled.
209 @param DataLength Indicates the length of data to be received at the rate specified by
210 PollingInterval from the target asynchronous interrupt
211 endpoint. This parameter is only required when IsNewTransfer is TRUE.
212 @param CallBackFunction The Callback function. This function is called at the rate specified by
213 PollingInterval. This parameter is only required when IsNewTransfer is TRUE.
214 @param Context The context that is passed to the CallBackFunction.
216 @retval EFI_SUCCESS The asynchronous interrupt transfer request has been successfully
217 submitted or canceled.
218 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
219 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
220 @retval EFI_TIMEOUT The bulk transfer failed due to timeout.
221 @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error.
226 (EFIAPI
*EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER
)(
227 IN EFI_USB_HC_PROTOCOL
*This
,
228 IN UINT8 DeviceAddress
,
229 IN UINT8 EndPointAddress
,
230 IN BOOLEAN IsSlowDevice
,
231 IN UINT8 MaxiumPacketLength
,
232 IN BOOLEAN IsNewTransfer
,
233 IN OUT UINT8
*DataToggle
,
234 IN UINTN PollingInterval OPTIONAL
,
235 IN UINTN DataLength OPTIONAL
,
236 IN EFI_ASYNC_USB_TRANSFER_CALLBACK CallBackFunction OPTIONAL
,
237 IN VOID
*Context OPTIONAL
241 Submits synchronous interrupt transfer to an interrupt endpoint of a USB device.
243 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
244 @param DeviceAddress Represents the address of the target device on the USB, which is
245 assigned during USB enumeration.
246 @param EndPointAddress The combination of an endpoint number and an endpoint
247 direction of the target USB device. Each endpoint address
248 supports data transfer in one direction except the control
249 endpoint (whose default endpoint address is zero). It is the
250 caller's responsibility to make sure that the
251 EndPointAddress represents an interrupt endpoint.
252 @param IsSlowDevice Indicates whether the target device is slow device or full-speed
254 @param MaximumPacketLength Indicates the maximum packet size that the default control
255 transfer endpoint is capable of sending or receiving.
256 @param Data A pointer to the buffer of data that will be transmitted to USB
257 device or received from USB device. asynchronous interrupt pipe is canceled.
258 @param DataLength On input, the size, in bytes, of the data buffer specified by Data.
259 On output, the number of bytes transferred.
260 @param DataToggle A pointer to the data toggle value. On input, it indicates the initial
261 data toggle value the synchronous interrupt transfer should adopt;
262 on output, it is updated to indicate the data toggle value of the
263 subsequent synchronous interrupt transfer.
264 @param TimeOut Indicates the maximum time, in milliseconds, which the transfer
265 is allowed to complete.
266 @param TransferResult A pointer to the detailed result information from the synchronous
269 @retval EFI_SUCCESS The synchronous interrupt transfer was completed successfully.
270 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
271 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
272 @retval EFI_TIMEOUT The synchronous interrupt transfer failed due to timeout.
273 @retval EFI_DEVICE_ERROR The synchronous interrupt transfer failed due to host controller or device error.
278 (EFIAPI
*EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER
)(
279 IN EFI_USB_HC_PROTOCOL
*This
,
280 IN UINT8 DeviceAddress
,
281 IN UINT8 EndPointAddress
,
282 IN BOOLEAN IsSlowDevice
,
283 IN UINT8 MaximumPacketLength
,
285 IN OUT UINTN
*DataLength
,
286 IN OUT UINT8
*DataToggle
,
288 OUT UINT32
*TransferResult
292 Submits isochronous transfer to an isochronous endpoint of a USB device.
294 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
295 @param DeviceAddress Represents the address of the target device on the USB, which is
296 assigned during USB enumeration.
297 @param EndPointAddress The combination of an endpoint number and an endpoint
298 direction of the target USB device. Each endpoint address
299 supports data transfer in one direction except the control
300 endpoint (whose default endpoint address is 0). It is the caller's
301 responsibility to make sure that the EndPointAddress
302 represents an isochronous endpoint.
303 @param MaximumPacketLength Indicates the maximum packet size that the default control
304 transfer endpoint is capable of sending or receiving.
305 @param Data A pointer to the buffer of data that will be transmitted to USB
306 device or received from USB device. asynchronous interrupt pipe is canceled.
307 @param DataLength Specifies the length, in bytes, of the data to be sent to or received
309 @param TransferResult A pointer to the detailed result information from the isochronous
312 @retval EFI_SUCCESS The isochronous transfer was completed successfully.
313 @retval EFI_OUT_OF_RESOURCES The isochronous could not be completed due to a lack of resources.
314 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
315 @retval EFI_TIMEOUT The isochronous transfer failed due to timeout.
316 @retval EFI_DEVICE_ERROR The isochronous transfer failed due to host controller or device error.
321 (EFIAPI
*EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER
)(
322 IN EFI_USB_HC_PROTOCOL
*This
,
323 IN UINT8 DeviceAddress
,
324 IN UINT8 EndPointAddress
,
325 IN UINT8 MaximumPacketLength
,
328 OUT UINT32
*TransferResult
332 Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device.
334 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
335 @param DeviceAddress Represents the address of the target device on the USB, which is
336 assigned during USB enumeration.
337 @param EndPointAddress The combination of an endpoint number and an endpoint
338 direction of the target USB device. Each endpoint address
339 supports data transfer in one direction except the control
340 endpoint (whose default endpoint address is zero). It is the
341 caller's responsibility to make sure that the
342 EndPointAddress represents an isochronous endpoint.
343 @param MaximumPacketLength Indicates the maximum packet size that the default control
344 transfer endpoint is capable of sending or receiving. For isochronous
345 endpoints, this value is used to reserve the bus time in the schedule,
346 required for the perframe data payloads. The pipe may, on an ongoing basis,
347 actually use less bandwidth than that reserved.
348 @param Data A pointer to the buffer of data that will be transmitted to USB
349 device or received from USB device. asynchronous interrupt pipe is canceled.
350 @param DataLength Specifies the length, in bytes, of the data to be sent to or received
352 @param IsochronousCallback The Callback function.This function is called if the requested
353 isochronous transfer is completed.
354 @param Context Data passed to the IsochronousCallback function. This is
355 an optional parameter and may be NULL.
357 @retval EFI_SUCCESS The asynchronous isochronous transfer was completed successfully.
358 @retval EFI_OUT_OF_RESOURCES The asynchronous isochronous could not be completed due to a lack of resources.
359 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
364 (EFIAPI
*EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER
)(
365 IN EFI_USB_HC_PROTOCOL
*This
,
366 IN UINT8 DeviceAddress
,
367 IN UINT8 EndPointAddress
,
368 IN UINT8 MaximumPacketLength
,
371 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack
,
372 IN VOID
*Context OPTIONAL
376 Retrieves the number of root hub ports.
378 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
379 @param PortNumber A pointer to the number of the root hub ports.
381 @retval EFI_SUCCESS The port number was retrieved successfully.
382 @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the port number.
383 @retval EFI_INVALID_PARAMETER PortNumber is NULL.
388 (EFIAPI
*EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER
)(
389 IN EFI_USB_HC_PROTOCOL
*This
,
390 OUT UINT8
*PortNumber
394 Retrieves the current status of a USB root hub port.
396 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
397 @param PortNumber Specifies the root hub port from which the status is to be retrieved.
398 This value is zero based. For example, if a root hub has two ports,
399 then the first port is numbered 0, and the second port is
401 @param PortStatus A pointer to the current port status bits and port status change bits.
403 @retval EFI_SUCCESS The status of the USB root hub port specified by PortNumber
404 was returned in PortStatus.
405 @retval EFI_INVALID_PARAMETER PortNumber is invalid.
410 (EFIAPI
*EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS
)(
411 IN EFI_USB_HC_PROTOCOL
*This
,
413 OUT EFI_USB_PORT_STATUS
*PortStatus
417 Sets a feature for the specified root hub port.
419 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
420 @param PortNumber Specifies the root hub port from which the status is to be retrieved.
421 This value is zero based. For example, if a root hub has two ports,
422 then the first port is numbered 0, and the second port is
424 @param PortFeature Indicates the feature selector associated with the feature set
427 @retval EFI_SUCCESS The feature specified by PortFeature was set for the USB
428 root hub port specified by PortNumber.
429 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.
434 (EFIAPI
*EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE
)(
435 IN EFI_USB_HC_PROTOCOL
*This
,
437 IN EFI_USB_PORT_FEATURE PortFeature
441 Clears a feature for the specified root hub port.
443 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
444 @param PortNumber Specifies the root hub port from which the status is to be retrieved.
445 This value is zero based. For example, if a root hub has two ports,
446 then the first port is numbered 0, and the second port is
448 @param PortFeature Indicates the feature selector associated with the feature clear
451 @retval EFI_SUCCESS The feature specified by PortFeature was cleared for the USB
452 root hub port specified by PortNumber.
453 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.
458 (EFIAPI
*EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE
)(
459 IN EFI_USB_HC_PROTOCOL
*This
,
461 IN EFI_USB_PORT_FEATURE PortFeature
466 /// The EFI_USB_HC_PROTOCOL provides USB host controller management, basic data transactions
467 /// over a USB bus, and USB root hub access. A device driver that wishes to manage a USB bus in a
468 /// system retrieves the EFI_USB_HC_PROTOCOL instance that is associated with the USB bus to be
469 /// managed. A device handle for a USB host controller will minimally contain an
470 /// EFI_DEVICE_PATH_PROTOCOL instance, and an EFI_USB_HC_PROTOCOL instance.
472 struct _EFI_USB_HC_PROTOCOL
{
473 EFI_USB_HC_PROTOCOL_RESET Reset
;
474 EFI_USB_HC_PROTOCOL_GET_STATE GetState
;
475 EFI_USB_HC_PROTOCOL_SET_STATE SetState
;
476 EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER ControlTransfer
;
477 EFI_USB_HC_PROTOCOL_BULK_TRANSFER BulkTransfer
;
478 EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER AsyncInterruptTransfer
;
479 EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER SyncInterruptTransfer
;
480 EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER IsochronousTransfer
;
481 EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER AsyncIsochronousTransfer
;
482 EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER GetRootHubPortNumber
;
483 EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus
;
484 EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature
;
485 EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature
;
487 /// The major revision number of the USB host controller. The revision information
488 /// indicates the release of the Universal Serial Bus Specification with which the
489 /// host controller is compliant.
491 UINT16 MajorRevision
;
493 /// The minor revision number of the USB host controller. The revision information
494 /// indicates the release of the Universal Serial Bus Specification with which the
495 /// host controller is compliant.
497 UINT16 MinorRevision
;
500 extern EFI_GUID gEfiUsbHcProtocolGuid
;