-/*++\r
+/** @file\r
+ Common Dxe Libarary for USB.\r
\r
-Copyright (c) 2006, Intel Corporation \r
-All rights reserved. This program and the accompanying materials \r
-are licensed and made available under the terms and conditions of the BSD License \r
-which accompanies this distribution. The full text of the license may be found at \r
-http://opensource.org/licenses/bsd-license.php \r
- \r
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+ Copyright (c) 2006 - 2008, Intel Corporation<BR>\r
+ All rights reserved. This program and the accompanying materials\r
+ are licensed and made available under the terms and conditions of the BSD License\r
+ which accompanies this distribution. The full text of the license may be found at\r
+ http://opensource.org/licenses/bsd-license.php\r
\r
- Module Name:\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
- UsbDxeLib.h\r
+**/\r
\r
- Abstract:\r
\r
- Common Dxe Libarary for USB\r
- Add Constants & structure definitions for Usb HID\r
+#ifndef __USB_DXE_LIB_H__\r
+#define __USB_DXE_LIB_H__\r
\r
- Revision History\r
-\r
---*/\r
-\r
-#ifndef _USB_DXE_LIB_H\r
-#define _USB_DXE_LIB_H\r
+#include <Protocol/UsbIo.h>\r
\r
//\r
// define the timeout time as 3ms\r
//\r
#define TIMEOUT_VALUE 3 * 1000\r
\r
-//\r
-// HID constants definition, see HID rev1.0\r
-//\r
-//\r
-// HID report item format\r
-//\r
-#define HID_ITEM_FORMAT_SHORT 0\r
-#define HID_ITEM_FORMAT_LONG 1\r
-\r
-//\r
-// Special tag indicating long items\r
-//\r
-#define HID_ITEM_TAG_LONG 15\r
-\r
-//\r
-// HID report descriptor item type (prefix bit 2,3)\r
-//\r
-#define HID_ITEM_TYPE_MAIN 0\r
-#define HID_ITEM_TYPE_GLOBAL 1\r
-#define HID_ITEM_TYPE_LOCAL 2\r
-#define HID_ITEM_TYPE_RESERVED 3\r
-\r
-//\r
-// HID report descriptor main item tags\r
-//\r
-#define HID_MAIN_ITEM_TAG_INPUT 8\r
-#define HID_MAIN_ITEM_TAG_OUTPUT 9\r
-#define HID_MAIN_ITEM_TAG_FEATURE 11\r
-#define HID_MAIN_ITEM_TAG_BEGIN_COLLECTION 10\r
-#define HID_MAIN_ITEM_TAG_END_COLLECTION 12\r
-\r
-//\r
-// HID report descriptor main item contents\r
-//\r
-#define HID_MAIN_ITEM_CONSTANT 0x001\r
-#define HID_MAIN_ITEM_VARIABLE 0x002\r
-#define HID_MAIN_ITEM_RELATIVE 0x004\r
-#define HID_MAIN_ITEM_WRAP 0x008\r
-#define HID_MAIN_ITEM_NONLINEAR 0x010\r
-#define HID_MAIN_ITEM_NO_PREFERRED 0x020\r
-#define HID_MAIN_ITEM_NULL_STATE 0x040\r
-#define HID_MAIN_ITEM_VOLATILE 0x080\r
-#define HID_MAIN_ITEM_BUFFERED_BYTE 0x100\r
-\r
-//\r
-// HID report descriptor collection item types\r
-//\r
-#define HID_COLLECTION_PHYSICAL 0\r
-#define HID_COLLECTION_APPLICATION 1\r
-#define HID_COLLECTION_LOGICAL 2\r
-\r
-//\r
-// HID report descriptor global item tags\r
-//\r
-#define HID_GLOBAL_ITEM_TAG_USAGE_PAGE 0\r
-#define HID_GLOBAL_ITEM_TAG_LOGICAL_MINIMUM 1\r
-#define HID_GLOBAL_ITEM_TAG_LOGICAL_MAXIMUM 2\r
-#define HID_GLOBAL_ITEM_TAG_PHYSICAL_MINIMUM 3\r
-#define HID_GLOBAL_ITEM_TAG_PHYSICAL_MAXIMUM 4\r
-#define HID_GLOBAL_ITEM_TAG_UNIT_EXPONENT 5\r
-#define HID_GLOBAL_ITEM_TAG_UNIT 6\r
-#define HID_GLOBAL_ITEM_TAG_REPORT_SIZE 7\r
-#define HID_GLOBAL_ITEM_TAG_REPORT_ID 8\r
-#define HID_GLOBAL_ITEM_TAG_REPORT_COUNT 9\r
-#define HID_GLOBAL_ITEM_TAG_PUSH 10\r
-#define HID_GLOBAL_ITEM_TAG_POP 11\r
-\r
-//\r
-// HID report descriptor local item tags\r
-//\r
-#define HID_LOCAL_ITEM_TAG_USAGE 0\r
-#define HID_LOCAL_ITEM_TAG_USAGE_MINIMUM 1\r
-#define HID_LOCAL_ITEM_TAG_USAGE_MAXIMUM 2\r
-#define HID_LOCAL_ITEM_TAG_DESIGNATOR_INDEX 3\r
-#define HID_LOCAL_ITEM_TAG_DESIGNATOR_MINIMUM 4\r
-#define HID_LOCAL_ITEM_TAG_DESIGNATOR_MAXIMUM 5\r
-#define HID_LOCAL_ITEM_TAG_STRING_INDEX 7\r
-#define HID_LOCAL_ITEM_TAG_STRING_MINIMUM 8\r
-#define HID_LOCAL_ITEM_TAG_STRING_MAXIMUM 9\r
-#define HID_LOCAL_ITEM_TAG_DELIMITER 10\r
-\r
-//\r
-// HID usage tables\r
-//\r
-#define HID_USAGE_PAGE 0xffff0000\r
-\r
-#define HID_UP_GENDESK 0x00010000\r
-#define HID_UP_KEYBOARD 0x00070000\r
-#define HID_UP_LED 0x00080000\r
-#define HID_UP_BUTTON 0x00090000\r
-#define HID_UP_CONSUMER 0x000c0000\r
-#define HID_UP_DIGITIZER 0x000d0000\r
-#define HID_UP_PID 0x000f0000\r
+/**\r
+ Get Hid Descriptor.\r
\r
-#define HID_USAGE 0x0000ffff\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param InterfaceNum Hid interface number.\r
+ @param HidDescriptor Caller allocated buffer to store Usb hid descriptor if\r
+ successfully returned.\r
\r
-#define HID_GD_POINTER 0x00010001\r
-#define HID_GD_MOUSE 0x00010002\r
-#define HID_GD_JOYSTICK 0x00010004\r
-#define HID_GD_GAMEPAD 0x00010005\r
-#define HID_GD_HATSWITCH 0x00010039\r
-\r
-//\r
-// HID report types\r
-//\r
-#define HID_INPUT_REPORT 1\r
-#define HID_OUTPUT_REPORT 2\r
-#define HID_FEATURE_REPORT 3\r
-\r
-//\r
-// HID device quirks.\r
-//\r
-#define HID_QUIRK_INVERT 0x01\r
-#define HID_QUIRK_NOTOUCH 0x02\r
-\r
-//\r
-// HID class protocol request\r
-//\r
-#define EFI_USB_GET_REPORT_REQUEST 0x01\r
-#define EFI_USB_GET_IDLE_REQUEST 0x02\r
-#define EFI_USB_GET_PROTOCOL_REQUEST 0x03\r
-#define EFI_USB_SET_REPORT_REQUEST 0x09\r
-#define EFI_USB_SET_IDLE_REQUEST 0x0a\r
-#define EFI_USB_SET_PROTOCOL_REQUEST 0x0b\r
-\r
-#pragma pack(1)\r
-//\r
-// Descriptor header for Report/Physical Descriptors\r
-//\r
-typedef struct hid_class_descriptor {\r
- UINT8 DescriptorType;\r
- UINT16 DescriptorLength;\r
-} EFI_USB_HID_CLASS_DESCRIPTOR;\r
-\r
-typedef struct hid_descriptor {\r
- UINT8 Length;\r
- UINT8 DescriptorType;\r
- UINT16 BcdHID;\r
- UINT8 CountryCode;\r
- UINT8 NumDescriptors;\r
- EFI_USB_HID_CLASS_DESCRIPTOR HidClassDesc[1];\r
-} EFI_USB_HID_DESCRIPTOR;\r
-\r
-#pragma pack()\r
+ @return Status of getting HID descriptor through USB I/O\r
+ protocol's UsbControlTransfer().\r
\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbGetHidDescriptor (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 InterfaceNum,\r
OUT EFI_USB_HID_DESCRIPTOR *HidDescriptor\r
);\r
\r
+\r
+/**\r
+ get Report Class descriptor.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param InterfaceNum Report interface number.\r
+ @param DescriptorSize Length of DescriptorBuffer.\r
+ @param DescriptorBuffer Caller allocated buffer to store Usb report descriptor\r
+ if successfully returned.\r
+\r
+ @return Status of getting Report Class descriptor through USB\r
+ I/O protocol's UsbControlTransfer().\r
+\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbGetReportDescriptor (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 InterfaceNum,\r
OUT UINT8 *DescriptorBuffer\r
);\r
\r
+/**\r
+ Get Hid Protocol Request.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Interface Which interface the caller wants to get protocol.\r
+ @param Protocol Protocol value returned.\r
+\r
+ @return Status of getting Protocol Request through USB I/O\r
+ protocol's UsbControlTransfer().\r
+\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbGetProtocolRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
IN UINT8 *Protocol\r
);\r
\r
+/**\r
+ Set Hid Protocol Request.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Interface Which interface the caller wants to set protocol.\r
+ @param Protocol Protocol value the caller wants to set.\r
+\r
+ @return Status of setting Protocol Request through USB I/O\r
+ protocol's UsbControlTransfer().\r
+\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbSetProtocolRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
IN UINT8 Protocol\r
);\r
\r
+/**\r
+ Set Idel request.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Interface Which interface the caller wants to set.\r
+ @param ReportId Which report the caller wants to set.\r
+ @param Duration Idle rate the caller wants to set.\r
+\r
+ @return Status of setting IDLE Request through USB I/O\r
+ protocol's UsbControlTransfer().\r
+\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbSetIdleRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
IN UINT8 Duration\r
);\r
\r
+/**\r
+ Get Idel request.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Interface Which interface the caller wants to get.\r
+ @param ReportId Which report the caller wants to get.\r
+ @param Duration Idle rate the caller wants to get.\r
+\r
+ @return Status of getting IDLE Request through USB I/O\r
+ protocol's UsbControlTransfer().\r
+\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbGetIdleRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
OUT UINT8 *Duration\r
);\r
\r
+/**\r
+ Hid Set Report request.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Interface Which interface the caller wants to set.\r
+ @param ReportId Which report the caller wants to set.\r
+ @param ReportType Type of report.\r
+ @param ReportLen Length of report descriptor.\r
+ @param Report Report Descriptor buffer.\r
+\r
+ @return Status of setting Report Request through USB I/O\r
+ protocol's UsbControlTransfer().\r
+\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbSetReportRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
IN UINT8 *Report\r
);\r
\r
+/**\r
+ Hid Set Report request.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Interface Which interface the caller wants to set.\r
+ @param ReportId Which report the caller wants to set.\r
+ @param ReportType Type of report.\r
+ @param ReportLen Length of report descriptor.\r
+ @param Report Caller allocated buffer to store Report Descriptor.\r
+\r
+ @return Status of getting Report Request through USB I/O\r
+ protocol's UsbControlTransfer().\r
+\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbGetReportRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
IN UINT8 *Report\r
);\r
\r
-//\r
-// Get Device Descriptor\r
-//\r
+/**\r
+ Usb Get Descriptor.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Value Device Request Value.\r
+ @param Index Device Request Index.\r
+ @param DescriptorLength Descriptor Length.\r
+ @param Descriptor Descriptor buffer to contain result.\r
+ @param Status Transfer Status.\r
+\r
+ @retval EFI_INVALID_PARAMETER Parameter is error.\r
+ @retval EFI_SUCCESS Success.\r
+ @retval EFI_TIMEOUT Device has no response.\r
+\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbGetDescriptor (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT16 Value,\r
OUT UINT32 *Status\r
);\r
\r
-//\r
-// Set Device Descriptor\r
-//\r
+/**\r
+ Usb Set Descriptor.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Value Device Request Value.\r
+ @param Index Device Request Index.\r
+ @param DescriptorLength Descriptor Length.\r
+ @param Descriptor Descriptor buffer to set.\r
+ @param Status Transfer Status.\r
+\r
+ @retval EFI_INVALID_PARAMETER Parameter is error.\r
+ @retval EFI_SUCCESS Success.\r
+ @retval EFI_TIMEOUT Device has no response.\r
+\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbSetDescriptor (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT16 Value,\r
OUT UINT32 *Status\r
);\r
\r
-//\r
-// Get device Interface\r
-//\r
+/**\r
+ Usb Get Device Interface.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Index Interface index value.\r
+ @param AltSetting Alternate setting.\r
+ @param Status Trasnsfer status.\r
+\r
+ @retval EFI_INVALID_PARAMETER Parameter is error.\r
+ @retval EFI_SUCCESS Success.\r
+ @retval EFI_TIMEOUT Device has no response.\r
+\r
+**/\r
EFI_STATUS\r
-UsbGetDeviceInterface (\r
+EFIAPI\r
+UsbGetInterface (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT16 Index,\r
OUT UINT8 *AltSetting,\r
OUT UINT32 *Status\r
);\r
\r
-//\r
-// Set device interface\r
-//\r
+/**\r
+ Usb Set Device Interface.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param InterfaceNo Interface Number.\r
+ @param AltSetting Alternate setting.\r
+ @param Status Trasnsfer status.\r
+\r
+ @retval EFI_INVALID_PARAMETER Parameter is error.\r
+ @retval EFI_SUCCESS Success.\r
+ @retval EFI_TIMEOUT Device has no response.\r
+\r
+**/\r
EFI_STATUS\r
-UsbSetDeviceInterface (\r
+EFIAPI\r
+UsbSetInterface (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT16 InterfaceNo,\r
IN UINT16 AltSetting,\r
OUT UINT32 *Status\r
);\r
\r
-//\r
-// Get device configuration\r
-//\r
+/**\r
+ Usb Get Device Configuration.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param ConfigValue Config Value.\r
+ @param Status Transfer Status.\r
+\r
+ @retval EFI_INVALID_PARAMETER Parameter is error.\r
+ @retval EFI_SUCCESS Success.\r
+ @retval EFI_TIMEOUT Device has no response.\r
+\r
+**/\r
EFI_STATUS\r
-UsbGetDeviceConfiguration (\r
+EFIAPI\r
+UsbGetConfiguration (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
OUT UINT8 *ConfigValue,\r
OUT UINT32 *Status\r
);\r
\r
-//\r
-// Set device configuration\r
-//\r
+/**\r
+ Usb Set Device Configuration.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Value Configuration Value to set.\r
+ @param Status Transfer status.\r
+\r
+ @retval EFI_INVALID_PARAMETER Parameter is error.\r
+ @retval EFI_SUCCESS Success.\r
+ @retval EFI_TIMEOUT Device has no response.\r
+\r
+**/\r
EFI_STATUS\r
-UsbSetDeviceConfiguration (\r
+EFIAPI\r
+UsbSetConfiguration (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT16 Value,\r
OUT UINT32 *Status\r
);\r
\r
-//\r
-// Set Device Feature\r
-//\r
+/**\r
+ Usb Set Device Feature.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Recipient Interface/Device/Endpoint.\r
+ @param Value Request value.\r
+ @param Target Request Index.\r
+ @param Status Transfer status.\r
+\r
+ @retval EFI_INVALID_PARAMETER Parameter is error.\r
+ @retval EFI_SUCCESS Success.\r
+ @retval EFI_TIMEOUT Device has no response.\r
+\r
+**/\r
EFI_STATUS\r
-UsbSetDeviceFeature (\r
+EFIAPI\r
+UsbSetFeature (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
- IN EFI_USB_RECIPIENT Recipient,\r
+ IN UINTN Recipient,\r
IN UINT16 Value,\r
IN UINT16 Target,\r
OUT UINT32 *Status\r
);\r
\r
-//\r
-// Clear Device Feature\r
-//\r
+/**\r
+ Usb Clear Device Feature.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Recipient Interface/Device/Endpoint.\r
+ @param Value Request value.\r
+ @param Target Request Index.\r
+ @param Status Transfer status.\r
+\r
+ @retval EFI_INVALID_PARAMETER Parameter is error.\r
+ @retval EFI_SUCCESS Success.\r
+ @retval EFI_TIMEOUT Device has no response.\r
+\r
+**/\r
EFI_STATUS\r
-UsbClearDeviceFeature (\r
+EFIAPI\r
+UsbClearFeature (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
- IN EFI_USB_RECIPIENT Recipient,\r
+ IN UINTN Recipient,\r
IN UINT16 Value,\r
IN UINT16 Target,\r
OUT UINT32 *Status\r
);\r
\r
-//\r
-// Get Device Status\r
-//\r
+/**\r
+ Usb Get Device Status.\r
+\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param Recipient Interface/Device/Endpoint.\r
+ @param Target Request index.\r
+ @param DevStatus Device status.\r
+ @param Status Transfer status.\r
+\r
+ @retval EFI_INVALID_PARAMETER Parameter is error.\r
+ @retval EFI_SUCCESS Success.\r
+ @retval EFI_TIMEOUT Device has no response.\r
+\r
+**/\r
EFI_STATUS\r
-UsbGetDeviceStatus (\r
+EFIAPI\r
+UsbGetStatus (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
- IN EFI_USB_RECIPIENT Recipient,\r
+ IN UINTN Recipient,\r
IN UINT16 Target,\r
OUT UINT16 *DevStatus,\r
OUT UINT32 *Status\r
);\r
\r
-//\r
-// The following APIs are not basic library, but they are common used.\r
-//\r
-//\r
-// Usb Get String\r
-//\r
-EFI_STATUS\r
-UsbGetString (\r
- IN EFI_USB_IO_PROTOCOL *UsbIo,\r
- IN UINT16 LangID,\r
- IN UINT8 Index,\r
- IN VOID *Buf,\r
- IN UINTN BufSize,\r
- OUT UINT32 *Status\r
- );\r
+/**\r
+ Clear endpoint stall.\r
\r
-//\r
-// Clear endpoint stall\r
-//\r
+ @param UsbIo A pointer to EFI_USB_IO_PROTOCOL.\r
+ @param EndpointNo Endpoint Number.\r
+ @param Status Transfer Status.\r
+\r
+ @retval EFI_NOT_FOUND Can't find the Endpoint.\r
+ @retval EFI_DEVICE_ERROR Hardware error.\r
+ @retval EFI_SUCCESS Success.\r
+\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
UsbClearEndpointHalt (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 EndpointNo,\r