← Back to branch summary

~pmdj/ubuntu/trusty/qemu/2.9+applesmc+fadtv3

« back to all changes in this revision

Viewing changes to roms/ipxe/src/include/ipxe/efi/Protocol/Usb2HostController.h

  • Committer: Phil Dennis-Jordan
  • Date: 2017-07-21 08:03:43 UTC
  • mfrom: (1.1.1)
  • Revision ID: phil@philjordan.eu-20170721080343-2yr2vdj7713czahv
New upstream release 2.9.0.

Show diffs side-by-side

added added

removed removed

Lines of Context:
roms/ipxe/src/include/ipxe/efi/Protocol/Usb2HostController.h
 
1
/** @file
 
2
  EFI_USB2_HC_PROTOCOL as defined in UEFI 2.0.
 
3
  The USB Host Controller Protocol is used by code, typically USB bus drivers,
 
4
  running in the EFI boot services environment, to perform data transactions over
 
5
  a USB bus. In addition, it provides an abstraction for the root hub of the USB bus.
 
6
 
 
7
  Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR>
 
8
  This program and the accompanying materials
 
9
  are licensed and made available under the terms and conditions of the BSD License
 
10
  which accompanies this distribution.  The full text of the license may be found at
 
11
  http://opensource.org/licenses/bsd-license.php
 
12
 
 
13
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
 
14
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
15
 
 
16
**/
 
17
 
 
18
#ifndef _USB2_HOSTCONTROLLER_H_
 
19
#define _USB2_HOSTCONTROLLER_H_
 
20
 
 
21
FILE_LICENCE ( BSD3 );
 
22
 
 
23
#include <ipxe/efi/Protocol/UsbIo.h>
 
24
 
 
25
#define EFI_USB2_HC_PROTOCOL_GUID \
 
26
  { \
 
27
    0x3e745226, 0x9818, 0x45b6, {0xa2, 0xac, 0xd7, 0xcd, 0xe, 0x8b, 0xa2, 0xbc } \
 
28
  }
 
29
 
 
30
///
 
31
/// Forward reference for pure ANSI compatability
 
32
///
 
33
typedef struct _EFI_USB2_HC_PROTOCOL EFI_USB2_HC_PROTOCOL;
 
34
 
 
35
 
 
36
typedef struct {
 
37
  UINT16          PortStatus;        ///< Contains current port status bitmap.
 
38
  UINT16          PortChangeStatus;  ///< Contains current port status change bitmap.
 
39
} EFI_USB_PORT_STATUS;
 
40
 
 
41
///
 
42
/// EFI_USB_PORT_STATUS.PortStatus bit definition
 
43
///
 
44
#define USB_PORT_STAT_CONNECTION    0x0001
 
45
#define USB_PORT_STAT_ENABLE        0x0002
 
46
#define USB_PORT_STAT_SUSPEND       0x0004
 
47
#define USB_PORT_STAT_OVERCURRENT   0x0008
 
48
#define USB_PORT_STAT_RESET         0x0010
 
49
#define USB_PORT_STAT_POWER         0x0100
 
50
#define USB_PORT_STAT_LOW_SPEED     0x0200
 
51
#define USB_PORT_STAT_HIGH_SPEED    0x0400
 
52
#define USB_PORT_STAT_SUPER_SPEED   0x0800
 
53
#define USB_PORT_STAT_OWNER         0x2000
 
54
 
 
55
///
 
56
/// EFI_USB_PORT_STATUS.PortChangeStatus bit definition
 
57
///
 
58
#define USB_PORT_STAT_C_CONNECTION  0x0001
 
59
#define USB_PORT_STAT_C_ENABLE      0x0002
 
60
#define USB_PORT_STAT_C_SUSPEND     0x0004
 
61
#define USB_PORT_STAT_C_OVERCURRENT 0x0008
 
62
#define USB_PORT_STAT_C_RESET       0x0010
 
63
 
 
64
 
 
65
///
 
66
/// Usb port features value
 
67
/// Each value indicates its bit index in the port status and status change bitmaps,
 
68
/// if combines these two bitmaps into a 32-bit bitmap.
 
69
///
 
70
typedef enum {
 
71
  EfiUsbPortEnable            = 1,
 
72
  EfiUsbPortSuspend           = 2,
 
73
  EfiUsbPortReset             = 4,
 
74
  EfiUsbPortPower             = 8,
 
75
  EfiUsbPortOwner             = 13,
 
76
  EfiUsbPortConnectChange     = 16,
 
77
  EfiUsbPortEnableChange      = 17,
 
78
  EfiUsbPortSuspendChange     = 18,
 
79
  EfiUsbPortOverCurrentChange = 19,
 
80
  EfiUsbPortResetChange       = 20
 
81
} EFI_USB_PORT_FEATURE;
 
