MdeModulePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdeModulePkg / Bus / Pci / EhciDxe / EhciUrb.h

/** @file\r
\r
    This file contains URB request, each request is warpped in a\r
    URB (Usb Request Block).\r
\r
Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _EFI_EHCI_URB_H_\r
#define _EFI_EHCI_URB_H_\r
\r
\r
typedef struct _EHC_QTD  EHC_QTD;\r
typedef struct _EHC_QH   EHC_QH;\r
typedef struct _URB      URB;\r
\r
//\r
// Transfer types, used in URB to identify the transfer type\r
//\r
#define EHC_CTRL_TRANSFER       0x01\r
#define EHC_BULK_TRANSFER       0x02\r
#define EHC_INT_TRANSFER_SYNC   0x04\r
#define EHC_INT_TRANSFER_ASYNC  0x08\r
\r
#define EHC_QTD_SIG             SIGNATURE_32 ('U', 'S', 'B', 'T')\r
#define EHC_QH_SIG              SIGNATURE_32 ('U', 'S', 'B', 'H')\r
#define EHC_URB_SIG             SIGNATURE_32 ('U', 'S', 'B', 'R')\r
\r
//\r
// Hardware related bit definitions\r
//\r
#define EHC_TYPE_ITD            0x00\r
#define EHC_TYPE_QH             0x02\r
#define EHC_TYPE_SITD           0x04\r
#define EHC_TYPE_FSTN           0x06\r
\r
#define QH_NAK_RELOAD           3\r
#define QH_HSHBW_MULTI          1\r
\r
#define QTD_MAX_ERR             3\r
#define QTD_PID_OUTPUT          0x00\r
#define QTD_PID_INPUT           0x01\r
#define QTD_PID_SETUP           0x02\r
\r
#define QTD_STAT_DO_OUT         0\r
#define QTD_STAT_DO_SS          0\r
#define QTD_STAT_DO_PING        0x01\r
#define QTD_STAT_DO_CS          0x02\r
#define QTD_STAT_TRANS_ERR      0x08\r
#define QTD_STAT_BABBLE_ERR     0x10\r
#define QTD_STAT_BUFF_ERR       0x20\r
#define QTD_STAT_HALTED         0x40\r
#define QTD_STAT_ACTIVE         0x80\r
#define QTD_STAT_ERR_MASK       (QTD_STAT_TRANS_ERR | QTD_STAT_BABBLE_ERR | QTD_STAT_BUFF_ERR)\r
\r
#define QTD_MAX_BUFFER          4\r
#define QTD_BUF_LEN             4096\r
#define QTD_BUF_MASK            0x0FFF\r
\r
#define QH_MICROFRAME_0         0x01\r
#define QH_MICROFRAME_1         0x02\r
#define QH_MICROFRAME_2         0x04\r
#define QH_MICROFRAME_3         0x08\r
#define QH_MICROFRAME_4         0x10\r
#define QH_MICROFRAME_5         0x20\r
#define QH_MICROFRAME_6         0x40\r
#define QH_MICROFRAME_7         0x80\r
\r
#define USB_ERR_SHORT_PACKET    0x200\r
\r
//\r
// Fill in the hardware link point: pass in a EHC_QH/QH_HW\r
// pointer to QH_LINK; A EHC_QTD/QTD_HW pointer to QTD_LINK\r
//\r
#define QH_LINK(Addr, Type, Term) \\r
          ((UINT32) ((EHC_LOW_32BIT (Addr) & 0xFFFFFFE0) | (Type) | ((Term) ? 1 : 0)))\r
\r
#define QTD_LINK(Addr, Term)      QH_LINK((Addr), 0, (Term))\r
\r
//\r
// The defination of EHCI hardware used data structure for\r
// little endian architecture. The QTD and QH structures\r
// are required to be 32 bytes aligned. Don't add members\r
// to the head of the associated software strucuture.\r
//\r
#pragma pack(1)\r
typedef struct {\r
  UINT32                  NextQtd;\r
  UINT32                  AltNext;\r
\r
  UINT32                  Status       : 8;\r
  UINT32                  Pid          : 2;\r
  UINT32                  ErrCnt       : 2;\r
  UINT32                  CurPage      : 3;\r
  UINT32                  Ioc          : 1;\r
  UINT32                  TotalBytes   : 15;\r
  UINT32                  DataToggle   : 1;\r
\r
  UINT32                  Page[5];\r
  UINT32                  PageHigh[5];\r
} QTD_HW;\r
\r
typedef struct {\r
  UINT32                  HorizonLink;\r
  //\r
  // Endpoint capabilities/Characteristics DWord 1 and DWord 2\r
  //\r
  UINT32                  DeviceAddr   : 7;\r
  UINT32                  Inactive     : 1;\r
  UINT32                  EpNum        : 4;\r
  UINT32                  EpSpeed      : 2;\r
  UINT32                  DtCtrl       : 1;\r
  UINT32                  ReclaimHead  : 1;\r
  UINT32                  MaxPacketLen : 11;\r
  UINT32                  CtrlEp       : 1;\r
  UINT32                  NakReload    : 4;\r
\r
  UINT32                  SMask        : 8;\r
  UINT32                  CMask        : 8;\r
  UINT32                  HubAddr      : 7;\r
  UINT32                  PortNum      : 7;\r
  UINT32                  Multiplier   : 2;\r
\r
  //\r
  // Transaction execution overlay area\r
  //\r
  UINT32                  CurQtd;\r
  UINT32                  NextQtd;\r
  UINT32                  AltQtd;\r
\r
  UINT32                  Status       : 8;\r
  UINT32                  Pid          : 2;\r
  UINT32                  ErrCnt       : 2;\r
  UINT32                  CurPage      : 3;\r
  UINT32                  Ioc          : 1;\r
  UINT32                  TotalBytes   : 15;\r
  UINT32                  DataToggle   : 1;\r
\r
  UINT32                  Page[5];\r
  UINT32                  PageHigh[5];\r
} QH_HW;\r
#pragma pack()\r
\r
\r
//\r
// Endpoint address and its capabilities\r
//\r
typedef struct _USB_ENDPOINT {\r
  UINT8                   DevAddr;\r
  UINT8                   EpAddr;     // Endpoint address, no direction encoded in\r
  EFI_USB_DATA_DIRECTION  Direction;\r
  UINT8                   DevSpeed;\r
  UINTN                   MaxPacket;\r
  UINT8                   HubAddr;\r
  UINT8                   HubPort;\r
  UINT8                   Toggle;     // Data toggle, not used for control transfer\r
  UINTN                   Type;\r
  UINTN                   PollRate;   // Polling interval used by EHCI\r
} USB_ENDPOINT;\r
\r
//\r
// Software QTD strcture, this is used to manage all the\r
// QTD generated from a URB. Don't add fields before QtdHw.\r
//\r
struct _EHC_QTD {\r
  QTD_HW                  QtdHw;\r
  UINT32                  Signature;\r
  LIST_ENTRY              QtdList;   // The list of QTDs to one end point\r
  UINT8                   *Data;     // Buffer of the original data\r
  UINTN                   DataLen;   // Original amount of data in this QTD\r
};\r
\r
//\r
// Software QH structure. All three different transaction types\r
// supported by UEFI USB, that is the control/bulk/interrupt\r
// transfers use the queue head and queue token strcuture.\r
//\r
// Interrupt QHs are linked to periodic frame list in the reversed\r
// 2^N tree. Each interrupt QH is linked to the list starting at\r
// frame 0. There is a dummy interrupt QH linked to each frame as\r
// a sentinental whose polling interval is 1. Synchronous interrupt\r
// transfer is linked after this dummy QH.\r
//\r
// For control/bulk transfer, only synchronous (in the sense of UEFI)\r
// transfer is supported. A dummy QH is linked to EHCI AsyncListAddr\r
// as the reclamation header. New transfer is inserted after this QH.\r
//\r
struct _EHC_QH {\r
  QH_HW                   QhHw;\r
  UINT32                  Signature;\r
  EHC_QH                  *NextQh;    // The queue head pointed to by horizontal link\r
  LIST_ENTRY              Qtds;       // The list of QTDs to this queue head\r
  UINTN                   Interval;\r
};\r
\r
//\r
// URB (Usb Request Block) contains information for all kinds of\r
// usb requests.\r
//\r
struct _URB {\r
  UINT32                          Signature;\r
  LIST_ENTRY                      UrbList;\r
\r
  //\r
  // Transaction information\r
  //\r
  USB_ENDPOINT                    Ep;\r
  EFI_USB_DEVICE_REQUEST          *Request;     // Control transfer only\r
  VOID                            *RequestPhy;  // Address of the mapped request\r
  VOID                            *RequestMap;\r
  VOID                            *Data;\r
  UINTN                           DataLen;\r
  VOID                            *DataPhy;     // Address of the mapped user data\r
  VOID                            *DataMap;\r
  EFI_ASYNC_USB_TRANSFER_CALLBACK Callback;\r
  VOID                            *Context;\r
\r
  //\r
  // Schedule data\r
  //\r
  EHC_QH                          *Qh;\r
\r
  //\r
  // Transaction result\r
  //\r
  UINT32                          Result;\r
  UINTN                           Completed;    // completed data length\r
  UINT8                           DataToggle;\r
};\r
\r
\r
\r
/**\r
  Create a single QTD to hold the data.\r
\r
  @param  Ehc        The EHCI device.\r
  @param  Data       The cpu memory address of current data not associated with a QTD.\r
  @param  DataPhy    The pci bus address of current data not associated with a QTD.\r
  @param  DataLen    The length of the data.\r
  @param  PktId      Packet ID to use in the QTD.\r
  @param  Toggle     Data toggle to use in the QTD.\r
  @param  MaxPacket  Maximu packet length of the endpoint.\r
\r
  @return Created QTD or NULL if failed to create one.\r
\r
**/\r
EHC_QTD *\r
EhcCreateQtd (\r
  IN USB2_HC_DEV          *Ehc,\r
  IN UINT8                *Data,\r
  IN UINT8                *DataPhy,\r
  IN UINTN                DataLen,\r
  IN UINT8                PktId,\r
  IN UINT8                Toggle,\r
  IN UINTN                MaxPacket\r
  );\r
