]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Protocol/UsbIo.h
MdePkg: Replace BSD License with BSD+Patent License
[mirror_edk2.git] / MdePkg / Include / Protocol / UsbIo.h
1 /** @file
2 EFI Usb I/O Protocol as defined in UEFI specification.
3 This protocol is used by code, typically drivers, running in the EFI
4 boot services environment to access USB devices like USB keyboards,
5 mice and mass storage devices. In particular, functions for managing devices
6 on USB buses are defined here.
7
8 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
9 SPDX-License-Identifier: BSD-2-Clause-Patent
10
11 **/
12
13 #ifndef __USB_IO_H__
14 #define __USB_IO_H__
15
16 #include <IndustryStandard/Usb.h>
17
18 //
19 // Global ID for the USB I/O Protocol
20 //
21 #define EFI_USB_IO_PROTOCOL_GUID \
22 { \
23 0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \
24 }
25
26 typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL;
27
28 //
29 // Related Definition for EFI USB I/O protocol
30 //
31
32 //
33 // USB standard descriptors and reqeust
34 //
35 typedef USB_DEVICE_REQUEST EFI_USB_DEVICE_REQUEST;
36 typedef USB_DEVICE_DESCRIPTOR EFI_USB_DEVICE_DESCRIPTOR;
37 typedef USB_CONFIG_DESCRIPTOR EFI_USB_CONFIG_DESCRIPTOR;
38 typedef USB_INTERFACE_DESCRIPTOR EFI_USB_INTERFACE_DESCRIPTOR;
39 typedef USB_ENDPOINT_DESCRIPTOR EFI_USB_ENDPOINT_DESCRIPTOR;
40
41 ///
42 /// USB data transfer direction
43 ///
44 typedef enum {
45 EfiUsbDataIn,
46 EfiUsbDataOut,
47 EfiUsbNoData
48 } EFI_USB_DATA_DIRECTION;
49
50 //
51 // USB Transfer Results
52 //
53 #define EFI_USB_NOERROR 0x00
54 #define EFI_USB_ERR_NOTEXECUTE 0x01
55 #define EFI_USB_ERR_STALL 0x02
56 #define EFI_USB_ERR_BUFFER 0x04
57 #define EFI_USB_ERR_BABBLE 0x08
58 #define EFI_USB_ERR_NAK 0x10
59 #define EFI_USB_ERR_CRC 0x20
60 #define EFI_USB_ERR_TIMEOUT 0x40
61 #define EFI_USB_ERR_BITSTUFF 0x80
62 #define EFI_USB_ERR_SYSTEM 0x100
63
64 /**
65 Async USB transfer callback routine.
66
67 @param Data Data received or sent via the USB Asynchronous Transfer, if the
68 transfer completed successfully.
69 @param DataLength The length of Data received or sent via the Asynchronous
70 Transfer, if transfer successfully completes.
71 @param Context Data passed from UsbAsyncInterruptTransfer() request.
72 @param Status Indicates the result of the asynchronous transfer.
73
74 @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed.
75 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
76
77 **/
78 typedef
79 EFI_STATUS
80 (EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK)(
81 IN VOID *Data,
82 IN UINTN DataLength,
83 IN VOID *Context,
84 IN UINT32 Status
85 );
86
87 //
88 // Prototype for EFI USB I/O protocol
89 //
90
91
92 /**
93 This function is used to manage a USB device with a control transfer pipe. A control transfer is
94 typically used to perform device initialization and configuration.
95
96 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
97 @param Request A pointer to the USB device request that will be sent to the USB
98 device.
99 @param Direction Indicates the data direction.
100 @param Timeout Indicating the transfer should be completed within this time frame.
101 The units are in milliseconds.
102 @param Data A pointer to the buffer of data that will be transmitted to USB
103 device or received from USB device.
104 @param DataLength The size, in bytes, of the data buffer specified by Data.
105 @param Status A pointer to the result of the USB transfer.
106
107 @retval EFI_SUCCESS The control transfer has been successfully executed.
108 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
109 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.
110 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
111 @retval EFI_TIMEOUT The control transfer fails due to timeout.
112
113 **/
114 typedef
115 EFI_STATUS
116 (EFIAPI *EFI_USB_IO_CONTROL_TRANSFER)(
117 IN EFI_USB_IO_PROTOCOL *This,
118 IN EFI_USB_DEVICE_REQUEST *Request,
119 IN EFI_USB_DATA_DIRECTION Direction,
120 IN UINT32 Timeout,
121 IN OUT VOID *Data OPTIONAL,
122 IN UINTN DataLength OPTIONAL,
123 OUT UINT32 *Status
124 );
125
126 /**
127 This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are
128 typically used to transfer large amounts of data to/from USB devices.
129
130 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
131 @param DeviceEndpoint The destination USB device endpoint to which the
132 device request is being sent. DeviceEndpoint must
133 be between 0x01 and 0x0F or between 0x81 and 0x8F,
134 otherwise EFI_INVALID_PARAMETER is returned. If
135 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
136 is returned. The MSB of this parameter indicates
137 the endpoint direction. The number "1" stands for
138 an IN endpoint, and "0" stands for an OUT endpoint.
139 @param Data A pointer to the buffer of data that will be transmitted to USB
140 device or received from USB device.
141 @param DataLength The size, in bytes, of the data buffer specified by Data.
142 On input, the size, in bytes, of the data buffer specified by Data.
143 On output, the number of bytes that were actually transferred.
144 @param Timeout Indicating the transfer should be completed within this time frame.
145 The units are in milliseconds. If Timeout is 0, then the
146 caller must wait for the function to be completed until
147 EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
148 @param Status This parameter indicates the USB transfer status.
149
150 @retval EFI_SUCCESS The bulk transfer has been successfully executed.
151 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
152 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.
153 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
154 @retval EFI_TIMEOUT The control transfer fails due to timeout.
155
156 **/
157 typedef
158 EFI_STATUS
159 (EFIAPI *EFI_USB_IO_BULK_TRANSFER)(
160 IN EFI_USB_IO_PROTOCOL *This,
161 IN UINT8 DeviceEndpoint,
162 IN OUT VOID *Data,
163 IN OUT UINTN *DataLength,
164 IN UINTN Timeout,
165 OUT UINT32 *Status
166 );
167
168 /**
169 This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous
170 Interrupt Transfer is typically used to query a device's status at a fixed rate. For example,
171 keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at
172 a fixed rate.
173
174 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
175 @param DeviceEndpoint The destination USB device endpoint to which the
176 device request is being sent. DeviceEndpoint must
177 be between 0x01 and 0x0F or between 0x81 and 0x8F,
178 otherwise EFI_INVALID_PARAMETER is returned. If
179 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
180 is returned. The MSB of this parameter indicates
181 the endpoint direction. The number "1" stands for
182 an IN endpoint, and "0" stands for an OUT endpoint.
183 @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If
184 FALSE, the interrupt transfer is deleted from the device's interrupt
185 transfer queue.
186 @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be
187 executed.This parameter is required when IsNewTransfer is TRUE. The
188 value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned.
189 The units are in milliseconds.
190 @param DataLength Specifies the length, in bytes, of the data to be received from the
191 USB device. This parameter is only required when IsNewTransfer is TRUE.
192 @param InterruptCallback The Callback function. This function is called if the asynchronous
193 interrupt transfer is completed. This parameter is required
194 when IsNewTransfer is TRUE.
195 @param Context Data passed to the InterruptCallback function. This is an optional
196 parameter and may be NULL.
197
198 @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed.
199 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
200
201 **/
202 typedef
203 EFI_STATUS
204 (EFIAPI *EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER)(
205 IN EFI_USB_IO_PROTOCOL *This,
206 IN UINT8 DeviceEndpoint,
207 IN BOOLEAN IsNewTransfer,
208 IN UINTN PollingInterval OPTIONAL,
209 IN UINTN DataLength OPTIONAL,
210 IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL,
211 IN VOID *Context OPTIONAL
212 );
213
214 /**
215 This function is used to manage a USB device with an interrupt transfer pipe.
216
217 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
218 @param DeviceEndpoint The destination USB device endpoint to which the
219 device request is being sent. DeviceEndpoint must
220 be between 0x01 and 0x0F or between 0x81 and 0x8F,
221 otherwise EFI_INVALID_PARAMETER is returned. If
222 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
223 is returned. The MSB of this parameter indicates
224 the endpoint direction. The number "1" stands for
225 an IN endpoint, and "0" stands for an OUT endpoint.
226 @param Data A pointer to the buffer of data that will be transmitted to USB
227 device or received from USB device.
228 @param DataLength On input, then size, in bytes, of the buffer Data. On output, the
229 amount of data actually transferred.
230 @param Timeout The time out, in seconds, for this transfer. If Timeout is 0,
231 then the caller must wait for the function to be completed
232 until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the
233 transfer is not completed in this time frame, then EFI_TIMEOUT is returned.
234 @param Status This parameter indicates the USB transfer status.
235
236 @retval EFI_SUCCESS The sync interrupt transfer has been successfully executed.
237 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
238 @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed.
239 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
240 @retval EFI_TIMEOUT The transfer fails due to timeout.
241 **/
242 typedef
243 EFI_STATUS
244 (EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER)(
245 IN EFI_USB_IO_PROTOCOL *This,
246 IN UINT8 DeviceEndpoint,
247 IN OUT VOID *Data,
248 IN OUT UINTN *DataLength,
249 IN UINTN Timeout,
250 OUT UINT32 *Status
251 );
252
253 /**
254 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
255 transfer is typically used to transfer streaming data.
256
257 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
258 @param DeviceEndpoint The destination USB device endpoint to which the
259 device request is being sent. DeviceEndpoint must
260 be between 0x01 and 0x0F or between 0x81 and 0x8F,
261 otherwise EFI_INVALID_PARAMETER is returned. If
262 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
263 is returned. The MSB of this parameter indicates
264 the endpoint direction. The number "1" stands for
265 an IN endpoint, and "0" stands for an OUT endpoint.
266 @param Data A pointer to the buffer of data that will be transmitted to USB
267 device or received from USB device.
268 @param DataLength The size, in bytes, of the data buffer specified by Data.
269 @param Status This parameter indicates the USB transfer status.
270
271 @retval EFI_SUCCESS The isochronous transfer has been successfully executed.
272 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
273 @retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status
274 is returned in Status.
275 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
276 @retval EFI_TIMEOUT The transfer fails due to timeout.
277 **/
278 typedef
279 EFI_STATUS
280 (EFIAPI *EFI_USB_IO_ISOCHRONOUS_TRANSFER)(
281 IN EFI_USB_IO_PROTOCOL *This,
282 IN UINT8 DeviceEndpoint,
283 IN OUT VOID *Data,
284 IN UINTN DataLength,
285 OUT UINT32 *Status
286 );
287
288 /**
289 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
290 transfer is typically used to transfer streaming data.
291
292 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
293 @param DeviceEndpoint The destination USB device endpoint to which the
294 device request is being sent. DeviceEndpoint must
295 be between 0x01 and 0x0F or between 0x81 and 0x8F,
296 otherwise EFI_INVALID_PARAMETER is returned. If
297 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
298 is returned. The MSB of this parameter indicates
299 the endpoint direction. The number "1" stands for
300 an IN endpoint, and "0" stands for an OUT endpoint.
301 @param Data A pointer to the buffer of data that will be transmitted to USB
302 device or received from USB device.
303 @param DataLength The size, in bytes, of the data buffer specified by Data.
304 This is an optional parameter and may be NULL.
305 @param IsochronousCallback The IsochronousCallback() function.This function is
306 called if the requested isochronous transfer is completed.
307 @param Context Data passed to the IsochronousCallback() function.
308
309 @retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted
310 to the system.
311 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
312 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
313
314 **/
315 typedef
316 EFI_STATUS
317 (EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER)(
318 IN EFI_USB_IO_PROTOCOL *This,
319 IN UINT8 DeviceEndpoint,
320 IN OUT VOID *Data,
321 IN UINTN DataLength,
322 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack,
323 IN VOID *Context OPTIONAL
324 );
325
326 /**
327 Resets and reconfigures the USB controller. This function will work for all USB devices except
328 USB Hub Controllers.
329
330 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
331
332 @retval EFI_SUCCESS The USB controller was reset.
333 @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.
334 @retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process.
335
336 **/
337 typedef
338 EFI_STATUS
339 (EFIAPI *EFI_USB_IO_PORT_RESET)(
340 IN EFI_USB_IO_PROTOCOL *This
341 );
342
343 /**
344 Retrieves the USB Device Descriptor.
345
346 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
347 @param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor.
348
349 @retval EFI_SUCCESS The device descriptor was retrieved successfully.
350 @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.
351 @retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured.
352
353 **/
354 typedef
355 EFI_STATUS
356 (EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR)(
357 IN EFI_USB_IO_PROTOCOL *This,
358 OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor
359 );
360
361 /**
362 Retrieves the USB Device Descriptor.
363
364 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
365 @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration
366 Descriptor.
367 @retval EFI_SUCCESS The active configuration descriptor was retrieved successfully.
368 @retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL.
369 @retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not
370 be configured.
371
372 **/
373 typedef
374 EFI_STATUS
375 (EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR)(
376 IN EFI_USB_IO_PROTOCOL *This,
377 OUT EFI_USB_CONFIG_DESCRIPTOR *ConfigurationDescriptor
378 );
379
380 /**
381 Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface
382 within a USB device is equivalently to a USB Controller within the current configuration.
383
384 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
385 @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within
386 the configuration setting.
387 @retval EFI_SUCCESS The interface descriptor retrieved successfully.
388 @retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL.
389 @retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be
390 correctly configured.
391
392 **/
393 typedef
394 EFI_STATUS
395 (EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR)(
396 IN EFI_USB_IO_PROTOCOL *This,
397 OUT EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor
398 );
399
400 /**
401 Retrieves an Endpoint Descriptor within a USB Controller.
402
403 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
404 @param EndpointIndex Indicates which endpoint descriptor to retrieve.
405 @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of
406 a USB controller.
407
408 @retval EFI_SUCCESS The endpoint descriptor was retrieved successfully.
409 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
410 @retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be
411 correctly configured.
412
413 **/
414 typedef
415 EFI_STATUS
416 (EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR)(
417 IN EFI_USB_IO_PROTOCOL *This,
418 IN UINT8 EndpointIndex,
419 OUT EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDescriptor
420 );
421
422 /**
423 Retrieves a string stored in a USB Device.
424
425 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
426 @param LangID The Language ID for the string being retrieved.
427 @param StringID The ID of the string being retrieved.
428 @param String A pointer to a buffer allocated by this function with
429 AllocatePool() to store the string.If this function
430 returns EFI_SUCCESS, it stores the string the caller
431 wants to get. The caller should release the string
432 buffer with FreePool() after the string is not used any more.
433
434 @retval EFI_SUCCESS The string was retrieved successfully.
435 @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found.
436 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.
437
438 **/
439 typedef
440 EFI_STATUS
441 (EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR)(
442 IN EFI_USB_IO_PROTOCOL *This,
443 IN UINT16 LangID,
444 IN UINT8 StringID,
445 OUT CHAR16 **String
446 );
447
448 /**
449 Retrieves all the language ID codes that the USB device supports.
450
451 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
452 @param LangIDTable Language ID for the string the caller wants to get.
453 This is a 16-bit ID defined by Microsoft. This
454 buffer pointer is allocated and maintained by
455 the USB Bus Driver, the caller should not modify
456 its contents.
457 @param TableSize The size, in bytes, of the table LangIDTable.
458
459 @retval EFI_SUCCESS The support languages were retrieved successfully.
460
461 **/
462 typedef
463 EFI_STATUS
464 (EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE)(
465 IN EFI_USB_IO_PROTOCOL *This,
466 OUT UINT16 **LangIDTable,
467 OUT UINT16 *TableSize
468 );
469
470 ///
471 /// The EFI_USB_IO_PROTOCOL provides four basic transfers types described
472 /// in the USB 1.1 Specification. These include control transfer, interrupt
473 /// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL
474 /// also provides some basic USB device/controller management and configuration
475 /// interfaces. A USB device driver uses the services of this protocol to manage USB devices.
476 ///
477 struct _EFI_USB_IO_PROTOCOL {
478 //
479 // IO transfer
480 //
481 EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer;
482 EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer;
483 EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer;
484 EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer;
485 EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer;
486 EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer;
487
488 //
489 // Common device request
490 //
491 EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor;
492 EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor;
493 EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor;
494 EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor;
495 EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor;
496 EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages;
497
498 //
499 // Reset controller's parent port
500 //
501 EFI_USB_IO_PORT_RESET UsbPortReset;
502 };
503
504 extern EFI_GUID gEfiUsbIoProtocolGuid;
505
506 #endif