X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FLibrary%2FUefiUsbLib%2FHid.c;h=fca02838f112704fda63e228819e49274cf859d5;hp=7c0ee14284c5edc2456dca2a6b56ead46c34c99b;hb=9095d37b8fe5bfc3d02adad6ba7fd7359ebc0107;hpb=ce821dff82f69711cb6bbacd25c51c540616225a
diff --git a/MdePkg/Library/UefiUsbLib/Hid.c b/MdePkg/Library/UefiUsbLib/Hid.c
index 7c0ee14284..fca02838f1 100644
--- a/MdePkg/Library/UefiUsbLib/Hid.c
+++ b/MdePkg/Library/UefiUsbLib/Hid.c
@@ -1,37 +1,58 @@
/** @file
-Copyright (c) 2004, 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 library provides USB HID Class standard and specific requests defined
+ in USB HID Firmware Specification 7 section : Requests.
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+ Copyright (c) 2004 - 2018, 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.
**/
-#include
+#include "UefiUsbLibInternal.h"
+//
+// Hid RequestType Bits specifying characteristics of request.
+// Valid values are 10100001b (0xa1) or 00100001b (0x21).
+// The following description:
+// 7 Data transfer direction
+// 0 = Host to device
+// 1 = Device to host
+// 6..5 Type
+// 1 = Class
+// 4..0 Recipient
+// 1 = Interface
+//
/**
- Get Hid Descriptor
+ Get the descriptor of the specified USB HID interface.
+
+ Submit a USB get HID descriptor request for the USB device specified by UsbIo
+ and Interface and return the HID descriptor in HidDescriptor.
+ If UsbIo is NULL, then ASSERT().
+ If HidDescriptor is NULL, then ASSERT().
- @param UsbIo EFI_USB_IO_PROTOCOL
- @param InterfaceNum Hid interface number
- @param HidDescriptor Caller allocated buffer to store Usb hid descriptor if
- successfully returned.
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
+ @param Interface The index of the HID interface on the USB target.
+ @param HidDescriptor The pointer to the USB HID descriptor that was retrieved from
+ the specified USB target and interface. Type EFI_USB_HID_DESCRIPTOR
+ is defined in the MDE Package Industry Standard include file Usb.h.
- @return EFI_SUCCESS
- @return EFI_DEVICE_ERROR
- @return EFI_TIMEOUT
+ @retval EFI_SUCCESS The request executed successfully.
+ @retval EFI_TIMEOUT A timeout occurred executing the request.
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.
**/
EFI_STATUS
+EFIAPI
UsbGetHidDescriptor (
IN EFI_USB_IO_PROTOCOL *UsbIo,
- IN UINT8 InterfaceNum,
+ IN UINT8 Interface,
OUT EFI_USB_HID_DESCRIPTOR *HidDescriptor
)
{
@@ -39,17 +60,20 @@ UsbGetHidDescriptor (
EFI_STATUS Result;
EFI_USB_DEVICE_REQUEST Request;
- Request.RequestType = 0x81;
- Request.Request = 0x06;
- Request.Value = (UINT16) (0x21 << 8);
- Request.Index = InterfaceNum;
- Request.Length = sizeof (EFI_USB_HID_DESCRIPTOR);
+ ASSERT(UsbIo != NULL);
+ ASSERT(HidDescriptor != NULL);
+
+ Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE;
+ Request.Request = USB_REQ_GET_DESCRIPTOR;
+ Request.Value = (UINT16) (USB_DESC_TYPE_HID << 8);
+ Request.Index = Interface;
+ Request.Length = (UINT16) sizeof (EFI_USB_HID_DESCRIPTOR);
Result = UsbIo->UsbControlTransfer (
UsbIo,
&Request,
EfiUsbDataIn,
- TIMEOUT_VALUE,
+ PcdGet32 (PcdUsbTransferTimeoutValue),
HidDescriptor,
sizeof (EFI_USB_HID_DESCRIPTOR),
&Status
@@ -58,29 +82,34 @@ UsbGetHidDescriptor (
return Result;
}
-//
-// Function to get Report Class descriptor
-//
/**
- get Report Class descriptor
+ Get the report descriptor of the specified USB HID interface.
- @param UsbIo EFI_USB_IO_PROTOCOL.
- @param InterfaceNum Report interface number.
- @param DescriptorSize Length of DescriptorBuffer.
- @param DescriptorBuffer Caller allocated buffer to store Usb report descriptor
- if successfully returned.
+ Submit a USB get HID report descriptor request for the USB device specified by
+ UsbIo and Interface and return the report descriptor in DescriptorBuffer.
+ If UsbIo is NULL, then ASSERT().
+ If DescriptorBuffer is NULL, then ASSERT().
- @return EFI_SUCCESS
- @return EFI_DEVICE_ERROR
- @return EFI_TIMEOUT
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
+ @param Interface The index of the report interface on the USB target.
+ @param DescriptorLength The size, in bytes, of DescriptorBuffer.
+ @param DescriptorBuffer A pointer to the buffer to store the report class descriptor.
+
+ @retval EFI_SUCCESS The request executed successfully.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed because the
+ buffer specified by DescriptorLength and DescriptorBuffer
+ is not large enough to hold the result of the request.
+ @retval EFI_TIMEOUT A timeout occurred executing the request.
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.
**/
EFI_STATUS
+EFIAPI
UsbGetReportDescriptor (
IN EFI_USB_IO_PROTOCOL *UsbIo,
- IN UINT8 InterfaceNum,
- IN UINT16 DescriptorSize,
+ IN UINT8 Interface,
+ IN UINT16 DescriptorLength,
OUT UINT8 *DescriptorBuffer
)
{
@@ -88,62 +117,68 @@ UsbGetReportDescriptor (
EFI_STATUS Result;
EFI_USB_DEVICE_REQUEST Request;
+ ASSERT (UsbIo != NULL);
+ ASSERT (DescriptorBuffer != NULL);
+
//
// Fill Device request packet
//
- Request.RequestType = 0x81;
- Request.Request = 0x06;
- Request.Value = (UINT16) (0x22 << 8);
- Request.Index = InterfaceNum;
- Request.Length = DescriptorSize;
+ Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE;
+ Request.Request = USB_REQ_GET_DESCRIPTOR;
+ Request.Value = (UINT16) (USB_DESC_TYPE_REPORT << 8);
+ Request.Index = Interface;
+ Request.Length = DescriptorLength;
Result = UsbIo->UsbControlTransfer (
UsbIo,
&Request,
EfiUsbDataIn,
- TIMEOUT_VALUE,
+ PcdGet32 (PcdUsbTransferTimeoutValue),
DescriptorBuffer,
- DescriptorSize,
+ DescriptorLength,
&Status
);
return Result;
}
-//
-// Following are HID class request
-//
/**
- Get Hid Protocol Request
+ Get the HID protocol of the specified USB HID interface.
- @param UsbIo EFI_USB_IO_PROTOCOL
- @param Interface Which interface the caller wants to get protocol
- @param Protocol Protocol value returned.
+ Submit a USB get HID protocol request for the USB device specified by UsbIo
+ and Interface and return the protocol retrieved in Protocol.
+ If UsbIo is NULL, then ASSERT().
+ If Protocol is NULL, then ASSERT().
- @return EFI_SUCCESS
- @return EFI_DEVICE_ERROR
- @return EFI_TIMEOUT
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
+ @param Interface The index of the report interface on the USB target.
+ @param Protocol A pointer to the protocol for the specified USB target.
+
+ @retval EFI_SUCCESS The request executed successfully.
+ @retval EFI_TIMEOUT A timeout occurred executing the request.
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.
**/
EFI_STATUS
+EFIAPI
UsbGetProtocolRequest (
IN EFI_USB_IO_PROTOCOL *UsbIo,
IN UINT8 Interface,
- IN UINT8 *Protocol
+ OUT UINT8 *Protocol
)
{
UINT32 Status;
EFI_STATUS Result;
EFI_USB_DEVICE_REQUEST Request;
+ ASSERT (UsbIo != NULL);
+ ASSERT (Protocol != NULL);
+
//
// Fill Device request packet
//
- Request.RequestType = 0xa1;
- //
- // 10100001b;
- //
+ Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;
Request.Request = EFI_USB_GET_PROTOCOL_REQUEST;
Request.Value = 0;
Request.Index = Interface;
@@ -153,7 +188,7 @@ UsbGetProtocolRequest (
UsbIo,
&Request,
EfiUsbDataIn,
- TIMEOUT_VALUE,
+ PcdGet32 (PcdUsbTransferTimeoutValue),
Protocol,
sizeof (UINT8),
&Status
@@ -165,18 +200,23 @@ UsbGetProtocolRequest (
/**
- Set Hid Protocol Request
+ Set the HID protocol of the specified USB HID interface.
+
+ Submit a USB set HID protocol request for the USB device specified by UsbIo
+ and Interface and set the protocol to the value specified by Protocol.
+ If UsbIo is NULL, then ASSERT().
- @param UsbIo EFI_USB_IO_PROTOCOL
- @param Interface Which interface the caller wants to set protocol
- @param Protocol Protocol value the caller wants to set.
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
+ @param Interface The index of the report interface on the USB target.
+ @param Protocol The protocol value to set for the specified USB target.
- @return EFI_SUCCESS
- @return EFI_DEVICE_ERROR
- @return EFI_TIMEOUT
+ @retval EFI_SUCCESS The request executed successfully.
+ @retval EFI_TIMEOUT A timeout occurred executing the request.
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.
**/
EFI_STATUS
+EFIAPI
UsbSetProtocolRequest (
IN EFI_USB_IO_PROTOCOL *UsbIo,
IN UINT8 Interface,
@@ -187,13 +227,12 @@ UsbSetProtocolRequest (
EFI_STATUS Result;
EFI_USB_DEVICE_REQUEST Request;
+ ASSERT (UsbIo != NULL);
+
//
// Fill Device request packet
//
- Request.RequestType = 0x21;
- //
- // 00100001b;
- //
+ Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;
Request.Request = EFI_USB_SET_PROTOCOL_REQUEST;
Request.Value = Protocol;
Request.Index = Interface;
@@ -203,7 +242,7 @@ UsbSetProtocolRequest (
UsbIo,
&Request,
EfiUsbNoData,
- TIMEOUT_VALUE,
+ PcdGet32 (PcdUsbTransferTimeoutValue),
NULL,
0,
&Status
@@ -212,21 +251,25 @@ UsbSetProtocolRequest (
}
-
/**
- Set Idel request.
+ Set the idle rate of the specified USB HID report.
- @param UsbIo EFI_USB_IO_PROTOCOL
- @param Interface Which interface the caller wants to set.
- @param ReportId Which report the caller wants to set.
- @param Duration Idle rate the caller wants to set.
+ Submit a USB set HID report idle request for the USB device specified by UsbIo,
+ Interface, and ReportId, and set the idle rate to the value specified by Duration.
+ If UsbIo is NULL, then ASSERT().
- @return EFI_SUCCESS
- @return EFI_DEVICE_ERROR
- @return EFI_TIMEOUT
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
+ @param Interface The index of the report interface on the USB target.
+ @param ReportId The identifier of the report to retrieve.
+ @param Duration The idle rate to set for the specified USB target.
+
+ @retval EFI_SUCCESS The request executed successfully.
+ @retval EFI_TIMEOUT A timeout occurred executing the request.
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.
**/
EFI_STATUS
+EFIAPI
UsbSetIdleRequest (
IN EFI_USB_IO_PROTOCOL *UsbIo,
IN UINT8 Interface,
@@ -238,13 +281,11 @@ UsbSetIdleRequest (
EFI_STATUS Result;
EFI_USB_DEVICE_REQUEST Request;
+ ASSERT (UsbIo != NULL);
//
// Fill Device request packet
//
- Request.RequestType = 0x21;
- //
- // 00100001b;
- //
+ Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;
Request.Request = EFI_USB_SET_IDLE_REQUEST;
Request.Value = (UINT16) ((Duration << 8) | ReportId);
Request.Index = Interface;
@@ -254,7 +295,7 @@ UsbSetIdleRequest (
UsbIo,
&Request,
EfiUsbNoData,
- TIMEOUT_VALUE,
+ PcdGet32 (PcdUsbTransferTimeoutValue),
NULL,
0,
&Status
@@ -264,19 +305,25 @@ UsbSetIdleRequest (
/**
- Get Idel request.
+ Get the idle rate of the specified USB HID report.
+
+ Submit a USB get HID report idle request for the USB device specified by UsbIo,
+ Interface, and ReportId, and return the ide rate in Duration.
+ If UsbIo is NULL, then ASSERT().
+ If Duration is NULL, then ASSERT().
- @param UsbIo EFI_USB_IO_PROTOCOL
- @param Interface Which interface the caller wants to get.
- @param ReportId Which report the caller wants to get.
- @param Duration Idle rate the caller wants to get.
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
+ @param Interface The index of the report interface on the USB target.
+ @param ReportId The identifier of the report to retrieve.
+ @param Duration A pointer to the idle rate retrieved from the specified USB target.
- @return EFI_SUCCESS
- @return EFI_DEVICE_ERROR
- @return EFI_TIMEOUT
+ @retval EFI_SUCCESS The request executed successfully.
+ @retval EFI_TIMEOUT A timeout occurred executing the request.
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.
**/
EFI_STATUS
+EFIAPI
UsbGetIdleRequest (
IN EFI_USB_IO_PROTOCOL *UsbIo,
IN UINT8 Interface,
@@ -288,13 +335,12 @@ UsbGetIdleRequest (
EFI_STATUS Result;
EFI_USB_DEVICE_REQUEST Request;
+ ASSERT (UsbIo != NULL);
+ ASSERT (Duration != NULL);
//
// Fill Device request packet
//
- Request.RequestType = 0xa1;
- //
- // 10100001b;
- //
+ Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;
Request.Request = EFI_USB_GET_IDLE_REQUEST;
Request.Value = ReportId;
Request.Index = Interface;
@@ -304,7 +350,7 @@ UsbGetIdleRequest (
UsbIo,
&Request,
EfiUsbDataIn,
- TIMEOUT_VALUE,
+ PcdGet32 (PcdUsbTransferTimeoutValue),
Duration,
1,
&Status
@@ -316,21 +362,28 @@ UsbGetIdleRequest (
/**
- Hid Set Report request.
+ Set the report descriptor of the specified USB HID interface.
+
+ Submit a USB set HID report request for the USB device specified by UsbIo,
+ Interface, ReportId, and ReportType, and set the report descriptor using the
+ buffer specified by ReportLength and Report.
+ If UsbIo is NULL, then ASSERT().
+ If Report is NULL, then ASSERT().
- @param UsbIo EFI_USB_IO_PROTOCOL
- @param Interface Which interface the caller wants to set.
- @param ReportId Which report the caller wants to set.
- @param ReportType Type of report.
- @param ReportLen Length of report descriptor.
- @param Report Report Descriptor buffer.
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
+ @param Interface The index of the report interface on the USB target.
+ @param ReportId The identifier of the report to retrieve.
+ @param ReportType The type of report to retrieve.
+ @param ReportLength The size, in bytes, of Report.
+ @param Report A pointer to the report descriptor buffer to set.
- @return EFI_SUCCESS
- @return EFI_DEVICE_ERROR
- @return EFI_TIMEOUT
+ @retval EFI_SUCCESS The request executed successfully.
+ @retval EFI_TIMEOUT A timeout occurred executing the request.
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.
**/
EFI_STATUS
+EFIAPI
UsbSetReportRequest (
IN EFI_USB_IO_PROTOCOL *UsbIo,
IN UINT8 Interface,
@@ -344,13 +397,13 @@ UsbSetReportRequest (
EFI_STATUS Result;
EFI_USB_DEVICE_REQUEST Request;
+ ASSERT (UsbIo != NULL);
+ ASSERT (Report != NULL);
+
//
// Fill Device request packet
//
- Request.RequestType = 0x21;
- //
- // 00100001b;
- //
+ Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;
Request.Request = EFI_USB_SET_REPORT_REQUEST;
Request.Value = (UINT16) ((ReportType << 8) | ReportId);
Request.Index = Interface;
@@ -360,7 +413,7 @@ UsbSetReportRequest (
UsbIo,
&Request,
EfiUsbDataOut,
- TIMEOUT_VALUE,
+ PcdGet32 (PcdUsbTransferTimeoutValue),
Report,
ReportLen,
&Status
@@ -371,41 +424,51 @@ UsbSetReportRequest (
/**
- Hid Set Report request.
-
- @param UsbIo EFI_USB_IO_PROTOCOL
- @param Interface Which interface the caller wants to set.
- @param ReportId Which report the caller wants to set.
- @param ReportType Type of report.
- @param ReportLen Length of report descriptor.
- @param Report Caller allocated buffer to store Report Descriptor.
-
- @return EFI_SUCCESS
- @return EFI_DEVICE_ERROR
- @return EFI_TIMEOUT
+ Get the report descriptor of the specified USB HID interface.
+
+ Submit a USB get HID report request for the USB device specified by UsbIo,
+ Interface, ReportId, and ReportType, and return the report in the buffer
+ specified by Report.
+ If UsbIo is NULL, then ASSERT().
+ If Report is NULL, then ASSERT().
+
+ @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target.
+ @param Interface The index of the report interface on the USB target.
+ @param ReportId The identifier of the report to retrieve.
+ @param ReportType The type of report to retrieve.
+ @param ReportLength The size, in bytes, of Report.
+ @param Report A pointer to the buffer to store the report descriptor.
+
+ @retval EFI_SUCCESS The request executed successfully.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed because the
+ buffer specified by ReportLength and Report is not
+ large enough to hold the result of the request.
+ @retval EFI_TIMEOUT A timeout occurred executing the request.
+ @retval EFI_DEVICE_ERROR The request failed due to a device error.
**/
EFI_STATUS
+EFIAPI
UsbGetReportRequest (
- IN EFI_USB_IO_PROTOCOL *UsbIo,
- IN UINT8 Interface,
- IN UINT8 ReportId,
- IN UINT8 ReportType,
- IN UINT16 ReportLen,
- IN UINT8 *Report
+ IN EFI_USB_IO_PROTOCOL *UsbIo,
+ IN UINT8 Interface,
+ IN UINT8 ReportId,
+ IN UINT8 ReportType,
+ IN UINT16 ReportLen,
+ OUT UINT8 *Report
)
{
UINT32 Status;
EFI_STATUS Result;
EFI_USB_DEVICE_REQUEST Request;
+ ASSERT (UsbIo != NULL);
+ ASSERT (Report != NULL);
+
//
// Fill Device request packet
//
- Request.RequestType = 0xa1;
- //
- // 10100001b;
- //
+ Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;
Request.Request = EFI_USB_GET_REPORT_REQUEST;
Request.Value = (UINT16) ((ReportType << 8) | ReportId);
Request.Index = Interface;
@@ -415,7 +478,7 @@ UsbGetReportRequest (
UsbIo,
&Request,
EfiUsbDataIn,
- TIMEOUT_VALUE,
+ PcdGet32 (PcdUsbTransferTimeoutValue),
Report,
ReportLen,
&Status