\r
\r
\r
/**\r
  Allocate and initialize a EHCI queue head.\r
\r
  @param  Ehci       The EHCI device.\r
  @param  Ep         The endpoint to create queue head for.\r
\r
  @return Created queue head or NULL if failed to create one.\r
\r
**/\r
EHC_QH *\r
EhcCreateQh (\r
  IN USB2_HC_DEV          *Ehci,\r
  IN USB_ENDPOINT         *Ep\r
  );\r
\r
\r
/**\r
  Free an allocated URB. It is possible for it to be partially inited.\r
\r
  @param  Ehc        The EHCI device.\r
  @param  Urb        The URB to free.\r
\r
**/\r
VOID\r
EhcFreeUrb (\r
  IN USB2_HC_DEV          *Ehc,\r
  IN URB                  *Urb\r
  );\r
\r
\r
/**\r
  Create a new URB and its associated QTD.\r
\r
  @param  Ehc        The EHCI device.\r
  @param  DevAddr    The device address.\r
  @param  EpAddr     Endpoint addrress & its direction.\r
  @param  DevSpeed   The device speed.\r
  @param  Toggle     Initial data toggle to use.\r
  @param  MaxPacket  The max packet length of the endpoint.\r
  @param  Hub        The transaction translator to use.\r
  @param  Type       The transaction type.\r
  @param  Request    The standard USB request for control transfer.\r
  @param  Data       The user data to transfer.\r
  @param  DataLen    The length of data buffer.\r
  @param  Callback   The function to call when data is transferred.\r
  @param  Context    The context to the callback.\r
  @param  Interval   The interval for interrupt transfer.\r
\r
  @return Created URB or NULL.\r
\r
**/\r
URB *\r
EhcCreateUrb (\r
  IN USB2_HC_DEV                        *Ehc,\r
  IN UINT8                              DevAddr,\r
  IN UINT8                              EpAddr,\r
  IN UINT8                              DevSpeed,\r
  IN UINT8                              Toggle,\r
  IN UINTN                              MaxPacket,\r
  IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Hub,\r
  IN UINTN                              Type,\r
  IN EFI_USB_DEVICE_REQUEST             *Request,\r
  IN VOID                               *Data,\r
  IN UINTN                              DataLen,\r
  IN EFI_ASYNC_USB_TRANSFER_CALLBACK    Callback,\r
  IN VOID                               *Context,\r
  IN UINTN                              Interval\r
  );\r
#endif\r