MdeModulePkg: Replace BSD License with BSD+Patent License

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

/** @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
#include "Ehci.h"\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
  EHC_QTD                 *Qtd;\r
  QTD_HW                  *QtdHw;\r
  UINTN                   Index;\r
  UINTN                   Len;\r
  UINTN                   ThisBufLen;\r
\r
  ASSERT (Ehc != NULL);\r
\r
  Qtd = UsbHcAllocateMem (Ehc->MemPool, sizeof (EHC_QTD));\r
\r
  if (Qtd == NULL) {\r
    return NULL;\r
  }\r
\r
  Qtd->Signature    = EHC_QTD_SIG;\r
  Qtd->Data         = Data;\r
  Qtd->DataLen      = 0;\r
\r
  InitializeListHead (&Qtd->QtdList);\r
\r
  QtdHw             = &Qtd->QtdHw;\r
  QtdHw->NextQtd    = QTD_LINK (NULL, TRUE);\r
  QtdHw->AltNext    = QTD_LINK (NULL, TRUE);\r
  QtdHw->Status     = QTD_STAT_ACTIVE;\r
  QtdHw->Pid        = PktId;\r
  QtdHw->ErrCnt     = QTD_MAX_ERR;\r
  QtdHw->Ioc        = 0;\r
  QtdHw->TotalBytes = 0;\r
  QtdHw->DataToggle = Toggle;\r
\r
  //\r
  // Fill in the buffer points\r
  //\r
  if (Data != NULL) {\r
    Len = 0;\r
\r
    for (Index = 0; Index <= QTD_MAX_BUFFER; Index++) {\r
      //\r
      // Set the buffer point (Check page 41 EHCI Spec 1.0). No need to\r
      // compute the offset and clear Reserved fields. This is already\r
      // done in the data point.\r
      //\r
      QtdHw->Page[Index]      = EHC_LOW_32BIT (DataPhy);\r
      QtdHw->PageHigh[Index]  = EHC_HIGH_32BIT (DataPhy);\r
\r
      ThisBufLen              = QTD_BUF_LEN - (EHC_LOW_32BIT (DataPhy) & QTD_BUF_MASK);\r
\r
      if (Len + ThisBufLen >= DataLen) {\r
        Len = DataLen;\r
        break;\r
      }\r
\r
      Len += ThisBufLen;\r
      Data += ThisBufLen;\r
      DataPhy += ThisBufLen;\r
    }\r
\r
    //\r
    // Need to fix the last pointer if the Qtd can't hold all the\r
    // user's data to make sure that the length is in the unit of\r
    // max packets. If it can hold all the data, there is no such\r
    // need.\r
    //\r
    if (Len < DataLen) {\r
      Len = Len - Len % MaxPacket;\r
    }\r
\r
    QtdHw->TotalBytes = (UINT32) Len;\r
    Qtd->DataLen      = Len;\r
  }\r
\r
  return Qtd;\r
}\r
\r
\r
\r
/**\r
  Initialize the queue head for interrupt transfer,\r
  that is, initialize the following three fields:\r
  1. SplitXState in the Status field\r
  2. Microframe S-mask\r
  3. Microframe C-mask\r
\r
  @param  Ep                    The queue head's related endpoint.\r
  @param  QhHw                  The queue head to initialize.\r
\r
**/\r
VOID\r
EhcInitIntQh (\r
  IN USB_ENDPOINT         *Ep,\r
  IN QH_HW                *QhHw\r
  )\r
{\r
  //\r
  // Because UEFI interface can't utilitize an endpoint with\r
  // poll rate faster than 1ms, only need to set one bit in\r
  // the queue head. simple. But it may be changed later. If\r
  // sub-1ms interrupt is supported, need to update the S-Mask\r
  // here\r
  //\r
  if (Ep->DevSpeed == EFI_USB_SPEED_HIGH) {\r
    QhHw->SMask = QH_MICROFRAME_0;\r
    return ;\r
  }\r
\r
  //\r
  // For low/full speed device, the transfer must go through\r
  // the split transaction. Need to update three fields\r
  // 1. SplitXState in the status\r
  // 2. Microframe S-Mask\r
  // 3. Microframe C-Mask\r
  // UEFI USB doesn't exercise admission control. It simplely\r
  // schedule the high speed transactions in microframe 0, and\r
  // full/low speed transactions at microframe 1. This also\r
  // avoid the use of FSTN.\r
  //\r
  QhHw->SMask = QH_MICROFRAME_1;\r
  QhHw->CMask = QH_MICROFRAME_3 | QH_MICROFRAME_4 | QH_MICROFRAME_5;\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
  EHC_QH                  *Qh;\r
  QH_HW                   *QhHw;\r
\r
  Qh = UsbHcAllocateMem (Ehci->MemPool, sizeof (EHC_QH));\r
\r
  if (Qh == NULL) {\r
    return NULL;\r
  }\r
\r
  Qh->Signature       = EHC_QH_SIG;\r
  Qh->NextQh          = NULL;\r
  Qh->Interval        = Ep->PollRate;\r
\r
  InitializeListHead (&Qh->Qtds);\r
\r
  QhHw                = &Qh->QhHw;\r
  QhHw->HorizonLink   = QH_LINK (NULL, 0, TRUE);\r
  QhHw->DeviceAddr    = Ep->DevAddr;\r
  QhHw->Inactive      = 0;\r
  QhHw->EpNum         = Ep->EpAddr;\r
  QhHw->EpSpeed       = Ep->DevSpeed;\r
  QhHw->DtCtrl        = 0;\r
  QhHw->ReclaimHead   = 0;\r
  QhHw->MaxPacketLen  = (UINT32) Ep->MaxPacket;\r
  QhHw->CtrlEp        = 0;\r
  QhHw->NakReload     = QH_NAK_RELOAD;\r
  QhHw->HubAddr       = Ep->HubAddr;\r
  QhHw->PortNum       = Ep->HubPort;\r
  QhHw->Multiplier    = 1;\r
  QhHw->DataToggle    = Ep->Toggle;\r
\r
  if (Ep->DevSpeed != EFI_USB_SPEED_HIGH) {\r
    QhHw->Status |= QTD_STAT_DO_SS;\r
  }\r
\r
  switch (Ep->Type) {\r
  case EHC_CTRL_TRANSFER:\r
    //\r
    // Special initialization for the control transfer:\r
    // 1. Control transfer initialize data toggle from each QTD\r
    // 2. Set the Control Endpoint Flag (C) for low/full speed endpoint.\r
    //\r
    QhHw->DtCtrl = 1;\r
\r
    if (Ep->DevSpeed != EFI_USB_SPEED_HIGH) {\r
      QhHw->CtrlEp = 1;\r
    }\r
    break;\r
\r
  case EHC_INT_TRANSFER_ASYNC:\r
  case EHC_INT_TRANSFER_SYNC:\r
    //\r
    // Special initialization for the interrupt transfer\r
    // to set the S-Mask and C-Mask\r
    //\r
    QhHw->NakReload = 0;\r
    EhcInitIntQh (Ep, QhHw);\r
    break;\r
\r
  case EHC_BULK_TRANSFER:\r
    if ((Ep->DevSpeed == EFI_USB_SPEED_HIGH) && (Ep->Direction == EfiUsbDataOut)) {\r
      QhHw->Status |= QTD_STAT_DO_PING;\r
    }\r
\r
    break;\r
  }\r
\r
  return Qh;\r
}\r
\r
\r
/**\r
  Convert the poll interval from application to that\r
  be used by EHCI interface data structure. Only need\r
  to get the max 2^n that is less than interval. UEFI\r
  can't support high speed endpoint with a interval less\r
  than 8 microframe because interval is specified in\r
  the unit of ms (millisecond).\r
\r
  @param  Interval              The interval to convert.\r
\r
  @return The converted interval.\r
\r
**/\r
UINTN\r
EhcConvertPollRate (\r
  IN  UINTN               Interval\r
  )\r
{\r
  UINTN                   BitCount;\r
\r
  if (Interval == 0) {\r
    return 1;\r
  }\r
\r
  //\r
  // Find the index (1 based) of the highest non-zero bit\r
  //\r
  BitCount = 0;\r
\r
  while (Interval != 0) {\r
    Interval >>= 1;\r
    BitCount++;\r
  }\r
\r
  return (UINTN)1 << (BitCount - 1);\r
}\r
\r
\r
/**\r
  Free a list of QTDs.\r
\r
  @param  Ehc                   The EHCI device.\r
  @param  Qtds                  The list head of the QTD.\r
\r
**/\r
VOID\r
EhcFreeQtds (\r
  IN USB2_HC_DEV          *Ehc,\r
  IN LIST_ENTRY           *Qtds\r
  )\r
{\r
  LIST_ENTRY              *Entry;\r
  LIST_ENTRY              *Next;\r
  EHC_QTD                 *Qtd;\r
\r
  EFI_LIST_FOR_EACH_SAFE (Entry, Next, Qtds) {\r
    Qtd = EFI_LIST_CONTAINER (Entry, EHC_QTD, QtdList);\r
\r
    RemoveEntryList (&Qtd->QtdList);\r
    UsbHcFreeMem (Ehc->MemPool, Qtd, sizeof (EHC_QTD));\r
  }\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
  EFI_PCI_IO_PROTOCOL       *PciIo;\r
\r
  PciIo = Ehc->PciIo;\r
\r
  if (Urb->RequestPhy != NULL) {\r
    PciIo->Unmap (PciIo, Urb->RequestMap);\r
  }\r
\r
  if (Urb->DataMap != NULL) {\r
    PciIo->Unmap (PciIo, Urb->DataMap);\r
  }\r
\r
  if (Urb->Qh != NULL) {\r
    //\r
    // Ensure that this queue head has been unlinked from the\r
    // schedule data structures. Free all the associated QTDs\r
    //\r
    EhcFreeQtds (Ehc, &Urb->Qh->Qtds);\r
    UsbHcFreeMem (Ehc->MemPool, Urb->Qh, sizeof (EHC_QH));\r
  }\r
\r
  gBS->FreePool (Urb);\r
}\r
\r
\r
/**\r
  Create a list of QTDs for the URB.\r
\r
  @param  Ehc                   The EHCI device.\r
  @param  Urb                   The URB to create QTDs for.\r
\r
  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for QTD.\r
  @retval EFI_SUCCESS           The QTDs are allocated for the URB.\r
\r
**/\r
EFI_STATUS\r
EhcCreateQtds (\r
  IN USB2_HC_DEV          *Ehc,\r
  IN URB                  *Urb\r
  )\r
{\r
  USB_ENDPOINT            *Ep;\r
  EHC_QH                  *Qh;\r
  EHC_QTD                 *Qtd;\r
  EHC_QTD                 *StatusQtd;\r
  EHC_QTD                 *NextQtd;\r
  LIST_ENTRY              *Entry;\r
  UINT32                  AlterNext;\r
  UINT8                   Toggle;\r
  UINTN                   Len;\r
  UINT8                   Pid;\r
  EFI_PHYSICAL_ADDRESS    PhyAddr;\r
\r
  ASSERT ((Urb != NULL) && (Urb->Qh != NULL));\r
\r
  //\r
  // EHCI follows the alternet next QTD pointer if it meets\r
  // a short read and the AlterNext pointer is valid. UEFI\r
  // EHCI driver should terminate the transfer except the\r
  // control transfer.\r
  //\r
  Toggle    = 0;\r
  Qh        = Urb->Qh;\r
  Ep        = &Urb->Ep;\r
  StatusQtd = NULL;\r
  AlterNext = QTD_LINK (NULL, TRUE);\r
\r
  PhyAddr   = UsbHcGetPciAddressForHostMem (Ehc->MemPool, Ehc->ShortReadStop, sizeof (EHC_QTD));\r
  if (Ep->Direction == EfiUsbDataIn) {\r
    AlterNext = QTD_LINK (PhyAddr, FALSE);\r
  }\r
\r
  //\r
  // Build the Setup and status packets for control transfer\r
  //\r
  if (Urb->Ep.Type == EHC_CTRL_TRANSFER) {\r
    Len = sizeof (EFI_USB_DEVICE_REQUEST);\r
    Qtd = EhcCreateQtd (Ehc, (UINT8 *)Urb->Request, (UINT8 *)Urb->RequestPhy, Len, QTD_PID_SETUP, 0, Ep->MaxPacket);\r
\r
    if (Qtd == NULL) {\r
      return EFI_OUT_OF_RESOURCES;\r
    }\r
\r
    InsertTailList (&Qh->Qtds, &Qtd->QtdList);\r
\r
    //\r
    // Create the status packet now. Set the AlterNext to it. So, when\r
    // EHCI meets a short control read, it can resume at the status stage.\r
    // Use the opposite direction of the data stage, or IN if there is\r
    // no data stage.\r
    //\r
    if (Ep->Direction == EfiUsbDataIn) {\r
      Pid = QTD_PID_OUTPUT;\r
    } else {\r
      Pid = QTD_PID_INPUT;\r
    }\r
\r
    StatusQtd = EhcCreateQtd (Ehc, NULL, NULL, 0, Pid, 1, Ep->MaxPacket);\r
\r
    if (StatusQtd == NULL) {\r
      goto ON_ERROR;\r
    }\r
\r
    if (Ep->Direction == EfiUsbDataIn) {\r
      PhyAddr   = UsbHcGetPciAddressForHostMem (Ehc->MemPool, StatusQtd, sizeof (EHC_QTD));\r
      AlterNext = QTD_LINK (PhyAddr, FALSE);\r
    }\r
\r
    Toggle = 1;\r
  }\r
\r
  //\r
  // Build the data packets for all the transfers\r
  //\r
  if (Ep->Direction == EfiUsbDataIn) {\r
    Pid = QTD_PID_INPUT;\r
  } else {\r
    Pid = QTD_PID_OUTPUT;\r
  }\r
\r
  Qtd = NULL;\r
  Len = 0;\r
\r
  while (Len < Urb->DataLen) {\r
    Qtd = EhcCreateQtd (\r
            Ehc,\r
            (UINT8 *) Urb->Data + Len,\r
            (UINT8 *) Urb->DataPhy + Len,\r
            Urb->DataLen - Len,\r
            Pid,\r
            Toggle,\r
            Ep->MaxPacket\r
            );\r
\r
    if (Qtd == NULL) {\r
      goto ON_ERROR;\r
    }\r
\r
    Qtd->QtdHw.AltNext = AlterNext;\r
    InsertTailList (&Qh->Qtds, &Qtd->QtdList);\r
\r
    //\r
    // Switch the Toggle bit if odd number of packets are included in the QTD.\r
    //\r
    if (((Qtd->DataLen + Ep->MaxPacket - 1) / Ep->MaxPacket) % 2) {\r
      Toggle = (UINT8) (1 - Toggle);\r
    }\r
\r
    Len += Qtd->DataLen;\r
  }\r
\r
  //\r
  // Insert the status packet for control transfer\r
  //\r
  if (Ep->Type == EHC_CTRL_TRANSFER) {\r
    InsertTailList (&Qh->Qtds, &StatusQtd->QtdList);\r
  }\r
\r
  //\r
  // OK, all the QTDs needed are created. Now, fix the NextQtd point\r
  //\r
  EFI_LIST_FOR_EACH (Entry, &Qh->Qtds) {\r
    Qtd = EFI_LIST_CONTAINER (Entry, EHC_QTD, QtdList);\r
\r
    //\r
    // break if it is the last entry on the list\r
    //\r
    if (Entry->ForwardLink == &Qh->Qtds) {\r
      break;\r
    }\r
\r
    NextQtd             = EFI_LIST_CONTAINER (Entry->ForwardLink, EHC_QTD, QtdList);\r
    PhyAddr             = UsbHcGetPciAddressForHostMem (Ehc->MemPool, NextQtd, sizeof (EHC_QTD));\r
    Qtd->QtdHw.NextQtd  = QTD_LINK (PhyAddr, FALSE);\r
  }\r
\r
  //\r
  // Link the QTDs to the queue head\r
  //\r
  NextQtd           = EFI_LIST_CONTAINER (Qh->Qtds.ForwardLink, EHC_QTD, QtdList);\r
  PhyAddr           = UsbHcGetPciAddressForHostMem (Ehc->MemPool, NextQtd, sizeof (EHC_QTD));\r
  Qh->QhHw.NextQtd  = QTD_LINK (PhyAddr, FALSE);\r
  return EFI_SUCCESS;\r
\r
ON_ERROR:\r
  EhcFreeQtds (Ehc, &Qh->Qtds);\r
  return EFI_OUT_OF_RESOURCES;\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
{\r
  USB_ENDPOINT                  *Ep;\r
  EFI_PHYSICAL_ADDRESS          PhyAddr;\r
  EFI_PCI_IO_PROTOCOL_OPERATION MapOp;\r
  EFI_PCI_IO_PROTOCOL           *PciIo;\r
  EFI_STATUS                    Status;\r
  UINTN                         Len;\r
  URB                           *Urb;\r
  VOID                          *Map;\r
\r
  Urb = AllocateZeroPool (sizeof (URB));\r
\r
  if (Urb == NULL) {\r
    return NULL;\r
  }\r
\r
  Urb->Signature  = EHC_URB_SIG;\r
  InitializeListHead (&Urb->UrbList);\r
\r
  Ep              = &Urb->Ep;\r
  Ep->DevAddr     = DevAddr;\r
  Ep->EpAddr      = (UINT8) (EpAddr & 0x0F);\r
  Ep->Direction   = (((EpAddr & 0x80) != 0) ? EfiUsbDataIn : EfiUsbDataOut);\r
  Ep->DevSpeed    = DevSpeed;\r
  Ep->MaxPacket   = MaxPacket;\r
\r
  Ep->HubAddr     = 0;\r
  Ep->HubPort     = 0;\r
\r
  if (DevSpeed != EFI_USB_SPEED_HIGH) {\r
    ASSERT (Hub != NULL);\r
\r
    Ep->HubAddr   = Hub->TranslatorHubAddress;\r
    Ep->HubPort   = Hub->TranslatorPortNumber;\r
  }\r
\r
  Ep->Toggle      = Toggle;\r
  Ep->Type        = Type;\r
  Ep->PollRate    = EhcConvertPollRate (Interval);\r
\r
  Urb->Request    = Request;\r
  Urb->Data       = Data;\r
  Urb->DataLen    = DataLen;\r
  Urb->Callback   = Callback;\r
  Urb->Context    = Context;\r
\r
  PciIo           = Ehc->PciIo;\r
  Urb->Qh         = EhcCreateQh (Ehc, &Urb->Ep);\r
\r
  if (Urb->Qh == NULL) {\r
    goto ON_ERROR;\r
  }\r
\r
  //\r
  // Map the request and user data\r
  //\r
  if (Request != NULL) {\r
    Len     = sizeof (EFI_USB_DEVICE_REQUEST);\r
    MapOp   = EfiPciIoOperationBusMasterRead;\r
    Status  = PciIo->Map (PciIo, MapOp, Request, &Len, &PhyAddr, &Map);\r
\r
    if (EFI_ERROR (Status) || (Len != sizeof (EFI_USB_DEVICE_REQUEST))) {\r
      goto ON_ERROR;\r
    }\r
\r
    Urb->RequestPhy = (VOID *) ((UINTN) PhyAddr);\r
    Urb->RequestMap = Map;\r
  }\r
\r
  if (Data != NULL) {\r
    Len     = DataLen;\r
\r
    if (Ep->Direction == EfiUsbDataIn) {\r
      MapOp = EfiPciIoOperationBusMasterWrite;\r
    } else {\r
      MapOp = EfiPciIoOperationBusMasterRead;\r
    }\r
\r
    Status  = PciIo->Map (PciIo, MapOp, Data, &Len, &PhyAddr, &Map);\r
\r
    if (EFI_ERROR (Status) || (Len != DataLen)) {\r
      goto ON_ERROR;\r
    }\r
\r
    Urb->DataPhy  = (VOID *) ((UINTN) PhyAddr);\r
    Urb->DataMap  = Map;\r
  }\r
\r
  Status = EhcCreateQtds (Ehc, Urb);\r
\r
  if (EFI_ERROR (Status)) {\r
    goto ON_ERROR;\r
  }\r
\r
  return Urb;\r
\r
ON_ERROR:\r
  EhcFreeUrb (Ehc, Urb);\r
  return NULL;\r
}\r