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 - 2017, 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 One or more of the following conditions is TRUE:
 277                                 BufferSize is NULL.
 278                                 *BufferSize is not 0 and Buffer is NULL.
 279                                 Id in invalid.
 280   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 281   @retval EFI_BUFFER_TOO_SMALL  The buffer is too small to hold the buffer.
 282                                 *BufferSize has been updated with the size needed to hold the request string.
 283
 284 **/
 285 typedef
 286 EFI_STATUS
 287 (EFIAPI *EFI_USBFN_IO_GET_DEVICE_INFO) (
 288   IN     EFI_USBFN_IO_PROTOCOL         *This,
 289   IN     EFI_USBFN_DEVICE_INFO_ID      Id,
 290   IN OUT UINTN                         *BufferSize,
 291      OUT VOID                          *Buffer OPTIONAL
 292 );
 293
 294 /**
 295   Returns the vendor-id and product-id of the device.
 296
 297   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 298   @param[out] Vid               Returned vendor-id of the device.
 299   @param[out] Pid               Returned product-id of the device.
 300
 301   @retval EFI_SUCCESS           The function returned successfully.
 302   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 303   @retval EFI_NOT_FOUND         Unable to return the vendor-id or the product-id.
 304
 305 **/
 306 typedef
 307 EFI_STATUS
 308 (EFIAPI *EFI_USBFN_IO_GET_VENDOR_ID_PRODUCT_ID) (
 309   IN     EFI_USBFN_IO_PROTOCOL         *This,
 310      OUT UINT16                        *Vid,
 311      OUT UINT16                        *Pid
 312 );
 313
 314 /**
 315   Aborts the transfer on the specified endpoint.
 316
 317   This function should fail with EFI_INVALID_PARAMETER if the specified direction
 318   is incorrect for the endpoint.
 319
 320   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 321   @param[in]  EndpointIndex     Indicates the endpoint on which the ongoing transfer
 322                                 needs to be canceled.
 323   @param[in]  Direction         Direction of the endpoint.
 324
 325   @retval EFI_SUCCESS           The function returned successfully.
 326   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 327   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 328   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 329                                 this request.
 330
 331 **/
 332 typedef
 333 EFI_STATUS
 334 (EFIAPI *EFI_USBFN_IO_ABORT_TRANSFER) (
 335   IN  EFI_USBFN_IO_PROTOCOL            *This,
 336   IN  UINT8                            EndpointIndex,
 337   IN  EFI_USBFN_ENDPOINT_DIRECTION     Direction
 338 );
 339
 340 /**
 341   Returns the stall state on the specified endpoint.
 342
 343   This function should fail with EFI_INVALID_PARAMETER if the specified direction
 344   is incorrect for the endpoint.
 345
 346   @param[in]      This          A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 347   @param[in]      EndpointIndex Indicates the endpoint.
 348   @param[in]      Direction     Direction of the endpoint.
 349   @param[in, out] State         Boolean, true value indicates that the endpoint
 350                                 is in a stalled state, false otherwise.
 351
 352   @retval EFI_SUCCESS           The function returned successfully.
 353   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 354   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 355   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 356                                 this request.
 357
 358 **/
 359 typedef
 360 EFI_STATUS
 361 (EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_STALL_STATE) (
 362   IN     EFI_USBFN_IO_PROTOCOL         *This,
 363   IN     UINT8                         EndpointIndex,
 364   IN     EFI_USBFN_ENDPOINT_DIRECTION  Direction,
 365   IN OUT BOOLEAN                       *State
 366 );
 367
 368 /**
 369   Sets or clears the stall state on the specified endpoint.
 370
 371   This function should fail with EFI_INVALID_PARAMETER if the specified direction
 372   is incorrect for the endpoint.
 373
 374   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 375   @param[in]  EndpointIndex     Indicates the endpoint.
 376   @param[in]  Direction         Direction of the endpoint.
 377   @param[in]  State             Requested stall state on the specified endpoint.
 378                                 True value causes the endpoint to stall; false
 379                                 value clears an existing stall.
 380
 381   @retval EFI_SUCCESS           The function returned successfully.
 382   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 383   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 384   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 385                                 this request.
 386
 387 **/
 388 typedef
 389 EFI_STATUS
 390 (EFIAPI *EFI_USBFN_IO_SET_ENDPOINT_STALL_STATE) (
 391   IN     EFI_USBFN_IO_PROTOCOL         *This,
 392   IN     UINT8                         EndpointIndex,
 393   IN     EFI_USBFN_ENDPOINT_DIRECTION  Direction,
 394   IN OUT BOOLEAN                       *State
 395 );
 396
 397 /**
 398   This function is called repeatedly to get information on USB bus states,
 399   receive-completion and transmit-completion events on the endpoints, and
 400   notification on setup packet on endpoint 0.
 401
 402   A class driver must call EFI_USBFN_IO_PROTOCOL.EventHandler()repeatedly
 403   to receive updates on the transfer status and number of bytes transferred
 404   on various endpoints.
 405
 406   @param[in]      This          A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 407   @param[out]     Message       Indicates the event that initiated this notification.
 408   @param[in, out] PayloadSize   On input, the size of the memory pointed by
 409                                 Payload. On output, the amount ofdata returned
 410                                 in Payload.
 411   @param[out]     Payload       A pointer to EFI_USBFN_MESSAGE_PAYLOAD instance
 412                                 to return additional payload for current message.
 413
 414   @retval EFI_SUCCESS           The function returned successfully.
 415   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 416   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 417   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 418                                 this request.
 419   @retval EFI_BUFFER_TOO_SMALL  The Supplied buffer is not large enough to hold
 420                                 the message payload.
 421
 422 **/
 423 typedef
 424 EFI_STATUS
 425 (EFIAPI *EFI_USBFN_IO_EVENTHANDLER) (
 426   IN     EFI_USBFN_IO_PROTOCOL         *This,
 427      OUT EFI_USBFN_MESSAGE             *Message,
 428   IN OUT UINTN                         *PayloadSize,
 429      OUT EFI_USBFN_MESSAGE_PAYLOAD     *Payload
 430 );
 431
 432 /**
 433   This function handles transferring data to or from the host on the specified
 434   endpoint, depending on the direction specified.
 435
 436   A class driver must call EFI_USBFN_IO_PROTOCOL.EventHandler() repeatedly to
 437   receive updates on the transfer status and the number of bytes transferred on
 438   various endpoints. Upon an update of the transfer status, the Buffer field of
 439   the EFI_USBFN_TRANSFER_RESULT structure (as described in the function description
 440   for EFI_USBFN_IO_PROTOCOL.EventHandler()) must be initialized with the Buffer
 441   pointer that was supplied to this method.
 442
 443   The overview of the call sequence is illustrated in the Figure 54.
 444
 445   This function should fail with EFI_INVALID_PARAMETER if the specified direction
 446   is incorrect for the endpoint.
 447
 448   @param[in]      This          A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 449   @param[in]      EndpointIndex Indicates the endpoint on which TX or RX transfer
 450                                 needs to take place.
 451   @param[in]      Direction     Direction of the endpoint.
 452   @param[in, out] BufferSize    If Direction is EfiUsbEndpointDirectionDeviceRx:
 453                                   On input, the size of the Bufferin bytes.
 454                                   On output, the amount of data returned in Buffer
 455                                   in bytes.
 456                                 If Direction is EfiUsbEndpointDirectionDeviceTx:
 457                                   On input, the size of the Bufferin bytes.
 458                                   On output, the amount of data transmitted in bytes.
 459   @param[in, out] Buffer        If Direction is EfiUsbEndpointDirectionDeviceRx:
 460                                   The Buffer to return the received data.
 461                                 If Directionis EfiUsbEndpointDirectionDeviceTx:
 462                                   The Buffer that contains the data to be transmitted.
 463
 464   @retval EFI_SUCCESS           The function returned successfully.
 465   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 466   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 467   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 468                                 this request.
 469
 470 **/
 471 typedef
 472 EFI_STATUS
 473 (EFIAPI *EFI_USBFN_IO_TRANSFER) (
 474   IN     EFI_USBFN_IO_PROTOCOL         *This,
 475   IN     UINT8                         EndpointIndex,
 476   IN     EFI_USBFN_ENDPOINT_DIRECTION  Direction,
 477   IN OUT UINTN                         *BufferSize,
 478   IN OUT VOID                          *Buffer
 479 );
 480
 481 /**
 482   Returns the maximum supported transfer size.
 483
 484   Returns the maximum number of bytes that the underlying controller can accommodate
 485   in a single transfer.
 486
 487   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 488   @param[out] MaxTransferSize   The maximum supported transfer size, in bytes.
 489
 490   @retval EFI_SUCCESS           The function returned successfully.
 491   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 492   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 493   @retval EFI_NOT_READY         The physical device is busy or not ready to process
 494                                 this request.
 495
 496 **/
 497 typedef
 498 EFI_STATUS
 499 (EFIAPI *EFI_USBFN_IO_GET_MAXTRANSFER_SIZE) (
 500   IN     EFI_USBFN_IO_PROTOCOL         *This,
 501      OUT UINTN                         *MaxTransferSize
 502   );
 503
 504 /**
 505   Allocates a transfer buffer of the specified sizethat satisfies the controller
 506   requirements.
 507
 508   The AllocateTransferBuffer() function allocates a memory region of Size bytes and
 509   returns the address of the allocated memory that satisfies the underlying controller
 510   requirements in the location referenced by Buffer.
 511
 512   The allocated transfer buffer must be freed using a matching call to
 513   EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer()function.
 514
 515   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 516   @param[in]  Size              The number of bytes to allocate for the transfer buffer.
 517   @param[out] Buffer            A pointer to a pointer to the allocated buffer if the
 518                                 call succeeds; undefined otherwise.
 519
 520   @retval EFI_SUCCESS           The function returned successfully.
 521   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 522   @retval EFI_OUT_OF_RESOURCES  The requested transfer buffer could not be allocated.
 523
 524 **/
 525 typedef
 526 EFI_STATUS
 527 (EFIAPI *EFI_USBFN_IO_ALLOCATE_TRANSFER_BUFFER) (
 528   IN     EFI_USBFN_IO_PROTOCOL         *This,
 529   IN     UINTN                         Size,
 530      OUT VOID                          **Buffer
 531   );
 532
 533 /**
 534   Deallocates the memory allocated for the transfer buffer by the
 535   EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer() function.
 536
 537   The EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer() function deallocates the
 538   memory specified by Buffer. The Buffer that is freed must have been allocated
 539   by EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer().
 540
 541   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 542   @param[in]  Buffer            A pointer to the transfer buffer to deallocate.
 543
 544   @retval EFI_SUCCESS           The function returned successfully.
 545   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 546
 547 **/
 548 typedef
 549 EFI_STATUS
 550 (EFIAPI *EFI_USBFN_IO_FREE_TRANSFER_BUFFER) (
 551   IN  EFI_USBFN_IO_PROTOCOL         *This,
 552   IN  VOID                          *Buffer
 553   );
 554
 555 /**
 556   This function supplies power to the USB controller if needed and initializes
 557   the hardware and the internal data structures. The port must not be activated
 558   by this function.
 559
 560   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 561
 562   @retval EFI_SUCCESS           The function returned successfully.
 563   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 564   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 565
 566 **/
 567 typedef
 568 EFI_STATUS
 569 (EFIAPI *EFI_USBFN_IO_START_CONTROLLER) (
 570   IN  EFI_USBFN_IO_PROTOCOL         *This
 571   );
 572
 573 /**
 574   This function stops the USB hardware device.
 575
 576   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 577
 578   @retval EFI_SUCCESS           The function returned successfully.
 579   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 580   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 581
 582 **/
 583 typedef
 584 EFI_STATUS
 585 (EFIAPI *EFI_USBFN_IO_STOP_CONTROLLER) (
 586   IN  EFI_USBFN_IO_PROTOCOL         *This
 587   );
 588
 589 /**
 590   This function sets the configuration policy for the specified non-control
 591   endpoint.
 592
 593   This function can only be called before EFI_USBFN_IO_PROTOCOL.StartController()
 594   or after EFI_USBFN_IO_PROTOCOL.StopController() has been called.
 595
 596   @param[in]  This              A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 597   @param[in]  EndpointIndex     Indicates the non-control endpoint for which the
 598                                 policy needs to be set.
 599   @param[in]  Direction         Direction of the endpoint.
 600   @param[in]  PolicyType        Policy type the user is trying to set for the
 601                                 specified non-control endpoint.
 602   @param[in]  BufferSize        The size of the Bufferin bytes.
 603   @param[in]  Buffer            The new value for the policy parameter that
 604                                 PolicyType specifies.
 605
 606   @retval EFI_SUCCESS           The function returned successfully.
 607   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 608   @retval EFI_DEVICE_ERROR      The physical device reported an error.
 609   @retval EFI_UNSUPPORTED       Changing this policy value is not supported.
 610
 611 **/
 612 typedef
 613 EFI_STATUS
 614 (EFIAPI *EFI_USBFN_IO_SET_ENDPOINT_POLICY) (
 615   IN  EFI_USBFN_IO_PROTOCOL         *This,
 616   IN  UINT8                         EndpointIndex,
 617   IN  EFI_USBFN_ENDPOINT_DIRECTION  Direction,
 618   IN  EFI_USBFN_POLICY_TYPE         PolicyType,
 619   IN  UINTN                         BufferSize,
 620   IN  VOID                          *Buffer
 621   );
 622
 623 /**
 624   This function sets the configuration policy for the specified non-control
 625   endpoint.
 626
 627   This function can only be called before EFI_USBFN_IO_PROTOCOL.StartController()
 628   or after EFI_USBFN_IO_PROTOCOL.StopController() has been called.
 629
 630   @param[in]      This          A pointer to the EFI_USBFN_IO_PROTOCOL instance.
 631   @param[in]      EndpointIndex Indicates the non-control endpoint for which the
 632                                 policy needs to be set.
 633   @param[in]      Direction     Direction of the endpoint.
 634   @param[in]      PolicyType    Policy type the user is trying to retrieve for
 635                                 the specified non-control endpoint.
 636   @param[in, out] BufferSize    On input, the size of Bufferin bytes. On output,
 637                                 the amount of data returned in Bufferin bytes.
 638   @param[in, out] Buffer        A pointer to a buffer to return requested endpoint
 639                                 policy value.
 640
 641   @retval EFI_SUCCESS           The function returned successfully.
 642   @retval EFI_INVALID_PARAMETER A parameter is invalid.
 643   @retval EFI_DEVICE_ERROR      The specified policy value is not supported.
 644   @retval EFI_BUFFER_TOO_SMALL  Supplied buffer is not large enough to hold requested
 645                                 policy value.
 646
 647 **/
 648 typedef
 649 EFI_STATUS
 650 (EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_POLICY) (
 651   IN     EFI_USBFN_IO_PROTOCOL         *This,
 652   IN     UINT8                         EndpointIndex,
 653   IN     EFI_USBFN_ENDPOINT_DIRECTION  Direction,
 654   IN     EFI_USBFN_POLICY_TYPE         PolicyType,
 655   IN OUT UINTN                         *BufferSize,
 656   IN OUT VOID                          *Buffer
 657   );
 658
 659 ///
 660 /// The EFI_USBFN_IO_PROTOCOL provides basic data transactions and basic USB
 661 /// controller management for a USB Function port.
 662 ///
 663 struct _EFI_USBFN_IO_PROTOCOL {
 664   UINT32                                    Revision;
 665   EFI_USBFN_IO_DETECT_PORT                  DetectPort;
 666   EFI_USBFN_IO_CONFIGURE_ENABLE_ENDPOINTS   ConfigureEnableEndpoints;
 667   EFI_USBFN_IO_GET_ENDPOINT_MAXPACKET_SIZE  GetEndpointMaxPacketSize;
 668   EFI_USBFN_IO_GET_DEVICE_INFO              GetDeviceInfo;
 669   EFI_USBFN_IO_GET_VENDOR_ID_PRODUCT_ID     GetVendorIdProductId;
 670   EFI_USBFN_IO_ABORT_TRANSFER               AbortTransfer;
 671   EFI_USBFN_IO_GET_ENDPOINT_STALL_STATE     GetEndpointStallState;
 672   EFI_USBFN_IO_SET_ENDPOINT_STALL_STATE     SetEndpointStallState;
 673   EFI_USBFN_IO_EVENTHANDLER                 EventHandler;
 674   EFI_USBFN_IO_TRANSFER                     Transfer;
 675   EFI_USBFN_IO_GET_MAXTRANSFER_SIZE         GetMaxTransferSize;
 676   EFI_USBFN_IO_ALLOCATE_TRANSFER_BUFFER     AllocateTransferBuffer;
 677   EFI_USBFN_IO_FREE_TRANSFER_BUFFER         FreeTransferBuffer;
 678   EFI_USBFN_IO_START_CONTROLLER             StartController;
 679   EFI_USBFN_IO_STOP_CONTROLLER              StopController;
 680   EFI_USBFN_IO_SET_ENDPOINT_POLICY          SetEndpointPolicy;
 681   EFI_USBFN_IO_GET_ENDPOINT_POLICY          GetEndpointPolicy;
 682 };
 683
 684 extern EFI_GUID gEfiUsbFunctionIoProtocolGuid;
 685
 686 #endif
 687