iPXE
Data Structures | Defines | Typedefs | Enumerations | Functions | Variables
UsbIo.h File Reference

EFI Usb I/O Protocol as defined in UEFI specification. More...

#include <ipxe/efi/IndustryStandard/Usb.h>

Go to the source code of this file.

Data Structures

struct  _EFI_USB_IO_PROTOCOL
 The EFI_USB_IO_PROTOCOL provides four basic transfers types described in the USB 1.1 Specification. More...

Defines

#define EFI_USB_IO_PROTOCOL_GUID
#define EFI_USB_NOERROR   0x00
#define EFI_USB_ERR_NOTEXECUTE   0x01
#define EFI_USB_ERR_STALL   0x02
#define EFI_USB_ERR_BUFFER   0x04
#define EFI_USB_ERR_BABBLE   0x08
#define EFI_USB_ERR_NAK   0x10
#define EFI_USB_ERR_CRC   0x20
#define EFI_USB_ERR_TIMEOUT   0x40
#define EFI_USB_ERR_BITSTUFF   0x80
#define EFI_USB_ERR_SYSTEM   0x100

Typedefs

typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL
typedef USB_DEVICE_REQUEST EFI_USB_DEVICE_REQUEST
typedef USB_DEVICE_DESCRIPTOR EFI_USB_DEVICE_DESCRIPTOR
typedef USB_CONFIG_DESCRIPTOR EFI_USB_CONFIG_DESCRIPTOR
typedef USB_INTERFACE_DESCRIPTOR EFI_USB_INTERFACE_DESCRIPTOR
typedef USB_ENDPOINT_DESCRIPTOR EFI_USB_ENDPOINT_DESCRIPTOR
typedef EFI_STATUS(EFIAPIEFI_ASYNC_USB_TRANSFER_CALLBACK )(IN VOID *Data, IN UINTN DataLength, IN VOID *Context, IN UINT32 Status)
 Async USB transfer callback routine.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_CONTROL_TRANSFER )(IN EFI_USB_IO_PROTOCOL *This, IN EFI_USB_DEVICE_REQUEST *Request, IN EFI_USB_DATA_DIRECTION Direction, IN UINT32 Timeout, IN OUT VOID *Data OPTIONAL, IN UINTN DataLength OPTIONAL, OUT UINT32 *Status)
 This function is used to manage a USB device with a control transfer pipe.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_BULK_TRANSFER )(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 DeviceEndpoint, IN OUT VOID *Data, IN OUT UINTN *DataLength, IN UINTN Timeout, OUT UINT32 *Status)
 This function is used to manage a USB device with the bulk transfer pipe.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_ASYNC_INTERRUPT_TRANSFER )(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 DeviceEndpoint, IN BOOLEAN IsNewTransfer, IN UINTN PollingInterval OPTIONAL, IN UINTN DataLength OPTIONAL, IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL, IN VOID *Context OPTIONAL)
 This function is used to manage a USB device with an interrupt transfer pipe.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_SYNC_INTERRUPT_TRANSFER )(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 DeviceEndpoint, IN OUT VOID *Data, IN OUT UINTN *DataLength, IN UINTN Timeout, OUT UINT32 *Status)
 This function is used to manage a USB device with an interrupt transfer pipe.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_ISOCHRONOUS_TRANSFER )(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 DeviceEndpoint, IN OUT VOID *Data, IN UINTN DataLength, OUT UINT32 *Status)
 This function is used to manage a USB device with an isochronous transfer pipe.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER )(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 DeviceEndpoint, IN OUT VOID *Data, IN UINTN DataLength, IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack, IN VOID *Context OPTIONAL)
 This function is used to manage a USB device with an isochronous transfer pipe.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_PORT_RESET )(IN EFI_USB_IO_PROTOCOL *This)
 Resets and reconfigures the USB controller.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_GET_DEVICE_DESCRIPTOR )(IN EFI_USB_IO_PROTOCOL *This, OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor)
 Retrieves the USB Device Descriptor.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_GET_CONFIG_DESCRIPTOR )(IN EFI_USB_IO_PROTOCOL *This, OUT EFI_USB_CONFIG_DESCRIPTOR *ConfigurationDescriptor)
 Retrieves the USB Device Descriptor.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_GET_INTERFACE_DESCRIPTOR )(IN EFI_USB_IO_PROTOCOL *This, OUT EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor)
 Retrieves the Interface Descriptor for a USB Device Controller.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_GET_ENDPOINT_DESCRIPTOR )(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 EndpointIndex, OUT EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDescriptor)
 Retrieves an Endpoint Descriptor within a USB Controller.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_GET_STRING_DESCRIPTOR )(IN EFI_USB_IO_PROTOCOL *This, IN UINT16 LangID, IN UINT8 StringID, OUT CHAR16 **String)
 Retrieves a string stored in a USB Device.
