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