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