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