UefiCpuPkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / UefiCpuPkg / Include / Library / MtrrLib.h

diff --git a/UefiCpuPkg/Include/Library/MtrrLib.h b/UefiCpuPkg/Include/Library/MtrrLib.h
index 612052640a6059c4d3444882151109b089cd17cb..95ffbc8bf172a589a95d75e82dc679c9e568452d 100644 (file)
--- a/UefiCpuPkg/Include/Library/MtrrLib.h
+++ b/UefiCpuPkg/Include/Library/MtrrLib.h
@@ -1,14 +1,8 @@
 /** @file\r
   MTRR setting library\r
 \r
-  Copyright (c) 2008 - 2017, Intel Corporation. All rights reserved.<BR>\r
-  This program and the accompanying materials\r
-  are licensed and made available under the terms and conditions of the BSD License\r
-  which accompanies this distribution.  The full text of the license may be found at\r
-  http://opensource.org/licenses/bsd-license.php\r
-\r
-  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
-  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+  Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR>\r
+  SPDX-License-Identifier: BSD-2-Clause-Patent\r
 \r
 **/\r
 \r
@@ -103,6 +97,12 @@ typedef enum {
 #define  MTRR_CACHE_WRITE_BACK       6\r
 #define  MTRR_CACHE_INVALID_TYPE     7\r
 \r
+typedef struct {\r
+  UINT64                 BaseAddress;\r
+  UINT64                 Length;\r
+  MTRR_MEMORY_CACHE_TYPE Type;\r
+} MTRR_MEMORY_RANGE;\r
+\r
 /**\r
   Returns the variable MTRR count for the CPU.\r
 \r
@@ -151,7 +151,14 @@ GetFirmwareVariableMtrrCount (
   @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to\r
                                     modify the attributes of the memory\r
                                     resource range.\r
-\r
+                                    Multiple memory range attributes setting by calling this API multiple\r
+                                    times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean\r
+                                    the number of CPU MTRRs are too small to set such memory attributes.\r
+                                    Pass the multiple memory range attributes to one call of\r
+                                    MtrrSetMemoryAttributesInMtrrSettings() may succeed.\r
+  @retval RETURN_BUFFER_TOO_SMALL   The fixed internal scratch buffer is too small for MTRR calculation.\r
+                                    Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify\r
+                                    external scratch buffer.\r
 **/\r
 RETURN_STATUS\r
 EFIAPI\r
@@ -346,7 +353,14 @@ MtrrGetDefaultMemoryType (
                                     BaseAddress and Length cannot be modified.\r
   @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to modify the attributes of\r
                                     the memory resource range.\r
-\r
+                                    Multiple memory range attributes setting by calling this API multiple\r
+                                    times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean\r
+                                    the number of CPU MTRRs are too small to set such memory attributes.\r
+                                    Pass the multiple memory range attributes to one call of\r
+                                    MtrrSetMemoryAttributesInMtrrSettings() may succeed.\r
+  @retval RETURN_BUFFER_TOO_SMALL   The fixed internal scratch buffer is too small for MTRR calculation.\r
+                                    Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify\r
+                                    external scratch buffer.\r
 **/\r
 RETURN_STATUS\r
 EFIAPI\r
@@ -357,4 +371,39 @@ MtrrSetMemoryAttributeInMtrrSettings (
   IN MTRR_MEMORY_CACHE_TYPE  Attribute\r
   );\r
 \r
+/**\r
+  This function attempts to set the attributes into MTRR setting buffer for multiple memory ranges.\r
+\r
+  @param[in, out]  MtrrSetting  MTRR setting buffer to be set.\r
+  @param[in]       Scratch      A temporary scratch buffer that is used to perform the calculation.\r
+  @param[in, out]  ScratchSize  Pointer to the size in bytes of the scratch buffer.\r
+                                It may be updated to the actual required size when the calculation\r
+                                needs more scratch buffer.\r
+  @param[in]       Ranges       Pointer to an array of MTRR_MEMORY_RANGE.\r
+                                When range overlap happens, the last one takes higher priority.\r
+                                When the function returns, either all the attributes are set successfully,\r
+                                or none of them is set.\r
+  @param[in]      RangeCount    Count of MTRR_MEMORY_RANGE.\r
+\r
+  @retval RETURN_SUCCESS            The attributes were set for all the memory ranges.\r
+  @retval RETURN_INVALID_PARAMETER  Length in any range is zero.\r
+  @retval RETURN_UNSUPPORTED        The processor does not support one or more bytes of the\r
+                                    memory resource range specified by BaseAddress and Length in any range.\r
+  @retval RETURN_UNSUPPORTED        The bit mask of attributes is not support for the memory resource\r
+                                    range specified by BaseAddress and Length in any range.\r
+  @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to modify the attributes of\r
+                                    the memory resource ranges.\r
+  @retval RETURN_ACCESS_DENIED      The attributes for the memory resource range specified by\r
+                                    BaseAddress and Length cannot be modified.\r
+  @retval RETURN_BUFFER_TOO_SMALL   The scratch buffer is too small for MTRR calculation.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+MtrrSetMemoryAttributesInMtrrSettings (\r
+  IN OUT MTRR_SETTINGS           *MtrrSetting,\r
+  IN     VOID                    *Scratch,\r
+  IN OUT UINTN                   *ScratchSize,\r
+  IN     CONST MTRR_MEMORY_RANGE *Ranges,\r
+  IN     UINTN                   RangeCount\r
+  );\r
 #endif // _MTRR_LIB_H_\r