typedef EFI_STATUS(EFIAPIEFI_USB_IO_GET_SUPPORTED_LANGUAGE )(IN EFI_USB_IO_PROTOCOL *This, OUT UINT16 **LangIDTable, OUT UINT16 *TableSize)
 Retrieves all the language ID codes that the USB device supports.

Enumerations

enum  EFI_USB_DATA_DIRECTION { EfiUsbDataIn, EfiUsbDataOut, EfiUsbNoData }
 USB data transfer direction. More...

Functions

 FILE_LICENCE (BSD3)

Variables

EFI_GUID gEfiUsbIoProtocolGuid

Detailed Description

EFI Usb I/O Protocol as defined in UEFI specification.

This protocol is used by code, typically drivers, running in the EFI boot services environment to access USB devices like USB keyboards, mice and mass storage devices. In particular, functions for managing devices on USB buses are defined here.

Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at http://opensource.org/licenses/bsd-license.php

THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

Definition in file UsbIo.h.


Define Documentation

Value:
{ \
    0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \
  }

Definition at line 29 of file UsbIo.h.

#define EFI_USB_NOERROR   0x00

Definition at line 61 of file UsbIo.h.

#define EFI_USB_ERR_NOTEXECUTE   0x01

Definition at line 62 of file UsbIo.h.

#define EFI_USB_ERR_STALL   0x02

Definition at line 63 of file UsbIo.h.

Referenced by efi_usb_async_complete(), and efi_usb_control_transfer().

#define EFI_USB_ERR_BUFFER   0x04

Definition at line 64 of file UsbIo.h.

#define EFI_USB_ERR_BABBLE   0x08

Definition at line 65 of file UsbIo.h.

#define EFI_USB_ERR_NAK   0x10

Definition at line 66 of file UsbIo.h.

#define EFI_USB_ERR_CRC   0x20

Definition at line 67 of file UsbIo.h.

#define EFI_USB_ERR_TIMEOUT   0x40

Definition at line 68 of file UsbIo.h.

Referenced by efi_usb_bulk_transfer(), and efi_usb_sync_interrupt_transfer().

#define EFI_USB_ERR_BITSTUFF   0x80

Definition at line 69 of file UsbIo.h.

#define EFI_USB_ERR_SYSTEM   0x100

Definition at line 70 of file UsbIo.h.


Typedef Documentation

Definition at line 34 of file UsbIo.h.

Definition at line 43 of file UsbIo.h.

Definition at line 44 of file UsbIo.h.

Definition at line 45 of file UsbIo.h.

Definition at line 46 of file UsbIo.h.

Definition at line 47 of file UsbIo.h.

typedef EFI_STATUS(EFIAPI * EFI_ASYNC_USB_TRANSFER_CALLBACK)(IN VOID *Data, IN UINTN DataLength, IN VOID *Context, IN UINT32 Status)

Async USB transfer callback routine.

Parameters:
DataData received or sent via the USB Asynchronous Transfer, if the transfer completed successfully.
DataLengthThe length of Data received or sent via the Asynchronous Transfer, if transfer successfully completes.
ContextData passed from UsbAsyncInterruptTransfer() request.
StatusIndicates the result of the asynchronous transfer.
Return values:
EFI_SUCCESSThe asynchronous USB transfer request has been successfully executed.
EFI_DEVICE_ERRORThe asynchronous USB transfer request failed.

