1 /** @file 2 Provides most USB APIs to support the Hid requests defined in USB Hid 1.1 spec 3 and the standard requests defined in USB 1.1 spec. 4 5 Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> 6 This program and the accompanying materials 7 are licensed and made available under the terms and conditions of the BSD License 8 which accompanies this distribution. The full text of the license may be found at 9 http://opensource.org/licenses/bsd-license.php 10 11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 13 14 **/ 15 16 17 #ifndef __USB_DXE_LIB_H__ 18 #define __USB_DXE_LIB_H__ 19 20 #include <Protocol/UsbIo.h> 21 22 /** 23 Get the descriptor of the specified USB HID interface. 24 25 Submit a UsbGetHidDescriptor() request for the USB device specified by UsbIo 26 and Interface, and return the HID descriptor in HidDescriptor. 27 If UsbIo is NULL, then ASSERT(). 28 If HidDescriptor is NULL, then ASSERT(). 29 30 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 31 @param Interface The index of the HID interface on the USB target. 32 @param HidDescriptor Pointer to the USB HID descriptor that was retrieved from 33 the specified USB target and interface. Type EFI_USB_HID_DESCRIPTOR 34 is defined in the MDE Package Industry Standard include file Usb.h. 35 36 @retval EFI_SUCCESS The request executed successfully. 37 @retval EFI_TIMEOUT A timeout occurred executing the request. 38 @retval EFI_DEVICE_ERROR The request failed due to a device error. 39 40 **/ 41 EFI_STATUS 42 EFIAPI 43 UsbGetHidDescriptor ( 44 IN EFI_USB_IO_PROTOCOL *UsbIo, 45 IN UINT8 Interface, 46 OUT EFI_USB_HID_DESCRIPTOR *HidDescriptor 47 ); 48 49 50 /** 51 Get the report descriptor of the specified USB HID interface. 52 53 Submit a USB get HID report descriptor request for the USB device specified by 54 UsbIo and Interface, and return the report descriptor in DescriptorBuffer. 55 If UsbIo is NULL, then ASSERT(). 56 If DescriptorBuffer is NULL, then ASSERT(). 57 58 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 59 @param Interface The index of the report interface on the USB target. 60 @param DescriptorLength The size, in bytes, of DescriptorBuffer. 61 @param DescriptorBuffer A pointer to the buffer to store the report class descriptor. 62 63 @retval EFI_SUCCESS The request executed successfully. 64 @retval EFI_OUT_OF_RESOURCES The request could not be completed because the 65 buffer specified by DescriptorLength and DescriptorBuffer 66 is not large enough to hold the result of the request. 67 @retval EFI_TIMEOUT A timeout occurred executing the request. 68 @retval EFI_DEVICE_ERROR The request failed due to a device error. 69 70 **/ 71 EFI_STATUS 72 EFIAPI 73 UsbGetReportDescriptor ( 74 IN EFI_USB_IO_PROTOCOL *UsbIo, 75 IN UINT8 Interface, 76 IN UINT16 DescriptorLength, 77 OUT UINT8 *DescriptorBuffer 78 ); 79 80 /** 81 Get the HID protocol of the specified USB HID interface. 82 83 Submit a USB get HID protocol request for the USB device specified by UsbIo 84 and Interface, and return the protocol retrieved in Protocol. 85 If UsbIo is NULL, then ASSERT(). 86 If Protocol is NULL, then ASSERT(). 87 88 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 89 @param Interface The index of the report interface on the USB target. 90 @param Protocol A pointer to the protocol for the specified USB target. 91 92 @retval EFI_SUCCESS The request executed successfully. 93 @retval EFI_TIMEOUT A timeout occurred executing the request. 94 @retval EFI_DEVICE_ERROR The request failed due to a device error. 95 96 **/ 97 EFI_STATUS 98 EFIAPI 99 UsbGetProtocolRequest ( 100 IN EFI_USB_IO_PROTOCOL *UsbIo, 101 IN UINT8 Interface, 102 OUT UINT8 *Protocol 103 ); 104 105 /** 106 Set the HID protocol of the specified USB HID interface. 107 108 Submit a USB set HID protocol request for the USB device specified by UsbIo 109 and Interface, and set the protocol to the value specified by Protocol. 110 If UsbIo is NULL, then ASSERT(). 111 112 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 113 @param Interface The index of the report interface on the USB target. 114 @param Protocol The protocol value to set for the specified USB target. 115 116 @retval EFI_SUCCESS The request executed successfully. 117 @retval EFI_TIMEOUT A timeout occurred executing the request. 118 @retval EFI_DEVICE_ERROR The request failed due to a device error. 119 120 **/ 121 EFI_STATUS 122 EFIAPI 123 UsbSetProtocolRequest ( 124 IN EFI_USB_IO_PROTOCOL *UsbIo, 125 IN UINT8 Interface, 126 IN UINT8 Protocol 127 ); 128 129 /** 130 Set the idle rate of the specified USB HID report. 131 132 Submit a USB set HID report idle request for the USB device specified by UsbIo, 133 Interface, and ReportId, and set the idle rate to the value specified by Duration. 134 If UsbIo is NULL, then ASSERT(). 135 136 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 137 @param Interface The index of the report interface on the USB target. 138 @param ReportId The identifier of the report to retrieve. 139 @param Duration The idle rate to set for the specified USB target. 140 141 @retval EFI_SUCCESS The request executed successfully. 142 @retval EFI_TIMEOUT A timeout occurred executing the request. 143 @retval EFI_DEVICE_ERROR The request failed due to a device error. 144 145 **/ 146 EFI_STATUS 147 EFIAPI 148 UsbSetIdleRequest ( 149 IN EFI_USB_IO_PROTOCOL *UsbIo, 150 IN UINT8 Interface, 151 IN UINT8 ReportId, 152 IN UINT8 Duration 153 ); 154 155 /** 156 Get the idle rate of the specified USB HID report. 157 158 Submit a USB get HID report idle request for the USB device specified by UsbIo, 159 Interface, and ReportId, and return the ide rate in Duration. 160 If UsbIo is NULL, then ASSERT(). 161 If Duration is NULL, then ASSERT(). 162 163 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 164 @param Interface The index of the report interface on the USB target. 165 @param ReportId The identifier of the report to retrieve. 166 @param Duration A pointer to the idle rate retrieved from the specified USB target. 167 168 @retval EFI_SUCCESS The request executed successfully. 169 @retval EFI_TIMEOUT A timeout occurred executing the request. 170 @retval EFI_DEVICE_ERROR The request failed due to a device error. 171 172 **/ 173 EFI_STATUS 174 EFIAPI 175 UsbGetIdleRequest ( 176 IN EFI_USB_IO_PROTOCOL *UsbIo, 177 IN UINT8 Interface, 178 IN UINT8 ReportId, 179 OUT UINT8 *Duration 180 ); 181 182 /** 183 Set the report descriptor of the specified USB HID interface. 184 185 Submit a USB set HID report request for the USB device specified by UsbIo, 186 Interface, ReportId, and ReportType, and set the report descriptor using the 187 buffer specified by ReportLength and Report. 188 If UsbIo is NULL, then ASSERT(). 189 If Report is NULL, then ASSERT(). 190 191 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 192 @param Interface The index of the report interface on the USB target. 193 @param ReportId The identifier of the report to retrieve. 194 @param ReportType The type of report to retrieve. 195 @param ReportLength The size, in bytes, of Report. 196 @param Report A pointer to the report descriptor buffer to set. 197 198 @retval EFI_SUCCESS The request executed successfully. 199 @retval EFI_TIMEOUT A timeout occurred executing the request. 200 @retval EFI_DEVICE_ERROR The request failed due to a device error. 201 202 **/ 203 EFI_STATUS 204 EFIAPI 205 UsbSetReportRequest ( 206 IN EFI_USB_IO_PROTOCOL *UsbIo, 207 IN UINT8 Interface, 208 IN UINT8 ReportId, 209 IN UINT8 ReportType, 210 IN UINT16 ReportLen, 211 IN UINT8 *Report 212 ); 213 214 /** 215 Get the report descriptor of the specified USB HID interface. 216 217 Submit a USB get HID report request for the USB device specified by UsbIo, 218 Interface, ReportId, and ReportType, and return the report in the buffer 219 specified by Report. 220 If UsbIo is NULL, then ASSERT(). 221 If Report is NULL, then ASSERT(). 222 223 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 224 @param Interface The index of the report interface on the USB target. 225 @param ReportId The identifier of the report to retrieve. 226 @param ReportType The type of report to retrieve. 227 @param ReportLength The size, in bytes, of Report. 228 @param Report A pointer to the buffer to store the report descriptor. 229 230 @retval EFI_SUCCESS The request executed successfully. 231 @retval EFI_OUT_OF_RESOURCES The request could not be completed because the 232 buffer specified by ReportLength and Report is not 233 large enough to hold the result of the request. 234 @retval EFI_TIMEOUT A timeout occurred executing the request. 235 @retval EFI_DEVICE_ERROR The request failed due to a device error. 236 237 **/ 238 EFI_STATUS 239 EFIAPI 240 UsbGetReportRequest ( 241 IN EFI_USB_IO_PROTOCOL *UsbIo, 242 IN UINT8 Interface, 243 IN UINT8 ReportId, 244 IN UINT8 ReportType, 245 IN UINT16 ReportLen, 246 OUT UINT8 *Report 247 ); 248 249 /** 250 Get the descriptor of the specified USB device. 251 252 Submit a USB get descriptor request for the USB device specified by UsbIo, Value, 253 and Index, and return the descriptor in the buffer specified by Descriptor. 254 The status of the transfer is returned in Status. 255 If UsbIo is NULL, then ASSERT(). 256 If Descriptor is NULL, then ASSERT(). 257 If Status is NULL, then ASSERT(). 258 259 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 260 @param Value The device request value. 261 @param Index The device request index. 262 @param DescriptorLength The size, in bytes, of Descriptor. 263 @param Descriptor A pointer to the descriptor buffer to get. 264 @param Status A pointer to the status of the transfer. 265 266 @retval EFI_SUCCESS The request executed successfully. 267 @retval EFI_OUT_OF_RESOURCES The request could not be completed because the 268 buffer specified by DescriptorLength and Descriptor 269 is not large enough to hold the result of the request. 270 @retval EFI_TIMEOUT A timeout occurred executing the request. 271 @retval EFI_DEVICE_ERROR The request failed due to a device error. The transfer 272 status is returned in Status. 273 274 **/ 275 EFI_STATUS 276 EFIAPI 277 UsbGetDescriptor ( 278 IN EFI_USB_IO_PROTOCOL *UsbIo, 279 IN UINT16 Value, 280 IN UINT16 Index, 281 IN UINT16 DescriptorLength, 282 OUT VOID *Descriptor, 283 OUT UINT32 *Status 284 ); 285 286 /** 287 Set the descriptor of the specified USB device. 288 289 Submit a USB set descriptor request for the USB device specified by UsbIo, 290 Value, and Index, and set the descriptor using the buffer specified by DesriptorLength 291 and Descriptor. The status of the transfer is returned in Status. 292 If UsbIo is NULL, then ASSERT(). 293 If Descriptor is NULL, then ASSERT(). 294 If Status is NULL, then ASSERT(). 295 296 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 297 @param Value The device request value. 298 @param Index The device request index. 299 @param DescriptorLength The size, in bytes, of Descriptor. 300 @param Descriptor A pointer to the descriptor buffer to set. 301 @param Status A pointer to the status of the transfer. 302 303 @retval EFI_SUCCESS The request executed successfully. 304 @retval EFI_TIMEOUT A timeout occurred executing the request. 305 @retval EFI_DEVICE_ERROR The request failed due to a device error. 306 The transfer status is returned in Status. 307 308 **/ 309 EFI_STATUS 310 EFIAPI 311 UsbSetDescriptor ( 312 IN EFI_USB_IO_PROTOCOL *UsbIo, 313 IN UINT16 Value, 314 IN UINT16 Index, 315 IN UINT16 DescriptorLength, 316 IN VOID *Descriptor, 317 OUT UINT32 *Status 318 ); 319 320 /** 321 Get the interface setting of the specified USB device. 322 323 Submit a USB get interface request for the USB device specified by UsbIo, 324 and Interface, and place the result in the buffer specified by AlternateSetting. 325 The status of the transfer is returned in Status. 326 If UsbIo is NULL, then ASSERT(). 327 If AlternateSetting is NULL, then ASSERT(). 328 If Status is NULL, then ASSERT(). 329 330 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 331 @param Interface The interface index value. 332 @param AlternateSetting A pointer to the alternate setting to be retrieved. 333 @param Status A pointer to the status of the transfer. 334 335 @retval EFI_SUCCESS The request executed successfully. 336 @retval EFI_TIMEOUT A timeout occurred executing the request. 337 @retval EFI_DEVICE_ERROR The request failed due to a device error. 338 The transfer status is returned in Status. 339 340 **/ 341 EFI_STATUS 342 EFIAPI 343 UsbGetInterface ( 344 IN EFI_USB_IO_PROTOCOL *UsbIo, 345 IN UINT16 Interface, 346 OUT UINT16 *AlternateSetting, 347 OUT UINT32 *Status 348 ); 349 350 /** 351 Set the interface setting of the specified USB device. 352 353 Submit a USB set interface request for the USB device specified by UsbIo, and 354 Interface, and set the alternate setting to the value specified by AlternateSetting. 355 The status of the transfer is returned in Status. 356 If UsbIo is NULL, then ASSERT(). 357 If Status is NULL, then ASSERT(). 358 359 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 360 @param Interface The interface index value. 361 @param AlternateSetting The alternate setting to be set. 362 @param Status A pointer to the status of the transfer. 363 364 @retval EFI_SUCCESS The request executed successfully. 365 @retval EFI_TIMEOUT A timeout occurred executing the request. 366 @retval EFI_SUCCESS The request failed due to a device error. 367 The transfer status is returned in Status. 368 369 **/ 370 EFI_STATUS 371 EFIAPI 372 UsbSetInterface ( 373 IN EFI_USB_IO_PROTOCOL *UsbIo, 374 IN UINT16 Interface, 375 IN UINT16 AlternateSetting, 376 OUT UINT32 *Status 377 ); 378 379 /** 380 Get the device configuration. 381 382 Submit a USB get configuration request for the USB device specified by UsbIo 383 and place the result in the buffer specified by ConfigurationValue. The status 384 of the transfer is returned in Status. 385 If UsbIo is NULL, then ASSERT(). 386 If ConfigurationValue is NULL, then ASSERT(). 387 If Status is NULL, then ASSERT(). 388 389 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 390 @param ConfigurationValue A pointer to the device configuration to be retrieved. 391 @param Status A pointer to the status of the transfer. 392 393 @retval EFI_SUCCESS The request executed successfully. 394 @retval EFI_TIMEOUT A timeout occurred executing the request. 395 @retval EFI_DEVICE_ERROR The request failed due to a device error. 396 The transfer status is returned in Status. 397 398 **/ 399 EFI_STATUS 400 EFIAPI 401 UsbGetConfiguration ( 402 IN EFI_USB_IO_PROTOCOL *UsbIo, 403 OUT UINT16 *ConfigurationValue, 404 OUT UINT32 *Status 405 ); 406 407 /** 408 Set the device configuration. 409 410 Submit a USB set configuration request for the USB device specified by UsbIo 411 and set the device configuration to the value specified by ConfigurationValue. 412 The status of the transfer is returned in Status. 413 If UsbIo is NULL, then ASSERT(). 414 If Status is NULL, then ASSERT(). 415 416 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 417 @param ConfigurationValue The device configuration value to be set. 418 @param Status A pointer to the status of the transfer. 419 420 @retval EFI_SUCCESS The request executed successfully. 421 @retval EFI_TIMEOUT A timeout occurred executing the request. 422 @retval EFI_DEVICE_ERROR The request failed due to a device error. 423 The transfer status is returned in Status. 424 425 **/ 426 EFI_STATUS 427 EFIAPI 428 UsbSetConfiguration ( 429 IN EFI_USB_IO_PROTOCOL *UsbIo, 430 IN UINT16 ConfigurationValue, 431 OUT UINT32 *Status 432 ); 433 434 /** 435 Set the specified feature of the specified device. 436 437 Submit a USB set device feature request for the USB device specified by UsbIo, 438 Recipient, and Target to the value specified by Value. The status of the 439 transfer is returned in Status. 440 If UsbIo is NULL, then ASSERT(). 441 If Status is NULL, then ASSERT(). 442 443 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 444 @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint). 445 Type USB_TYPES_DEFINITION is defined in the MDE Package Industry 446 Standard include file Usb.h. 447 @param Value The value of the feature to be set. 448 @param Target The index of the device to be set. 449 @param Status A pointer to the status of the transfer. 450 451 @retval EFI_SUCCESS The request executed successfully. 452 @retval EFI_TIMEOUT A timeout occurred executing the request. 453 @retval EFI_DEVICE_ERROR The request failed due to a device error. 454 The transfer status is returned in Status. 455 456 **/ 457 EFI_STATUS 458 EFIAPI 459 UsbSetFeature ( 460 IN EFI_USB_IO_PROTOCOL *UsbIo, 461 IN USB_TYPES_DEFINITION Recipient, 462 IN UINT16 Value, 463 IN UINT16 Target, 464 OUT UINT32 *Status 465 ); 466 467 /** 468 Clear the specified feature of the specified device. 469 470 Submit a USB clear device feature request for the USB device specified by UsbIo, 471 Recipient, and Target to the value specified by Value. The status of the transfer 472 is returned in Status. 473 If UsbIo is NULL, then ASSERT(). 474 If Status is NULL, then ASSERT(). 475 476 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 477 @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint). 478 Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard 479 include file Usb.h. 480 @param Value The value of the feature to be cleared. 481 @param Target The index of the device to be cleared. 482 @param Status A pointer to the status of the transfer. 483 484 @retval EFI_SUCCESS The request executed successfully. 485 @retval EFI_TIMEOUT A timeout occurred executing the request. 486 @retval EFI_DEVICE_ERROR The request failed due to a device error. 487 The transfer status is returned in Status. 488 489 **/ 490 EFI_STATUS 491 EFIAPI 492 UsbClearFeature ( 493 IN EFI_USB_IO_PROTOCOL *UsbIo, 494 IN USB_TYPES_DEFINITION Recipient, 495 IN UINT16 Value, 496 IN UINT16 Target, 497 OUT UINT32 *Status 498 ); 499 500 /** 501 Get the status of the specified device. 502 503 Submit a USB device get status request for the USB device specified by UsbIo, 504 Recipient, and Target, and place the result in the buffer specified by DeviceStatus. 505 The status of the transfer is returned in Status. 506 If UsbIo is NULL, then ASSERT(). 507 If DeviceStatus is NULL, then ASSERT(). 508 If Status is NULL, then ASSERT(). 509 510 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 511 @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint). 512 Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard 513 include file Usb.h. 514 @param Target The index of the device to be get the status of. 515 @param DeviceStatus A pointer to the device status to be retrieved. 516 @param Status A pointer to the status of the transfer. 517 518 @retval EFI_SUCCESS The request executed successfully. 519 @retval EFI_TIMEOUT A timeout occurred executing the request. 520 @retval EFI_DEVICE_ERROR The request failed due to a device error. 521 The transfer status is returned in Status. 522 523 **/ 524 EFI_STATUS 525 EFIAPI 526 UsbGetStatus ( 527 IN EFI_USB_IO_PROTOCOL *UsbIo, 528 IN USB_TYPES_DEFINITION Recipient, 529 IN UINT16 Target, 530 OUT UINT16 *DeviceStatus, 531 OUT UINT32 *Status 532 ); 533 534 /** 535 Clear halt feature of the specified usb endpoint. 536 537 Retrieve the USB endpoint descriptor specified by UsbIo and EndPoint. 538 If the USB endpoint descriptor can not be retrieved, then return EFI_NOT_FOUND. 539 If the endpoint descriptor is found, then clear the halt feature of this USB endpoint. 540 The status of the transfer is returned in Status. 541 If UsbIo is NULL, then ASSERT(). 542 If Status is NULL, then ASSERT(). 543 544 @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. 545 @param Endpoint The endpoint address. 546 @param Status A pointer to the status of the transfer. 547 548 @retval EFI_SUCCESS The request executed successfully. 549 @retval EFI_TIMEOUT A timeout occurred executing the request. 550 @retval EFI_DEVICE_ERROR The request failed due to a device error. 551 The transfer status is returned in Status. 552 @retval EFI_NOT_FOUND The specified USB endpoint descriptor can not be found 553 554 **/ 555 EFI_STATUS 556 EFIAPI 557 UsbClearEndpointHalt ( 558 IN EFI_USB_IO_PROTOCOL *UsbIo, 559 IN UINT8 Endpoint, 560 OUT UINT32 *Status 561 ); 562 563 #endif 564