MdeModulePkg/Include/Ppi/IoMmu.h

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