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
  65 /**
  66   Initialize the memory management pool for the host controller.
  67
  68   @param  PciIo               The PciIo that can be used to access the host controller.
  69
  70   @retval EFI_SUCCESS         The memory pool is initialized.
  71   @retval EFI_OUT_OF_RESOURCE Fail to init the memory pool.
  72
  73 **/
  74 USBHC_MEM_POOL *
  75 UsbHcInitMemPool (
  76   IN EFI_PCI_IO_PROTOCOL  *PciIo
  77   );
  78
  79
  80 /**
  81   Release the memory management pool.
  82
  83   @param   Pool               The USB memory pool to free.
  84
  85   @retval EFI_SUCCESS       The memory pool is freed.
  86   @retval EFI_DEVICE_ERROR  Failed to free the memory pool.
  87
  88 **/
  89 EFI_STATUS
  90 UsbHcFreeMemPool (
  91   IN USBHC_MEM_POOL       *Pool
  92   );
  93
  94
  95 /**
  96   Allocate some memory from the host controller's memory pool
  97   which can be used to communicate with host controller.
  98
  99   @param  Pool  The host controller's memory pool.
 100   @param  Size  Size of the memory to allocate.
 101
 102   @return The allocated memory or NULL.
 103
 104 **/
 105 VOID *
 106 UsbHcAllocateMem (
 107   IN  USBHC_MEM_POOL      *Pool,
 108   IN  UINTN               Size
 109   );
 110
 111
 112 /**
 113   Free the allocated memory back to the memory pool.
 114
 115   @param  Pool  The memory pool of the host controller.
 116   @param  Mem   The memory to free.
 117   @param  Size  The size of the memory to free.
 118
 119 **/
 120 VOID
 121 UsbHcFreeMem (
 122   IN USBHC_MEM_POOL       *Pool,
 123   IN VOID                 *Mem,
 124   IN UINTN                Size
 125   );
 126
 127 /**
 128   Calculate the corresponding pci bus address according to the Mem parameter.
 129
 130   @param  Pool           The memory pool of the host controller.
 131   @param  Mem            The pointer to host memory.
 132   @param  Size           The size of the memory region.
 133
 134   @return                The pci memory address
 135
 136 **/
 137 EFI_PHYSICAL_ADDRESS
 138 UsbHcGetPciAddrForHostAddr (
 139   IN USBHC_MEM_POOL       *Pool,
 140   IN VOID                 *Mem,
 141   IN UINTN                Size
 142   );
 143
 144 /**
 145   Calculate the corresponding host address according to the pci address.
 146
 147   @param  Pool           The memory pool of the host controller.
 148   @param  Mem            The pointer to pci memory.
 149   @param  Size           The size of the memory region.
 150
 151   @return                The host memory address
 152
 153 **/
 154 EFI_PHYSICAL_ADDRESS
 155 UsbHcGetHostAddrForPciAddr (
 156   IN USBHC_MEM_POOL       *Pool,
 157   IN VOID                 *Mem,
 158   IN UINTN                Size
 159   );
 160
 161 /**
 162   Allocates pages at a specified alignment that are suitable for an EfiPciIoOperationBusMasterCommonBuffer mapping.
 163
 164   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 165
 166   @param  PciIo                 The PciIo that can be used to access the host controller.
 167   @param  Pages                 The number of pages to allocate.
 168   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 169   @param  HostAddress           The system memory address to map to the PCI controller.
 170   @param  DeviceAddress         The resulting map address for the bus master PCI controller to
 171                                 use to access the hosts HostAddress.
 172   @param  Mapping               A resulting value to pass to Unmap().
 173
 174   @retval EFI_SUCCESS           Success to allocate aligned pages.
 175   @retval EFI_INVALID_PARAMETER Pages or Alignment is not valid.
 176   @retval EFI_OUT_OF_RESOURCES  Do not have enough resources to allocate memory.
 177
 178
 179 **/
 180 EFI_STATUS
 181 UsbHcAllocateAlignedPages (
 182   IN EFI_PCI_IO_PROTOCOL    *PciIo,
 183   IN UINTN                  Pages,
 184   IN UINTN                  Alignment,
 185   OUT VOID                  **HostAddress,
 186   OUT EFI_PHYSICAL_ADDRESS  *DeviceAddress,
 187   OUT VOID                  **Mapping
 188   );
 189
 190 /**
 191   Frees memory that was allocated with UsbHcAllocateAlignedPages().
 192
 193   @param  PciIo                 The PciIo that can be used to access the host controller.
 194   @param  HostAddress           The system memory address to map to the PCI controller.
 195   @param  Pages                 The number of pages to free.
 196   @param  Mapping               The mapping value returned from Map().
 197
 198 **/
 199 VOID
 200 UsbHcFreeAlignedPages (
 201   IN EFI_PCI_IO_PROTOCOL    *PciIo,
 202   IN VOID                   *HostAddress,
 203   IN UINTN                  Pages,
 204   VOID                      *Mapping
 205   );
 206
 207 #endif