Definition at line 88 of file UsbIo.h.

This function is used to manage a USB device with a control transfer pipe.

A control transfer is typically used to perform device initialization and configuration.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
RequestA pointer to the USB device request that will be sent to the USB device.
DirectionIndicates the data direction.
TimeoutIndicating the transfer should be completed within this time frame. The units are in milliseconds.
DataA pointer to the buffer of data that will be transmitted to USB device or received from USB device.
DataLengthThe size, in bytes, of the data buffer specified by Data.
StatusA pointer to the result of the USB transfer.
Return values:
EFI_SUCCESSThe control transfer has been successfully executed.
EFI_DEVICE_ERRORThe transfer failed. The transfer status is returned in Status.
EFI_INVALID_PARAMETEOne or more parameters are invalid.
EFI_OUT_OF_RESOURCESThe request could not be completed due to a lack of resources.
EFI_TIMEOUTThe control transfer fails due to timeout.

Definition at line 124 of file UsbIo.h.

typedef EFI_STATUS(EFIAPI * EFI_USB_IO_BULK_TRANSFER)(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 DeviceEndpoint, IN OUT VOID *Data, IN OUT UINTN *DataLength, IN UINTN Timeout, OUT UINT32 *Status)

This function is used to manage a USB device with the bulk transfer pipe.

Bulk Transfers are typically used to transfer large amounts of data to/from USB devices.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceEndpointThe destination USB device endpoint to which the device request is being sent. DeviceEndpoint must be between 0x01 and 0x0F or between 0x81 and 0x8F, otherwise EFI_INVALID_PARAMETER is returned. If the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER is returned. The MSB of this parameter indicates the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint.
DataA pointer to the buffer of data that will be transmitted to USB device or received from USB device.
DataLengthThe size, in bytes, of the data buffer specified by Data. On input, the size, in bytes, of the data buffer specified by Data. On output, the number of bytes that were actually transferred.
TimeoutIndicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
StatusThis parameter indicates the USB transfer status.
Return values:
EFI_SUCCESSThe bulk transfer has been successfully executed.
EFI_DEVICE_ERRORThe transfer failed. The transfer status is returned in Status.
EFI_INVALID_PARAMETEOne or more parameters are invalid.
EFI_OUT_OF_RESOURCESThe request could not be submitted due to a lack of resources.
EFI_TIMEOUTThe control transfer fails due to timeout.

Definition at line 167 of file UsbIo.h.

typedef EFI_STATUS(EFIAPI * EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER)(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 DeviceEndpoint, IN BOOLEAN IsNewTransfer, IN UINTN PollingInterval OPTIONAL, IN UINTN DataLength OPTIONAL, IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL, IN VOID *Context OPTIONAL)

This function is used to manage a USB device with an interrupt transfer pipe.

An Asynchronous Interrupt Transfer is typically used to query a device's status at a fixed rate. For example, keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at a fixed rate.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceEndpointThe destination USB device endpoint to which the device request is being sent. DeviceEndpoint must be between 0x01 and 0x0F or between 0x81 and 0x8F, otherwise EFI_INVALID_PARAMETER is returned. If the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER is returned. The MSB of this parameter indicates the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint.
IsNewTransferIf TRUE, a new transfer will be submitted to USB controller. If FALSE, the interrupt transfer is deleted from the device's interrupt transfer queue.
PollingIntervalIndicates the periodic rate, in milliseconds, that the transfer is to be executed.This parameter is required when IsNewTransfer is TRUE. The value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned. The units are in milliseconds.
DataLengthSpecifies the length, in bytes, of the data to be received from the USB device. This parameter is only required when IsNewTransfer is TRUE.
InterruptCallbackThe Callback function. This function is called if the asynchronous interrupt transfer is completed. This parameter is required when IsNewTransfer is TRUE.
ContextData passed to the InterruptCallback function. This is an optional parameter and may be NULL.
Return values:
EFI_SUCCESSThe asynchronous USB transfer request transfer has been successfully executed.
EFI_DEVICE_ERRORThe asynchronous USB transfer request failed.