82
 
 
83
#define EFI_USB_SPEED_FULL      0x0000  ///< 12 Mb/s, USB 1.1 OHCI and UHCI HC.
 
84
#define EFI_USB_SPEED_LOW       0x0001  ///< 1 Mb/s, USB 1.1 OHCI and UHCI HC.
 
85
#define EFI_USB_SPEED_HIGH      0x0002  ///< 480 Mb/s, USB 2.0 EHCI HC.
 
86
#define EFI_USB_SPEED_SUPER     0x0003  ///< 4.8 Gb/s, USB 3.0 XHCI HC.
 
87
 
 
88
typedef struct {
 
89
  UINT8      TranslatorHubAddress; ///< device address
 
90
  UINT8      TranslatorPortNumber; ///< the port number of the hub that device is connected to.
 
91
} EFI_USB2_HC_TRANSACTION_TRANSLATOR;
 
92
 
 
93
//
 
94
// Protocol definitions
 
95
//
 
96
 
 
97
/**
 
98
  Retrieves the Host Controller capabilities.
 
99
 
 
100
  @param  This           A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
101
  @param  MaxSpeed       Host controller data transfer speed.
 
102
  @param  PortNumber     Number of the root hub ports.
 
103
  @param  Is64BitCapable TRUE if controller supports 64-bit memory addressing,
 
104
                         FALSE otherwise.
 
105
 
 
106
  @retval EFI_SUCCESS           The host controller capabilities were retrieved successfully.
 
107
  @retval EFI_INVALID_PARAMETER One of the input args was NULL.
 
108
  @retval EFI_DEVICE_ERROR      An error was encountered while attempting to
 
109
                                retrieve the capabilities.
 
110
 
 
111
**/
 
112
typedef
 
113
EFI_STATUS
 
114
(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_CAPABILITY)(
 
115
  IN  EFI_USB2_HC_PROTOCOL  *This,
 
116
  OUT UINT8                 *MaxSpeed,
 
117
  OUT UINT8                 *PortNumber,
 
118
  OUT UINT8                 *Is64BitCapable
 
119
  );
 
120
 
 
121
#define EFI_USB_HC_RESET_GLOBAL             0x0001
 
122
#define EFI_USB_HC_RESET_HOST_CONTROLLER    0x0002
 
123
#define EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG  0x0004
 
124
#define EFI_USB_HC_RESET_HOST_WITH_DEBUG    0x0008
 
125
/**
 
126
  Provides software reset for the USB host controller.
 
127
 
 
128
  @param  This       A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
129
  @param  Attributes A bit mask of the reset operation to perform.
 
130
 
 
131
  @retval EFI_SUCCESS           The reset operation succeeded.
 
132
  @retval EFI_INVALID_PARAMETER Attributes is not valid.
 
133
  @retval EFI_UNSUPPORTED       The type of reset specified by Attributes is not currently
 
134
                                supported by the host controller hardware.
 
135
  @retval EFI_ACCESS_DENIED     Reset operation is rejected due to the debug port being configured
 
136
                                and active; only EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG or
 
137
                                EFI_USB_HC_RESET_HOST_WITH_DEBUG reset Attributes can be used to
 
138
                                perform reset operation for this host controller.
 
139
  @retval EFI_DEVICE_ERROR      An error was encountered while attempting to
 
140
                                retrieve the capabilities.
 
141
 
 
142
**/
 
143
typedef
 
144
EFI_STATUS
 
145
(EFIAPI *EFI_USB2_HC_PROTOCOL_RESET)(
 
146
  IN EFI_USB2_HC_PROTOCOL   *This,
 
147
  IN UINT16                 Attributes
 
148
  );
 
149
 
 
150
/**
 
151
  Enumration value for status of USB HC.
 
152
**/
 
