blob: cd9d52d9496529b6057d6b2f41d93c9191513d18 [file] [log] [blame]
Vishal Bhoj82c80712015-12-15 21:13:33 +05301/** @file
2 EFI_USB_HC_PROTOCOL as defined in EFI 1.10.
3
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.
7
8 Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR>
9 This program and the accompanying materials
10 are licensed and made available under the terms and conditions of the BSD License
11 which accompanies this distribution. The full text of the license may be found at
12 http://opensource.org/licenses/bsd-license.php
13
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16
17**/
18
19#ifndef _USB_HOSTCONTROLLER_H_
20#define _USB_HOSTCONTROLLER_H_
21
22#include <Protocol/Usb2HostController.h>
23
24#define EFI_USB_HC_PROTOCOL_GUID \
25 { \
26 0xf5089266, 0x1aa0, 0x4953, {0x97, 0xd8, 0x56, 0x2f, 0x8a, 0x73, 0xb5, 0x19 } \
27 }
28
29///
30/// Forward reference for pure ANSI compatability
31///
32typedef struct _EFI_USB_HC_PROTOCOL EFI_USB_HC_PROTOCOL;
33
34//
35// Protocol definitions
36//
37
38/**
39 Provides software reset for the USB host controller.
40
41 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
42 @param Attributes A bit mask of the reset operation to perform.
43
44 @retval EFI_SUCCESS The reset operation succeeded.
45 @retval EFI_UNSUPPORTED The type of reset specified by Attributes is not currently supported
46 by the host controller hardware.
47 @retval EFI_INVALID_PARAMETER Attributes is not valid.
48 @retval EFI_DEVICE_ERROR An error was encountered while attempting to perform the reset operation.
49
50**/
51typedef
52EFI_STATUS
53(EFIAPI *EFI_USB_HC_PROTOCOL_RESET)(
54 IN EFI_USB_HC_PROTOCOL *This,
55 IN UINT16 Attributes
56 );
57
58/**
59 Retrieves current state of the USB host controller.
60
61 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
62 @param State A pointer to the EFI_USB_HC_STATE data structure that
63 indicates current state of the USB host controller.
64
65 @retval EFI_SUCCESS The state information of the host controller was returned in State.
66 @retval EFI_INVALID_PARAMETER State is NULL.
67 @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the host controller's
68 current state.
69
70**/
71typedef
72EFI_STATUS
73(EFIAPI *EFI_USB_HC_PROTOCOL_GET_STATE)(
74 IN EFI_USB_HC_PROTOCOL *This,
75 OUT EFI_USB_HC_STATE *State
76 );
77
78/**
79 Sets the USB host controller to a specific state.
80
81 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
82 @param State Indicates the state of the host controller that will be set.
83
84 @retval EFI_SUCCESS The USB host controller was successfully placed in the state specified by
85 State.
86 @retval EFI_INVALID_PARAMETER State is NULL.
87 @retval EFI_DEVICE_ERROR Failed to set the state specified by State due to device error.
88
89**/
90typedef
91EFI_STATUS
92(EFIAPI *EFI_USB_HC_PROTOCOL_SET_STATE)(
93 IN EFI_USB_HC_PROTOCOL *This,
94 IN EFI_USB_HC_STATE State
95 );
96
97/**
98 Submits control transfer to a target USB device.
99
100 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
101 @param DeviceAddress Represents the address of the target device on the USB, which is
102 assigned during USB enumeration.
103 @param IsSlowDevice Indicates whether the target device is slow device or full-speed
104 device.
105 @param MaximumPacketLength Indicates the maximum packet size that the default control
106 transfer endpoint is capable of sending or receiving.
107 @param Request A pointer to the USB device request that will be sent to the USB
108 device.
109 @param TransferDirection Specifies the data direction for the transfer. There are three
110 values available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData.
111 @param Data A pointer to the buffer of data that will be transmitted to USB
112 device or received from USB device.
113 @param DataLength On input, indicates the size, in bytes, of the data buffer specified
114 by Data. On output, indicates the amount of data actually
115 transferred.
116 @param TimeOut Indicates the maximum time, in milliseconds, which the transfer
117 is allowed to complete.
118 @param TransferResult A pointer to the detailed result information generated by this
119 control transfer.
120
121 @retval EFI_SUCCESS The control transfer was completed successfully.
122 @retval EFI_OUT_OF_RESOURCES The control transfer could not be completed due to a lack of resources.
123 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
124 @retval EFI_TIMEOUT The control transfer failed due to timeout.
125 @retval EFI_DEVICE_ERROR The control transfer failed due to host controller or device error.
126
127**/
128typedef
129EFI_STATUS
130(EFIAPI *EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER)(
131 IN EFI_USB_HC_PROTOCOL *This,
132 IN UINT8 DeviceAddress,
133 IN BOOLEAN IsSlowDevice,
134 IN UINT8 MaximumPacketLength,
135 IN EFI_USB_DEVICE_REQUEST *Request,
136 IN EFI_USB_DATA_DIRECTION TransferDirection,
137 IN OUT VOID *Data OPTIONAL,
138 IN OUT UINTN *DataLength OPTIONAL,
139 IN UINTN TimeOut,
140 OUT UINT32 *TransferResult
141 );
142
143/**
144 Submits bulk transfer to a bulk endpoint of a USB device.
145
146 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
147 @param DeviceAddress Represents the address of the target device on the USB, which is
148 assigned during USB enumeration.
149 @param EndPointAddress The combination of an endpoint number and an endpoint
150 direction of the target USB device. Each endpoint address
151 supports data transfer in one direction except the control
152 endpoint (whose default endpoint address is 0). It is the
153 caller's responsibility to make sure that the EndPointAddress
154 represents a bulk endpoint.
155 @param MaximumPacketLength Indicates the maximum packet size that the default control
156 transfer endpoint is capable of sending or receiving.
157 @param Data A pointer to the buffer of data that will be transmitted to USB
158 device or received from USB device.
159 @param DataLength On input, indicates the size, in bytes, of the data buffer specified
160 by Data. On output, indicates the amount of data actually
161 transferred.
162 @param DataToggle A pointer to the data toggle value.
163 @param TimeOut Indicates the maximum time, in milliseconds, which the transfer
164 is allowed to complete.
165 @param TransferResult A pointer to the detailed result information of the bulk transfer.
166
167 @retval EFI_SUCCESS The bulk transfer was completed successfully.
168 @retval EFI_OUT_OF_RESOURCES The bulk transfer could not be completed due to a lack of resources.
169 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
170 @retval EFI_TIMEOUT The bulk transfer failed due to timeout.
171 @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error.
172
173**/
174typedef
175EFI_STATUS
176(EFIAPI *EFI_USB_HC_PROTOCOL_BULK_TRANSFER)(
177 IN EFI_USB_HC_PROTOCOL *This,
178 IN UINT8 DeviceAddress,
179 IN UINT8 EndPointAddress,
180 IN UINT8 MaximumPacketLength,
181 IN OUT VOID *Data,
182 IN OUT UINTN *DataLength,
183 IN OUT UINT8 *DataToggle,
184 IN UINTN TimeOut,
185 OUT UINT32 *TransferResult
186 );
187
188/**
189 Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
190
191 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
192 @param DeviceAddress Represents the address of the target device on the USB, which is
193 assigned during USB enumeration.
194 @param EndPointAddress The combination of an endpoint number and an endpoint
195 direction of the target USB device. Each endpoint address
196 supports data transfer in one direction except the control
197 endpoint (whose default endpoint address is zero). It is the
198 caller's responsibility to make sure that the
199 EndPointAddress represents an interrupt endpoint.
200 @param IsSlowDevice Indicates whether the target device is slow device or full-speed
201 device.
202 @param MaximumPacketLength Indicates the maximum packet size that the default control
203 transfer endpoint is capable of sending or receiving.
204 @param IsNewTransfer If TRUE, an asynchronous interrupt pipe is built between the host
205 and the target interrupt endpoint. If FALSE, the specified asynchronous
206 interrupt pipe is canceled. If TRUE, and an interrupt transfer exists
207 for the target end point, then EFI_INVALID_PARAMETER is returned.
208 @param DataToggle A pointer to the data toggle value. On input, it is valid when
209 IsNewTransfer is TRUE, and it indicates the initial data toggle
210 value the asynchronous interrupt transfer should adopt. On output,
211 it is valid when IsNewTransfer is FALSE, and it is updated to indicate
212 the data toggle value of the subsequent asynchronous interrupt transfer.
213 @param PollingInterval Indicates the interval, in milliseconds, that the asynchronous
214 interrupt transfer is polled.
215 @param DataLength Indicates the length of data to be received at the rate specified by
216 PollingInterval from the target asynchronous interrupt
217 endpoint. This parameter is only required when IsNewTransfer is TRUE.
218 @param CallBackFunction The Callback function. This function is called at the rate specified by
219 PollingInterval. This parameter is only required when IsNewTransfer is TRUE.
220 @param Context The context that is passed to the CallBackFunction.
221
222 @retval EFI_SUCCESS The asynchronous interrupt transfer request has been successfully
223 submitted or canceled.
224 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
225 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
226 @retval EFI_TIMEOUT The bulk transfer failed due to timeout.
227 @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error.
228
229**/
230typedef
231EFI_STATUS
232(EFIAPI *EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER)(
233 IN EFI_USB_HC_PROTOCOL *This,
234 IN UINT8 DeviceAddress,
235 IN UINT8 EndPointAddress,
236 IN BOOLEAN IsSlowDevice,
237 IN UINT8 MaxiumPacketLength,
238 IN BOOLEAN IsNewTransfer,
239 IN OUT UINT8 *DataToggle,
240 IN UINTN PollingInterval OPTIONAL,
241 IN UINTN DataLength OPTIONAL,
242 IN EFI_ASYNC_USB_TRANSFER_CALLBACK CallBackFunction OPTIONAL,
243 IN VOID *Context OPTIONAL
244 );
245
246/**
247 Submits synchronous interrupt transfer to an interrupt endpoint of a USB device.
248
249 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
250 @param DeviceAddress Represents the address of the target device on the USB, which is
251 assigned during USB enumeration.
252 @param EndPointAddress The combination of an endpoint number and an endpoint
253 direction of the target USB device. Each endpoint address
254 supports data transfer in one direction except the control
255 endpoint (whose default endpoint address is zero). It is the
256 caller's responsibility to make sure that the
257 EndPointAddress represents an interrupt endpoint.
258 @param IsSlowDevice Indicates whether the target device is slow device or full-speed
259 device.
260 @param MaximumPacketLength Indicates the maximum packet size that the default control
261 transfer endpoint is capable of sending or receiving.
262 @param Data A pointer to the buffer of data that will be transmitted to USB
263 device or received from USB device. asynchronous interrupt pipe is canceled.
264 @param DataLength On input, the size, in bytes, of the data buffer specified by Data.
265 On output, the number of bytes transferred.
266 @param DataToggle A pointer to the data toggle value. On input, it indicates the initial
267 data toggle value the synchronous interrupt transfer should adopt;
268 on output, it is updated to indicate the data toggle value of the
269 subsequent synchronous interrupt transfer.
270 @param TimeOut Indicates the maximum time, in milliseconds, which the transfer
271 is allowed to complete.
272 @param TransferResult A pointer to the detailed result information from the synchronous
273 interrupt transfer.
274
275 @retval EFI_SUCCESS The synchronous interrupt transfer was completed successfully.
276 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
277 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
278 @retval EFI_TIMEOUT The synchronous interrupt transfer failed due to timeout.
279 @retval EFI_DEVICE_ERROR The synchronous interrupt transfer failed due to host controller or device error.
280
281**/
282typedef
283EFI_STATUS
284(EFIAPI *EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER)(
285 IN EFI_USB_HC_PROTOCOL *This,
286 IN UINT8 DeviceAddress,
287 IN UINT8 EndPointAddress,
288 IN BOOLEAN IsSlowDevice,
289 IN UINT8 MaximumPacketLength,
290 IN OUT VOID *Data,
291 IN OUT UINTN *DataLength,
292 IN OUT UINT8 *DataToggle,
293 IN UINTN TimeOut,
294 OUT UINT32 *TransferResult
295 );
296
297/**
298 Submits isochronous transfer to an isochronous endpoint of a USB device.
299
300 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
301 @param DeviceAddress Represents the address of the target device on the USB, which is
302 assigned during USB enumeration.
303 @param EndPointAddress The combination of an endpoint number and an endpoint
304 direction of the target USB device. Each endpoint address
305 supports data transfer in one direction except the control
306 endpoint (whose default endpoint address is 0). It is the caller's
307 responsibility to make sure that the EndPointAddress
308 represents an isochronous endpoint.
309 @param MaximumPacketLength Indicates the maximum packet size that the default control
310 transfer endpoint is capable of sending or receiving.
311 @param Data A pointer to the buffer of data that will be transmitted to USB
312 device or received from USB device. asynchronous interrupt pipe is canceled.
313 @param DataLength Specifies the length, in bytes, of the data to be sent to or received
314 from the USB device.
315 @param TransferResult A pointer to the detailed result information from the isochronous
316 transfer.
317
318 @retval EFI_SUCCESS The isochronous transfer was completed successfully.
319 @retval EFI_OUT_OF_RESOURCES The isochronous could not be completed due to a lack of resources.
320 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
321 @retval EFI_TIMEOUT The isochronous transfer failed due to timeout.
322 @retval EFI_DEVICE_ERROR The isochronous transfer failed due to host controller or device error.
323
324**/
325typedef
326EFI_STATUS
327(EFIAPI *EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER)(
328 IN EFI_USB_HC_PROTOCOL *This,
329 IN UINT8 DeviceAddress,
330 IN UINT8 EndPointAddress,
331 IN UINT8 MaximumPacketLength,
332 IN OUT VOID *Data,
333 IN UINTN DataLength,
334 OUT UINT32 *TransferResult
335 );
336
337/**
338 Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device.
339
340 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
341 @param DeviceAddress Represents the address of the target device on the USB, which is
342 assigned during USB enumeration.
343 @param EndPointAddress The combination of an endpoint number and an endpoint
344 direction of the target USB device. Each endpoint address
345 supports data transfer in one direction except the control
346 endpoint (whose default endpoint address is zero). It is the
347 caller's responsibility to make sure that the
348 EndPointAddress represents an isochronous endpoint.
349 @param MaximumPacketLength Indicates the maximum packet size that the default control
350 transfer endpoint is capable of sending or receiving. For isochronous
351 endpoints, this value is used to reserve the bus time in the schedule,
352 required for the perframe data payloads. The pipe may, on an ongoing basis,
353 actually use less bandwidth than that reserved.
354 @param Data A pointer to the buffer of data that will be transmitted to USB
355 device or received from USB device. asynchronous interrupt pipe is canceled.
356 @param DataLength Specifies the length, in bytes, of the data to be sent to or received
357 from the USB device.
358 @param IsochronousCallback The Callback function.This function is called if the requested
359 isochronous transfer is completed.
360 @param Context Data passed to the IsochronousCallback function. This is
361 an optional parameter and may be NULL.
362
363 @retval EFI_SUCCESS The asynchronous isochronous transfer was completed successfully.
364 @retval EFI_OUT_OF_RESOURCES The asynchronous isochronous could not be completed due to a lack of resources.
365 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
366
367**/
368typedef
369EFI_STATUS
370(EFIAPI *EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER)(
371 IN EFI_USB_HC_PROTOCOL *This,
372 IN UINT8 DeviceAddress,
373 IN UINT8 EndPointAddress,
374 IN UINT8 MaximumPacketLength,
375 IN OUT VOID *Data,
376 IN UINTN DataLength,
377 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack,
378 IN VOID *Context OPTIONAL
379 );
380
381/**
382 Retrieves the number of root hub ports.
383
384 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
385 @param PortNumber A pointer to the number of the root hub ports.
386
387 @retval EFI_SUCCESS The port number was retrieved successfully.
388 @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the port number.
389 @retval EFI_INVALID_PARAMETER PortNumber is NULL.
390
391**/
392typedef
393EFI_STATUS
394(EFIAPI *EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER)(
395 IN EFI_USB_HC_PROTOCOL *This,
396 OUT UINT8 *PortNumber
397 );
398
399/**
400 Retrieves the current status of a USB root hub port.
401
402 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
403 @param PortNumber Specifies the root hub port from which the status is to be retrieved.
404 This value is zero based. For example, if a root hub has two ports,
405 then the first port is numbered 0, and the second port is
406 numbered 1.
407 @param PortStatus A pointer to the current port status bits and port status change bits.
408
409 @retval EFI_SUCCESS The status of the USB root hub port specified by PortNumber
410 was returned in PortStatus.
411 @retval EFI_INVALID_PARAMETER PortNumber is invalid.
412
413**/
414typedef
415EFI_STATUS
416(EFIAPI *EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS)(
417 IN EFI_USB_HC_PROTOCOL *This,
418 IN UINT8 PortNumber,
419 OUT EFI_USB_PORT_STATUS *PortStatus
420 );
421
422/**
423 Sets a feature for the specified root hub port.
424
425 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
426 @param PortNumber Specifies the root hub port from which the status is to be retrieved.
427 This value is zero based. For example, if a root hub has two ports,
428 then the first port is numbered 0, and the second port is
429 numbered 1.
430 @param PortFeature Indicates the feature selector associated with the feature set
431 request.
432
433 @retval EFI_SUCCESS The feature specified by PortFeature was set for the USB
434 root hub port specified by PortNumber.
435 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.
436
437**/
438typedef
439EFI_STATUS
440(EFIAPI *EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE)(
441 IN EFI_USB_HC_PROTOCOL *This,
442 IN UINT8 PortNumber,
443 IN EFI_USB_PORT_FEATURE PortFeature
444 );
445
446/**
447 Clears a feature for the specified root hub port.
448
449 @param This A pointer to the EFI_USB_HC_PROTOCOL instance.
450 @param PortNumber Specifies the root hub port from which the status is to be retrieved.
451 This value is zero based. For example, if a root hub has two ports,
452 then the first port is numbered 0, and the second port is
453 numbered 1.
454 @param PortFeature Indicates the feature selector associated with the feature clear
455 request.
456
457 @retval EFI_SUCCESS The feature specified by PortFeature was cleared for the USB
458 root hub port specified by PortNumber.
459 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.
460
461**/
462typedef
463EFI_STATUS
464(EFIAPI *EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE)(
465 IN EFI_USB_HC_PROTOCOL *This,
466 IN UINT8 PortNumber,
467 IN EFI_USB_PORT_FEATURE PortFeature
468 );
469
470
471///
472/// The EFI_USB_HC_PROTOCOL provides USB host controller management, basic data transactions
473/// over a USB bus, and USB root hub access. A device driver that wishes to manage a USB bus in a
474/// system retrieves the EFI_USB_HC_PROTOCOL instance that is associated with the USB bus to be
475/// managed. A device handle for a USB host controller will minimally contain an
476/// EFI_DEVICE_PATH_PROTOCOL instance, and an EFI_USB_HC_PROTOCOL instance.
477///
478struct _EFI_USB_HC_PROTOCOL {
479 EFI_USB_HC_PROTOCOL_RESET Reset;
480 EFI_USB_HC_PROTOCOL_GET_STATE GetState;
481 EFI_USB_HC_PROTOCOL_SET_STATE SetState;
482 EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER ControlTransfer;
483 EFI_USB_HC_PROTOCOL_BULK_TRANSFER BulkTransfer;
484 EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER AsyncInterruptTransfer;
485 EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER SyncInterruptTransfer;
486 EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER IsochronousTransfer;
487 EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER AsyncIsochronousTransfer;
488 EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER GetRootHubPortNumber;
489 EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus;
490 EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature;
491 EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature;
492 ///
493 /// The major 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.
496 ///
497 UINT16 MajorRevision;
498 ///
499 /// The minor revision number of the USB host controller. The revision information
500 /// indicates the release of the Universal Serial Bus Specification with which the
501 /// host controller is compliant.
502 ///
503 UINT16 MinorRevision;
504};
505
506extern EFI_GUID gEfiUsbHcProtocolGuid;
507
508#endif