/** @file\r
\r
- The library provides USB descriptor, protocol operations.\r
+ The library provides USB HID Class standard and specific requests defined\r
+ in USB HID Firmware Specification 7 section : Requests.\r
\r
Copyright (c) 2004, Intel Corporation\r
All rights reserved. This program and the accompanying materials\r
\r
**/\r
\r
-#include <UefiUsbLibInternal.h>\r
-\r
+#include "UefiUsbLibInternal.h"\r
+\r
+// \r
+// Hid RequestType Bits specifying characteristics of request.\r
+// Valid values are 10100001b (0xa1) or 00100001b (0x21).\r
+// The following description:\r
+// 7 Data transfer direction\r
+// 0 = Host to device\r
+// 1 = Device to host\r
+// 6..5 Type\r
+// 1 = Class\r
+// 4..0 Recipient\r
+// 1 = Interface\r
+//\r
\r
/**\r
- Get Hid Descriptor.\r
+ Get the descriptor of the specified USB HID interface.\r
+\r
+ Submit a USB get HID descriptor request for the USB device specified by UsbIo\r
+ and Interface and return the HID descriptor in HidDescriptor.\r
+ If UsbIo is NULL, then ASSERT().\r
+ If HidDescriptor is NULL, then ASSERT().\r
\r
- @param UsbIo 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
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.\r
+ @param Interface The index of the HID interface on the USB target.\r
+ @param HidDescriptor Pointer to the USB HID descriptor that was retrieved from\r
+ the specified USB target and interface. Type EFI_USB_HID_DESCRIPTOR\r
+ is defined in the MDE Package Industry Standard include file Usb.h.\r
\r
- @return Status of getting HID descriptor through USB I/O\r
- protocol's UsbControlTransfer().\r
+ @retval EFI_SUCCESS The request executed successfully.\r
+ @retval EFI_TIMEOUT A timeout occurred executing the request.\r
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
UsbGetHidDescriptor (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
- IN UINT8 InterfaceNum,\r
+ IN UINT8 Interface,\r
OUT EFI_USB_HID_DESCRIPTOR *HidDescriptor\r
)\r
{\r
UINT32 Status;\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\r
- \r
- if (UsbIo == NULL) {\r
- return EFI_INVALID_PARAMETER;\r
- }\r
-\r
- Request.RequestType = 0x81;\r
- Request.Request = 0x06;\r
- Request.Value = (UINT16) (0x21 << 8);\r
- Request.Index = InterfaceNum;\r
+\r
+ ASSERT(UsbIo != NULL);\r
+ ASSERT(HidDescriptor != NULL);\r
+\r
+ Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE;\r
+ Request.Request = USB_REQ_GET_DESCRIPTOR;\r
+ Request.Value = (UINT16) (USB_DESC_TYPE_HID << 8);\r
+ Request.Index = Interface;\r
Request.Length = sizeof (EFI_USB_HID_DESCRIPTOR);\r
\r
Result = UsbIo->UsbControlTransfer (\r
}\r
\r
/**\r
- Get Report Class descriptor.\r
+ Get the report descriptor of the specified USB HID interface.\r
\r
- @param UsbIo 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
+ Submit a USB get HID report descriptor request for the USB device specified by\r
+ UsbIo and Interface and return the report descriptor in DescriptorBuffer.\r
+ If UsbIo is NULL, then ASSERT().\r
+ If DescriptorBuffer is NULL, then ASSERT().\r
\r
- @return Status of getting Report Class descriptor through USB\r
- I/O protocol's UsbControlTransfer().\r
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.\r
+ @param Interface The index of the report interface on the USB target.\r
+ @param DescriptorLength The size, in bytes, of DescriptorBuffer.\r
+ @param DescriptorBuffer A pointer to the buffer to store the report class descriptor.\r
+\r
+ @retval EFI_SUCCESS The request executed successfully.\r
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed because the\r
+ buffer specifed by DescriptorLength and DescriptorBuffer\r
+ is not large enough to hold the result of the request.\r
+ @retval EFI_TIMEOUT A timeout occurred executing the request.\r
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
UsbGetReportDescriptor (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
- IN UINT8 InterfaceNum,\r
- IN UINT16 DescriptorSize,\r
+ IN UINT8 Interface,\r
+ IN UINT16 DescriptorLength,\r
OUT UINT8 *DescriptorBuffer\r
)\r
{\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\r
\r
- if (UsbIo == NULL) {\r
- return EFI_INVALID_PARAMETER;\r
- }\r
+ ASSERT (UsbIo != NULL);\r
+ ASSERT (DescriptorBuffer != NULL);\r
+\r
//\r
// Fill Device request packet\r
//\r
- Request.RequestType = 0x81;\r
- Request.Request = 0x06;\r
- Request.Value = (UINT16) (0x22 << 8);\r
- Request.Index = InterfaceNum;\r
- Request.Length = DescriptorSize;\r
+ Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE;\r
+ Request.Request = USB_REQ_GET_DESCRIPTOR;\r
+ Request.Value = (UINT16) (USB_DESC_TYPE_REPORT << 8);\r
+ Request.Index = Interface;\r
+ Request.Length = DescriptorLength;\r
\r
Result = UsbIo->UsbControlTransfer (\r
UsbIo,\r
EfiUsbDataIn,\r
TIMEOUT_VALUE,\r
DescriptorBuffer,\r
- DescriptorSize,\r
+ DescriptorLength,\r
&Status\r
);\r
\r
}\r
\r
/**\r
- Get Hid Protocol Request\r
+ Get the HID protocol of the specified USB HID interface.\r
+\r
+ Submit a USB get HID protocol request for the USB device specified by UsbIo\r
+ and Interface and return the protocol retrieved in Protocol.\r
+ If UsbIo is NULL, then ASSERT().\r
+ If Protocol is NULL, then ASSERT().\r
\r
- @param UsbIo EFI_USB_IO_PROTOCOL.\r
- @param Interface Which interface the caller wants to get protocol\r
- @param Protocol Protocol value returned.\r
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.\r
+ @param Interface The index of the report interface on the USB target.\r
+ @param Protocol A pointer to the protocol for the specified USB target.\r
\r
- @return Status of getting Protocol Request through USB I/O\r
- protocol's UsbControlTransfer().\r
+ @retval EFI_SUCCESS The request executed successfully.\r
+ @retval EFI_TIMEOUT A timeout occurred executing the request.\r
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.\r
\r
**/\r
EFI_STATUS\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\r
\r
- if (UsbIo == NULL) {\r
- return EFI_INVALID_PARAMETER;\r
- }\r
+ ASSERT (UsbIo != NULL);\r
+ ASSERT (Protocol != NULL);\r
+\r
//\r
// Fill Device request packet\r
//\r
- Request.RequestType = 0xa1;\r
- //\r
- // 10100001b;\r
- //\r
+ Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;\r
Request.Request = EFI_USB_GET_PROTOCOL_REQUEST;\r
Request.Value = 0;\r
Request.Index = Interface;\r
\r
\r
/**\r
- Set Hid Protocol Request.\r
+ Set the HID protocol of the specified USB HID interface.\r
+\r
+ Submit a USB set HID protocol request for the USB device specified by UsbIo\r
+ and Interface and set the protocol to the value specified by Protocol.\r
+ If UsbIo is NULL, then ASSERT().\r
\r
- @param UsbIo EFI_USB_IO_PROTOCOL.\r
- @param Interface Which interface the caller wants to\r
- set protocol.\r
- @param Protocol Protocol value the caller wants to set.\r
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.\r
+ @param Interface The index of the report interface on the USB target.\r
+ @param Protocol The protocol value to set for the specified USB target.\r
\r
- @return Status of setting Protocol Request through USB I/O\r
- protocol's UsbControlTransfer().\r
+ @retval EFI_SUCCESS The request executed successfully.\r
+ @retval EFI_TIMEOUT A timeout occurred executing the request.\r
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.\r
\r
**/\r
EFI_STATUS\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\r
\r
- if (UsbIo == NULL) {\r
- return EFI_INVALID_PARAMETER;\r
- }\r
+ ASSERT (UsbIo != NULL);\r
+ \r
//\r
// Fill Device request packet\r
//\r
- Request.RequestType = 0x21;\r
- //\r
- // 00100001b;\r
- //\r
+ Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;\r
Request.Request = EFI_USB_SET_PROTOCOL_REQUEST;\r
Request.Value = Protocol;\r
Request.Index = Interface;\r
\r
\r
/**\r
- Set Idel request.\r
+ Set the idle rate of the specified USB HID report.\r
+\r
+ Submit a USB set HID report idle request for the USB device specified by UsbIo,\r
+ Interface, and ReportId, and set the idle rate to the value specified by Duration.\r
+ If UsbIo is NULL, then ASSERT().\r
\r
- @param UsbIo 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
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.\r
+ @param Interface The index of the report interface on the USB target.\r
+ @param ReportId The identifier of the report to retrieve.\r
+ @param Duration The idle rate to set for the specified USB target.\r
\r
- @return Status of setting IDLE Request through USB I/O\r
- protocol's UsbControlTransfer().\r
+ @retval EFI_SUCCESS The request executed successfully.\r
+ @retval EFI_TIMEOUT A timeout occurred executing the request.\r
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.\r
\r
**/\r
EFI_STATUS\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\r
\r
- if (UsbIo == NULL) {\r
- return EFI_INVALID_PARAMETER;\r
- }\r
+ ASSERT (UsbIo != NULL);\r
//\r
// Fill Device request packet\r
//\r
- Request.RequestType = 0x21;\r
- //\r
- // 00100001b;\r
- //\r
+ Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;\r
Request.Request = EFI_USB_SET_IDLE_REQUEST;\r
Request.Value = (UINT16) ((Duration << 8) | ReportId);\r
Request.Index = Interface;\r
\r
\r
/**\r
- Get Idel request.\r
+ Get the idle rate of the specified USB HID report.\r
+\r
+ Submit a USB get HID report idle request for the USB device specified by UsbIo,\r
+ Interface, and ReportId, and return the ide rate in Duration.\r
+ If UsbIo is NULL, then ASSERT().\r
+ If Duration is NULL, then ASSERT().\r
\r
- @param UsbIo 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
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.\r
+ @param Interface The index of the report interface on the USB target.\r
+ @param ReportId The identifier of the report to retrieve.\r
+ @param Duration A pointer to the idle rate retrieved from the specified USB target.\r
\r
- @return Status of getting IDLE Request through USB I/O\r
- protocol's UsbControlTransfer().\r
+ @retval EFI_SUCCESS The request executed successfully.\r
+ @retval EFI_TIMEOUT A timeout occurred executing the request.\r
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.\r
\r
**/\r
EFI_STATUS\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\r
\r
- if (UsbIo == NULL) {\r
- return EFI_INVALID_PARAMETER;\r
- }\r
+ ASSERT (UsbIo != NULL);\r
+ ASSERT (Duration != NULL);\r
//\r
// Fill Device request packet\r
//\r
- Request.RequestType = 0xa1;\r
- //\r
- // 10100001b;\r
- //\r
+ Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;\r
Request.Request = EFI_USB_GET_IDLE_REQUEST;\r
Request.Value = ReportId;\r
Request.Index = Interface;\r
\r
\r
/**\r
- Hid Set Report request.\r
+ Set the report descriptor of the specified USB HID interface.\r
\r
- @param UsbIo 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
+ Submit a USB set HID report request for the USB device specified by UsbIo,\r
+ Interface, ReportId, and ReportType, and set the report descriptor using the\r
+ buffer specified by ReportLength and Report.\r
+ If UsbIo is NULL, then ASSERT().\r
+ If Report is NULL, then ASSERT().\r
\r
- @return Status of setting Report Request through USB I/O\r
- protocol's UsbControlTransfer().\r
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.\r
+ @param Interface The index of the report interface on the USB target.\r
+ @param ReportId The identifier of the report to retrieve.\r
+ @param ReportType The type of report to retrieve.\r
+ @param ReportLength The size, in bytes, of Report.\r
+ @param Report A pointer to the report descriptor buffer to set.\r
+\r
+ @retval EFI_SUCCESS The request executed successfully.\r
+ @retval EFI_TIMEOUT A timeout occurred executing the request.\r
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.\r
\r
**/\r
EFI_STATUS\r
IN UINT8 Interface,\r
IN UINT8 ReportId,\r
IN UINT8 ReportType,\r
- IN UINT16 ReportLen,\r
+ IN UINT16 ReportLength,\r
IN UINT8 *Report\r
)\r
{\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\r
\r
- if (UsbIo == NULL) {\r
- return EFI_INVALID_PARAMETER;\r
- }\r
+ ASSERT (UsbIo != NULL);\r
+ ASSERT (Report != NULL);\r
+\r
//\r
// Fill Device request packet\r
//\r
- Request.RequestType = 0x21;\r
- //\r
- // 00100001b;\r
- //\r
+ Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;\r
Request.Request = EFI_USB_SET_REPORT_REQUEST;\r
Request.Value = (UINT16) ((ReportType << 8) | ReportId);\r
Request.Index = Interface;\r
- Request.Length = ReportLen;\r
+ Request.Length = ReportLength;\r
\r
Result = UsbIo->UsbControlTransfer (\r
UsbIo,\r
EfiUsbDataOut,\r
TIMEOUT_VALUE,\r
Report,\r
- ReportLen,\r
+ ReportLength,\r
&Status\r
);\r
\r
\r
\r
/**\r
- Hid Set Report request.\r
-\r
- @param UsbIo 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
+ Get the report descriptor of the specified USB HID interface.\r
+\r
+ Submit a USB get HID report request for the USB device specified by UsbIo,\r
+ Interface, ReportId, and ReportType, and return the report in the buffer\r
+ specified by Report.\r
+ If UsbIo is NULL, then ASSERT().\r
+ If Report is NULL, then ASSERT().\r
+\r
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.\r
+ @param Interface The index of the report interface on the USB target.\r
+ @param ReportId The identifier of the report to retrieve.\r
+ @param ReportType The type of report to retrieve.\r
+ @param ReportLength The size, in bytes, of Report.\r
+ @param Report A pointer to the buffer to store the report descriptor.\r
+\r
+ @retval EFI_SUCCESS The request executed successfully.\r
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed because the\r
+ buffer specifed by ReportLength and Report is not\r
+ large enough to hold the result of the request.\r
+ @retval EFI_TIMEOUT A timeout occurred executing the request.\r
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.\r
\r
**/\r
EFI_STATUS\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\r
\r
- if (UsbIo == NULL) {\r
- return EFI_INVALID_PARAMETER;\r
- }\r
+ ASSERT (UsbIo != NULL);\r
+ ASSERT (Report != NULL);\r
+\r
//\r
// Fill Device request packet\r
//\r
- Request.RequestType = 0xa1;\r
- //\r
- // 10100001b;\r
- //\r
+ Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;\r
Request.Request = EFI_USB_GET_REPORT_REQUEST;\r
Request.Value = (UINT16) ((ReportType << 8) | ReportId);\r
Request.Index = Interface;\r