diff --git a/src/include/ipxe/efi/IndustryStandard/Usb.h b/src/include/ipxe/efi/IndustryStandard/Usb.h new file mode 100644 index 00000000..1af062c4 --- /dev/null +++ b/src/include/ipxe/efi/IndustryStandard/Usb.h @@ -0,0 +1,362 @@ +/** @file + Support for USB 2.0 standard. + + 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. + +**/ + +#ifndef __USB_H__ +#define __USB_H__ + +FILE_LICENCE ( BSD3 ); + +// +// Standard device request and request type +// USB 2.0 spec, Section 9.4 +// +#define USB_DEV_GET_STATUS 0x00 +#define USB_DEV_GET_STATUS_REQ_TYPE_D 0x80 // Receiver : Device +#define USB_DEV_GET_STATUS_REQ_TYPE_I 0x81 // Receiver : Interface +#define USB_DEV_GET_STATUS_REQ_TYPE_E 0x82 // Receiver : Endpoint + +#define USB_DEV_CLEAR_FEATURE 0x01 +#define USB_DEV_CLEAR_FEATURE_REQ_TYPE_D 0x00 // Receiver : Device +#define USB_DEV_CLEAR_FEATURE_REQ_TYPE_I 0x01 // Receiver : Interface +#define USB_DEV_CLEAR_FEATURE_REQ_TYPE_E 0x02 // Receiver : Endpoint + +#define USB_DEV_SET_FEATURE 0x03 +#define USB_DEV_SET_FEATURE_REQ_TYPE_D 0x00 // Receiver : Device +#define USB_DEV_SET_FEATURE_REQ_TYPE_I 0x01 // Receiver : Interface +#define USB_DEV_SET_FEATURE_REQ_TYPE_E 0x02 // Receiver : Endpoint + +#define USB_DEV_SET_ADDRESS 0x05 +#define USB_DEV_SET_ADDRESS_REQ_TYPE 0x00 + +#define USB_DEV_GET_DESCRIPTOR 0x06 +#define USB_DEV_GET_DESCRIPTOR_REQ_TYPE 0x80 + +#define USB_DEV_SET_DESCRIPTOR 0x07 +#define USB_DEV_SET_DESCRIPTOR_REQ_TYPE 0x00 + +#define USB_DEV_GET_CONFIGURATION 0x08 +#define USB_DEV_GET_CONFIGURATION_REQ_TYPE 0x80 + +#define USB_DEV_SET_CONFIGURATION 0x09 +#define USB_DEV_SET_CONFIGURATION_REQ_TYPE 0x00 + +#define USB_DEV_GET_INTERFACE 0x0A +#define USB_DEV_GET_INTERFACE_REQ_TYPE 0x81 + +#define USB_DEV_SET_INTERFACE 0x0B +#define USB_DEV_SET_INTERFACE_REQ_TYPE 0x01 + +#define USB_DEV_SYNCH_FRAME 0x0C +#define USB_DEV_SYNCH_FRAME_REQ_TYPE 0x82 + + +// +// USB standard descriptors and reqeust +// +#pragma pack(1) + +/// +/// Format of Setup Data for USB Device Requests +/// USB 2.0 spec, Section 9.3 +/// +typedef struct { + UINT8 RequestType; + UINT8 Request; + UINT16 Value; + UINT16 Index; + UINT16 Length; +} USB_DEVICE_REQUEST; + +/// +/// Standard Device Descriptor +/// USB 2.0 spec, Section 9.6.1 +/// +typedef struct { + UINT8 Length; + UINT8 DescriptorType; + UINT16 BcdUSB; + UINT8 DeviceClass; + UINT8 DeviceSubClass; + UINT8 DeviceProtocol; + UINT8 MaxPacketSize0; + UINT16 IdVendor; + UINT16 IdProduct; + UINT16 BcdDevice; + UINT8 StrManufacturer; + UINT8 StrProduct; + UINT8 StrSerialNumber; + UINT8 NumConfigurations; +} USB_DEVICE_DESCRIPTOR; + +/// +/// Standard Configuration Descriptor +/// USB 2.0 spec, Section 9.6.3 +/// +typedef struct { + UINT8 Length; + UINT8 DescriptorType; + UINT16 TotalLength; + UINT8 NumInterfaces; + UINT8 ConfigurationValue; + UINT8 Configuration; + UINT8 Attributes; + UINT8 MaxPower; +} USB_CONFIG_DESCRIPTOR; + +/// +/// Standard Interface Descriptor +/// USB 2.0 spec, Section 9.6.5 +/// +typedef struct { + UINT8 Length; + UINT8 DescriptorType; + UINT8 InterfaceNumber; + UINT8 AlternateSetting; + UINT8 NumEndpoints; + UINT8 InterfaceClass; + UINT8 InterfaceSubClass; + UINT8 InterfaceProtocol; + UINT8 Interface; +} USB_INTERFACE_DESCRIPTOR; + +/// +/// Standard Endpoint Descriptor +/// USB 2.0 spec, Section 9.6.6 +/// +typedef struct { + UINT8 Length; + UINT8 DescriptorType; + UINT8 EndpointAddress; + UINT8 Attributes; + UINT16 MaxPacketSize; + UINT8 Interval; +} USB_ENDPOINT_DESCRIPTOR; + +/// +/// UNICODE String Descriptor +/// USB 2.0 spec, Section 9.6.7 +/// +typedef struct { + UINT8 Length; + UINT8 DescriptorType; + CHAR16 String[1]; +} EFI_USB_STRING_DESCRIPTOR; + +#pragma pack() + + +typedef enum { + // + // USB request type + // + USB_REQ_TYPE_STANDARD = (0x00 << 5), + USB_REQ_TYPE_CLASS = (0x01 << 5), + USB_REQ_TYPE_VENDOR = (0x02 << 5), + + // + // Standard control transfer request type, or the value + // to fill in EFI_USB_DEVICE_REQUEST.Request + // + USB_REQ_GET_STATUS = 0x00, + USB_REQ_CLEAR_FEATURE = 0x01, + USB_REQ_SET_FEATURE = 0x03, + USB_REQ_SET_ADDRESS = 0x05, + USB_REQ_GET_DESCRIPTOR = 0x06, + USB_REQ_SET_DESCRIPTOR = 0x07, + USB_REQ_GET_CONFIG = 0x08, + USB_REQ_SET_CONFIG = 0x09, + USB_REQ_GET_INTERFACE = 0x0A, + USB_REQ_SET_INTERFACE = 0x0B, + USB_REQ_SYNCH_FRAME = 0x0C, + + // + // Usb control transfer target + // + USB_TARGET_DEVICE = 0, + USB_TARGET_INTERFACE = 0x01, + USB_TARGET_ENDPOINT = 0x02, + USB_TARGET_OTHER = 0x03, + + // + // USB Descriptor types + // + USB_DESC_TYPE_DEVICE = 0x01, + USB_DESC_TYPE_CONFIG = 0x02, + USB_DESC_TYPE_STRING = 0x03, + USB_DESC_TYPE_INTERFACE = 0x04, + USB_DESC_TYPE_ENDPOINT = 0x05, + USB_DESC_TYPE_HID = 0x21, + USB_DESC_TYPE_REPORT = 0x22, + + // + // Features to be cleared by CLEAR_FEATURE requests + // + USB_FEATURE_ENDPOINT_HALT = 0, + + // + // USB endpoint types: 00: control, 01: isochronous, 10: bulk, 11: interrupt + // + USB_ENDPOINT_CONTROL = 0x00, + USB_ENDPOINT_ISO = 0x01, + USB_ENDPOINT_BULK = 0x02, + USB_ENDPOINT_INTERRUPT = 0x03, + + USB_ENDPOINT_TYPE_MASK = 0x03, + USB_ENDPOINT_DIR_IN = 0x80, + + // + //Use 200 ms to increase the error handling response time + // + EFI_USB_INTERRUPT_DELAY = 2000000 +} USB_TYPES_DEFINITION; + + +// +// HID constants definition, see Device Class Definition +// for Human Interface Devices (HID) rev1.11 +// + +// +// HID standard GET_DESCRIPTOR request. +// +#define USB_HID_GET_DESCRIPTOR_REQ_TYPE 0x81 + +// +// HID specific requests. +// +#define USB_HID_CLASS_GET_REQ_TYPE 0xa1 +#define USB_HID_CLASS_SET_REQ_TYPE 0x21 + +// +// HID report item format +// +#define HID_ITEM_FORMAT_SHORT 0 +#define HID_ITEM_FORMAT_LONG 1 + +// +// Special tag indicating long items +// +#define HID_ITEM_TAG_LONG 15 + +// +// HID report descriptor item type (prefix bit 2,3) +// +#define HID_ITEM_TYPE_MAIN 0 +#define HID_ITEM_TYPE_GLOBAL 1 +#define HID_ITEM_TYPE_LOCAL 2 +#define HID_ITEM_TYPE_RESERVED 3 + +// +// HID report descriptor main item tags +// +#define HID_MAIN_ITEM_TAG_INPUT 8 +#define HID_MAIN_ITEM_TAG_OUTPUT 9 +#define HID_MAIN_ITEM_TAG_FEATURE 11 +#define HID_MAIN_ITEM_TAG_BEGIN_COLLECTION 10 +#define HID_MAIN_ITEM_TAG_END_COLLECTION 12 + +// +// HID report descriptor main item contents +// +#define HID_MAIN_ITEM_CONSTANT 0x001 +#define HID_MAIN_ITEM_VARIABLE 0x002 +#define HID_MAIN_ITEM_RELATIVE 0x004 +#define HID_MAIN_ITEM_WRAP 0x008 +#define HID_MAIN_ITEM_NONLINEAR 0x010 +#define HID_MAIN_ITEM_NO_PREFERRED 0x020 +#define HID_MAIN_ITEM_NULL_STATE 0x040 +#define HID_MAIN_ITEM_VOLATILE 0x080 +#define HID_MAIN_ITEM_BUFFERED_BYTE 0x100 + +// +// HID report descriptor collection item types +// +#define HID_COLLECTION_PHYSICAL 0 +#define HID_COLLECTION_APPLICATION 1 +#define HID_COLLECTION_LOGICAL 2 + +// +// HID report descriptor global item tags +// +#define HID_GLOBAL_ITEM_TAG_USAGE_PAGE 0 +#define HID_GLOBAL_ITEM_TAG_LOGICAL_MINIMUM 1 +#define HID_GLOBAL_ITEM_TAG_LOGICAL_MAXIMUM 2 +#define HID_GLOBAL_ITEM_TAG_PHYSICAL_MINIMUM 3 +#define HID_GLOBAL_ITEM_TAG_PHYSICAL_MAXIMUM 4 +#define HID_GLOBAL_ITEM_TAG_UNIT_EXPONENT 5 +#define HID_GLOBAL_ITEM_TAG_UNIT 6 +#define HID_GLOBAL_ITEM_TAG_REPORT_SIZE 7 +#define HID_GLOBAL_ITEM_TAG_REPORT_ID 8 +#define HID_GLOBAL_ITEM_TAG_REPORT_COUNT 9 +#define HID_GLOBAL_ITEM_TAG_PUSH 10 +#define HID_GLOBAL_ITEM_TAG_POP 11 + +// +// HID report descriptor local item tags +// +#define HID_LOCAL_ITEM_TAG_USAGE 0 +#define HID_LOCAL_ITEM_TAG_USAGE_MINIMUM 1 +#define HID_LOCAL_ITEM_TAG_USAGE_MAXIMUM 2 +#define HID_LOCAL_ITEM_TAG_DESIGNATOR_INDEX 3 +#define HID_LOCAL_ITEM_TAG_DESIGNATOR_MINIMUM 4 +#define HID_LOCAL_ITEM_TAG_DESIGNATOR_MAXIMUM 5 +#define HID_LOCAL_ITEM_TAG_STRING_INDEX 7 +#define HID_LOCAL_ITEM_TAG_STRING_MINIMUM 8 +#define HID_LOCAL_ITEM_TAG_STRING_MAXIMUM 9 +#define HID_LOCAL_ITEM_TAG_DELIMITER 10 + +// +// HID report types +// +#define HID_INPUT_REPORT 1 +#define HID_OUTPUT_REPORT 2 +#define HID_FEATURE_REPORT 3 + +// +// HID class protocol request +// +#define EFI_USB_GET_REPORT_REQUEST 0x01 +#define EFI_USB_GET_IDLE_REQUEST 0x02 +#define EFI_USB_GET_PROTOCOL_REQUEST 0x03 +#define EFI_USB_SET_REPORT_REQUEST 0x09 +#define EFI_USB_SET_IDLE_REQUEST 0x0a +#define EFI_USB_SET_PROTOCOL_REQUEST 0x0b + +#pragma pack(1) +/// +/// Descriptor header for Report/Physical Descriptors +/// HID 1.1, section 6.2.1 +/// +typedef struct hid_class_descriptor { + UINT8 DescriptorType; + UINT16 DescriptorLength; +} EFI_USB_HID_CLASS_DESCRIPTOR; + +/// +/// The HID descriptor identifies the length and type +/// of subordinate descriptors for a device. +/// HID 1.1, section 6.2.1 +/// +typedef struct hid_descriptor { + UINT8 Length; + UINT8 DescriptorType; + UINT16 BcdHID; + UINT8 CountryCode; + UINT8 NumDescriptors; + EFI_USB_HID_CLASS_DESCRIPTOR HidClassDesc[1]; +} EFI_USB_HID_DESCRIPTOR; + +#pragma pack() + +#endif diff --git a/src/include/ipxe/efi/Protocol/Usb2HostController.h b/src/include/ipxe/efi/Protocol/Usb2HostController.h new file mode 100644 index 00000000..01f61701 --- /dev/null +++ b/src/include/ipxe/efi/Protocol/Usb2HostController.h @@ -0,0 +1,603 @@ +/** @file + EFI_USB2_HC_PROTOCOL as defined in UEFI 2.0. + The USB Host Controller Protocol is used by code, typically USB bus drivers, + running in the EFI boot services environment, to perform data transactions over + a USB bus. In addition, it provides an abstraction for the root hub of the USB bus. + + Copyright (c) 2006 - 2011, 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. + +**/ + +#ifndef _USB2_HOSTCONTROLLER_H_ +#define _USB2_HOSTCONTROLLER_H_ + +FILE_LICENCE ( BSD3 ); + +#include + +#define EFI_USB2_HC_PROTOCOL_GUID \ + { \ + 0x3e745226, 0x9818, 0x45b6, {0xa2, 0xac, 0xd7, 0xcd, 0xe, 0x8b, 0xa2, 0xbc } \ + } + +/// +/// Forward reference for pure ANSI compatability +/// +typedef struct _EFI_USB2_HC_PROTOCOL EFI_USB2_HC_PROTOCOL; + + +typedef struct { + UINT16 PortStatus; ///< Contains current port status bitmap. + UINT16 PortChangeStatus; ///< Contains current port status change bitmap. +} EFI_USB_PORT_STATUS; + +/// +/// EFI_USB_PORT_STATUS.PortStatus bit definition +/// +#define USB_PORT_STAT_CONNECTION 0x0001 +#define USB_PORT_STAT_ENABLE 0x0002 +#define USB_PORT_STAT_SUSPEND 0x0004 +#define USB_PORT_STAT_OVERCURRENT 0x0008 +#define USB_PORT_STAT_RESET 0x0010 +#define USB_PORT_STAT_POWER 0x0100 +#define USB_PORT_STAT_LOW_SPEED 0x0200 +#define USB_PORT_STAT_HIGH_SPEED 0x0400 +#define USB_PORT_STAT_SUPER_SPEED 0x0800 +#define USB_PORT_STAT_OWNER 0x2000 + +/// +/// EFI_USB_PORT_STATUS.PortChangeStatus bit definition +/// +#define USB_PORT_STAT_C_CONNECTION 0x0001 +#define USB_PORT_STAT_C_ENABLE 0x0002 +#define USB_PORT_STAT_C_SUSPEND 0x0004 +#define USB_PORT_STAT_C_OVERCURRENT 0x0008 +#define USB_PORT_STAT_C_RESET 0x0010 + + +/// +/// Usb port features value +/// Each value indicates its bit index in the port status and status change bitmaps, +/// if combines these two bitmaps into a 32-bit bitmap. +/// +typedef enum { + EfiUsbPortEnable = 1, + EfiUsbPortSuspend = 2, + EfiUsbPortReset = 4, + EfiUsbPortPower = 8, + EfiUsbPortOwner = 13, + EfiUsbPortConnectChange = 16, + EfiUsbPortEnableChange = 17, + EfiUsbPortSuspendChange = 18, + EfiUsbPortOverCurrentChange = 19, + EfiUsbPortResetChange = 20 +} EFI_USB_PORT_FEATURE; + +#define EFI_USB_SPEED_FULL 0x0000 ///< 12 Mb/s, USB 1.1 OHCI and UHCI HC. +#define EFI_USB_SPEED_LOW 0x0001 ///< 1 Mb/s, USB 1.1 OHCI and UHCI HC. +#define EFI_USB_SPEED_HIGH 0x0002 ///< 480 Mb/s, USB 2.0 EHCI HC. +#define EFI_USB_SPEED_SUPER 0x0003 ///< 4.8 Gb/s, USB 3.0 XHCI HC. + +typedef struct { + UINT8 TranslatorHubAddress; ///< device address + UINT8 TranslatorPortNumber; ///< the port number of the hub that device is connected to. +} EFI_USB2_HC_TRANSACTION_TRANSLATOR; + +// +// Protocol definitions +// + +/** + Retrieves the Host Controller capabilities. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param MaxSpeed Host controller data transfer speed. + @param PortNumber Number of the root hub ports. + @param Is64BitCapable TRUE if controller supports 64-bit memory addressing, + FALSE otherwise. + + @retval EFI_SUCCESS The host controller capabilities were retrieved successfully. + @retval EFI_INVALID_PARAMETER One of the input args was NULL. + @retval EFI_DEVICE_ERROR An error was encountered while attempting to + retrieve the capabilities. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_CAPABILITY)( + IN EFI_USB2_HC_PROTOCOL *This, + OUT UINT8 *MaxSpeed, + OUT UINT8 *PortNumber, + OUT UINT8 *Is64BitCapable + ); + +#define EFI_USB_HC_RESET_GLOBAL 0x0001 +#define EFI_USB_HC_RESET_HOST_CONTROLLER 0x0002 +#define EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG 0x0004 +#define EFI_USB_HC_RESET_HOST_WITH_DEBUG 0x0008 +/** + Provides software reset for the USB host controller. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param Attributes A bit mask of the reset operation to perform. + + @retval EFI_SUCCESS The reset operation succeeded. + @retval EFI_INVALID_PARAMETER Attributes is not valid. + @retval EFI_UNSUPPORTED The type of reset specified by Attributes is not currently + supported by the host controller hardware. + @retval EFI_ACCESS_DENIED Reset operation is rejected due to the debug port being configured + and active; only EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG or + EFI_USB_HC_RESET_HOST_WITH_DEBUG reset Attributes can be used to + perform reset operation for this host controller. + @retval EFI_DEVICE_ERROR An error was encountered while attempting to + retrieve the capabilities. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_RESET)( + IN EFI_USB2_HC_PROTOCOL *This, + IN UINT16 Attributes + ); + +/** + Enumration value for status of USB HC. +**/ +typedef enum { + EfiUsbHcStateHalt, ///< The host controller is in halt + ///< state. No USB transactions can occur + ///< while in this state. The host + ///< controller can enter this state for + ///< three reasons: 1) After host + ///< controller hardware reset. 2) + ///< Explicitly set by software. 3) + ///< Triggered by a fatal error such as + ///< consistency check failure. + + EfiUsbHcStateOperational, ///< The host controller is in an + ///< operational state. When in + ///< this state, the host + ///< controller can execute bus + ///< traffic. This state must be + ///< explicitly set to enable the + ///< USB bus traffic. + + EfiUsbHcStateSuspend, ///< The host controller is in the + ///< suspend state. No USB + ///< transactions can occur while in + ///< this state. The host controller + ///< enters this state for the + ///< following reasons: 1) Explicitly + ///< set by software. 2) Triggered + ///< when there is no bus traffic for + ///< 3 microseconds. + + EfiUsbHcStateMaximum ///< Maximum value for enumration value of HC status. +} EFI_USB_HC_STATE; + +/** + Retrieves current state of the USB host controller. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param State A pointer to the EFI_USB_HC_STATE data structure that + indicates current state of the USB host controller. + + @retval EFI_SUCCESS The state information of the host controller was returned in State. + @retval EFI_INVALID_PARAMETER State is NULL. + @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the + host controller's current state. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_STATE)( + IN EFI_USB2_HC_PROTOCOL *This, + OUT EFI_USB_HC_STATE *State +); + +/** + Sets the USB host controller to a specific state. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param State Indicates the state of the host controller that will be set. + + @retval EFI_SUCCESS The USB host controller was successfully placed in the state + specified by State. + @retval EFI_INVALID_PARAMETER State is not valid. + @retval EFI_DEVICE_ERROR Failed to set the state specified by State due to device error. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_SET_STATE)( + IN EFI_USB2_HC_PROTOCOL *This, + IN EFI_USB_HC_STATE State + ); + +/** + Submits control transfer to a target USB device. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB. + @param DeviceSpeed Indicates device speed. + @param MaximumPacketLength Indicates the maximum packet size that the default control transfer + endpoint is capable of sending or receiving. + @param Request A pointer to the USB device request that will be sent to the USB device. + @param TransferDirection Specifies the data direction for the transfer. There are three values + available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData. + @param Data A pointer to the buffer of data that will be transmitted to USB device or + received from USB device. + @param DataLength On input, indicates the size, in bytes, of the data buffer specified by Data. + On output, indicates the amount of data actually transferred. + @param TimeOut Indicates the maximum time, in milliseconds, which the transfer is + allowed to complete. + @param Translator A pointer to the transaction translator data. + @param TransferResult A pointer to the detailed result information generated by this control + transfer. + + @retval EFI_SUCCESS The control transfer was completed successfully. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_OUT_OF_RESOURCES The control transfer could not be completed due to a lack of resources. + @retval EFI_TIMEOUT The control transfer failed due to timeout. + @retval EFI_DEVICE_ERROR The control transfer failed due to host controller or device error. + Caller should check TransferResult for detailed error information. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_CONTROL_TRANSFER)( + IN EFI_USB2_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 DeviceSpeed, + IN UINTN MaximumPacketLength, + IN EFI_USB_DEVICE_REQUEST *Request, + IN EFI_USB_DATA_DIRECTION TransferDirection, + IN OUT VOID *Data OPTIONAL, + IN OUT UINTN *DataLength OPTIONAL, + IN UINTN TimeOut, + IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator, + OUT UINT32 *TransferResult + ); + +#define EFI_USB_MAX_BULK_BUFFER_NUM 10 + +/** + Submits bulk transfer to a bulk endpoint of a USB device. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB. + @param EndPointAddress The combination of an endpoint number and an endpoint direction of the + target USB device. + @param DeviceSpeed Indicates device speed. + @param MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of + sending or receiving. + @param DataBuffersNumber Number of data buffers prepared for the transfer. + @param Data Array of pointers to the buffers of data that will be transmitted to USB + device or received from USB device. + @param DataLength When input, indicates the size, in bytes, of the data buffers specified by + Data. When output, indicates the actually transferred data size. + @param DataToggle A pointer to the data toggle value. + @param TimeOut Indicates the maximum time, in milliseconds, which the transfer is + allowed to complete. + @param Translator A pointer to the transaction translator data. + @param TransferResult A pointer to the detailed result information of the bulk transfer. + + @retval EFI_SUCCESS The bulk transfer was completed successfully. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_OUT_OF_RESOURCES The bulk transfer could not be submitted due to a lack of resources. + @retval EFI_TIMEOUT The bulk transfer failed due to timeout. + @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. + Caller should check TransferResult for detailed error information. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_BULK_TRANSFER)( + IN EFI_USB2_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 EndPointAddress, + IN UINT8 DeviceSpeed, + IN UINTN MaximumPacketLength, + IN UINT8 DataBuffersNumber, + IN OUT VOID *Data[EFI_USB_MAX_BULK_BUFFER_NUM], + IN OUT UINTN *DataLength, + IN OUT UINT8 *DataToggle, + IN UINTN TimeOut, + IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator, + OUT UINT32 *TransferResult + ); + +/** + Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device. + Translator parameter doesn't exist in UEFI2.0 spec, but it will be updated in the following specification version. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB. + @param EndPointAddress The combination of an endpoint number and an endpoint direction of the + target USB device. + @param DeviceSpeed Indicates device speed. + @param MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of + sending or receiving. + @param IsNewTransfer If TRUE, an asynchronous interrupt pipe is built between the host and the + target interrupt endpoint. If FALSE, the specified asynchronous interrupt + pipe is canceled. If TRUE, and an interrupt transfer exists for the target + end point, then EFI_INVALID_PARAMETER is returned. + @param DataToggle A pointer to the data toggle value. + @param PollingInterval Indicates the interval, in milliseconds, that the asynchronous interrupt + transfer is polled. + @param DataLength Indicates the length of data to be received at the rate specified by + PollingInterval from the target asynchronous interrupt endpoint. + @param Translator A pointr to the transaction translator data. + @param CallBackFunction The Callback function. This function is called at the rate specified by + PollingInterval. + @param Context The context that is passed to the CallBackFunction. This is an + optional parameter and may be NULL. + + @retval EFI_SUCCESS The asynchronous interrupt transfer request has been successfully + submitted or canceled. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER)( + IN EFI_USB2_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 EndPointAddress, + IN UINT8 DeviceSpeed, + IN UINTN MaxiumPacketLength, + IN BOOLEAN IsNewTransfer, + IN OUT UINT8 *DataToggle, + IN UINTN PollingInterval OPTIONAL, + IN UINTN DataLength OPTIONAL, + IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator OPTIONAL, + IN EFI_ASYNC_USB_TRANSFER_CALLBACK CallBackFunction OPTIONAL, + IN VOID *Context OPTIONAL + ); + +/** + Submits synchronous interrupt transfer to an interrupt endpoint of a USB device. + Translator parameter doesn't exist in UEFI2.0 spec, but it will be updated in the following specification version. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB. + @param EndPointAddress The combination of an endpoint number and an endpoint direction of the + target USB device. + @param DeviceSpeed Indicates device speed. + @param MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of + sending or receiving. + @param Data A pointer to the buffer of data that will be transmitted to USB device or + received from USB device. + @param DataLength On input, the size, in bytes, of the data buffer specified by Data. On + output, the number of bytes transferred. + @param DataToggle A pointer to the data toggle value. + @param TimeOut Indicates the maximum time, in milliseconds, which the transfer is + allowed to complete. + @param Translator A pointr to the transaction translator data. + @param TransferResult A pointer to the detailed result information from the synchronous + interrupt transfer. + + @retval EFI_SUCCESS The synchronous interrupt transfer was completed successfully. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_OUT_OF_RESOURCES The synchronous interrupt transfer could not be submitted due to a lack of resources. + @retval EFI_TIMEOUT The synchronous interrupt transfer failed due to timeout. + @retval EFI_DEVICE_ERROR The synchronous interrupt transfer failed due to host controller or device error. + Caller should check TransferResult for detailed error information. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER)( + IN EFI_USB2_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 EndPointAddress, + IN UINT8 DeviceSpeed, + IN UINTN MaximumPacketLength, + IN OUT VOID *Data, + IN OUT UINTN *DataLength, + IN OUT UINT8 *DataToggle, + IN UINTN TimeOut, + IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator, + OUT UINT32 *TransferResult + ); + +#define EFI_USB_MAX_ISO_BUFFER_NUM 7 +#define EFI_USB_MAX_ISO_BUFFER_NUM1 2 + +/** + Submits isochronous transfer to an isochronous endpoint of a USB device. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB. + @param EndPointAddress The combination of an endpoint number and an endpoint direction of the + target USB device. + @param DeviceSpeed Indicates device speed. + @param MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of + sending or receiving. + @param DataBuffersNumber Number of data buffers prepared for the transfer. + @param Data Array of pointers to the buffers of data that will be transmitted to USB + device or received from USB device. + @param DataLength Specifies the length, in bytes, of the data to be sent to or received from + the USB device. + @param Translator A pointer to the transaction translator data. + @param TransferResult A pointer to the detailed result information of the isochronous transfer. + + @retval EFI_SUCCESS The isochronous transfer was completed successfully. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_OUT_OF_RESOURCES The isochronous transfer could not be submitted due to a lack of resources. + @retval EFI_TIMEOUT The isochronous transfer cannot be completed within the one USB frame time. + @retval EFI_DEVICE_ERROR The isochronous transfer failed due to host controller or device error. + Caller should check TransferResult for detailed error information. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_ISOCHRONOUS_TRANSFER)( + IN EFI_USB2_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 EndPointAddress, + IN UINT8 DeviceSpeed, + IN UINTN MaximumPacketLength, + IN UINT8 DataBuffersNumber, + IN OUT VOID *Data[EFI_USB_MAX_ISO_BUFFER_NUM], + IN UINTN DataLength, + IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator, + OUT UINT32 *TransferResult + ); + +/** + Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB. + @param EndPointAddress The combination of an endpoint number and an endpoint direction of the + target USB device. + @param DeviceSpeed Indicates device speed. + @param MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of + sending or receiving. + @param DataBuffersNumber Number of data buffers prepared for the transfer. + @param Data Array of pointers to the buffers of data that will be transmitted to USB + device or received from USB device. + @param DataLength Specifies the length, in bytes, of the data to be sent to or received from + the USB device. + @param Translator A pointer to the transaction translator data. + @param IsochronousCallback The Callback function. This function is called if the requested + isochronous transfer is completed. + @param Context Data passed to the IsochronousCallback function. This is an + optional parameter and may be NULL. + + @retval EFI_SUCCESS The asynchronous isochronous transfer request has been successfully + submitted or canceled. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_OUT_OF_RESOURCES The asynchronous isochronous transfer could not be submitted due to + a lack of resources. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER)( + IN EFI_USB2_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 EndPointAddress, + IN UINT8 DeviceSpeed, + IN UINTN MaximumPacketLength, + IN UINT8 DataBuffersNumber, + IN OUT VOID *Data[EFI_USB_MAX_ISO_BUFFER_NUM], + IN UINTN DataLength, + IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator, + IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack, + IN VOID *Context OPTIONAL + ); + +/** + Retrieves the current status of a USB root hub port. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param PortNumber Specifies the root hub port from which the status is to be retrieved. + This value is zero based. + @param PortStatus A pointer to the current port status bits and port status change bits. + + @retval EFI_SUCCESS The status of the USB root hub port specified by PortNumber + was returned in PortStatus. + @retval EFI_INVALID_PARAMETER PortNumber is invalid. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS)( + IN EFI_USB2_HC_PROTOCOL *This, + IN UINT8 PortNumber, + OUT EFI_USB_PORT_STATUS *PortStatus + ); + +/** + Sets a feature for the specified root hub port. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param PortNumber Specifies the root hub port whose feature is requested to be set. This + value is zero based. + @param PortFeature Indicates the feature selector associated with the feature set request. + + @retval EFI_SUCCESS The feature specified by PortFeature was set for the USB + root hub port specified by PortNumber. + @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE)( + IN EFI_USB2_HC_PROTOCOL *This, + IN UINT8 PortNumber, + IN EFI_USB_PORT_FEATURE PortFeature + ); + +/** + Clears a feature for the specified root hub port. + + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param PortNumber Specifies the root hub port whose feature is requested to be cleared. This + value is zero based. + @param PortFeature Indicates the feature selector associated with the feature clear request. + + @retval EFI_SUCCESS The feature specified by PortFeature was cleared for the USB + root hub port specified by PortNumber. + @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE)( + IN EFI_USB2_HC_PROTOCOL *This, + IN UINT8 PortNumber, + IN EFI_USB_PORT_FEATURE PortFeature + ); + +/// +/// The EFI_USB2_HC_PROTOCOL provides USB host controller management, basic +/// data transactions over a USB bus, and USB root hub access. A device driver +/// that wishes to manage a USB bus in a system retrieves the EFI_USB2_HC_PROTOCOL +/// instance that is associated with the USB bus to be managed. A device handle +/// for a USB host controller will minimally contain an EFI_DEVICE_PATH_PROTOCOL +/// instance, and an EFI_USB2_HC_PROTOCOL instance. +/// +struct _EFI_USB2_HC_PROTOCOL { + EFI_USB2_HC_PROTOCOL_GET_CAPABILITY GetCapability; + EFI_USB2_HC_PROTOCOL_RESET Reset; + EFI_USB2_HC_PROTOCOL_GET_STATE GetState; + EFI_USB2_HC_PROTOCOL_SET_STATE SetState; + EFI_USB2_HC_PROTOCOL_CONTROL_TRANSFER ControlTransfer; + EFI_USB2_HC_PROTOCOL_BULK_TRANSFER BulkTransfer; + EFI_USB2_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER AsyncInterruptTransfer; + EFI_USB2_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER SyncInterruptTransfer; + EFI_USB2_HC_PROTOCOL_ISOCHRONOUS_TRANSFER IsochronousTransfer; + EFI_USB2_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER AsyncIsochronousTransfer; + EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus; + EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature; + EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature; + + /// + /// The major revision number of the USB host controller. The revision information + /// indicates the release of the Universal Serial Bus Specification with which the + /// host controller is compliant. + /// + UINT16 MajorRevision; + + /// + /// The minor revision number of the USB host controller. The revision information + /// indicates the release of the Universal Serial Bus Specification with which the + /// host controller is compliant. + /// + UINT16 MinorRevision; +}; + +extern EFI_GUID gEfiUsb2HcProtocolGuid; + +#endif diff --git a/src/include/ipxe/efi/Protocol/UsbHostController.h b/src/include/ipxe/efi/Protocol/UsbHostController.h new file mode 100644 index 00000000..a29088c6 --- /dev/null +++ b/src/include/ipxe/efi/Protocol/UsbHostController.h @@ -0,0 +1,510 @@ +/** @file + EFI_USB_HC_PROTOCOL as defined in EFI 1.10. + + The USB Host Controller Protocol is used by code, typically USB bus drivers, + running in the EFI boot services environment, to perform data transactions + over a USB bus. In addition, it provides an abstraction for the root hub of the USB bus. + + 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. + +**/ + +#ifndef _USB_HOSTCONTROLLER_H_ +#define _USB_HOSTCONTROLLER_H_ + +FILE_LICENCE ( BSD3 ); + +#include + +#define EFI_USB_HC_PROTOCOL_GUID \ + { \ + 0xf5089266, 0x1aa0, 0x4953, {0x97, 0xd8, 0x56, 0x2f, 0x8a, 0x73, 0xb5, 0x19 } \ + } + +/// +/// Forward reference for pure ANSI compatability +/// +typedef struct _EFI_USB_HC_PROTOCOL EFI_USB_HC_PROTOCOL; + +// +// Protocol definitions +// + +/** + Provides software reset for the USB host controller. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param Attributes A bit mask of the reset operation to perform. + + @retval EFI_SUCCESS The reset operation succeeded. + @retval EFI_UNSUPPORTED The type of reset specified by Attributes is not currently supported + by the host controller hardware. + @retval EFI_INVALID_PARAMETER Attributes is not valid. + @retval EFI_DEVICE_ERROR An error was encountered while attempting to perform the reset operation. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_RESET)( + IN EFI_USB_HC_PROTOCOL *This, + IN UINT16 Attributes + ); + +/** + Retrieves current state of the USB host controller. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param State A pointer to the EFI_USB_HC_STATE data structure that + indicates current state of the USB host controller. + + @retval EFI_SUCCESS The state information of the host controller was returned in State. + @retval EFI_INVALID_PARAMETER State is NULL. + @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the host controller's + current state. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_GET_STATE)( + IN EFI_USB_HC_PROTOCOL *This, + OUT EFI_USB_HC_STATE *State + ); + +/** + Sets the USB host controller to a specific state. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param State Indicates the state of the host controller that will be set. + + @retval EFI_SUCCESS The USB host controller was successfully placed in the state specified by + State. + @retval EFI_INVALID_PARAMETER State is NULL. + @retval EFI_DEVICE_ERROR Failed to set the state specified by State due to device error. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_SET_STATE)( + IN EFI_USB_HC_PROTOCOL *This, + IN EFI_USB_HC_STATE State + ); + +/** + Submits control transfer to a target USB device. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB, which is + assigned during USB enumeration. + @param IsSlowDevice Indicates whether the target device is slow device or full-speed + device. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. + @param Request A pointer to the USB device request that will be sent to the USB + device. + @param TransferDirection Specifies the data direction for the transfer. There are three + values available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. + @param DataLength On input, indicates the size, in bytes, of the data buffer specified + by Data. On output, indicates the amount of data actually + transferred. + @param TimeOut Indicates the maximum time, in milliseconds, which the transfer + is allowed to complete. + @param TransferResult A pointer to the detailed result information generated by this + control transfer. + + @retval EFI_SUCCESS The control transfer was completed successfully. + @retval EFI_OUT_OF_RESOURCES The control transfer could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_TIMEOUT The control transfer failed due to timeout. + @retval EFI_DEVICE_ERROR The control transfer failed due to host controller or device error. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER)( + IN EFI_USB_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN BOOLEAN IsSlowDevice, + IN UINT8 MaximumPacketLength, + IN EFI_USB_DEVICE_REQUEST *Request, + IN EFI_USB_DATA_DIRECTION TransferDirection, + IN OUT VOID *Data OPTIONAL, + IN OUT UINTN *DataLength OPTIONAL, + IN UINTN TimeOut, + OUT UINT32 *TransferResult + ); + +/** + Submits bulk transfer to a bulk endpoint of a USB device. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB, which is + assigned during USB enumeration. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is 0). It is the + caller's responsibility to make sure that the EndPointAddress + represents a bulk endpoint. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. + @param DataLength On input, indicates the size, in bytes, of the data buffer specified + by Data. On output, indicates the amount of data actually + transferred. + @param DataToggle A pointer to the data toggle value. + @param TimeOut Indicates the maximum time, in milliseconds, which the transfer + is allowed to complete. + @param TransferResult A pointer to the detailed result information of the bulk transfer. + + @retval EFI_SUCCESS The bulk transfer was completed successfully. + @retval EFI_OUT_OF_RESOURCES The bulk transfer could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_TIMEOUT The bulk transfer failed due to timeout. + @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_BULK_TRANSFER)( + IN EFI_USB_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 EndPointAddress, + IN UINT8 MaximumPacketLength, + IN OUT VOID *Data, + IN OUT UINTN *DataLength, + IN OUT UINT8 *DataToggle, + IN UINTN TimeOut, + OUT UINT32 *TransferResult + ); + +/** + Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB, which is + assigned during USB enumeration. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is zero). It is the + caller's responsibility to make sure that the + EndPointAddress represents an interrupt endpoint. + @param IsSlowDevice Indicates whether the target device is slow device or full-speed + device. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. + @param IsNewTransfer If TRUE, an asynchronous interrupt pipe is built between the host + and the target interrupt endpoint. If FALSE, the specified asynchronous + interrupt pipe is canceled. If TRUE, and an interrupt transfer exists + for the target end point, then EFI_INVALID_PARAMETER is returned. + @param DataToggle A pointer to the data toggle value. On input, it is valid when + IsNewTransfer is TRUE, and it indicates the initial data toggle + value the asynchronous interrupt transfer should adopt. On output, + it is valid when IsNewTransfer is FALSE, and it is updated to indicate + the data toggle value of the subsequent asynchronous interrupt transfer. + @param PollingInterval Indicates the interval, in milliseconds, that the asynchronous + interrupt transfer is polled. + @param DataLength Indicates the length of data to be received at the rate specified by + PollingInterval from the target asynchronous interrupt + endpoint. This parameter is only required when IsNewTransfer is TRUE. + @param CallBackFunction The Callback function. This function is called at the rate specified by + PollingInterval. This parameter is only required when IsNewTransfer is TRUE. + @param Context The context that is passed to the CallBackFunction. + + @retval EFI_SUCCESS The asynchronous interrupt transfer request has been successfully + submitted or canceled. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_TIMEOUT The bulk transfer failed due to timeout. + @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER)( + IN EFI_USB_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 EndPointAddress, + IN BOOLEAN IsSlowDevice, + IN UINT8 MaxiumPacketLength, + IN BOOLEAN IsNewTransfer, + IN OUT UINT8 *DataToggle, + IN UINTN PollingInterval OPTIONAL, + IN UINTN DataLength OPTIONAL, + IN EFI_ASYNC_USB_TRANSFER_CALLBACK CallBackFunction OPTIONAL, + IN VOID *Context OPTIONAL + ); + +/** + Submits synchronous interrupt transfer to an interrupt endpoint of a USB device. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB, which is + assigned during USB enumeration. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is zero). It is the + caller's responsibility to make sure that the + EndPointAddress represents an interrupt endpoint. + @param IsSlowDevice Indicates whether the target device is slow device or full-speed + device. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. asynchronous interrupt pipe is canceled. + @param DataLength On input, the size, in bytes, of the data buffer specified by Data. + On output, the number of bytes transferred. + @param DataToggle A pointer to the data toggle value. On input, it indicates the initial + data toggle value the synchronous interrupt transfer should adopt; + on output, it is updated to indicate the data toggle value of the + subsequent synchronous interrupt transfer. + @param TimeOut Indicates the maximum time, in milliseconds, which the transfer + is allowed to complete. + @param TransferResult A pointer to the detailed result information from the synchronous + interrupt transfer. + + @retval EFI_SUCCESS The synchronous interrupt transfer was completed successfully. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_TIMEOUT The synchronous interrupt transfer failed due to timeout. + @retval EFI_DEVICE_ERROR The synchronous interrupt transfer failed due to host controller or device error. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER)( + IN EFI_USB_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 EndPointAddress, + IN BOOLEAN IsSlowDevice, + IN UINT8 MaximumPacketLength, + IN OUT VOID *Data, + IN OUT UINTN *DataLength, + IN OUT UINT8 *DataToggle, + IN UINTN TimeOut, + OUT UINT32 *TransferResult + ); + +/** + Submits isochronous transfer to an isochronous endpoint of a USB device. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB, which is + assigned during USB enumeration. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is 0). It is the caller's + responsibility to make sure that the EndPointAddress + represents an isochronous endpoint. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. asynchronous interrupt pipe is canceled. + @param DataLength Specifies the length, in bytes, of the data to be sent to or received + from the USB device. + @param TransferResult A pointer to the detailed result information from the isochronous + transfer. + + @retval EFI_SUCCESS The isochronous transfer was completed successfully. + @retval EFI_OUT_OF_RESOURCES The isochronous could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_TIMEOUT The isochronous transfer failed due to timeout. + @retval EFI_DEVICE_ERROR The isochronous transfer failed due to host controller or device error. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER)( + IN EFI_USB_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 EndPointAddress, + IN UINT8 MaximumPacketLength, + IN OUT VOID *Data, + IN UINTN DataLength, + OUT UINT32 *TransferResult + ); + +/** + Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param DeviceAddress Represents the address of the target device on the USB, which is + assigned during USB enumeration. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is zero). It is the + caller's responsibility to make sure that the + EndPointAddress represents an isochronous endpoint. + @param MaximumPacketLength Indicates the maximum packet size that the default control + transfer endpoint is capable of sending or receiving. For isochronous + endpoints, this value is used to reserve the bus time in the schedule, + required for the perframe data payloads. The pipe may, on an ongoing basis, + actually use less bandwidth than that reserved. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. asynchronous interrupt pipe is canceled. + @param DataLength Specifies the length, in bytes, of the data to be sent to or received + from the USB device. + @param IsochronousCallback The Callback function.This function is called if the requested + isochronous transfer is completed. + @param Context Data passed to the IsochronousCallback function. This is + an optional parameter and may be NULL. + + @retval EFI_SUCCESS The asynchronous isochronous transfer was completed successfully. + @retval EFI_OUT_OF_RESOURCES The asynchronous isochronous could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER)( + IN EFI_USB_HC_PROTOCOL *This, + IN UINT8 DeviceAddress, + IN UINT8 EndPointAddress, + IN UINT8 MaximumPacketLength, + IN OUT VOID *Data, + IN UINTN DataLength, + IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack, + IN VOID *Context OPTIONAL + ); + +/** + Retrieves the number of root hub ports. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param PortNumber A pointer to the number of the root hub ports. + + @retval EFI_SUCCESS The port number was retrieved successfully. + @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the port number. + @retval EFI_INVALID_PARAMETER PortNumber is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER)( + IN EFI_USB_HC_PROTOCOL *This, + OUT UINT8 *PortNumber + ); + +/** + Retrieves the current status of a USB root hub port. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param PortNumber Specifies the root hub port from which the status is to be retrieved. + This value is zero based. For example, if a root hub has two ports, + then the first port is numbered 0, and the second port is + numbered 1. + @param PortStatus A pointer to the current port status bits and port status change bits. + + @retval EFI_SUCCESS The status of the USB root hub port specified by PortNumber + was returned in PortStatus. + @retval EFI_INVALID_PARAMETER PortNumber is invalid. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS)( + IN EFI_USB_HC_PROTOCOL *This, + IN UINT8 PortNumber, + OUT EFI_USB_PORT_STATUS *PortStatus + ); + +/** + Sets a feature for the specified root hub port. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param PortNumber Specifies the root hub port from which the status is to be retrieved. + This value is zero based. For example, if a root hub has two ports, + then the first port is numbered 0, and the second port is + numbered 1. + @param PortFeature Indicates the feature selector associated with the feature set + request. + + @retval EFI_SUCCESS The feature specified by PortFeature was set for the USB + root hub port specified by PortNumber. + @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE)( + IN EFI_USB_HC_PROTOCOL *This, + IN UINT8 PortNumber, + IN EFI_USB_PORT_FEATURE PortFeature + ); + +/** + Clears a feature for the specified root hub port. + + @param This A pointer to the EFI_USB_HC_PROTOCOL instance. + @param PortNumber Specifies the root hub port from which the status is to be retrieved. + This value is zero based. For example, if a root hub has two ports, + then the first port is numbered 0, and the second port is + numbered 1. + @param PortFeature Indicates the feature selector associated with the feature clear + request. + + @retval EFI_SUCCESS The feature specified by PortFeature was cleared for the USB + root hub port specified by PortNumber. + @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE)( + IN EFI_USB_HC_PROTOCOL *This, + IN UINT8 PortNumber, + IN EFI_USB_PORT_FEATURE PortFeature + ); + + +/// +/// The EFI_USB_HC_PROTOCOL provides USB host controller management, basic data transactions +/// over a USB bus, and USB root hub access. A device driver that wishes to manage a USB bus in a +/// system retrieves the EFI_USB_HC_PROTOCOL instance that is associated with the USB bus to be +/// managed. A device handle for a USB host controller will minimally contain an +/// EFI_DEVICE_PATH_PROTOCOL instance, and an EFI_USB_HC_PROTOCOL instance. +/// +struct _EFI_USB_HC_PROTOCOL { + EFI_USB_HC_PROTOCOL_RESET Reset; + EFI_USB_HC_PROTOCOL_GET_STATE GetState; + EFI_USB_HC_PROTOCOL_SET_STATE SetState; + EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER ControlTransfer; + EFI_USB_HC_PROTOCOL_BULK_TRANSFER BulkTransfer; + EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER AsyncInterruptTransfer; + EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER SyncInterruptTransfer; + EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER IsochronousTransfer; + EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER AsyncIsochronousTransfer; + EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER GetRootHubPortNumber; + EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus; + EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature; + EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature; + /// + /// The major revision number of the USB host controller. The revision information + /// indicates the release of the Universal Serial Bus Specification with which the + /// host controller is compliant. + /// + UINT16 MajorRevision; + /// + /// The minor revision number of the USB host controller. The revision information + /// indicates the release of the Universal Serial Bus Specification with which the + /// host controller is compliant. + /// + UINT16 MinorRevision; +}; + +extern EFI_GUID gEfiUsbHcProtocolGuid; + +#endif diff --git a/src/include/ipxe/efi/Protocol/UsbIo.h b/src/include/ipxe/efi/Protocol/UsbIo.h new file mode 100644 index 00000000..b8d33ee0 --- /dev/null +++ b/src/include/ipxe/efi/Protocol/UsbIo.h @@ -0,0 +1,514 @@ +/** @file + 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. + +**/ + +#ifndef __USB_IO_H__ +#define __USB_IO_H__ + +FILE_LICENCE ( BSD3 ); + +#include + +// +// Global ID for the USB I/O Protocol +// +#define EFI_USB_IO_PROTOCOL_GUID \ + { \ + 0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \ + } + +typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL; + +// +// Related Definition for EFI USB I/O protocol +// + +// +// USB standard descriptors and reqeust +// +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; + +/// +/// USB data transfer direction +/// +typedef enum { + EfiUsbDataIn, + EfiUsbDataOut, + EfiUsbNoData +} EFI_USB_DATA_DIRECTION; + +// +// USB Transfer Results +// +#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 + +/** + Async USB transfer callback routine. + + @param Data Data received or sent via the USB Asynchronous Transfer, if the + transfer completed successfully. + @param DataLength The length of Data received or sent via the Asynchronous + Transfer, if transfer successfully completes. + @param Context Data passed from UsbAsyncInterruptTransfer() request. + @param Status Indicates the result of the asynchronous transfer. + + @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed. + @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK)( + IN VOID *Data, + IN UINTN DataLength, + IN VOID *Context, + IN UINT32 Status + ); + +// +// Prototype for EFI USB I/O protocol +// + + +/** + 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. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param Request A pointer to the USB device request that will be sent to the USB + device. + @param Direction Indicates the data direction. + @param Timeout Indicating the transfer should be completed within this time frame. + The units are in milliseconds. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. + @param DataLength The size, in bytes, of the data buffer specified by Data. + @param Status A pointer to the result of the USB transfer. + + @retval EFI_SUCCESS The control transfer has been successfully executed. + @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status. + @retval EFI_INVALID_PARAMETE One or more parameters are invalid. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_TIMEOUT The control transfer fails due to timeout. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_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 the bulk transfer pipe. Bulk Transfers are + typically used to transfer large amounts of data to/from USB devices. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param DeviceEndpoint The 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. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. + @param DataLength The 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. + @param Timeout Indicating 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. + @param Status This parameter indicates the USB transfer status. + + @retval EFI_SUCCESS The bulk transfer has been successfully executed. + @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status. + @retval EFI_INVALID_PARAMETE One or more parameters are invalid. + @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. + @retval EFI_TIMEOUT The control transfer fails due to timeout. + +**/ +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 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. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param DeviceEndpoint The 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. + @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If + FALSE, the interrupt transfer is deleted from the device's interrupt + transfer queue. + @param PollingInterval Indicates 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. + @param DataLength Specifies the length, in bytes, of the data to be received from the + USB device. This parameter is only required when IsNewTransfer is TRUE. + @param InterruptCallback The Callback function. This function is called if the asynchronous + interrupt transfer is completed. This parameter is required + when IsNewTransfer is TRUE. + @param Context Data passed to the InterruptCallback function. This is an optional + parameter and may be NULL. + + @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed. + @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed. + +**/ +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. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param DeviceEndpoint The 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. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. + @param DataLength On input, then size, in bytes, of the buffer Data. On output, the + amount of data actually transferred. + @param Timeout The 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. + @param Status This parameter indicates the USB transfer status. + + @retval EFI_SUCCESS The sync interrupt transfer has been successfully executed. + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed. + @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. + @retval EFI_TIMEOUT The transfer fails due to timeout. +**/ +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 isochronous transfer pipe. An Isochronous + transfer is typically used to transfer streaming data. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param DeviceEndpoint The 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. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. + @param DataLength The size, in bytes, of the data buffer specified by Data. + @param Status This parameter indicates the USB transfer status. + + @retval EFI_SUCCESS The isochronous transfer has been successfully executed. + @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid. + @retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status + is returned in Status. + @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. + @retval EFI_TIMEOUT The transfer fails due to timeout. +**/ +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. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param DeviceEndpoint The 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. + @param Data A pointer to the buffer of data that will be transmitted to USB + device or received from USB device. + @param DataLength The size, in bytes, of the data buffer specified by Data. + This is an optional parameter and may be NULL. + @param IsochronousCallback The IsochronousCallback() function.This function is + called if the requested isochronous transfer is completed. + @param Context Data passed to the IsochronousCallback() function. + + @retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted + to the system. + @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid. + @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. + +**/ +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 + ); + +/** + Resets and reconfigures the USB controller. This function will work for all USB devices except + USB Hub Controllers. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + + @retval EFI_SUCCESS The USB controller was reset. + @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub. + @retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_IO_PORT_RESET)( + IN EFI_USB_IO_PROTOCOL *This + ); + +/** + Retrieves the USB Device Descriptor. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor. + + @retval EFI_SUCCESS The device descriptor was retrieved successfully. + @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL. + @retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR)( + IN EFI_USB_IO_PROTOCOL *This, + OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor + ); + +/** + Retrieves the USB Device Descriptor. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration + Descriptor. + @retval EFI_SUCCESS The active configuration descriptor was retrieved successfully. + @retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL. + @retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not + be configured. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR)( + IN EFI_USB_IO_PROTOCOL *This, + OUT EFI_USB_CONFIG_DESCRIPTOR *ConfigurationDescriptor + ); + +/** + 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. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within + the configuration setting. + @retval EFI_SUCCESS The interface descriptor retrieved successfully. + @retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL. + @retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be + correctly configured. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR)( + IN EFI_USB_IO_PROTOCOL *This, + OUT EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor + ); + +/** + Retrieves an Endpoint Descriptor within a USB Controller. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param EndpointIndex Indicates which endpoint descriptor to retrieve. + @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of + a USB controller. + + @retval EFI_SUCCESS The endpoint descriptor was retrieved successfully. + @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + @retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be + correctly configured. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR)( + IN EFI_USB_IO_PROTOCOL *This, + IN UINT8 EndpointIndex, + OUT EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDescriptor + ); + +/** + Retrieves a string stored in a USB Device. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param LangID The Language ID for the string being retrieved. + @param StringID The ID of the string being retrieved. + @param String A 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. + + @retval EFI_SUCCESS The string was retrieved successfully. + @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found. + @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR)( + IN EFI_USB_IO_PROTOCOL *This, + IN UINT16 LangID, + IN UINT8 StringID, + OUT CHAR16 **String + ); + +/** + Retrieves all the language ID codes that the USB device supports. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + @param LangIDTable Language 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. + @param TableSize The size, in bytes, of the table LangIDTable. + + @retval EFI_SUCCESS The support languages were retrieved successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE)( + IN EFI_USB_IO_PROTOCOL *This, + OUT UINT16 **LangIDTable, + OUT UINT16 *TableSize + ); + +/// +/// The EFI_USB_IO_PROTOCOL provides four basic transfers types described +/// in the USB 1.1 Specification. These include control transfer, interrupt +/// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL +/// also provides some basic USB device/controller management and configuration +/// interfaces. A USB device driver uses the services of this protocol to manage USB devices. +/// +struct _EFI_USB_IO_PROTOCOL { + // + // IO transfer + // + EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer; + EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer; + EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer; + EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer; + EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer; + EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer; + + // + // Common device request + // + EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor; + EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor; + EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor; + EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor; + EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor; + EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages; + + // + // Reset controller's parent port + // + EFI_USB_IO_PORT_RESET UsbPortReset; +}; + +extern EFI_GUID gEfiUsbIoProtocolGuid; + +#endif diff --git a/src/include/ipxe/efi/efi.h b/src/include/ipxe/efi/efi.h index c289eebe..a32e391a 100644 --- a/src/include/ipxe/efi/efi.h +++ b/src/include/ipxe/efi/efi.h @@ -199,6 +199,9 @@ extern EFI_GUID efi_udp4_protocol_guid; extern EFI_GUID efi_udp4_service_binding_protocol_guid; extern EFI_GUID efi_uga_draw_protocol_guid; extern EFI_GUID efi_unicode_collation_protocol_guid; +extern EFI_GUID efi_usb_hc_protocol_guid; +extern EFI_GUID efi_usb2_hc_protocol_guid; +extern EFI_GUID efi_usb_io_protocol_guid; extern EFI_GUID efi_vlan_config_protocol_guid; extern EFI_HANDLE efi_image_handle; diff --git a/src/interface/efi/efi_debug.c b/src/interface/efi/efi_debug.c index 97f37c6d..ed18ff92 100644 --- a/src/interface/efi/efi_debug.c +++ b/src/interface/efi/efi_debug.c @@ -163,6 +163,12 @@ static struct efi_well_known_guid efi_well_known_guids[] = { "UgaDraw" }, { &efi_unicode_collation_protocol_guid, "UnicodeCollation" }, + { &efi_usb_hc_protocol_guid, + "UsbHc" }, + { &efi_usb2_hc_protocol_guid, + "Usb2Hc" }, + { &efi_usb_io_protocol_guid, + "UsbIo" }, { &efi_vlan_config_protocol_guid, "VlanConfig" }, { &efi_vlan_config_dxe_guid, diff --git a/src/interface/efi/efi_guid.c b/src/interface/efi/efi_guid.c index 0a841225..63074d1a 100644 --- a/src/interface/efi/efi_guid.c +++ b/src/interface/efi/efi_guid.c @@ -61,6 +61,9 @@ FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL ); #include #include #include +#include +#include +#include #include /** @file @@ -258,6 +261,18 @@ EFI_GUID efi_uga_draw_protocol_guid EFI_GUID efi_unicode_collation_protocol_guid = EFI_UNICODE_COLLATION_PROTOCOL_GUID; +/** USB host controller protocol GUID */ +EFI_GUID efi_usb_hc_protocol_guid + = EFI_USB_HC_PROTOCOL_GUID; + +/** USB2 host controller protocol GUID */ +EFI_GUID efi_usb2_hc_protocol_guid + = EFI_USB2_HC_PROTOCOL_GUID; + +/** USB I/O protocol GUID */ +EFI_GUID efi_usb_io_protocol_guid + = EFI_USB_IO_PROTOCOL_GUID; + /** VLAN configuration protocol GUID */ EFI_GUID efi_vlan_config_protocol_guid = EFI_VLAN_CONFIG_PROTOCOL_GUID;