Definition at line 212 of file UsbIo.h.

typedef EFI_STATUS(EFIAPI * EFI_USB_IO_SYNC_INTERRUPT_TRANSFER)(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 DeviceEndpoint, IN OUT VOID *Data, IN OUT UINTN *DataLength, IN UINTN Timeout, OUT UINT32 *Status)

This function is used to manage a USB device with an interrupt transfer pipe.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceEndpointThe destination USB device endpoint to which the device request is being sent. DeviceEndpoint must be between 0x01 and 0x0F or between 0x81 and 0x8F, otherwise EFI_INVALID_PARAMETER is returned. If the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER is returned. The MSB of this parameter indicates the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint.
DataA pointer to the buffer of data that will be transmitted to USB device or received from USB device.
DataLengthOn input, then size, in bytes, of the buffer Data. On output, the amount of data actually transferred.
TimeoutThe time out, in seconds, for this transfer. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the transfer is not completed in this time frame, then EFI_TIMEOUT is returned.
StatusThis parameter indicates the USB transfer status.
Return values:
EFI_SUCCESSThe sync interrupt transfer has been successfully executed.
EFI_INVALID_PARAMETEROne or more parameters are invalid.
EFI_DEVICE_ERRORThe sync interrupt transfer request failed.
EFI_OUT_OF_RESOURCESThe request could not be submitted due to a lack of resources.
EFI_TIMEOUTThe transfer fails due to timeout.

Definition at line 252 of file UsbIo.h.

typedef EFI_STATUS(EFIAPI * EFI_USB_IO_ISOCHRONOUS_TRANSFER)(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 DeviceEndpoint, IN OUT VOID *Data, IN UINTN DataLength, OUT UINT32 *Status)

This function is used to manage a USB device with an isochronous transfer pipe.

An Isochronous transfer is typically used to transfer streaming data.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceEndpointThe destination USB device endpoint to which the device request is being sent. DeviceEndpoint must be between 0x01 and 0x0F or between 0x81 and 0x8F, otherwise EFI_INVALID_PARAMETER is returned. If the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER is returned. The MSB of this parameter indicates the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint.
DataA pointer to the buffer of data that will be transmitted to USB device or received from USB device.
DataLengthThe size, in bytes, of the data buffer specified by Data.
StatusThis parameter indicates the USB transfer status.
Return values:
EFI_SUCCESSThe isochronous transfer has been successfully executed.
EFI_INVALID_PARAMETERThe parameter DeviceEndpoint is not valid.
EFI_DEVICE_ERRORThe transfer failed due to the reason other than timeout, The error status is returned in Status.
EFI_OUT_OF_RESOURCESThe request could not be submitted due to a lack of resources.
EFI_TIMEOUTThe transfer fails due to timeout.

Definition at line 288 of file UsbIo.h.

typedef EFI_STATUS(EFIAPI * EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER)(IN EFI_USB_IO_PROTOCOL *This, IN UINT8 DeviceEndpoint, IN OUT VOID *Data, IN UINTN DataLength, IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack, IN VOID *Context OPTIONAL)

This function is used to manage a USB device with an isochronous transfer pipe.

An Isochronous transfer is typically used to transfer streaming data.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceEndpointThe destination USB device endpoint to which the device request is being sent. DeviceEndpoint must be between 0x01 and 0x0F or between 0x81 and 0x8F, otherwise EFI_INVALID_PARAMETER is returned. If the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER is returned. The MSB of this parameter indicates the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint.
DataA pointer to the buffer of data that will be transmitted to USB device or received from USB device.
DataLengthThe size, in bytes, of the data buffer specified by Data. This is an optional parameter and may be NULL.
IsochronousCallbackThe IsochronousCallback() function.This function is called if the requested isochronous transfer is completed.
ContextData passed to the IsochronousCallback() function.
Return values:
EFI_SUCCESSThe asynchronous isochronous transfer has been successfully submitted to the system.
EFI_INVALID_PARAMETERThe parameter DeviceEndpoint is not valid.
EFI_OUT_OF_RESOURCESThe request could not be submitted due to a lack of resources.

