MdeModulePkg/Bus/Pci/XhciDxe/UsbHcMem.h

   1 /** @file
   2
   3   This file contains the definination for host controller memory management routines.
   4
   5 Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _EFI_XHCI_MEM_H_
  11 #define _EFI_XHCI_MEM_H_
  12
  13 #define USB_HC_BIT(a)  ((UINTN)(1 << (a)))
  14
  15 #define USB_HC_BIT_IS_SET(Data, Bit)   \
  16           ((BOOLEAN)(((Data) & USB_HC_BIT(Bit)) == USB_HC_BIT(Bit)))
  17
  18 typedef struct _USBHC_MEM_BLOCK USBHC_MEM_BLOCK;
  19 struct _USBHC_MEM_BLOCK {
  20   UINT8              *Bits;         // Bit array to record which unit is allocated
  21   UINTN              BitsLen;
  22   UINT8              *Buf;
  23   UINT8              *BufHost;
  24   UINTN              BufLen;        // Memory size in bytes
  25   VOID               *Mapping;
  26   USBHC_MEM_BLOCK    *Next;
  27 };
  28
  29 //
  30 // USBHC_MEM_POOL is used to manage the memory used by USB
  31 // host controller. XHCI requires the control memory and transfer
  32 // data to be on the same 4G memory.
  33 //
  34 typedef struct _USBHC_MEM_POOL {
  35   EFI_PCI_IO_PROTOCOL    *PciIo;
  36   BOOLEAN                Check4G;
  37   UINT32                 Which4G;
  38   USBHC_MEM_BLOCK        *Head;
  39 } USBHC_MEM_POOL;
  40
  41 //
  42 // Memory allocation unit, must be 2^n, n>4
  43 //
  44 #define USBHC_MEM_UNIT  64
  45
  46 #define USBHC_MEM_UNIT_MASK      (USBHC_MEM_UNIT - 1)
  47 #define USBHC_MEM_DEFAULT_PAGES  16
  48
  49 #define USBHC_MEM_ROUND(Len)  (((Len) + USBHC_MEM_UNIT_MASK) & (~USBHC_MEM_UNIT_MASK))
  50
  51 //
  52 // Advance the byte and bit to the next bit, adjust byte accordingly.
  53 //
  54 #define NEXT_BIT(Byte, Bit)   \
  55           do {                \
  56             (Bit)++;          \
  57             if ((Bit) > 7) {  \
  58               (Byte)++;       \
  59               (Bit) = 0;      \
  60             }                 \
  61           } while (0)
  62
  63 /**
  64   Initialize the memory management pool for the host controller.
  65
  66   @param  PciIo               The PciIo that can be used to access the host controller.
  67
  68   @retval EFI_SUCCESS         The memory pool is initialized.
  69   @retval EFI_OUT_OF_RESOURCE Fail to init the memory pool.
  70
  71 **/
  72 USBHC_MEM_POOL *
  73 UsbHcInitMemPool (
  74   IN EFI_PCI_IO_PROTOCOL  *PciIo
  75   );
  76
  77 /**
  78   Release the memory management pool.
  79
  80   @param   Pool               The USB memory pool to free.
  81
  82   @retval EFI_SUCCESS       The memory pool is freed.
  83   @retval EFI_DEVICE_ERROR  Failed to free the memory pool.
  84
  85 **/
  86 EFI_STATUS
  87 UsbHcFreeMemPool (
  88   IN USBHC_MEM_POOL  *Pool
  89   );
  90
  91 /**
  92   Allocate some memory from the host controller's memory pool
  93   which can be used to communicate with host controller.
  94
  95   @param  Pool  The host controller's memory pool.
  96   @param  Size  Size of the memory to allocate.
  97
  98   @return The allocated memory or NULL.
  99
 100 **/
 101 VOID *
 102 UsbHcAllocateMem (
 103   IN  USBHC_MEM_POOL  *Pool,
 104   IN  UINTN           Size
 105   );
 106
 107 /**
 108   Free the allocated memory back to the memory pool.
 109
 110   @param  Pool  The memory pool of the host controller.
 111   @param  Mem   The memory to free.
 112   @param  Size  The size of the memory to free.
 113
 114 **/
 115 VOID
 116 UsbHcFreeMem (
 117   IN USBHC_MEM_POOL  *Pool,
 118   IN VOID            *Mem,
 119   IN UINTN           Size
 120   );
 121
 122 /**
 123   Calculate the corresponding pci bus address according to the Mem parameter.
 124
 125   @param  Pool           The memory pool of the host controller.
 126   @param  Mem            The pointer to host memory.
 127   @param  Size           The size of the memory region.
 128
 129   @return                The pci memory address
 130
 131 **/
 132 EFI_PHYSICAL_ADDRESS
 133 UsbHcGetPciAddrForHostAddr (
 134   IN USBHC_MEM_POOL  *Pool,
 135   IN VOID            *Mem,
 136   IN UINTN           Size
 137   );
 138
 139 /**
 140   Calculate the corresponding host address according to the pci address.
 141
 142   @param  Pool           The memory pool of the host controller.
 143   @param  Mem            The pointer to pci memory.
 144   @param  Size           The size of the memory region.
 145
 146   @return                The host memory address
 147
 148 **/
 149 EFI_PHYSICAL_ADDRESS
 150 UsbHcGetHostAddrForPciAddr (
 151   IN USBHC_MEM_POOL  *Pool,
 152   IN VOID            *Mem,
 153   IN UINTN           Size
 154   );
 155
 156 /**
 157   Allocates pages at a specified alignment that are suitable for an EfiPciIoOperationBusMasterCommonBuffer mapping.
 158
 159   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 160
 161   @param  PciIo                 The PciIo that can be used to access the host controller.
 162   @param  Pages                 The number of pages to allocate.
 163   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 164   @param  HostAddress           The system memory address to map to the PCI controller.
 165   @param  DeviceAddress         The resulting map address for the bus master PCI controller to
 166                                 use to access the hosts HostAddress.
 167   @param  Mapping               A resulting value to pass to Unmap().
 168
 169   @retval EFI_SUCCESS           Success to allocate aligned pages.
 170   @retval EFI_INVALID_PARAMETER Pages or Alignment is not valid.
 171   @retval EFI_OUT_OF_RESOURCES  Do not have enough resources to allocate memory.
 172
 173
 174 **/
 175 EFI_STATUS
 176 UsbHcAllocateAlignedPages (
 177   IN EFI_PCI_IO_PROTOCOL    *PciIo,
 178   IN UINTN                  Pages,
 179   IN UINTN                  Alignment,
 180   OUT VOID                  **HostAddress,
 181   OUT EFI_PHYSICAL_ADDRESS  *DeviceAddress,
 182   OUT VOID                  **Mapping
 183   );
 184
 185 /**
 186   Frees memory that was allocated with UsbHcAllocateAlignedPages().
 187
 188   @param  PciIo                 The PciIo that can be used to access the host controller.
 189   @param  HostAddress           The system memory address to map to the PCI controller.
 190   @param  Pages                 The number of pages to free.
 191   @param  Mapping               The mapping value returned from Map().
 192
 193 **/
 194 VOID
 195 UsbHcFreeAlignedPages (
 196   IN EFI_PCI_IO_PROTOCOL  *PciIo,
 197   IN VOID                 *HostAddress,
 198   IN UINTN                Pages,
 199   VOID                    *Mapping
 200   );
 201
 202 #endif