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