153
typedef enum {
 
154
  EfiUsbHcStateHalt,                ///< The host controller is in halt
 
155
                                    ///< state. No USB transactions can occur
 
156
                                    ///< while in this state. The host
 
157
                                    ///< controller can enter this state for
 
158
                                    ///< three reasons: 1) After host
 
159
                                    ///< controller hardware reset. 2)
 
160
                                    ///< Explicitly set by software. 3)
 
161
                                    ///< Triggered by a fatal error such as
 
162
                                    ///< consistency check failure.
 
163
 
 
164
  EfiUsbHcStateOperational,         ///< The host controller is in an
 
165
                                    ///< operational state. When in
 
166
                                    ///< this state, the host
 
167
                                    ///< controller can execute bus
 
168
                                    ///< traffic. This state must be
 
169
                                    ///< explicitly set to enable the
 
170
                                    ///< USB bus traffic.
 
171
 
 
172
  EfiUsbHcStateSuspend,             ///< The host controller is in the
 
173
                                    ///< suspend state. No USB
 
174
                                    ///< transactions can occur while in
 
175
                                    ///< this state. The host controller
 
176
                                    ///< enters this state for the
 
177
                                    ///< following reasons: 1) Explicitly
 
178
                                    ///< set by software. 2) Triggered
 
179
                                    ///< when there is no bus traffic for
 
180
                                    ///< 3 microseconds.
 
181
 
 
182
  EfiUsbHcStateMaximum              ///< Maximum value for enumration value of HC status.
 
183
} EFI_USB_HC_STATE;
 
184
 
 
185
/**
 
186
  Retrieves current state of the USB host controller.
 
187
 
 
188
  @param  This  A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
189
  @param  State A pointer to the EFI_USB_HC_STATE data structure that
 
190
                indicates current state of the USB host controller.
 
191
 
 
192
  @retval EFI_SUCCESS           The state information of the host controller was returned in State.
 
193
  @retval EFI_INVALID_PARAMETER State is NULL.
 
194
  @retval EFI_DEVICE_ERROR      An error was encountered while attempting to retrieve the
 
195
                                host controller's current state.
 
196
 
 
197
**/
 
198
typedef
 
199
EFI_STATUS
 
200
(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_STATE)(
 
201
  IN        EFI_USB2_HC_PROTOCOL    *This,
 
202
  OUT       EFI_USB_HC_STATE        *State
 
203
);
 
204
 
 
205
/**
 
206
  Sets the USB host controller to a specific state.
 
207
 
 
208
  @param  This  A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
209
  @param  State Indicates the state of the host controller that will be set.
 
210
 
 
211
  @retval EFI_SUCCESS           The USB host controller was successfully placed in the state
 
212
                                specified by State.
 
213
  @retval EFI_INVALID_PARAMETER State is not valid.
 
214
  @retval EFI_DEVICE_ERROR      Failed to set the state specified by State due to device error.
 
215
 
 
216
**/
 
217
typedef
 
218
EFI_STATUS
 
219
(EFIAPI *EFI_USB2_HC_PROTOCOL_SET_STATE)(
 
220
  IN EFI_USB2_HC_PROTOCOL    *This,
 
221
  IN EFI_USB_HC_STATE        State
 
222
  );
 
223
 
 
224
/**
 
225
  Submits control transfer to a target USB device.
 
226
 
 
227
  @param  This                A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
228
  @param  DeviceAddress       Represents the address of the target device on the USB.
 
229
  @param  DeviceSpeed         Indicates device speed.
 
230
  @param  MaximumPacketLength Indicates the maximum packet size that the default control transfer
 
231
                              endpoint is capable of sending or receiving.
 
232
  @param  Request             A pointer to the USB device request that will be sent to the USB device.
 
233
  @param  TransferDirection   Specifies the data direction for the transfer. There are three values
 
234
                              available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData.
 
235
  @param  Data                A pointer to the buffer of data that will be transmitted to USB device or
 
236
                              received from USB device.
 
237
  @param  DataLength          On input, indicates the size, in bytes, of the data buffer specified by Data.
 
238
                              On output, indicates the amount of data actually transferred.
 
239
  @param  TimeOut             Indicates the maximum time, in milliseconds, which the transfer is
 
240
                              allowed to complete.
 
241
  @param  Translator          A pointer to the transaction translator data.
 
242
  @param  TransferResult      A pointer to the detailed result information generated by this control
 
243
                              transfer.
 
244
 
 
245
  @retval EFI_SUCCESS           The control transfer was completed successfully.
 
246
  @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 
247
  @retval EFI_OUT_OF_RESOURCES  The control transfer could not be completed due to a lack of resources.
 
248
  @retval EFI_TIMEOUT           The control transfer failed due to timeout.
 
249
  @retval EFI_DEVICE_ERROR      The control transfer failed due to host controller or device error.
 
250
                                Caller should check TransferResult for detailed error information.
 
251
 
 
252
**/
 
253
typedef
 
254
EFI_STATUS
 
