MdeModulePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdeModulePkg / Bus / Pci / XhciDxe / UsbHcMem.h

/** @file\r
\r
  This file contains the definination for host controller memory management routines.\r
\r
Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _EFI_XHCI_MEM_H_\r
#define _EFI_XHCI_MEM_H_\r
\r
#define USB_HC_BIT(a)                  ((UINTN)(1 << (a)))\r
\r
#define USB_HC_BIT_IS_SET(Data, Bit)   \\r
          ((BOOLEAN)(((Data) & USB_HC_BIT(Bit)) == USB_HC_BIT(Bit)))\r
\r
typedef struct _USBHC_MEM_BLOCK USBHC_MEM_BLOCK;\r
struct _USBHC_MEM_BLOCK {\r
  UINT8                   *Bits;    // Bit array to record which unit is allocated\r
  UINTN                   BitsLen;\r
  UINT8                   *Buf;\r
  UINT8                   *BufHost;\r
  UINTN                   BufLen;   // Memory size in bytes\r
  VOID                    *Mapping;\r
  USBHC_MEM_BLOCK         *Next;\r
};\r
\r
//\r
// USBHC_MEM_POOL is used to manage the memory used by USB\r
// host controller. XHCI requires the control memory and transfer\r
// data to be on the same 4G memory.\r
//\r
typedef struct _USBHC_MEM_POOL {\r
  EFI_PCI_IO_PROTOCOL     *PciIo;\r
  BOOLEAN                 Check4G;\r
  UINT32                  Which4G;\r
  USBHC_MEM_BLOCK         *Head;\r
} USBHC_MEM_POOL;\r
\r
//\r
// Memory allocation unit, must be 2^n, n>4\r
//\r
#define USBHC_MEM_UNIT           64\r
\r
#define USBHC_MEM_UNIT_MASK      (USBHC_MEM_UNIT - 1)\r
#define USBHC_MEM_DEFAULT_PAGES  16\r
\r
#define USBHC_MEM_ROUND(Len)  (((Len) + USBHC_MEM_UNIT_MASK) & (~USBHC_MEM_UNIT_MASK))\r
\r
//\r
// Advance the byte and bit to the next bit, adjust byte accordingly.\r
//\r
#define NEXT_BIT(Byte, Bit)   \\r
          do {                \\r
            (Bit)++;          \\r
            if ((Bit) > 7) {  \\r
              (Byte)++;       \\r
              (Bit) = 0;      \\r
            }                 \\r
          } while (0)\r
\r
\r
\r
/**\r
  Initialize the memory management pool for the host controller.\r
\r
  @param  PciIo               The PciIo that can be used to access the host controller.\r
\r
  @retval EFI_SUCCESS         The memory pool is initialized.\r
  @retval EFI_OUT_OF_RESOURCE Fail to init the memory pool.\r
\r
**/\r
USBHC_MEM_POOL *\r
UsbHcInitMemPool (\r
  IN EFI_PCI_IO_PROTOCOL  *PciIo\r
  );\r
\r
\r
/**\r
  Release the memory management pool.\r
\r
  @param   Pool               The USB memory pool to free.\r
\r
  @retval EFI_SUCCESS       The memory pool is freed.\r
  @retval EFI_DEVICE_ERROR  Failed to free the memory pool.\r
\r
**/\r
EFI_STATUS\r
UsbHcFreeMemPool (\r
  IN USBHC_MEM_POOL       *Pool\r
  );\r
\r
\r
/**\r
  Allocate some memory from the host controller's memory pool\r
  which can be used to communicate with host controller.\r
\r
  @param  Pool  The host controller's memory pool.\r
  @param  Size  Size of the memory to allocate.\r
\r
  @return The allocated memory or NULL.\r
\r
**/\r
VOID *\r
UsbHcAllocateMem (\r
  IN  USBHC_MEM_POOL      *Pool,\r
  IN  UINTN               Size\r
  );\r
\r
\r
/**\r
  Free the allocated memory back to the memory pool.\r
\r
  @param  Pool  The memory pool of the host controller.\r
  @param  Mem   The memory to free.\r
  @param  Size  The size of the memory to free.\r
\r
**/\r
VOID\r
UsbHcFreeMem (\r
  IN USBHC_MEM_POOL       *Pool,\r
  IN VOID                 *Mem,\r
  IN UINTN                Size\r
  );\r
\r
/**\r
  Calculate the corresponding pci bus address according to the Mem parameter.\r
\r
  @param  Pool           The memory pool of the host controller.\r
  @param  Mem            The pointer to host memory.\r
  @param  Size           The size of the memory region.\r
\r
  @return                The pci memory address\r
\r
**/\r
EFI_PHYSICAL_ADDRESS\r
UsbHcGetPciAddrForHostAddr (\r
  IN USBHC_MEM_POOL       *Pool,\r
  IN VOID                 *Mem,\r
  IN UINTN                Size\r
  );\r
\r
/**\r
  Calculate the corresponding host address according to the pci address.\r
\r
  @param  Pool           The memory pool of the host controller.\r
  @param  Mem            The pointer to pci memory.\r
  @param  Size           The size of the memory region.\r
\r
  @return                The host memory address\r
\r
**/\r
EFI_PHYSICAL_ADDRESS\r
UsbHcGetHostAddrForPciAddr (\r
  IN USBHC_MEM_POOL       *Pool,\r
  IN VOID                 *Mem,\r
  IN UINTN                Size\r
  );\r
\r
/**\r
  Allocates pages at a specified alignment that are suitable for an EfiPciIoOperationBusMasterCommonBuffer mapping.\r
\r
  If Alignment is not a power of two and Alignment is not zero, then ASSERT().\r
\r
  @param  PciIo                 The PciIo that can be used to access the host controller.\r
  @param  Pages                 The number of pages to allocate.\r
  @param  Alignment             The requested alignment of the allocation.  Must be a power of two.\r
  @param  HostAddress           The system memory address to map to the PCI controller.\r
  @param  DeviceAddress         The resulting map address for the bus master PCI controller to\r
                                use to access the hosts HostAddress.\r
  @param  Mapping               A resulting value to pass to Unmap().\r
\r
  @retval EFI_SUCCESS           Success to allocate aligned pages.\r
  @retval EFI_INVALID_PARAMETER Pages or Alignment is not valid.\r
  @retval EFI_OUT_OF_RESOURCES  Do not have enough resources to allocate memory.\r
\r
\r
**/\r
EFI_STATUS\r
UsbHcAllocateAlignedPages (\r
  IN EFI_PCI_IO_PROTOCOL    *PciIo,\r
  IN UINTN                  Pages,\r
  IN UINTN                  Alignment,\r
  OUT VOID                  **HostAddress,\r
  OUT EFI_PHYSICAL_ADDRESS  *DeviceAddress,\r
  OUT VOID                  **Mapping\r
  );\r
\r
/**\r
  Frees memory that was allocated with UsbHcAllocateAlignedPages().\r
\r
  @param  PciIo                 The PciIo that can be used to access the host controller.\r
  @param  HostAddress           The system memory address to map to the PCI controller.\r
  @param  Pages                 The number of pages to free.\r
  @param  Mapping               The mapping value returned from Map().\r
\r
**/\r
VOID\r
UsbHcFreeAlignedPages (\r
  IN EFI_PCI_IO_PROTOCOL    *PciIo,\r
  IN VOID                   *HostAddress,\r
  IN UINTN                  Pages,\r
  VOID                      *Mapping\r
  );\r
\r
#endif\r