Subrata Banik | 20fe24b | 2021-12-09 02:46:38 +0530 | [diff] [blame] | 1 | /** @file |
| 2 | EFI MM Access PPI definition. |
| 3 | |
| 4 | This PPI is used to control the visibility of the MMRAM on the platform. |
| 5 | The EFI_PEI_MM_ACCESS_PPI abstracts the location and characteristics of MMRAM. The |
| 6 | principal functionality found in the memory controller includes the following: |
| 7 | - Exposing the MMRAM to all non-MM agents, or the "open" state |
| 8 | - Shrouding the MMRAM to all but the MM agents, or the "closed" state |
| 9 | - Preserving the system integrity, or "locking" the MMRAM, such that the settings cannot be |
| 10 | perturbed by either boot service or runtime agents |
| 11 | |
| 12 | Copyright (c) 2019, Intel Corporation. All rights reserved.<BR> |
| 13 | SPDX-License-Identifier: BSD-2-Clause-Patent |
| 14 | |
| 15 | @par Revision Reference: |
| 16 | This PPI is introduced in PI Version 1.5. |
| 17 | |
| 18 | **/ |
| 19 | |
| 20 | #ifndef _MM_ACCESS_PPI_H_ |
| 21 | #define _MM_ACCESS_PPI_H_ |
| 22 | |
| 23 | #define EFI_PEI_MM_ACCESS_PPI_GUID \ |
| 24 | { 0x268f33a9, 0xcccd, 0x48be, { 0x88, 0x17, 0x86, 0x5, 0x3a, 0xc3, 0x2e, 0xd6 }} |
| 25 | |
| 26 | typedef struct _EFI_PEI_MM_ACCESS_PPI EFI_PEI_MM_ACCESS_PPI; |
| 27 | |
| 28 | /** |
| 29 | Opens the MMRAM area to be accessible by a PEIM. |
| 30 | |
| 31 | This function "opens" MMRAM so that it is visible while not inside of MM. The function should |
| 32 | return EFI_UNSUPPORTED if the hardware does not support hiding of MMRAM. The function |
| 33 | should return EFI_DEVICE_ERROR if the MMRAM configuration is locked. |
| 34 | |
| 35 | @param PeiServices An indirect pointer to the PEI Services Table published by the PEI Foundation. |
| 36 | @param This The EFI_PEI_MM_ACCESS_PPI instance. |
| 37 | @param DescriptorIndex The region of MMRAM to Open. |
| 38 | |
| 39 | @retval EFI_SUCCESS The operation was successful. |
| 40 | @retval EFI_UNSUPPORTED The system does not support opening and closing of MMRAM. |
| 41 | @retval EFI_DEVICE_ERROR MMRAM cannot be opened, perhaps because it is locked. |
| 42 | |
| 43 | **/ |
| 44 | typedef |
| 45 | EFI_STATUS |
| 46 | (EFIAPI *EFI_PEI_MM_OPEN)( |
| 47 | IN EFI_PEI_SERVICES **PeiServices, |
| 48 | IN EFI_PEI_MM_ACCESS_PPI *This, |
| 49 | IN UINTN DescriptorIndex |
| 50 | ); |
| 51 | |
| 52 | /** |
| 53 | Inhibits access to the MMRAM. |
| 54 | |
| 55 | This function "closes" MMRAM so that it is not visible while outside of MM. The function should |
| 56 | return EFI_UNSUPPORTED if the hardware does not support hiding of MMRAM. |
| 57 | |
| 58 | @param PeiServices An indirect pointer to the PEI Services Table published by the PEI Foundation. |
| 59 | @param This The EFI_PEI_MM_ACCESS_PPI instance. |
| 60 | @param DescriptorIndex The region of MMRAM to Close. |
| 61 | |
| 62 | @retval EFI_SUCCESS The operation was successful. |
| 63 | @retval EFI_UNSUPPORTED The system does not support opening and closing of MMRAM. |
| 64 | @retval EFI_DEVICE_ERROR MMRAM cannot be closed. |
| 65 | |
| 66 | **/ |
| 67 | typedef |
| 68 | EFI_STATUS |
| 69 | (EFIAPI *EFI_PEI_MM_CLOSE)( |
| 70 | IN EFI_PEI_SERVICES **PeiServices, |
| 71 | IN EFI_PEI_MM_ACCESS_PPI *This, |
| 72 | IN UINTN DescriptorIndex |
| 73 | ); |
| 74 | |
| 75 | /** |
| 76 | This function prohibits access to the MMRAM region. This function is usually implemented such |
| 77 | that it is a write-once operation. |
| 78 | |
| 79 | @param PeiServices An indirect pointer to the PEI Services Table published by the PEI Foundation. |
| 80 | @param This The EFI_PEI_MM_ACCESS_PPI instance. |
| 81 | @param DescriptorIndex The region of MMRAM to Lock. |
| 82 | |
| 83 | @retval EFI_SUCCESS The operation was successful. |
| 84 | @retval EFI_UNSUPPORTED The system does not support opening and closing of MMRAM. |
| 85 | |
| 86 | **/ |
| 87 | typedef |
| 88 | EFI_STATUS |
| 89 | (EFIAPI *EFI_PEI_MM_LOCK)( |
| 90 | IN EFI_PEI_SERVICES **PeiServices, |
| 91 | IN EFI_PEI_MM_ACCESS_PPI *This, |
| 92 | IN UINTN DescriptorIndex |
| 93 | ); |
| 94 | |
| 95 | /** |
| 96 | Queries the memory controller for the possible regions that will support MMRAM. |
| 97 | |
| 98 | This function describes the MMRAM regions. |
| 99 | This data structure forms the contract between the MM_ACCESS and MM_IPL drivers. There is an |
| 100 | ambiguity when any MMRAM region is remapped. For example, on some chipsets, some MMRAM |
| 101 | regions can be initialized at one physical address but is later accessed at another processor address. |
| 102 | There is currently no way for the MM IPL driver to know that it must use two different addresses |
| 103 | depending on what it is trying to do. As a result, initial configuration and loading can use the |
| 104 | physical address PhysicalStart while MMRAM is open. However, once the region has been |
| 105 | closed and needs to be accessed by agents in MM, the CpuStart address must be used. |
| 106 | This PPI publishes the available memory that the chipset can shroud for the use of installing code. |
| 107 | These regions serve the dual purpose of describing which regions have been open, closed, or locked. |
| 108 | In addition, these regions may include overlapping memory ranges, depending on the chipset |
| 109 | implementation. The latter might include a chipset that supports T-SEG, where memory near the top |
| 110 | of the physical DRAM can be allocated for MMRAM too. |
| 111 | The key thing to note is that the regions that are described by the PPI are a subset of the capabilities |
| 112 | of the hardware. |
| 113 | |
| 114 | @param PeiServices An indirect pointer to the PEI Services Table published by the PEI Foundation. |
| 115 | @param This The EFI_PEI_MM_ACCESS_PPI instance. |
| 116 | @param MmramMapSize A pointer to the size, in bytes, of the MmramMemoryMap buffer. On input, this value is |
| 117 | the size of the buffer that is allocated by the caller. On output, it is the size of the |
| 118 | buffer that was returned by the firmware if the buffer was large enough, or, if the |
| 119 | buffer was too small, the size of the buffer that is needed to contain the map. |
| 120 | @param MmramMap A pointer to the buffer in which firmware places the current memory map. The map is |
| 121 | an array of EFI_MMRAM_DESCRIPTORs |
| 122 | |
| 123 | @retval EFI_SUCCESS The chipset supported the given resource. |
| 124 | @retval EFI_BUFFER_TOO_SMALL The MmramMap parameter was too small. The current |
| 125 | buffer size needed to hold the memory map is returned in |
| 126 | MmramMapSize. |
| 127 | |
| 128 | **/ |
| 129 | typedef |
| 130 | EFI_STATUS |
| 131 | (EFIAPI *EFI_PEI_MM_CAPABILITIES)( |
| 132 | IN EFI_PEI_SERVICES **PeiServices, |
| 133 | IN EFI_PEI_MM_ACCESS_PPI *This, |
| 134 | IN OUT UINTN *MmramMapSize, |
| 135 | IN OUT EFI_MMRAM_DESCRIPTOR *MmramMap |
| 136 | ); |
| 137 | |
| 138 | /// |
| 139 | /// EFI MM Access PPI is used to control the visibility of the MMRAM on the platform. |
| 140 | /// It abstracts the location and characteristics of MMRAM. The platform should report |
| 141 | /// all MMRAM via EFI_PEI_MM_ACCESS_PPI. The expectation is that the north bridge or |
| 142 | /// memory controller would publish this PPI. |
| 143 | /// |
| 144 | struct _EFI_PEI_MM_ACCESS_PPI { |
| 145 | EFI_PEI_MM_OPEN Open; |
| 146 | EFI_PEI_MM_CLOSE Close; |
| 147 | EFI_PEI_MM_LOCK Lock; |
| 148 | EFI_PEI_MM_CAPABILITIES GetCapabilities; |
| 149 | BOOLEAN LockState; |
| 150 | BOOLEAN OpenState; |
| 151 | }; |
| 152 | |
| 153 | extern EFI_GUID gEfiPeiMmAccessPpiGuid; |
| 154 | |
| 155 | #endif |