255
(EFIAPI *EFI_USB2_HC_PROTOCOL_CONTROL_TRANSFER)(
 
256
  IN     EFI_USB2_HC_PROTOCOL               *This,
 
257
  IN     UINT8                              DeviceAddress,
 
258
  IN     UINT8                              DeviceSpeed,
 
259
  IN     UINTN                              MaximumPacketLength,
 
260
  IN     EFI_USB_DEVICE_REQUEST             *Request,
 
261
  IN     EFI_USB_DATA_DIRECTION             TransferDirection,
 
262
  IN OUT VOID                               *Data       OPTIONAL,
 
263
  IN OUT UINTN                              *DataLength OPTIONAL,
 
264
  IN     UINTN                              TimeOut,
 
265
  IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,
 
266
  OUT    UINT32                             *TransferResult
 
267
  );
 
268
 
 
269
#define EFI_USB_MAX_BULK_BUFFER_NUM 10
 
270
 
 
271
/**
 
272
  Submits bulk transfer to a bulk endpoint of a USB device.
 
273
 
 
274
  @param  This                A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
275
  @param  DeviceAddress       Represents the address of the target device on the USB.
 
276
  @param  EndPointAddress     The combination of an endpoint number and an endpoint direction of the
 
277
                              target USB device.
 
278
  @param  DeviceSpeed         Indicates device speed.
 
279
  @param  MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of
 
280
                              sending or receiving.
 
281
  @param  DataBuffersNumber   Number of data buffers prepared for the transfer.
 
282
  @param  Data                Array of pointers to the buffers of data that will be transmitted to USB
 
283
                              device or received from USB device.
 
284
  @param  DataLength          When input, indicates the size, in bytes, of the data buffers specified by
 
285
                              Data. When output, indicates the actually transferred data size.
 
286
  @param  DataToggle          A pointer to the data toggle value.
 
287
  @param  TimeOut             Indicates the maximum time, in milliseconds, which the transfer is
 
288
                              allowed to complete.
 
289
  @param  Translator          A pointer to the transaction translator data.
 
290
  @param  TransferResult      A pointer to the detailed result information of the bulk transfer.
 
291
 
 
292
  @retval EFI_SUCCESS           The bulk transfer was completed successfully.
 
293
  @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 
294
  @retval EFI_OUT_OF_RESOURCES  The bulk transfer could not be submitted due to a lack of resources.
 
295
  @retval EFI_TIMEOUT           The bulk transfer failed due to timeout.
 
296
  @retval EFI_DEVICE_ERROR      The bulk transfer failed due to host controller or device error.
 
297
                                Caller should check TransferResult for detailed error information.
 
298
 
 
299
**/
 
300
typedef
 
301
EFI_STATUS
 
302
(EFIAPI *EFI_USB2_HC_PROTOCOL_BULK_TRANSFER)(
 
303
  IN     EFI_USB2_HC_PROTOCOL               *This,
 
304
  IN     UINT8                              DeviceAddress,
 
305
  IN     UINT8                              EndPointAddress,
 
306
  IN     UINT8                              DeviceSpeed,
 
307
  IN     UINTN                              MaximumPacketLength,
 
308
  IN     UINT8                              DataBuffersNumber,
 
309
  IN OUT VOID                               *Data[EFI_USB_MAX_BULK_BUFFER_NUM],
 
310
  IN OUT UINTN                              *DataLength,
 
311
  IN OUT UINT8                              *DataToggle,
 
312
  IN     UINTN                              TimeOut,
 
313
  IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,
 
314
  OUT    UINT32                             *TransferResult
 
315
  );
 
316
 
 
317
/**
 
318
  Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
 
319
  Translator parameter doesn't exist in UEFI2.0 spec, but it will be updated in the following specification version.
 
320
 
 
321
  @param  This                A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
322
  @param  DeviceAddress       Represents the address of the target device on the USB.
 
323
  @param  EndPointAddress     The combination of an endpoint number and an endpoint direction of the
 
324
                              target USB device.
 
325
  @param  DeviceSpeed         Indicates device speed.
 
326
  @param  MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of
 
327
                              sending or receiving.
 
328
  @param  IsNewTransfer       If TRUE, an asynchronous interrupt pipe is built between the host and the
 
329
                              target interrupt endpoint. If FALSE, the specified asynchronous interrupt
 
330
                              pipe is canceled. If TRUE, and an interrupt transfer exists for the target
 
331
                              end point, then EFI_INVALID_PARAMETER is returned.
 
332
  @param  DataToggle          A pointer to the data toggle value.
 
333
  @param  PollingInterval     Indicates the interval, in milliseconds, that the asynchronous interrupt
 
334
                              transfer is polled.
 
335
  @param  DataLength          Indicates the length of data to be received at the rate specified by
 
336
                              PollingInterval from the target asynchronous interrupt endpoint.
 
337
  @param  Translator          A pointr to the transaction translator data.
 
338
  @param  CallBackFunction    The Callback function. This function is called at the rate specified by
 
339
                              PollingInterval.
 
340
  @param  Context             The context that is passed to the CallBackFunction. This is an
 
341
                              optional parameter and may be NULL.
 
342
 
 
343
  @retval EFI_SUCCESS           The asynchronous interrupt transfer request has been successfully
 
344
                                submitted or canceled.
 
345
  @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 
346
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 
347
 
 
348
**/
 
