MdeModulePkg/Include/Ppi/IoMmu.h

   1 /** @file
   2   PEI IOMMU PPI.
   3
   4 Copyright (c) 2017, 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
  73 **/
  74 typedef
  75 EFI_STATUS
  76 (EFIAPI *EDKII_PEI_IOMMU_SET_ATTRIBUTE)(
  77   IN EDKII_IOMMU_PPI       *This,
  78   IN VOID                  *Mapping,
  79   IN UINT64                IoMmuAccess
  80   );
  81
  82 /**
  83   Provides the controller-specific addresses required to access system memory from a
  84   DMA bus master.
  85
  86   @param  This                  The PPI instance pointer.
  87   @param  Operation             Indicates if the bus master is going to read or write to system memory.
  88   @param  HostAddress           The system memory address to map to the PCI controller.
  89   @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes
  90                                 that were mapped.
  91   @param  DeviceAddress         The resulting map address for the bus master PCI controller to use to
  92                                 access the hosts HostAddress.
  93   @param  Mapping               A resulting value to pass to Unmap().
  94
  95   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
  96   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
  97   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  98   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
  99   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
 100
 101 **/
 102 typedef
 103 EFI_STATUS
 104 (EFIAPI *EDKII_PEI_IOMMU_MAP)(
 105   IN     EDKII_IOMMU_PPI                            *This,
 106   IN     EDKII_IOMMU_OPERATION                      Operation,
 107   IN     VOID                                       *HostAddress,
 108   IN OUT UINTN                                      *NumberOfBytes,
 109   OUT    EFI_PHYSICAL_ADDRESS                       *DeviceAddress,
 110   OUT    VOID                                       **Mapping
 111   );
 112
 113 /**
 114   Completes the Map() operation and releases any corresponding resources.
 115
 116   @param  This                  The PPI instance pointer.
 117   @param  Mapping               The mapping value returned from Map().
 118
 119   @retval EFI_SUCCESS           The range was unmapped.
 120   @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
 121   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
 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 and MEMORY_CACHED.
 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
 148 **/
 149 typedef
 150 EFI_STATUS
 151 (EFIAPI *EDKII_PEI_IOMMU_ALLOCATE_BUFFER)(
 152   IN     EDKII_IOMMU_PPI                          *This,
 153   IN     EFI_MEMORY_TYPE                          MemoryType,
 154   IN     UINTN                                    Pages,
 155   IN OUT VOID                                     **HostAddress,
 156   IN     UINT64                                   Attributes
 157   );
 158
 159 /**
 160   Frees memory that was allocated with AllocateBuffer().
 161
 162   @param  This                  The protocol instance pointer.
 163   @param  Pages                 The number of pages to free.
 164   @param  HostAddress           The base system memory address of the allocated range.
 165
 166   @retval EFI_SUCCESS           The requested memory pages were freed.
 167   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
 168                                 was not allocated with AllocateBuffer().
 169
 170 **/
 171 typedef
 172 EFI_STATUS
 173 (EFIAPI *EDKII_PEI_IOMMU_FREE_BUFFER)(
 174   IN  EDKII_IOMMU_PPI                          *This,
 175   IN  UINTN                                    Pages,
 176   IN  VOID                                     *HostAddress
 177   );
 178
 179 ///
 180 /// IOMMU PPI structure.
 181 ///
 182 struct _EDKII_IOMMU_PPI {
 183   UINT64                              Revision;
 184   EDKII_PEI_IOMMU_SET_ATTRIBUTE       SetAttribute;
 185   EDKII_PEI_IOMMU_MAP                 Map;
 186   EDKII_PEI_IOMMU_UNMAP               Unmap;
 187   EDKII_PEI_IOMMU_ALLOCATE_BUFFER     AllocateBuffer;
 188   EDKII_PEI_IOMMU_FREE_BUFFER         FreeBuffer;
 189 };
 190
 191 ///
 192 /// IOMMU PPI GUID variable.
 193 ///
 194 extern EFI_GUID gEdkiiIoMmuPpiGuid;
 195
 196 #endif