Definition at line 325 of file UsbIo.h.

Resets and reconfigures the USB controller.

This function will work for all USB devices except USB Hub Controllers.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
Return values:
EFI_SUCCESSThe USB controller was reset.
EFI_INVALID_PARAMETERIf the controller specified by This is a USB hub.
EFI_DEVICE_ERRORAn error occurred during the reconfiguration process.

Definition at line 347 of file UsbIo.h.

Retrieves the USB Device Descriptor.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
DeviceDescriptorA pointer to the caller allocated USB Device Descriptor.
Return values:
EFI_SUCCESSThe device descriptor was retrieved successfully.
EFI_INVALID_PARAMETERDeviceDescriptor is NULL.
EFI_NOT_FOUNDThe device descriptor was not found. The device may not be configured.

Definition at line 364 of file UsbIo.h.

Retrieves the USB Device Descriptor.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
ConfigurationDescriptorA pointer to the caller allocated USB Active Configuration Descriptor.
Return values:
EFI_SUCCESSThe active configuration descriptor was retrieved successfully.
EFI_INVALID_PARAMETERConfigurationDescriptor is NULL.
EFI_NOT_FOUNDAn active configuration descriptor cannot be found. The device may not be configured.

Definition at line 383 of file UsbIo.h.

Retrieves the Interface Descriptor for a USB Device Controller.

As stated earlier, an interface within a USB device is equivalently to a USB Controller within the current configuration.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
InterfaceDescriptorA pointer to the caller allocated USB Interface Descriptor within the configuration setting.
Return values:
EFI_SUCCESSThe interface descriptor retrieved successfully.
EFI_INVALID_PARAMETERInterfaceDescriptor is NULL.
EFI_NOT_FOUNDThe interface descriptor cannot be found. The device may not be correctly configured.

Definition at line 403 of file UsbIo.h.

Retrieves an Endpoint Descriptor within a USB Controller.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
EndpointIndexIndicates which endpoint descriptor to retrieve.
EndpointDescriptorA pointer to the caller allocated USB Endpoint Descriptor of a USB controller.
Return values:
EFI_SUCCESSThe endpoint descriptor was retrieved successfully.
EFI_INVALID_PARAMETEROne or more parameters are invalid.
EFI_NOT_FOUNDThe endpoint descriptor cannot be found. The device may not be correctly configured.

Definition at line 424 of file UsbIo.h.

Retrieves a string stored in a USB Device.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
LangIDThe Language ID for the string being retrieved.
StringIDThe ID of the string being retrieved.
StringA pointer to a buffer allocated by this function with AllocatePool() to store the string.If this function returns EFI_SUCCESS, it stores the string the caller wants to get. The caller should release the string buffer with FreePool() after the string is not used any more.
Return values:
EFI_SUCCESSThe string was retrieved successfully.
EFI_NOT_FOUNDThe string specified by LangID and StringID was not found.
EFI_OUT_OF_RESOURCESThere are not enough resources to allocate the return buffer String.

Definition at line 449 of file UsbIo.h.

Retrieves all the language ID codes that the USB device supports.

Parameters:
ThisA pointer to the EFI_USB_IO_PROTOCOL instance.
LangIDTableLanguage ID for the string the caller wants to get. This is a 16-bit ID defined by Microsoft. This buffer pointer is allocated and maintained by the USB Bus Driver, the caller should not modify its contents.
TableSizeThe size, in bytes, of the table LangIDTable.
Return values:
EFI_SUCCESSThe support languages were retrieved successfully.

Definition at line 472 of file UsbIo.h.


Enumeration Type Documentation

USB data transfer direction.

Enumerator:
EfiUsbDataIn 
EfiUsbDataOut 
EfiUsbNoData 

Definition at line 52 of file UsbIo.h.


Function Documentation

FILE_LICENCE ( BSD3  )

Variable Documentation