349
typedef
 
350
EFI_STATUS
 
351
(EFIAPI *EFI_USB2_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER)(
 
352
  IN     EFI_USB2_HC_PROTOCOL                                *This,
 
353
  IN     UINT8                                               DeviceAddress,
 
354
  IN     UINT8                                               EndPointAddress,
 
355
  IN     UINT8                                               DeviceSpeed,
 
356
  IN     UINTN                                               MaxiumPacketLength,
 
357
  IN     BOOLEAN                                             IsNewTransfer,
 
358
  IN OUT UINT8                                               *DataToggle,
 
359
  IN     UINTN                                               PollingInterval  OPTIONAL,
 
360
  IN     UINTN                                               DataLength       OPTIONAL,
 
361
  IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR                  *Translator      OPTIONAL,
 
362
  IN     EFI_ASYNC_USB_TRANSFER_CALLBACK                     CallBackFunction OPTIONAL,
 
363
  IN     VOID                                                *Context         OPTIONAL
 
364
  );
 
365
 
 
366
/**
 
367
  Submits synchronous interrupt transfer to an interrupt endpoint of a USB device.
 
368
  Translator parameter doesn't exist in UEFI2.0 spec, but it will be updated in the following specification version.
 
369
 
 
370
  @param  This                  A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
371
  @param  DeviceAddress         Represents the address of the target device on the USB.
 
372
  @param  EndPointAddress       The combination of an endpoint number and an endpoint direction of the
 
373
                                target USB device.
 
374
  @param  DeviceSpeed           Indicates device speed.
 
375
  @param  MaximumPacketLength   Indicates the maximum packet size the target endpoint is capable of
 
376
                                sending or receiving.
 
377
  @param  Data                  A pointer to the buffer of data that will be transmitted to USB device or
 
378
                                received from USB device.
 
379
  @param  DataLength            On input, the size, in bytes, of the data buffer specified by Data. On
 
380
                                output, the number of bytes transferred.
 
381
  @param  DataToggle            A pointer to the data toggle value.
 
382
  @param  TimeOut               Indicates the maximum time, in milliseconds, which the transfer is
 
383
                                allowed to complete.
 
384
  @param  Translator            A pointr to the transaction translator data.
 
385
  @param  TransferResult        A pointer to the detailed result information from the synchronous
 
386
                                interrupt transfer.
 
387
 
 
388
  @retval EFI_SUCCESS           The synchronous interrupt transfer was completed successfully.
 
389
  @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 
390
  @retval EFI_OUT_OF_RESOURCES  The synchronous interrupt transfer could not be submitted due to a lack of resources.
 
391
  @retval EFI_TIMEOUT           The synchronous interrupt transfer failed due to timeout.
 
392
  @retval EFI_DEVICE_ERROR      The synchronous interrupt transfer failed due to host controller or device error.
 
393
                                Caller should check TransferResult for detailed error information.
 
394
 
 
395
**/
 
396
typedef
 
397
EFI_STATUS
 
398
(EFIAPI *EFI_USB2_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER)(
 
399
  IN     EFI_USB2_HC_PROTOCOL                        *This,
 
400
  IN     UINT8                                       DeviceAddress,
 
401
  IN     UINT8                                       EndPointAddress,
 
402
  IN     UINT8                                       DeviceSpeed,
 
403
  IN     UINTN                                       MaximumPacketLength,
 
404
  IN OUT VOID                                        *Data,
 
405
  IN OUT UINTN                                       *DataLength,
 
406
  IN OUT UINT8                                       *DataToggle,
 
407
  IN     UINTN                                       TimeOut,
 
408
  IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR          *Translator,
 
409
  OUT    UINT32                                      *TransferResult
 
410
  );
 
411
 
 
412
#define EFI_USB_MAX_ISO_BUFFER_NUM  7
 
413
#define EFI_USB_MAX_ISO_BUFFER_NUM1 2
 
