MdeModulePkg/Include/Ppi/IoMmu.h

   1 /** @file
   2   PEI IOMMU PPI.
   3
   4 Copyright (c) 2017 - 2018, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials are licensed and made available under
   6 the terms and conditions of the BSD License that accompanies this distribution.
   7 The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php.
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15
  16 #ifndef __PEI_IOMMU_H__
  17 #define __PEI_IOMMU_H__
  18
  19 //
  20 // for EFI_ALLOCATE_TYPE
  21 //
  22 #include <Uefi.h>
  23
  24 //
  25 // Include protocol for common definition
  26 //   EDKII_IOMMU_ACCESS_xxx
  27 //   EDKII_IOMMU_OPERATION
  28 //
  29 #include <Protocol/IoMmu.h>
  30
  31 //
  32 // IOMMU Ppi GUID value
  33 //
  34 #define EDKII_IOMMU_PPI_GUID \
  35     { \
  36       0x70b0af26, 0xf847, 0x4bb6, { 0xaa, 0xb9, 0xcd, 0xe8, 0x4f, 0xc6, 0x14, 0x31 } \
  37     }
  38
  39 //
  40 // Forward reference for pure ANSI compatability
  41 //
  42 typedef struct _EDKII_IOMMU_PPI  EDKII_IOMMU_PPI;
  43
  44 //
  45 // Revision The revision to which the IOMMU interface adheres.
  46 //          All future revisions must be backwards compatible.
  47 //          If a future version is not back wards compatible it is not the same GUID.
  48 //
  49 #define EDKII_IOMMU_PPI_REVISION 0x00010000
  50
  51 /**
  52   Set IOMMU attribute for a system memory.
  53
  54   If the IOMMU PPI exists, the system memory cannot be used
  55   for DMA by default.
  56
  57   When a device requests a DMA access for a system memory,
  58   the device driver need use SetAttribute() to update the IOMMU
  59   attribute to request DMA access (read and/or write).
  60
  61   @param[in]  This              The PPI instance pointer.
  62   @param[in]  Mapping           The mapping value returned from Map().
  63   @param[in]  IoMmuAccess       The IOMMU access.
  64
  65   @retval EFI_SUCCESS            The IoMmuAccess is set for the memory range specified by DeviceAddress and Length.
  66   @retval EFI_INVALID_PARAMETER  Mapping is not a value that was returned by Map().
  67   @retval EFI_INVALID_PARAMETER  IoMmuAccess specified an illegal combination of access.
  68   @retval EFI_UNSUPPORTED        The bit mask of IoMmuAccess is not supported by the IOMMU.
  69   @retval EFI_UNSUPPORTED        The IOMMU does not support the memory range specified by Mapping.
  70   @retval EFI_OUT_OF_RESOURCES   There are not enough resources available to modify the IOMMU access.
  71   @retval EFI_DEVICE_ERROR       The IOMMU device reported an error while attempting the operation.
  72   @retval EFI_NOT_AVAILABLE_YET  DMA protection has been enabled, but DMA buffer are
  73                                  not available to be allocated yet.
  74
  75 **/
  76 typedef
  77 EFI_STATUS
  78 (EFIAPI *EDKII_PEI_IOMMU_SET_ATTRIBUTE)(
  79   IN EDKII_IOMMU_PPI       *This,
  80   IN VOID                  *Mapping,
  81   IN UINT64                IoMmuAccess
  82   );
  83
  84 /**
  85   Provides the controller-specific addresses required to access system memory from a
  86   DMA bus master.
  87
  88   @param  This                  The PPI instance pointer.
  89   @param  Operation             Indicates if the bus master is going to read or write to system memory.
  90   @param  HostAddress           The system memory address to map to the PCI controller.
  91   @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes
  92                                 that were mapped.
  93   @param  DeviceAddress         The resulting map address for the bus master PCI controller to use to
  94                                 access the hosts HostAddress.
  95   @param  Mapping               A resulting value to pass to Unmap().
  96
  97   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
  98   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
  99   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 100   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 101   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
 102   @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
 103                                 not available to be allocated yet.
 104
 105 **/
 106 typedef
 107 EFI_STATUS
 108 (EFIAPI *EDKII_PEI_IOMMU_MAP)(
 109   IN     EDKII_IOMMU_PPI                            *This,
 110   IN     EDKII_IOMMU_OPERATION                      Operation,
 111   IN     VOID                                       *HostAddress,
 112   IN OUT UINTN                                      *NumberOfBytes,
 113   OUT    EFI_PHYSICAL_ADDRESS                       *DeviceAddress,
 114   OUT    VOID                                       **Mapping
 115   );
 116
 117 /**
 118   Completes the Map() operation and releases any corresponding resources.
 119
 120   @param  This                  The PPI instance pointer.
 121   @param  Mapping               The mapping value returned from Map().
 122
 123   @retval EFI_SUCCESS           The range was unmapped.
 124   @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
 125   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
 126   @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
 127                                 not available to be allocated yet.
 128
 129 **/
 130 typedef
 131 EFI_STATUS
 132 (EFIAPI *EDKII_PEI_IOMMU_UNMAP)(
 133   IN  EDKII_IOMMU_PPI                          *This,
 134   IN  VOID                                     *Mapping
 135   );
 136
 137 /**
 138   Allocates pages that are suitable for an OperationBusMasterCommonBuffer or
 139   OperationBusMasterCommonBuffer64 mapping.
 140
 141   @param  This                  The PPI instance pointer.
 142   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
 143                                 EfiRuntimeServicesData.
 144   @param  Pages                 The number of pages to allocate.
 145   @param  HostAddress           A pointer to store the base system memory address of the
 146                                 allocated range.
 147   @param  Attributes            The requested bit mask of attributes for the allocated range.
 148
 149   @retval EFI_SUCCESS           The requested memory pages were allocated.
 150   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 151                                 MEMORY_WRITE_COMBINE, MEMORY_CACHED and DUAL_ADDRESS_CYCLE.
 152   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 153   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 154   @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
 155                                 not available to be allocated yet.
 156
 157 **/
 158 typedef
 159 EFI_STATUS
 160 (EFIAPI *EDKII_PEI_IOMMU_ALLOCATE_BUFFER)(
 161   IN     EDKII_IOMMU_PPI                          *This,
 162   IN     EFI_MEMORY_TYPE                          MemoryType,
 163   IN     UINTN                                    Pages,
 164   IN OUT VOID                                     **HostAddress,
 165   IN     UINT64                                   Attributes
 166   );
 167
 168 /**
 169   Frees memory that was allocated with AllocateBuffer().
 170
 171   @param  This                  The PPI instance pointer.
 172   @param  Pages                 The number of pages to free.
 173   @param  HostAddress           The base system memory address of the allocated range.
 174
 175   @retval EFI_SUCCESS           The requested memory pages were freed.
 176   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
 177                                 was not allocated with AllocateBuffer().
 178   @retval EFI_NOT_AVAILABLE_YET DMA protection has been enabled, but DMA buffer are
 179                                 not available to be allocated yet.
 180
 181 **/
 182 typedef
 183 EFI_STATUS
 184 (EFIAPI *EDKII_PEI_IOMMU_FREE_BUFFER)(
 185   IN  EDKII_IOMMU_PPI                          *This,
 186   IN  UINTN                                    Pages,
 187   IN  VOID                                     *HostAddress
 188   );
 189
 190 ///
 191 /// IOMMU PPI structure.
 192 ///
 193 struct _EDKII_IOMMU_PPI {
 194   UINT64                              Revision;
 195   EDKII_PEI_IOMMU_SET_ATTRIBUTE       SetAttribute;
 196   EDKII_PEI_IOMMU_MAP                 Map;
 197   EDKII_PEI_IOMMU_UNMAP               Unmap;
 198   EDKII_PEI_IOMMU_ALLOCATE_BUFFER     AllocateBuffer;
 199   EDKII_PEI_IOMMU_FREE_BUFFER         FreeBuffer;
 200 };
 201
 202 ///
 203 /// IOMMU PPI GUID variable.
 204 ///
 205 extern EFI_GUID gEdkiiIoMmuPpiGuid;
 206
 207 #endif