/** @file\r
\r
-Copyright (c) 2004, 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
-\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 - 2008, Intel Corporation. All rights reserved.<BR>\r
+ 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
\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 EFI_SUCCESS\r
- @return EFI_DEVICE_ERROR\r
- @return EFI_TIMEOUT\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
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\r
\r
- Request.RequestType = 0x81;\r
- Request.Request = 0x06;\r
- Request.Value = (UINT16) (0x21 << 8);\r
- Request.Index = InterfaceNum;\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
UsbIo,\r
&Request,\r
EfiUsbDataIn,\r
- TIMEOUT_VALUE,\r
+ PcdGet32 (PcdUsbTransferTimeoutValue),\r
HidDescriptor,\r
sizeof (EFI_USB_HID_DESCRIPTOR),\r
&Status\r
return Result;\r
\r
}\r
-//\r
-// Function to get Report Class descriptor\r
-//\r
\r
/**\r
- get Report Class descriptor\r
+ Get the report descriptor of the specified USB HID interface.\r
+\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
- @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
+ @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
- @return EFI_SUCCESS\r
- @return EFI_DEVICE_ERROR\r
- @return EFI_TIMEOUT\r
+ @retval EFI_SUCCESS The request executed successfully.\r
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed because the\r
+ buffer specified 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
+ 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
&Request,\r
EfiUsbDataIn,\r
- TIMEOUT_VALUE,\r
+ PcdGet32 (PcdUsbTransferTimeoutValue),\r
DescriptorBuffer,\r
- DescriptorSize,\r
+ DescriptorLength,\r
&Status\r
);\r
\r
return Result;\r
\r
}\r
-//\r
-// Following are HID class request\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 EFI_SUCCESS\r
- @return EFI_DEVICE_ERROR\r
- @return EFI_TIMEOUT\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
UsbGetProtocolRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
- IN UINT8 *Protocol\r
+ OUT UINT8 *Protocol\r
)\r
{\r
UINT32 Status;\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\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
UsbIo,\r
&Request,\r
EfiUsbDataIn,\r
- TIMEOUT_VALUE,\r
+ PcdGet32 (PcdUsbTransferTimeoutValue),\r
Protocol,\r
sizeof (UINT8),\r
&Status\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 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 EFI_SUCCESS\r
- @return EFI_DEVICE_ERROR\r
- @return EFI_TIMEOUT\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
UsbSetProtocolRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\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
UsbIo,\r
&Request,\r
EfiUsbNoData,\r
- TIMEOUT_VALUE,\r
+ PcdGet32 (PcdUsbTransferTimeoutValue),\r
NULL,\r
0,\r
&Status\r
}\r
\r
\r
-\r
/**\r
- Set Idel request.\r
+ Set the idle rate of the specified USB HID report.\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
+ 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
- @return EFI_SUCCESS\r
- @return EFI_DEVICE_ERROR\r
- @return EFI_TIMEOUT\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
+ @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
UsbSetIdleRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\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
UsbIo,\r
&Request,\r
EfiUsbNoData,\r
- TIMEOUT_VALUE,\r
+ PcdGet32 (PcdUsbTransferTimeoutValue),\r
NULL,\r
0,\r
&Status\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 EFI_SUCCESS\r
- @return EFI_DEVICE_ERROR\r
- @return EFI_TIMEOUT\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
UsbGetIdleRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
UINT32 Status;\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\r
-\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
UsbIo,\r
&Request,\r
EfiUsbDataIn,\r
- TIMEOUT_VALUE,\r
+ PcdGet32 (PcdUsbTransferTimeoutValue),\r
Duration,\r
1,\r
&Status\r
\r
\r
/**\r
- Hid Set Report request.\r
+ Set the report descriptor of the specified USB HID interface.\r
+\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
- @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
+ @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
- @return EFI_SUCCESS\r
- @return EFI_DEVICE_ERROR\r
- @return EFI_TIMEOUT\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
UsbSetReportRequest (\r
IN EFI_USB_IO_PROTOCOL *UsbIo,\r
IN UINT8 Interface,\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\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
UsbIo,\r
&Request,\r
EfiUsbDataOut,\r
- TIMEOUT_VALUE,\r
+ PcdGet32 (PcdUsbTransferTimeoutValue),\r
Report,\r
ReportLen,\r
&Status\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 EFI_SUCCESS\r
- @return EFI_DEVICE_ERROR\r
- @return EFI_TIMEOUT\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 specified 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
+EFIAPI\r
UsbGetReportRequest (\r
- IN EFI_USB_IO_PROTOCOL *UsbIo,\r
- IN UINT8 Interface,\r
- IN UINT8 ReportId,\r
- IN UINT8 ReportType,\r
- IN UINT16 ReportLen,\r
- IN UINT8 *Report\r
+ IN EFI_USB_IO_PROTOCOL *UsbIo,\r
+ IN UINT8 Interface,\r
+ IN UINT8 ReportId,\r
+ IN UINT8 ReportType,\r
+ IN UINT16 ReportLen,\r
+ OUT UINT8 *Report\r
)\r
{\r
UINT32 Status;\r
EFI_STATUS Result;\r
EFI_USB_DEVICE_REQUEST Request;\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
UsbIo,\r
&Request,\r
EfiUsbDataIn,\r
- TIMEOUT_VALUE,\r
+ PcdGet32 (PcdUsbTransferTimeoutValue),\r
Report,\r
ReportLen,\r
&Status\r