414
 
 
415
/**
 
416
  Submits isochronous transfer to an isochronous endpoint of a USB device.
 
417
 
 
418
  This function is used to submit isochronous transfer to a target endpoint of a USB device.
 
419
  The target endpoint is specified by DeviceAddressand EndpointAddress. Isochronous transfers are
 
420
  used when working with isochronous date. It provides periodic, continuous communication between
 
421
  the host and a device. Isochronous transfers can beused only by full-speed, high-speed, and
 
422
  super-speed devices.
 
423
 
 
424
  High-speed isochronous transfers can be performed using multiple data buffers. The number of
 
425
  buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For
 
426
  full-speed isochronous transfers this value is ignored.
 
427
 
 
428
  Data represents a list of pointers to the data buffers. For full-speed isochronous transfers
 
429
  only the data pointed by Data[0]shall be used. For high-speed isochronous transfers and for
 
430
  the split transactions depending on DataLengththere several data buffers canbe used. For the
 
431
  high-speed isochronous transfers the total number of buffers must not exceed EFI_USB_MAX_ISO_BUFFER_NUM.
 
432
 
 
433
  For split transactions performed on full-speed device by high-speed host controller the total
 
434
  number of buffers is limited to EFI_USB_MAX_ISO_BUFFER_NUM1.
 
435
  If the isochronous transfer is successful, then EFI_SUCCESSis returned. The isochronous transfer
 
436
  is designed to be completed within one USB frame time, if it cannot be completed, EFI_TIMEOUT
 
437
  is returned. If an error other than timeout occurs during the USB transfer, then EFI_DEVICE_ERROR
 
438
  is returned and the detailed status code will be returned in TransferResult.
 
439
 
 
440
  EFI_INVALID_PARAMETERis returned if one of the following conditionsis satisfied:
 
441
    - Data is NULL.
 
442
    - DataLength is 0.
 
443
    - DeviceSpeed is not one of the supported values listed above.
 
444
    - MaximumPacketLength is invalid. MaximumPacketLength must be 1023 or less for full-speed devices,
 
445
      and 1024 or less for high-speed and super-speed devices.
 
446
    - TransferResult is NULL.
 
447
 
 
448
  @param  This                  A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
449
  @param  DeviceAddress         Represents the address of the target device on the USB.
 
450
  @param  EndPointAddress       The combination of an endpoint number and an endpoint direction of the
 
451
                                target USB device.
 
452
  @param  DeviceSpeed           Indicates device speed. The supported values are EFI_USB_SPEED_FULL,
 
453
                                EFI_USB_SPEED_HIGH, or EFI_USB_SPEED_SUPER.
 
454
  @param  MaximumPacketLength   Indicates the maximum packet size the target endpoint is capable of
 
455
                                sending or receiving.
 
456
  @param  DataBuffersNumber     Number of data buffers prepared for the transfer.
 
457
  @param  Data                  Array of pointers to the buffers of data that will be transmitted to USB
 
458
                                device or received from USB device.
 
459
  @param  DataLength            Specifies the length, in bytes, of the data to be sent to or received from
 
460
                                the USB device.
 
461
  @param  Translator            A pointer to the transaction translator data.
 
462
  @param  TransferResult        A pointer to the detailed result information of the isochronous transfer.
 
463
 
 
464
  @retval EFI_SUCCESS           The isochronous transfer was completed successfully.
 
465
  @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 
466
  @retval EFI_OUT_OF_RESOURCES  The isochronous transfer could not be submitted due to a lack of resources.
 
467
  @retval EFI_TIMEOUT           The isochronous transfer cannot be completed within the one USB frame time.
 
468
  @retval EFI_DEVICE_ERROR      The isochronous transfer failed due to host controller or device error.
 
469
                                Caller should check TransferResult for detailed error information.
 
470
 
 
471
**/
 
472
typedef
 
473
EFI_STATUS
 
474
(EFIAPI *EFI_USB2_HC_PROTOCOL_ISOCHRONOUS_TRANSFER)(
 
475
  IN     EFI_USB2_HC_PROTOCOL               *This,
 
476
  IN     UINT8                              DeviceAddress,
 
477
  IN     UINT8                              EndPointAddress,
 
478
  IN     UINT8                              DeviceSpeed,
 
479
  IN     UINTN                              MaximumPacketLength,
 
480
  IN     UINT8                              DataBuffersNumber,
 
481
  IN OUT VOID                               *Data[EFI_USB_MAX_ISO_BUFFER_NUM],
 
482
  IN     UINTN                              DataLength,
 
483
  IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,
 
484
  OUT    UINT32                             *TransferResult
 
485
  );
 
