MdePkg/Include/Protocol/UsbFunctionIo.h

   1 /** @file
   2   The USB Function Protocol provides an I/O abstraction for a USB Controller
   3   operating in Function mode (also commonly referred to as Device, Peripheral,
   4   or Target mode) and the mechanisms by which the USB Function can communicate
   5   with the USB Host. It is used by other UEFI drivers or applications to
   6   perform data transactions and basic USB controller management over a USB
   7   Function port.
   8
   9   This simple protocol only supports USB 2.0 bulk transfers on systems with a
  10   single configuration and a single interface. It does not support isochronous
  11   or interrupt transfers, alternate interfaces, or USB 3.0 functionality.
  12   Future revisions of this protocol may support these or additional features.
  13
  14   Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
  15   This program and the accompanying materials
  16   are licensed and made available under the terms and conditions of the BSD License
  17   which accompanies this distribution.  The full text of the license may be found at
  18   http://opensource.org/licenses/bsd-license.php
  19
  20   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  21   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  22
  23   @par Revision Reference:
  24   This Protocol was introduced in UEFI Specification 2.5.
  25
  26 **/
  27
  28 #ifndef __USB_FUNCTION_IO_H__
  29 #define __USB_FUNCTION_IO_H__
  30
  31 #include <Protocol/UsbIo.h>
  32
  33 #define EFI_USBFN_IO_PROTOCOL_GUID \
  34     { \
  35       0x32d2963a, 0xfe5d, 0x4f30, {0xb6, 0x33, 0x6e, 0x5d, 0xc5, 0x58, 0x3, 0xcc} \
  36     }
  37
  38 typedef struct _EFI_USBFN_IO_PROTOCOL  EFI_USBFN_IO_PROTOCOL;
  39
  40 #define EFI_USBFN_IO_PROTOCOL_REVISION 0x00010001
  41
  42 typedef enum _EFI_USBFN_PORT_TYPE {
  43   EfiUsbUnknownPort = 0,
  44   EfiUsbStandardDownstreamPort,
  45   EfiUsbChargingDownstreamPort,
  46   EfiUsbDedicatedChargingPort,
  47   EfiUsbInvalidDedicatedChargingPort
  48 } EFI_USBFN_PORT_TYPE;
  49
  50 typedef struct {
  51   EFI_USB_INTERFACE_DESCRIPTOR         *InterfaceDescriptor;
  52   EFI_USB_ENDPOINT_DESCRIPTOR          **EndpointDescriptorTable;
  53 } EFI_USB_INTERFACE_INFO;
  54
  55 typedef struct {
  56   EFI_USB_CONFIG_DESCRIPTOR            *ConfigDescriptor;
  57   EFI_USB_INTERFACE_INFO               **InterfaceInfoTable;
  58 } EFI_USB_CONFIG_INFO;
  59
  60 typedef struct {
  61   EFI_USB_DEVICE_DESCRIPTOR            *DeviceDescriptor;
  62   EFI_USB_CONFIG_INFO                  **ConfigInfoTable;
  63 } EFI_USB_DEVICE_INFO;
  64
  65 typedef enum _EFI_USB_ENDPOINT_TYPE {
  66   UsbEndpointControl = 0x00,
  67   //UsbEndpointIsochronous = 0x01,
  68   UsbEndpointBulk = 0x02,
  69   //UsbEndpointInterrupt = 0x03
  70 } EFI_USB_ENDPOINT_TYPE;
  71
  72 typedef enum _EFI_USBFN_DEVICE_INFO_ID {
  73   EfiUsbDeviceInfoUnknown = 0,
  74   EfiUsbDeviceInfoSerialNumber,
  75   EfiUsbDeviceInfoManufacturerName,
  76   EfiUsbDeviceInfoProductName
  77 } EFI_USBFN_DEVICE_INFO_ID;
  78
  79 typedef enum _EFI_USBFN_ENDPOINT_DIRECTION {
  80   EfiUsbEndpointDirectionHostOut = 0,
  81   EfiUsbEndpointDirectionHostIn,
  82   EfiUsbEndpointDirectionDeviceTx = EfiUsbEndpointDirectionHostIn,
  83   EfiUsbEndpointDirectionDeviceRx = EfiUsbEndpointDirectionHostOut
  84 } EFI_USBFN_ENDPOINT_DIRECTION;
  85
  86 typedef enum _EFI_USBFN_MESSAGE {
  87   //
  88   // Nothing
  89   //
  90   EfiUsbMsgNone = 0,
  91   //
  92   // SETUP packet is received, returned Buffer contains
  93   // EFI_USB_DEVICE_REQUEST struct
  94   //
  95   EfiUsbMsgSetupPacket,
  96   //
  97   // Indicates that some of the requested data has been received from the
  98   // host. It is the responsibility of the class driver to determine if it
  99   // needs to wait for any remaining data. Returned Buffer contains
 100   // EFI_USBFN_TRANSFER_RESULT struct containing endpoint number, transfer
 101   // status and count of bytes received.
 102   //
 103   EfiUsbMsgEndpointStatusChangedRx,
 104   //
 105   // Indicates that some of the requested data has been transmitted to the
 106   // host. It is the responsibility of the class driver to determine if any
 107   // remaining data needs to be resent. Returned Buffer contains
 108   // EFI_USBFN_TRANSFER_RESULT struct containing endpoint number, transfer
 109   // status and count of bytes sent.
 110   //
 111   EfiUsbMsgEndpointStatusChangedTx,
 112   //
 113   // DETACH bus event signaled
 114   //
 115   EfiUsbMsgBusEventDetach,
 116   //
 117   // ATTACH bus event signaled
 118   //
 119   EfiUsbMsgBusEventAttach,
 120   //
 121   // RESET bus event signaled
 122   //
 123   EfiUsbMsgBusEventReset,
 124   //
 125   // SUSPEND bus event signaled
 126   //
 127   EfiUsbMsgBusEventSuspend,
 128   //
 129   // RESUME bus event signaled
 130   //
 131   EfiUsbMsgBusEventResume,
 132   //
 133   // Bus speed updated, returned buffer indicated bus speed using
 134   // following enumeration named EFI_USB_BUS_SPEED
 135   //
 136   EfiUsbMsgBusEventSpeed
 137 } EFI_USBFN_MESSAGE;
 138
 139 typedef enum _EFI_USBFN_TRANSFER_STATUS {
 140   UsbTransferStatusUnknown = 0,
 141   UsbTransferStatusComplete,
 142   UsbTransferStatusAborted,
 143   UsbTransferStatusActive,
 144   UsbTransferStatusNone
 145 } EFI_USBFN_TRANSFER_STATUS;
 146
 147 typedef struct _EFI_USBFN_TRANSFER_RESULT {
 148   UINTN                         BytesTransferred;
 149   EFI_USBFN_TRANSFER_STATUS     TransferStatus;
 150   UINT8                         EndpointIndex;
 151   EFI_USBFN_ENDPOINT_DIRECTION  Direction;
 152   VOID                          *Buffer;
 153 } EFI_USBFN_TRANSFER_RESULT;
 154
 155 typedef enum _EFI_USB_BUS_SPEED {
 156   UsbBusSpeedUnknown = 0,
 157   UsbBusSpeedLow,
 158   UsbBusSpeedFull,
 159   UsbBusSpeedHigh,
 160   UsbBusSpeedSuper,
 161   UsbBusSpeedMaximum = UsbBusSpeedSuper
 162 } EFI_USB_BUS_SPEED;
 163
 164 typedef union _EFI_USBFN_MESSAGE_PAYLOAD {
 165   EFI_USB_DEVICE_REQUEST       udr;
 166   EFI_USBFN_TRANSFER_RESULT    utr;
 167   EFI_USB_BUS_SPEED            ubs;
 168 } EFI_USBFN_MESSAGE_PAYLOAD;
 169
 170 typedef enum _EFI_USBFN_POLICY_TYPE {
 171   EfiUsbPolicyUndefined = 0,
 172   EfiUsbPolicyMaxTransactionSize,
 173   EfiUsbPolicyZeroLengthTerminationSupport,
 174   EfiUsbPolicyZeroLengthTermination
 175 } EFI_USBFN_POLICY_TYPE;
 176
 177 /**
 178   Returns information about what USB port type was attached.
 179
 180   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 181   @param[out] PortType          Returns the USB port type.
 182
 183   @retval EFI_SUCCESS           The function returned successfully.
 184   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 185   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 186   @retval EFI_NOT_READY         The physical device is busy or not ready to
 187                                 process this request or there is no USB port
 188                                 attached to the device.
 189
 190 **/
 191 typedef
 192 EFI_STATUS
 193 (EFIAPI *EFI_USBFN_IO_DETECT_PORT) (
 194   IN     EFI_USBFN_IO_PROTOCOL         *This,
 195      OUT EFI_USBFN_PORT_TYPE           *PortType
 196   );
 197
 198 /**
 199   Configures endpoints based on supplied device and configuration descriptors.
 200
 201   Assuming that the hardware has already been initialized, this function configures
 202   the endpoints using the device information supplied by DeviceInfo, activates the
 203   port, and starts receiving USB events.
 204
 205   This function must ignore the bMaxPacketSize0field of the Standard Device Descriptor
 206   and the wMaxPacketSize field of the Standard Endpoint Descriptor that are made
 207   available through DeviceInfo.
 208
 209   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 210   @param[out] DeviceInfo        A pointer to EFI_USBFN_DEVICE_INFO instance.
 211
 212   @retval EFI_SUCCESS           The function returned successfully.
 213   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 214   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 215   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 216                                 this request.
 217   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to lack of
 218                                 resources.
 219
 220 **/
 221 typedef
 222 EFI_STATUS
 223 (EFIAPI *EFI_USBFN_IO_CONFIGURE_ENABLE_ENDPOINTS) (
 224   IN     EFI_USBFN_IO_PROTOCOL         *This,
 225      OUT EFI_USB_DEVICE_INFO           *DeviceInfo
 226   );
 227
 228 /**
 229   Returns the maximum packet size of the specified endpoint type for the supplied
 230   bus speed.
 231
 232   If the BusSpeed is UsbBusSpeedUnknown, the maximum speed the underlying controller
 233   supports is assumed.
 234
 235   This protocol currently does not support isochronous or interrupt transfers. Future
 236   revisions of this protocol may eventually support it.
 237
 238   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOLinstance.
 239   @param[in]  EndpointType      Endpoint type as defined as EFI_USB_ENDPOINT_TYPE.
 240   @param[in]  BusSpeed          Bus speed as defined as EFI_USB_BUS_SPEED.
 241   @param[out] MaxPacketSize     The maximum packet size, in bytes, of the specified
 242                                 endpoint type.
 243
 244   @retval EFI_SUCCESS           The function returned successfully.
 245   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 246   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 247   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 248                                 this request.
 249
 250 **/
 251 typedef
 252 EFI_STATUS
 253 (EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_MAXPACKET_SIZE) (
 254   IN     EFI_USBFN_IO_PROTOCOL         *This,
 255   IN     EFI_USB_ENDPOINT_TYPE         EndpointType,
 256   IN     EFI_USB_BUS_SPEED             BusSpeed,
 257      OUT UINT16                        *MaxPacketSize
 258   );
 259
 260 /**
 261   Returns device specific information based on the supplied identifier as a Unicode string.
 262
 263   If the supplied Buffer isn't large enough, or is NULL, the method fails with
 264   EFI_BUFFER_TOO_SMALL and the required size is returned through BufferSize. All returned
 265   strings are in Unicode format.
 266
 267   An Id of EfiUsbDeviceInfoUnknown is treated as an invalid parameter.
 268
 269   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOLinstance.
 270   @param[in]  Id                The requested information id.
 271
 272
 273   @param[in]  BufferSize        On input, the size of the Buffer in bytes. On output, the
 274                                 amount of data returned in Buffer in bytes.
 275   @param[out] Buffer            A pointer to a buffer to returnthe requested information
 276                                 as a Unicode string.
 277
 278   @retval EFI_SUCCESS           The function returned successfully.
 279   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 280                                 BufferSize is NULL.
 281                                 *BufferSize is not 0 and Buffer is NULL.
 282                                 Id in invalid.
 283   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 284   @retval EFI_BUFFER_TOO_SMALL  The buffer is too small to hold the buffer.
 285                                 *BufferSize has been updated with the size needed to hold the request string.
 286
 287 **/
 288 typedef
 289 EFI_STATUS
 290 (EFIAPI *EFI_USBFN_IO_GET_DEVICE_INFO) (
 291   IN     EFI_USBFN_IO_PROTOCOL         *This,
 292   IN     EFI_USBFN_DEVICE_INFO_ID      Id,
 293   IN OUT UINTN                         *BufferSize,
 294      OUT VOID                          *Buffer OPTIONAL
 295 );
 296
 297 /**
 298   Returns the vendor-id and product-id of the device.
 299
 300   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 301   @param[out] Vid               Returned vendor-id of the device.
 302   @param[out] Pid               Returned product-id of the device.
 303
 304   @retval EFI_SUCCESS           The function returned successfully.
 305   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 306   @retval EFI_NOT_FOUND         Unable to return the vendor-id or the product-id.
 307
 308 **/
 309 typedef
 310 EFI_STATUS
 311 (EFIAPI *EFI_USBFN_IO_GET_VENDOR_ID_PRODUCT_ID) (
 312   IN     EFI_USBFN_IO_PROTOCOL         *This,
 313      OUT UINT16                        *Vid,
 314      OUT UINT16                        *Pid
 315 );
 316
 317 /**
 318   Aborts the transfer on the specified endpoint.
 319
 320   This function should fail with EFI_INVALID_PARAMETER if the specified direction
 321   is incorrect for the endpoint.
 322
 323   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 324   @param[in]  EndpointIndex     Indicates the endpoint on which the ongoing transfer
 325                                 needs to be canceled.
 326   @param[in]  Direction         Direction of the endpoint.
 327
 328   @retval EFI_SUCCESS           The function returned successfully.
 329   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 330   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 331   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 332                                 this request.
 333
 334 **/
 335 typedef
 336 EFI_STATUS
 337 (EFIAPI *EFI_USBFN_IO_ABORT_TRANSFER) (
 338   IN  EFI_USBFN_IO_PROTOCOL            *This,
 339   IN  UINT8                            EndpointIndex,
 340   IN  EFI_USBFN_ENDPOINT_DIRECTION     Direction
 341 );
 342
 343 /**
 344   Returns the stall state on the specified endpoint.
 345
 346   This function should fail with EFI_INVALID_PARAMETER if the specified direction
 347   is incorrect for the endpoint.
 348
 349   @param[in]      This          A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 350   @param[in]      EndpointIndex Indicates the endpoint.
 351   @param[in]      Direction     Direction of the endpoint.
 352   @param[in, out] State         Boolean, true value indicates that the endpoint
 353                                 is in a stalled state, false otherwise.
 354
 355   @retval EFI_SUCCESS           The function returned successfully.
 356   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 357   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 358   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 359                                 this request.
 360
 361 **/
 362 typedef
 363 EFI_STATUS
 364 (EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_STALL_STATE) (
 365   IN     EFI_USBFN_IO_PROTOCOL         *This,
 366   IN     UINT8                         EndpointIndex,
 367   IN     EFI_USBFN_ENDPOINT_DIRECTION  Direction,
 368   IN OUT BOOLEAN                       *State
 369 );
 370
 371 /**
 372   Sets or clears the stall state on the specified endpoint.
 373
 374   This function should fail with EFI_INVALID_PARAMETER if the specified direction
 375   is incorrect for the endpoint.
 376
 377   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 378   @param[in]  EndpointIndex     Indicates the endpoint.
 379   @param[in]  Direction         Direction of the endpoint.
 380   @param[in]  State             Requested stall state on the specified endpoint.
 381                                 True value causes the endpoint to stall; false
 382                                 value clears an existing stall.
 383
 384   @retval EFI_SUCCESS           The function returned successfully.
 385   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 386   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 387   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 388                                 this request.
 389
 390 **/
 391 typedef
 392 EFI_STATUS
 393 (EFIAPI *EFI_USBFN_IO_SET_ENDPOINT_STALL_STATE) (
 394   IN     EFI_USBFN_IO_PROTOCOL         *This,
 395   IN     UINT8                         EndpointIndex,
 396   IN     EFI_USBFN_ENDPOINT_DIRECTION  Direction,
 397   IN OUT BOOLEAN                       *State
 398 );
 399
 400 /**
 401   This function is called repeatedly to get information on USB bus states,
 402   receive-completion and transmit-completion events on the endpoints, and
 403   notification on setup packet on endpoint 0.
 404
 405   A class driver must call EFI_USBFN_IO_PROTOCOL.EventHandler()repeatedly
 406   to receive updates on the transfer status and number of bytes transferred
 407   on various endpoints.
 408
 409   @param[in]      This          A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 410   @param[out]     Message       Indicates the event that initiated this notification.
 411   @param[in, out] PayloadSize   On input, the size of the memory pointed by
 412                                 Payload. On output, the amount ofdata returned
 413                                 in Payload.
 414   @param[out]     Payload       A pointer to EFI_USBFN_MESSAGE_PAYLOAD instance
 415                                 to return additional payload for current message.
 416
 417   @retval EFI_SUCCESS           The function returned successfully.
 418   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 419   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 420   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 421                                 this request.
 422   @retval EFI_BUFFER_TOO_SMALL  The Supplied buffer is not large enough to hold
 423                                 the message payload.
 424
 425 **/
 426 typedef
 427 EFI_STATUS
 428 (EFIAPI *EFI_USBFN_IO_EVENTHANDLER) (
 429   IN     EFI_USBFN_IO_PROTOCOL         *This,
 430      OUT EFI_USBFN_MESSAGE             *Message,
 431   IN OUT UINTN                         *PayloadSize,
 432      OUT EFI_USBFN_MESSAGE_PAYLOAD     *Payload
 433 );
 434
 435 /**
 436   This function handles transferring data to or from the host on the specified
 437   endpoint, depending on the direction specified.
 438
 439   A class driver must call EFI_USBFN_IO_PROTOCOL.EventHandler() repeatedly to
 440   receive updates on the transfer status and the number of bytes transferred on
 441   various endpoints. Upon an update of the transfer status, the Buffer field of
 442   the EFI_USBFN_TRANSFER_RESULT structure (as described in the function description
 443   for EFI_USBFN_IO_PROTOCOL.EventHandler()) must be initialized with the Buffer
 444   pointer that was supplied to this method.
 445
 446   The overview of the call sequence is illustrated in the Figure 54.
 447
 448   This function should fail with EFI_INVALID_PARAMETER if the specified direction
 449   is incorrect for the endpoint.
 450
 451   @param[in]      This          A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 452   @param[in]      EndpointIndex Indicates the endpoint on which TX or RX transfer
 453                                 needs to take place.
 454   @param[in]      Direction     Direction of the endpoint.
 455   @param[in, out] BufferSize    If Direction is EfiUsbEndpointDirectionDeviceRx:
 456                                   On input, the size of the Bufferin bytes.
 457                                   On output, the amount of data returned in Buffer
 458                                   in bytes.
 459                                 If Direction is EfiUsbEndpointDirectionDeviceTx:
 460                                   On input, the size of the Bufferin bytes.
 461                                   On output, the amount of data transmitted in bytes.
 462   @param[in, out] Buffer        If Direction is EfiUsbEndpointDirectionDeviceRx:
 463                                   The Buffer to return the received data.
 464                                 If Directionis EfiUsbEndpointDirectionDeviceTx:
 465                                   The Buffer that contains the data to be transmitted.
 466
 467   @retval EFI_SUCCESS           The function returned successfully.
 468   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 469   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 470   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 471                                 this request.
 472
 473 **/
 474 typedef
 475 EFI_STATUS
 476 (EFIAPI *EFI_USBFN_IO_TRANSFER) (
 477   IN     EFI_USBFN_IO_PROTOCOL         *This,
 478   IN     UINT8                         EndpointIndex,
 479   IN     EFI_USBFN_ENDPOINT_DIRECTION  Direction,
 480   IN OUT UINTN                         *BufferSize,
 481   IN OUT VOID                          *Buffer
 482 );
 483
 484 /**
 485   Returns the maximum supported transfer size.
 486
 487   Returns the maximum number of bytes that the underlying controller can accommodate
 488   in a single transfer.
 489
 490   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 491   @param[out] MaxTransferSize   The maximum supported transfer size, in bytes.
 492
 493   @retval EFI_SUCCESS           The function returned successfully.
 494   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 495   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 496   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 497                                 this request.
 498
 499 **/
 500 typedef
 501 EFI_STATUS
 502 (EFIAPI *EFI_USBFN_IO_GET_MAXTRANSFER_SIZE) (
 503   IN     EFI_USBFN_IO_PROTOCOL         *This,
 504      OUT UINTN                         *MaxTransferSize
 505   );
 506
 507 /**
 508   Allocates a transfer buffer of the specified sizethat satisfies the controller
 509   requirements.
 510
 511   The AllocateTransferBuffer() function allocates a memory region of Size bytes and
 512   returns the address of the allocated memory that satisfies the underlying controller
 513   requirements in the location referenced by Buffer.
 514
 515   The allocated transfer buffer must be freed using a matching call to
 516   EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer()function.
 517
 518   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 519   @param[in]  Size              The number of bytes to allocate for the transfer buffer.
 520   @param[out] Buffer            A pointer to a pointer to the allocated buffer if the
 521                                 call succeeds; undefined otherwise.
 522
 523   @retval EFI_SUCCESS           The function returned successfully.
 524   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 525   @retval EFI_OUT_OF_RESOURCES  The requested transfer buffer could not be allocated.
 526
 527 **/
 528 typedef
 529 EFI_STATUS
 530 (EFIAPI *EFI_USBFN_IO_ALLOCATE_TRANSFER_BUFFER) (
 531   IN     EFI_USBFN_IO_PROTOCOL         *This,
 532   IN     UINTN                         Size,
 533      OUT VOID                          **Buffer
 534   );
 535
 536 /**
 537   Deallocates the memory allocated for the transfer buffer by the
 538   EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer() function.
 539
 540   The EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer() function deallocates the
 541   memory specified by Buffer. The Buffer that is freed must have been allocated
 542   by EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer().
 543
 544   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 545   @param[in]  Buffer            A pointer to the transfer buffer to deallocate.
 546
 547   @retval EFI_SUCCESS           The function returned successfully.
 548   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 549
 550 **/
 551 typedef
 552 EFI_STATUS
 553 (EFIAPI *EFI_USBFN_IO_FREE_TRANSFER_BUFFER) (
 554   IN  EFI_USBFN_IO_PROTOCOL         *This,
 555   IN  VOID                          *Buffer
 556   );
 557
 558 /**
 559   This function supplies power to the USB controller if needed and initializes
 560   the hardware and the internal data structures. The port must not be activated
 561   by this function.
 562
 563   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 564
 565   @retval EFI_SUCCESS           The function returned successfully.
 566   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 567   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 568
 569 **/
 570 typedef
 571 EFI_STATUS
 572 (EFIAPI *EFI_USBFN_IO_START_CONTROLLER) (
 573   IN  EFI_USBFN_IO_PROTOCOL         *This
 574   );
 575
 576 /**
 577   This function stops the USB hardware device.
 578
 579   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 580
 581   @retval EFI_SUCCESS           The function returned successfully.
 582   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 583   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 584
 585 **/
 586 typedef
 587 EFI_STATUS
 588 (EFIAPI *EFI_USBFN_IO_STOP_CONTROLLER) (
 589   IN  EFI_USBFN_IO_PROTOCOL         *This
 590   );
 591
 592 /**
 593   This function sets the configuration policy for the specified non-control
 594   endpoint.
 595
 596   This function can only be called before EFI_USBFN_IO_PROTOCOL.StartController()
 597   or after EFI_USBFN_IO_PROTOCOL.StopController() has been called.
 598
 599   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 600   @param[in]  EndpointIndex     Indicates the non-control endpoint for which the
 601                                 policy needs to be set.
 602   @param[in]  Direction         Direction of the endpoint.
 603   @param[in]  PolicyType        Policy type the user is trying to set for the
 604                                 specified non-control endpoint.
 605   @param[in]  BufferSize        The size of the Bufferin bytes.
 606   @param[in]  Buffer            The new value for the policy parameter that
 607                                 PolicyType specifies.
 608
 609   @retval EFI_SUCCESS           The function returned successfully.
 610   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 611   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 612   @retval EFI_UNSUPPORTED       Changing this policy value is not supported.
 613
 614 **/
 615 typedef
 616 EFI_STATUS
 617 (EFIAPI *EFI_USBFN_IO_SET_ENDPOINT_POLICY) (
 618   IN  EFI_USBFN_IO_PROTOCOL         *This,
 619   IN  UINT8                         EndpointIndex,
 620   IN  EFI_USBFN_ENDPOINT_DIRECTION  Direction,
 621   IN  EFI_USBFN_POLICY_TYPE         PolicyType,
 622   IN  UINTN                         BufferSize,
 623   IN  VOID                          *Buffer
 624   );
 625
 626 /**
 627   This function sets the configuration policy for the specified non-control
 628   endpoint.
 629
 630   This function can only be called before EFI_USBFN_IO_PROTOCOL.StartController()
 631   or after EFI_USBFN_IO_PROTOCOL.StopController() has been called.
 632
 633   @param[in]      This          A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 634   @param[in]      EndpointIndex Indicates the non-control endpoint for which the
 635                                 policy needs to be set.
 636   @param[in]      Direction     Direction of the endpoint.
 637   @param[in]      PolicyType    Policy type the user is trying to retrieve for
 638                                 the specified non-control endpoint.
 639   @param[in, out] BufferSize    On input, the size of Bufferin bytes. On output,
 640                                 the amount of data returned in Bufferin bytes.
 641   @param[in, out] Buffer        A pointer to a buffer to return requested endpoint
 642                                 policy value.
 643
 644   @retval EFI_SUCCESS           The function returned successfully.
 645   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 646   @retval EFI_DEVICE_ERROR      The specified policy value is not supported.
 647   @retval EFI_BUFFER_TOO_SMALL  Supplied buffer is not large enough to hold requested
 648                                 policy value.
 649
 650 **/
 651 typedef
 652 EFI_STATUS
 653 (EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_POLICY) (
 654   IN     EFI_USBFN_IO_PROTOCOL         *This,
 655   IN     UINT8                         EndpointIndex,
 656   IN     EFI_USBFN_ENDPOINT_DIRECTION  Direction,
 657   IN     EFI_USBFN_POLICY_TYPE         PolicyType,
 658   IN OUT UINTN                         *BufferSize,
 659   IN OUT VOID                          *Buffer
 660   );
 661
 662 ///
 663 /// The EFI_USBFN_IO_PROTOCOL provides basic data transactions and basic USB
 664 /// controller management for a USB Function port.
 665 ///
 666 struct _EFI_USBFN_IO_PROTOCOL {
 667   UINT32                                    Revision;
 668   EFI_USBFN_IO_DETECT_PORT                  DetectPort;
 669   EFI_USBFN_IO_CONFIGURE_ENABLE_ENDPOINTS   ConfigureEnableEndpoints;
 670   EFI_USBFN_IO_GET_ENDPOINT_MAXPACKET_SIZE  GetEndpointMaxPacketSize;
 671   EFI_USBFN_IO_GET_DEVICE_INFO              GetDeviceInfo;
 672   EFI_USBFN_IO_GET_VENDOR_ID_PRODUCT_ID     GetVendorIdProductId;
 673   EFI_USBFN_IO_ABORT_TRANSFER               AbortTransfer;
 674   EFI_USBFN_IO_GET_ENDPOINT_STALL_STATE     GetEndpointStallState;
 675   EFI_USBFN_IO_SET_ENDPOINT_STALL_STATE     SetEndpointStallState;
 676   EFI_USBFN_IO_EVENTHANDLER                 EventHandler;
 677   EFI_USBFN_IO_TRANSFER                     Transfer;
 678   EFI_USBFN_IO_GET_MAXTRANSFER_SIZE         GetMaxTransferSize;
 679   EFI_USBFN_IO_ALLOCATE_TRANSFER_BUFFER     AllocateTransferBuffer;
 680   EFI_USBFN_IO_FREE_TRANSFER_BUFFER         FreeTransferBuffer;
 681   EFI_USBFN_IO_START_CONTROLLER             StartController;
 682   EFI_USBFN_IO_STOP_CONTROLLER              StopController;
 683   EFI_USBFN_IO_SET_ENDPOINT_POLICY          SetEndpointPolicy;
 684   EFI_USBFN_IO_GET_ENDPOINT_POLICY          GetEndpointPolicy;
 685 };
 686
 687 extern EFI_GUID gEfiUsbFunctionIoProtocolGuid;
 688
 689 #endif
 690