1 /** @file 2 3 The library provides USB HID Class standard and specific requests defined 4 in USB HID Firmware Specification 7 section : Requests. 5 6 Copyright (c) 2004 - 2010, Intel Corporation. All rights reserved.<BR> 7 This program and the accompanying materials 8 are licensed and made available under the terms and conditions of the BSD License 9 which accompanies this distribution. The full text of the license may be found at 10 http://opensource.org/licenses/bsd-license.php. 11 12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 14 15 **/ 16 17 #include "UefiUsbLibInternal.h" 18 19 // 20 // Hid RequestType Bits specifying characteristics of request. 21 // Valid values are 10100001b (0xa1) or 00100001b (0x21). 22 // The following description: 23 // 7 Data transfer direction 24 // 0 = Host to device 25 // 1 = Device to host 26 // 6..5 Type 27 // 1 = Class 28 // 4..0 Recipient 29 // 1 = Interface 30 // 31 32 /** 33 Get the descriptor of the specified USB HID interface. 34 35 Submit a USB get HID descriptor request for the USB device specified by UsbIo 36 and Interface and return the HID descriptor in HidDescriptor. 37 If UsbIo is NULL, then ASSERT(). 38 If HidDescriptor is NULL, then ASSERT(). 39 40 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 41 @param Interface The index of the HID interface on the USB target. 42 @param HidDescriptor The pointer to the USB HID descriptor that was retrieved from 43 the specified USB target and interface. Type EFI_USB_HID_DESCRIPTOR 44 is defined in the MDE Package Industry Standard include file Usb.h. 45 46 @retval EFI_SUCCESS The request executed successfully. 47 @retval EFI_TIMEOUT A timeout occurred executing the request. 48 @retval EFI_DEVICE_ERROR The request failed due to a device error. 49 50 **/ 51 EFI_STATUS 52 EFIAPI 53 UsbGetHidDescriptor ( 54 IN EFI_USB_IO_PROTOCOL *UsbIo, 55 IN UINT8 Interface, 56 OUT EFI_USB_HID_DESCRIPTOR *HidDescriptor 57 ) 58 { 59 UINT32 Status; 60 EFI_STATUS Result; 61 EFI_USB_DEVICE_REQUEST Request; 62 63 ASSERT(UsbIo != NULL); 64 ASSERT(HidDescriptor != NULL); 65 66 Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE; 67 Request.Request = USB_REQ_GET_DESCRIPTOR; 68 Request.Value = (UINT16) (USB_DESC_TYPE_HID << 8); 69 Request.Index = Interface; 70 Request.Length = (UINT16) sizeof (EFI_USB_HID_DESCRIPTOR); 71 72 Result = UsbIo->UsbControlTransfer ( 73 UsbIo, 74 &Request, 75 EfiUsbDataIn, 76 PcdGet32 (PcdUsbTransferTimeoutValue), 77 HidDescriptor, 78 sizeof (EFI_USB_HID_DESCRIPTOR), 79 &Status 80 ); 81 82 return Result; 83 84 } 85 86 /** 87 Get the report descriptor of the specified USB HID interface. 88 89 Submit a USB get HID report descriptor request for the USB device specified by 90 UsbIo and Interface and return the report descriptor in DescriptorBuffer. 91 If UsbIo is NULL, then ASSERT(). 92 If DescriptorBuffer is NULL, then ASSERT(). 93 94 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 95 @param Interface The index of the report interface on the USB target. 96 @param DescriptorLength The size, in bytes, of DescriptorBuffer. 97 @param DescriptorBuffer A pointer to the buffer to store the report class descriptor. 98 99 @retval EFI_SUCCESS The request executed successfully. 100 @retval EFI_OUT_OF_RESOURCES The request could not be completed because the 101 buffer specified by DescriptorLength and DescriptorBuffer 102 is not large enough to hold the result of the request. 103 @retval EFI_TIMEOUT A timeout occurred executing the request. 104 @retval EFI_DEVICE_ERROR The request failed due to a device error. 105 106 **/ 107 EFI_STATUS 108 EFIAPI 109 UsbGetReportDescriptor ( 110 IN EFI_USB_IO_PROTOCOL *UsbIo, 111 IN UINT8 Interface, 112 IN UINT16 DescriptorLength, 113 OUT UINT8 *DescriptorBuffer 114 ) 115 { 116 UINT32 Status; 117 EFI_STATUS Result; 118 EFI_USB_DEVICE_REQUEST Request; 119 120 ASSERT (UsbIo != NULL); 121 ASSERT (DescriptorBuffer != NULL); 122 123 // 124 // Fill Device request packet 125 // 126 Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE; 127 Request.Request = USB_REQ_GET_DESCRIPTOR; 128 Request.Value = (UINT16) (USB_DESC_TYPE_REPORT << 8); 129 Request.Index = Interface; 130 Request.Length = DescriptorLength; 131 132 Result = UsbIo->UsbControlTransfer ( 133 UsbIo, 134 &Request, 135 EfiUsbDataIn, 136 PcdGet32 (PcdUsbTransferTimeoutValue), 137 DescriptorBuffer, 138 DescriptorLength, 139 &Status 140 ); 141 142 return Result; 143 144 } 145 146 /** 147 Get the HID protocol of the specified USB HID interface. 148 149 Submit a USB get HID protocol request for the USB device specified by UsbIo 150 and Interface and return the protocol retrieved in Protocol. 151 If UsbIo is NULL, then ASSERT(). 152 If Protocol is NULL, then ASSERT(). 153 154 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 155 @param Interface The index of the report interface on the USB target. 156 @param Protocol A pointer to the protocol for the specified USB target. 157 158 @retval EFI_SUCCESS The request executed successfully. 159 @retval EFI_TIMEOUT A timeout occurred executing the request. 160 @retval EFI_DEVICE_ERROR The request failed due to a device error. 161 162 **/ 163 EFI_STATUS 164 EFIAPI 165 UsbGetProtocolRequest ( 166 IN EFI_USB_IO_PROTOCOL *UsbIo, 167 IN UINT8 Interface, 168 OUT UINT8 *Protocol 169 ) 170 { 171 UINT32 Status; 172 EFI_STATUS Result; 173 EFI_USB_DEVICE_REQUEST Request; 174 175 ASSERT (UsbIo != NULL); 176 ASSERT (Protocol != NULL); 177 178 // 179 // Fill Device request packet 180 // 181 Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE; 182 Request.Request = EFI_USB_GET_PROTOCOL_REQUEST; 183 Request.Value = 0; 184 Request.Index = Interface; 185 Request.Length = 1; 186 187 Result = UsbIo->UsbControlTransfer ( 188 UsbIo, 189 &Request, 190 EfiUsbDataIn, 191 PcdGet32 (PcdUsbTransferTimeoutValue), 192 Protocol, 193 sizeof (UINT8), 194 &Status 195 ); 196 197 return Result; 198 } 199 200 201 202 /** 203 Set the HID protocol of the specified USB HID interface. 204 205 Submit a USB set HID protocol request for the USB device specified by UsbIo 206 and Interface and set the protocol to the value specified by Protocol. 207 If UsbIo is NULL, then ASSERT(). 208 209 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 210 @param Interface The index of the report interface on the USB target. 211 @param Protocol The protocol value to set for the specified USB target. 212 213 @retval EFI_SUCCESS The request executed successfully. 214 @retval EFI_TIMEOUT A timeout occurred executing the request. 215 @retval EFI_DEVICE_ERROR The request failed due to a device error. 216 217 **/ 218 EFI_STATUS 219 EFIAPI 220 UsbSetProtocolRequest ( 221 IN EFI_USB_IO_PROTOCOL *UsbIo, 222 IN UINT8 Interface, 223 IN UINT8 Protocol 224 ) 225 { 226 UINT32 Status; 227 EFI_STATUS Result; 228 EFI_USB_DEVICE_REQUEST Request; 229 230 ASSERT (UsbIo != NULL); 231 232 // 233 // Fill Device request packet 234 // 235 Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE; 236 Request.Request = EFI_USB_SET_PROTOCOL_REQUEST; 237 Request.Value = Protocol; 238 Request.Index = Interface; 239 Request.Length = 0; 240 241 Result = UsbIo->UsbControlTransfer ( 242 UsbIo, 243 &Request, 244 EfiUsbNoData, 245 PcdGet32 (PcdUsbTransferTimeoutValue), 246 NULL, 247 0, 248 &Status 249 ); 250 return Result; 251 } 252 253 254 /** 255 Set the idle rate of the specified USB HID report. 256 257 Submit a USB set HID report idle request for the USB device specified by UsbIo, 258 Interface, and ReportId, and set the idle rate to the value specified by Duration. 259 If UsbIo is NULL, then ASSERT(). 260 261 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 262 @param Interface The index of the report interface on the USB target. 263 @param ReportId The identifier of the report to retrieve. 264 @param Duration The idle rate to set for the specified USB target. 265 266 @retval EFI_SUCCESS The request executed successfully. 267 @retval EFI_TIMEOUT A timeout occurred executing the request. 268 @retval EFI_DEVICE_ERROR The request failed due to a device error. 269 270 **/ 271 EFI_STATUS 272 EFIAPI 273 UsbSetIdleRequest ( 274 IN EFI_USB_IO_PROTOCOL *UsbIo, 275 IN UINT8 Interface, 276 IN UINT8 ReportId, 277 IN UINT8 Duration 278 ) 279 { 280 UINT32 Status; 281 EFI_STATUS Result; 282 EFI_USB_DEVICE_REQUEST Request; 283 284 ASSERT (UsbIo != NULL); 285 // 286 // Fill Device request packet 287 // 288 Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE; 289 Request.Request = EFI_USB_SET_IDLE_REQUEST; 290 Request.Value = (UINT16) ((Duration << 8) | ReportId); 291 Request.Index = Interface; 292 Request.Length = 0; 293 294 Result = UsbIo->UsbControlTransfer ( 295 UsbIo, 296 &Request, 297 EfiUsbNoData, 298 PcdGet32 (PcdUsbTransferTimeoutValue), 299 NULL, 300 0, 301 &Status 302 ); 303 return Result; 304 } 305 306 307 /** 308 Get the idle rate of the specified USB HID report. 309 310 Submit a USB get HID report idle request for the USB device specified by UsbIo, 311 Interface, and ReportId, and return the ide rate in Duration. 312 If UsbIo is NULL, then ASSERT(). 313 If Duration is NULL, then ASSERT(). 314 315 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 316 @param Interface The index of the report interface on the USB target. 317 @param ReportId The identifier of the report to retrieve. 318 @param Duration A pointer to the idle rate retrieved from the specified USB target. 319 320 @retval EFI_SUCCESS The request executed successfully. 321 @retval EFI_TIMEOUT A timeout occurred executing the request. 322 @retval EFI_DEVICE_ERROR The request failed due to a device error. 323 324 **/ 325 EFI_STATUS 326 EFIAPI 327 UsbGetIdleRequest ( 328 IN EFI_USB_IO_PROTOCOL *UsbIo, 329 IN UINT8 Interface, 330 IN UINT8 ReportId, 331 OUT UINT8 *Duration 332 ) 333 { 334 UINT32 Status; 335 EFI_STATUS Result; 336 EFI_USB_DEVICE_REQUEST Request; 337 338 ASSERT (UsbIo != NULL); 339 ASSERT (Duration != NULL); 340 // 341 // Fill Device request packet 342 // 343 Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE; 344 Request.Request = EFI_USB_GET_IDLE_REQUEST; 345 Request.Value = ReportId; 346 Request.Index = Interface; 347 Request.Length = 1; 348 349 Result = UsbIo->UsbControlTransfer ( 350 UsbIo, 351 &Request, 352 EfiUsbDataIn, 353 PcdGet32 (PcdUsbTransferTimeoutValue), 354 Duration, 355 1, 356 &Status 357 ); 358 359 return Result; 360 } 361 362 363 364 /** 365 Set the report descriptor of the specified USB HID interface. 366 367 Submit a USB set HID report request for the USB device specified by UsbIo, 368 Interface, ReportId, and ReportType, and set the report descriptor using the 369 buffer specified by ReportLength and Report. 370 If UsbIo is NULL, then ASSERT(). 371 If Report is NULL, then ASSERT(). 372 373 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 374 @param Interface The index of the report interface on the USB target. 375 @param ReportId The identifier of the report to retrieve. 376 @param ReportType The type of report to retrieve. 377 @param ReportLength The size, in bytes, of Report. 378 @param Report A pointer to the report descriptor buffer to set. 379 380 @retval EFI_SUCCESS The request executed successfully. 381 @retval EFI_TIMEOUT A timeout occurred executing the request. 382 @retval EFI_DEVICE_ERROR The request failed due to a device error. 383 384 **/ 385 EFI_STATUS 386 EFIAPI 387 UsbSetReportRequest ( 388 IN EFI_USB_IO_PROTOCOL *UsbIo, 389 IN UINT8 Interface, 390 IN UINT8 ReportId, 391 IN UINT8 ReportType, 392 IN UINT16 ReportLen, 393 IN UINT8 *Report 394 ) 395 { 396 UINT32 Status; 397 EFI_STATUS Result; 398 EFI_USB_DEVICE_REQUEST Request; 399 400 ASSERT (UsbIo != NULL); 401 ASSERT (Report != NULL); 402 403 // 404 // Fill Device request packet 405 // 406 Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE; 407 Request.Request = EFI_USB_SET_REPORT_REQUEST; 408 Request.Value = (UINT16) ((ReportType << 8) | ReportId); 409 Request.Index = Interface; 410 Request.Length = ReportLen; 411 412 Result = UsbIo->UsbControlTransfer ( 413 UsbIo, 414 &Request, 415 EfiUsbDataOut, 416 PcdGet32 (PcdUsbTransferTimeoutValue), 417 Report, 418 ReportLen, 419 &Status 420 ); 421 422 return Result; 423 } 424 425 426 /** 427 Get the report descriptor of the specified USB HID interface. 428 429 Submit a USB get HID report request for the USB device specified by UsbIo, 430 Interface, ReportId, and ReportType, and return the report in the buffer 431 specified by Report. 432 If UsbIo is NULL, then ASSERT(). 433 If Report is NULL, then ASSERT(). 434 435 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 436 @param Interface The index of the report interface on the USB target. 437 @param ReportId The identifier of the report to retrieve. 438 @param ReportType The type of report to retrieve. 439 @param ReportLength The size, in bytes, of Report. 440 @param Report A pointer to the buffer to store the report descriptor. 441 442 @retval EFI_SUCCESS The request executed successfully. 443 @retval EFI_OUT_OF_RESOURCES The request could not be completed because the 444 buffer specified by ReportLength and Report is not 445 large enough to hold the result of the request. 446 @retval EFI_TIMEOUT A timeout occurred executing the request. 447 @retval EFI_DEVICE_ERROR The request failed due to a device error. 448 449 **/ 450 EFI_STATUS 451 EFIAPI 452 UsbGetReportRequest ( 453 IN EFI_USB_IO_PROTOCOL *UsbIo, 454 IN UINT8 Interface, 455 IN UINT8 ReportId, 456 IN UINT8 ReportType, 457 IN UINT16 ReportLen, 458 OUT UINT8 *Report 459 ) 460 { 461 UINT32 Status; 462 EFI_STATUS Result; 463 EFI_USB_DEVICE_REQUEST Request; 464 465 ASSERT (UsbIo != NULL); 466 ASSERT (Report != NULL); 467 468 // 469 // Fill Device request packet 470 // 471 Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE; 472 Request.Request = EFI_USB_GET_REPORT_REQUEST; 473 Request.Value = (UINT16) ((ReportType << 8) | ReportId); 474 Request.Index = Interface; 475 Request.Length = ReportLen; 476 477 Result = UsbIo->UsbControlTransfer ( 478 UsbIo, 479 &Request, 480 EfiUsbDataIn, 481 PcdGet32 (PcdUsbTransferTimeoutValue), 482 Report, 483 ReportLen, 484 &Status 485 ); 486 487 return Result; 488 } 489