486
 
 
487
/**
 
488
  Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device.
 
489
 
 
490
  This is an asynchronous type of USB isochronous transfer. If the caller submits a USB
 
491
  isochronous transfer request through this function, this function will return immediately.
 
492
 
 
493
  When the isochronous transfer completes, the IsochronousCallbackfunction will be triggered,
 
494
  the caller can know the transfer results. If the transfer is successful, the caller can get
 
495
  the data received or sent in this callback function.
 
496
 
 
497
  The target endpoint is specified by DeviceAddressand EndpointAddress. Isochronous transfers
 
498
  are used when working with isochronous date. It provides periodic, continuous communication
 
499
  between the host and a device. Isochronous transfers can be used only by full-speed, high-speed,
 
500
  and super-speed devices.
 
501
 
 
502
  High-speed isochronous transfers can be performed using multiple data buffers. The number of
 
503
  buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For
 
504
  full-speed isochronous transfers this value is ignored.
 
505
 
 
506
  Data represents a list of pointers to the data buffers. For full-speed isochronous transfers
 
507
  only the data pointed by Data[0] shall be used. For high-speed isochronous transfers and for
 
508
  the split transactions depending on DataLength there several data buffers can be used. For
 
509
  the high-speed isochronous transfers the total number of buffers must not exceed EFI_USB_MAX_ISO_BUFFER_NUM.
 
510
 
 
511
  For split transactions performed on full-speed device by high-speed host controller the total
 
512
  number of buffers is limited to EFI_USB_MAX_ISO_BUFFER_NUM1.
 
513
 
 
514
  EFI_INVALID_PARAMETER is returned if one of the following conditionsis satisfied:
 
515
    - Data is NULL.
 
516
    - DataLength is 0.
 
517
    - DeviceSpeed is not one of the supported values listed above.
 
518
    - MaximumPacketLength is invalid. MaximumPacketLength must be 1023 or less for full-speed
 
519
      devices and 1024 or less for high-speed and super-speed devices.
 
520
 
 
521
  @param  This                  A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
522
  @param  DeviceAddress         Represents the address of the target device on the USB.
 
523
  @param  EndPointAddress       The combination of an endpoint number and an endpoint direction of the
 
524
                                target USB device.
 
525
  @param  DeviceSpeed           Indicates device speed. The supported values are EFI_USB_SPEED_FULL,
 
526
                                EFI_USB_SPEED_HIGH, or EFI_USB_SPEED_SUPER.
 
527
  @param  MaximumPacketLength   Indicates the maximum packet size the target endpoint is capable of
 
528
                                sending or receiving.
 
529
  @param  DataBuffersNumber     Number of data buffers prepared for the transfer.
 
530
  @param  Data                  Array of pointers to the buffers of data that will be transmitted to USB
 
531
                                device or received from USB device.
 
532
  @param  DataLength            Specifies the length, in bytes, of the data to be sent to or received from
 
533
                                the USB device.
 
534
  @param  Translator            A pointer to the transaction translator data.
 
535
  @param  IsochronousCallback   The Callback function. This function is called if the requested
 
536
                                isochronous transfer is completed.
 
537
  @param  Context               Data passed to the IsochronousCallback function. This is an
 
538
                                optional parameter and may be NULL.
 
539
 
 
540
  @retval EFI_SUCCESS           The asynchronous isochronous transfer request has been successfully
 
541
                                submitted or canceled.
 
542
  @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 
543
  @retval EFI_OUT_OF_RESOURCES  The asynchronous isochronous transfer could not be submitted due to
 
544
                                a lack of resources.
 
545
 
 
546
**/
 
547
typedef
 
548
EFI_STATUS
 
549
(EFIAPI *EFI_USB2_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER)(
 
550
  IN     EFI_USB2_HC_PROTOCOL               *This,
 
551
  IN     UINT8                              DeviceAddress,
 
552
  IN     UINT8                              EndPointAddress,
 
553
  IN     UINT8                              DeviceSpeed,
 
554
  IN     UINTN                              MaximumPacketLength,
 
555
  IN     UINT8                              DataBuffersNumber,
 
556
  IN OUT VOID                               *Data[EFI_USB_MAX_ISO_BUFFER_NUM],
 
557
  IN     UINTN                              DataLength,
 
558
  IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,
 
559
  IN     EFI_ASYNC_USB_TRANSFER_CALLBACK    IsochronousCallBack,
 
560
  IN     VOID                               *Context OPTIONAL
 
561
  );
 
562
 
 
563
/**
 
564
  Retrieves the current status of a USB root hub port.
 
565
 
 
566
  @param  This       A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
567
  @param  PortNumber Specifies the root hub port from which the status is to be retrieved.
 
568
                     This value is zero based.
 
569
  @param  PortStatus A pointer to the current port status bits and port status change bits.
 
570
 
 
571
  @retval EFI_SUCCESS           The status of the USB root hub port specified by PortNumber
 
572
                                was returned in PortStatus.
 
573
  @retval EFI_INVALID_PARAMETER PortNumber is invalid.
 
574
 
 
575
**/
 
576
typedef
 
577
EFI_STATUS
 
578
(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS)(
 
579
  IN        EFI_USB2_HC_PROTOCOL    *This,
 
580
  IN        UINT8                   PortNumber,
 
581
  OUT       EFI_USB_PORT_STATUS     *PortStatus
 
582
  );
 
583
 
 
584
/**
 
585
  Sets a feature for the specified root hub port.
 
586
 
 
587
  @param  This        A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
588
  @param  PortNumber  Specifies the root hub port whose feature is requested to be set. This
 
589
                      value is zero based.
 
590
  @param  PortFeature Indicates the feature selector associated with the feature set request.
 
591
 
 
592
  @retval EFI_SUCCESS           The feature specified by PortFeature was set for the USB
 
593
                                root hub port specified by PortNumber.
 
594
  @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.
 
595
 
 
596
**/
 
597
typedef
 
598
EFI_STATUS
 
599
(EFIAPI *EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE)(
 
600
  IN EFI_USB2_HC_PROTOCOL    *This,
 
601
  IN UINT8                   PortNumber,
 
602
  IN EFI_USB_PORT_FEATURE    PortFeature
 
603
  );
 
604
 
 
605
/**
 
606
  Clears a feature for the specified root hub port.
 
607
 
 
608
  @param  This        A pointer to the EFI_USB2_HC_PROTOCOL instance.
 
609
  @param  PortNumber  Specifies the root hub port whose feature is requested to be cleared. This
 
610
                      value is zero based.
 
611
  @param  PortFeature Indicates the feature selector associated with the feature clear request.
 
612
 
 
613
  @retval EFI_SUCCESS           The feature specified by PortFeature was cleared for the USB
 
614
                                root hub port specified by PortNumber.
 
615
  @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.
 
616
 
 
617
**/
 
618
typedef
 
619
EFI_STATUS
 
620
(EFIAPI *EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE)(
 
621
  IN EFI_USB2_HC_PROTOCOL    *This,
 
622
  IN UINT8                   PortNumber,
 
623
  IN EFI_USB_PORT_FEATURE    PortFeature
 
624
  );
 
625
 
 
626
///
 
627
/// The EFI_USB2_HC_PROTOCOL provides USB host controller management, basic
 
628
/// data transactions over a USB bus, and USB root hub access. A device driver
 
629
/// that wishes to manage a USB bus in a system retrieves the EFI_USB2_HC_PROTOCOL
 
630
/// instance that is associated with the USB bus to be managed. A device handle
 
631
/// for a USB host controller will minimally contain an EFI_DEVICE_PATH_PROTOCOL
 
632
/// instance, and an EFI_USB2_HC_PROTOCOL instance.
 
633
///
 
634
struct _EFI_USB2_HC_PROTOCOL {
 
635
  EFI_USB2_HC_PROTOCOL_GET_CAPABILITY              GetCapability;
 
636
  EFI_USB2_HC_PROTOCOL_RESET                       Reset;
 
637
  EFI_USB2_HC_PROTOCOL_GET_STATE                   GetState;
 
638
  EFI_USB2_HC_PROTOCOL_SET_STATE                   SetState;
 
639
  EFI_USB2_HC_PROTOCOL_CONTROL_TRANSFER            ControlTransfer;
 
640
  EFI_USB2_HC_PROTOCOL_BULK_TRANSFER               BulkTransfer;
 
641
  EFI_USB2_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER    AsyncInterruptTransfer;
 
642
  EFI_USB2_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER     SyncInterruptTransfer;
 
643
  EFI_USB2_HC_PROTOCOL_ISOCHRONOUS_TRANSFER        IsochronousTransfer;
 
644
  EFI_USB2_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER  AsyncIsochronousTransfer;
 
645
  EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS     GetRootHubPortStatus;
 
646
  EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE    SetRootHubPortFeature;
 
647
  EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE  ClearRootHubPortFeature;
 
648
 
 
649
  ///
 
650
  /// The major revision number of the USB host controller. The revision information
 
651
  /// indicates the release of the Universal Serial Bus Specification with which the
 
652
  /// host controller is compliant.
 
653
  ///
 
654
  UINT16                                           MajorRevision;
 
655
 
 
656
  ///
 
657
  /// The minor revision number of the USB host controller. The revision information
 
658
  /// indicates the release of the Universal Serial Bus Specification with which the
 
659
  /// host controller is compliant.
 
660
  ///
 
661
  UINT16                                           MinorRevision;
 
662
};
 
663
 
 
664
extern EFI_GUID gEfiUsb2HcProtocolGuid;
 
665
 
 
666
#endif