[mirror_edk2.git] / MdeModulePkg / Library / PiSmmCoreMemoryAllocationLib / PiSmmCoreMemoryAllocationServices.h

/** @file\r
  Contains function prototypes for Memory Services in the SMM Core.\r
\r
  This header file borrows the PiSmmCore Memory Allocation services as the primitive\r
  for memory allocation.\r
\r
  Copyright (c) 2008 - 2018, 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
\r
**/\r
\r
#ifndef _PI_SMM_CORE_MEMORY_ALLOCATION_SERVICES_H_\r
#define _PI_SMM_CORE_MEMORY_ALLOCATION_SERVICES_H_\r
\r
//\r
// It should be aligned with the definition in PiSmmCore.\r
//\r
typedef struct {\r
  UINTN                           Signature;\r
\r
  ///\r
  /// The ImageHandle passed into the entry point of the SMM IPL.  This ImageHandle\r
  /// is used by the SMM Core to fill in the ParentImageHandle field of the Loaded\r
  /// Image Protocol for each SMM Driver that is dispatched by the SMM Core.\r
  ///\r
  EFI_HANDLE                      SmmIplImageHandle;\r
\r
  ///\r
  /// The number of SMRAM ranges passed from the SMM IPL to the SMM Core.  The SMM\r
  /// Core uses these ranges of SMRAM to initialize the SMM Core memory manager.\r
  ///\r
  UINTN                           SmramRangeCount;\r
\r
  ///\r
  /// A table of SMRAM ranges passed from the SMM IPL to the SMM Core.  The SMM\r
  /// Core uses these ranges of SMRAM to initialize the SMM Core memory manager.\r
  ///\r
  EFI_SMRAM_DESCRIPTOR            *SmramRanges;\r
\r
  ///\r
  /// The SMM Foundation Entry Point.  The SMM Core fills in this field when the\r
  /// SMM Core is initialized.  The SMM IPL is responsbile for registering this entry\r
  /// point with the SMM Configuration Protocol.  The SMM Configuration Protocol may\r
  /// not be available at the time the SMM IPL and SMM Core are started, so the SMM IPL\r
  /// sets up a protocol notification on the SMM Configuration Protocol and registers\r
  /// the SMM Foundation Entry Point as soon as the SMM Configuration Protocol is\r
  /// available.\r
  ///\r
  EFI_SMM_ENTRY_POINT             SmmEntryPoint;\r
\r
  ///\r
  /// Boolean flag set to TRUE while an SMI is being processed by the SMM Core.\r
  ///\r
  BOOLEAN                         SmmEntryPointRegistered;\r
\r
  ///\r
  /// Boolean flag set to TRUE while an SMI is being processed by the SMM Core.\r
  ///\r
  BOOLEAN                         InSmm;\r
\r
  ///\r
  /// This field is set by the SMM Core then the SMM Core is initialized.  This field is\r
  /// used by the SMM Base 2 Protocol and SMM Communication Protocol implementations in\r
  /// the SMM IPL.\r
  ///\r
  EFI_SMM_SYSTEM_TABLE2           *Smst;\r
\r
  ///\r
  /// This field is used by the SMM Communicatioon Protocol to pass a buffer into\r
  /// a software SMI handler and for the software SMI handler to pass a buffer back to\r
  /// the caller of the SMM Communication Protocol.\r
  ///\r
  VOID                            *CommunicationBuffer;\r
\r
  ///\r
  /// This field is used by the SMM Communicatioon Protocol to pass the size of a buffer,\r
  /// in bytes, into a software SMI handler and for the software SMI handler to pass the\r
  /// size, in bytes, of a buffer back to the caller of the SMM Communication Protocol.\r
  ///\r
  UINTN                           BufferSize;\r
\r
  ///\r
  /// This field is used by the SMM Communication Protocol to pass the return status from\r
  /// a software SMI handler back to the caller of the SMM Communication Protocol.\r
  ///\r
  EFI_STATUS                      ReturnStatus;\r
\r
  EFI_PHYSICAL_ADDRESS            PiSmmCoreImageBase;\r
  UINT64                          PiSmmCoreImageSize;\r
  EFI_PHYSICAL_ADDRESS            PiSmmCoreEntryPoint;\r
} SMM_CORE_PRIVATE_DATA;\r
\r
/**\r
  Called to initialize the memory service.\r
\r
  @param   SmramRangeCount       Number of SMRAM Regions\r
  @param   SmramRanges           Pointer to SMRAM Descriptors\r
\r
**/\r
VOID\r
SmmInitializeMemoryServices (\r
  IN UINTN                 SmramRangeCount,\r
  IN EFI_SMRAM_DESCRIPTOR  *SmramRanges\r
  );\r
\r
/**\r
  Allocates pages from the memory map.\r
\r
  @param  Type                   The type of allocation to perform\r
  @param  MemoryType             The type of memory to turn the allocated pages\r
                                 into\r
  @param  NumberOfPages          The number of pages to allocate\r
  @param  Memory                 A pointer to receive the base allocated memory\r
                                 address\r
\r
  @retval EFI_INVALID_PARAMETER  Parameters violate checking rules defined in spec.\r
  @retval EFI_NOT_FOUND          Could not allocate pages match the requirement.\r
  @retval EFI_OUT_OF_RESOURCES   No enough pages to allocate.\r
  @retval EFI_SUCCESS            Pages successfully allocated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SmmAllocatePages (\r
  IN      EFI_ALLOCATE_TYPE         Type,\r
  IN      EFI_MEMORY_TYPE           MemoryType,\r
  IN      UINTN                     NumberOfPages,\r
  OUT     EFI_PHYSICAL_ADDRESS      *Memory\r
  );\r
\r
/**\r
  Frees previous allocated pages.\r
\r
  @param  Memory                 Base address of memory being freed\r
  @param  NumberOfPages          The number of pages to free\r
\r
  @retval EFI_NOT_FOUND          Could not find the entry that covers the range\r
  @retval EFI_INVALID_PARAMETER  Address not aligned\r
  @return EFI_SUCCESS            Pages successfully freed.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SmmFreePages (\r
  IN      EFI_PHYSICAL_ADDRESS      Memory,\r
  IN      UINTN                     NumberOfPages\r
  );\r
\r
/**\r
  Allocate pool of a particular type.\r
\r
  @param  PoolType               Type of pool to allocate\r
  @param  Size                   The amount of pool to allocate\r
  @param  Buffer                 The address to return a pointer to the allocated\r
                                 pool\r
\r
  @retval EFI_INVALID_PARAMETER  PoolType not valid\r
  @retval EFI_OUT_OF_RESOURCES   Size exceeds max pool size or allocation failed.\r
  @retval EFI_SUCCESS            Pool successfully allocated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SmmAllocatePool (\r
  IN      EFI_MEMORY_TYPE           PoolType,\r
  IN      UINTN                     Size,\r
  OUT     VOID                      **Buffer\r
  );\r
\r
/**\r
  Frees pool.\r
\r
  @param  Buffer                 The allocated pool entry to free\r
\r
  @retval EFI_INVALID_PARAMETER  Buffer is not a valid value.\r
  @retval EFI_SUCCESS            Pool successfully freed.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SmmFreePool (\r
  IN      VOID                      *Buffer\r
  );\r
\r
#endif\r
Commit	Line	Data
713b7781	1	/** @file\r
	2	Contains function prototypes for Memory Services in the SMM Core.\r
	3	\r
	4	This header file borrows the PiSmmCore Memory Allocation services as the primitive\r
d1102dba	5	for memory allocation.\r
713b7781	6	\r
d1102dba LG	7	Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR>\r
	8	This program and the accompanying materials\r
	9	are licensed and made available under the terms and conditions of the BSD License\r
	10	which accompanies this distribution. The full text of the license may be found at\r
	11	http://opensource.org/licenses/bsd-license.php\r
713b7781	12	\r
d1102dba LG	13	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
d1102dba LG	14	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
713b7781	15	\r
	16	**/\r
	17	\r
	18	#ifndef _PI_SMM_CORE_MEMORY_ALLOCATION_SERVICES_H_\r
	19	#define _PI_SMM_CORE_MEMORY_ALLOCATION_SERVICES_H_\r
	20	\r
f3b6e048 SZ	21	//\r
	22	// It should be aligned with the definition in PiSmmCore.\r
	23	//\r
842b1242 JY	24	typedef struct {\r
842b1242 JY	25	UINTN Signature;\r
f3b6e048	26	\r
842b1242 JY	27	///\r
	28	/// The ImageHandle passed into the entry point of the SMM IPL. This ImageHandle\r
	29	/// is used by the SMM Core to fill in the ParentImageHandle field of the Loaded\r
	30	/// Image Protocol for each SMM Driver that is dispatched by the SMM Core.\r
	31	///\r
	32	EFI_HANDLE SmmIplImageHandle;\r
f3b6e048	33	\r
842b1242 JY	34	///\r
	35	/// The number of SMRAM ranges passed from the SMM IPL to the SMM Core. The SMM\r
	36	/// Core uses these ranges of SMRAM to initialize the SMM Core memory manager.\r
	37	///\r
	38	UINTN SmramRangeCount;\r
f3b6e048	39	\r
842b1242 JY	40	///\r
	41	/// A table of SMRAM ranges passed from the SMM IPL to the SMM Core. The SMM\r
	42	/// Core uses these ranges of SMRAM to initialize the SMM Core memory manager.\r
	43	///\r
	44	EFI_SMRAM_DESCRIPTOR *SmramRanges;\r
f3b6e048 SZ	45	\r
f3b6e048 SZ	46	///\r
d1102dba LG	47	/// The SMM Foundation Entry Point. The SMM Core fills in this field when the\r
	48	/// SMM Core is initialized. The SMM IPL is responsbile for registering this entry\r
	49	/// point with the SMM Configuration Protocol. The SMM Configuration Protocol may\r
f3b6e048	50	/// not be available at the time the SMM IPL and SMM Core are started, so the SMM IPL\r
d1102dba LG	51	/// sets up a protocol notification on the SMM Configuration Protocol and registers\r
d1102dba LG	52	/// the SMM Foundation Entry Point as soon as the SMM Configuration Protocol is\r
f3b6e048 SZ	53	/// available.\r
	54	///\r
	55	EFI_SMM_ENTRY_POINT SmmEntryPoint;\r
d1102dba	56	\r
f3b6e048 SZ	57	///\r
f3b6e048 SZ	58	/// Boolean flag set to TRUE while an SMI is being processed by the SMM Core.\r
d1102dba	59	///\r
f3b6e048 SZ	60	BOOLEAN SmmEntryPointRegistered;\r
	61	\r
	62	///\r
	63	/// Boolean flag set to TRUE while an SMI is being processed by the SMM Core.\r
d1102dba	64	///\r
f3b6e048 SZ	65	BOOLEAN InSmm;\r
	66	\r
	67	///\r
	68	/// This field is set by the SMM Core then the SMM Core is initialized. This field is\r
	69	/// used by the SMM Base 2 Protocol and SMM Communication Protocol implementations in\r
d1102dba	70	/// the SMM IPL.\r
f3b6e048 SZ	71	///\r
	72	EFI_SMM_SYSTEM_TABLE2 *Smst;\r
	73	\r
	74	///\r
d1102dba	75	/// This field is used by the SMM Communicatioon Protocol to pass a buffer into\r
f3b6e048	76	/// a software SMI handler and for the software SMI handler to pass a buffer back to\r
d1102dba	77	/// the caller of the SMM Communication Protocol.\r
f3b6e048 SZ	78	///\r
	79	VOID *CommunicationBuffer;\r
	80	\r
	81	///\r
	82	/// This field is used by the SMM Communicatioon Protocol to pass the size of a buffer,\r
d1102dba	83	/// in bytes, into a software SMI handler and for the software SMI handler to pass the\r
f3b6e048 SZ	84	/// size, in bytes, of a buffer back to the caller of the SMM Communication Protocol.\r
	85	///\r
	86	UINTN BufferSize;\r
	87	\r
	88	///\r
	89	/// This field is used by the SMM Communication Protocol to pass the return status from\r
	90	/// a software SMI handler back to the caller of the SMM Communication Protocol.\r
	91	///\r
	92	EFI_STATUS ReturnStatus;\r
	93	\r
	94	EFI_PHYSICAL_ADDRESS PiSmmCoreImageBase;\r
	95	UINT64 PiSmmCoreImageSize;\r
	96	EFI_PHYSICAL_ADDRESS PiSmmCoreEntryPoint;\r
842b1242 JY	97	} SMM_CORE_PRIVATE_DATA;\r
	98	\r
	99	/**\r
	100	Called to initialize the memory service.\r
	101	\r
	102	@param SmramRangeCount Number of SMRAM Regions\r
	103	@param SmramRanges Pointer to SMRAM Descriptors\r
	104	\r
	105	**/\r
	106	VOID\r
	107	SmmInitializeMemoryServices (\r
	108	IN UINTN SmramRangeCount,\r
	109	IN EFI_SMRAM_DESCRIPTOR *SmramRanges\r
	110	);\r
	111	\r
713b7781	112	/**\r
	113	Allocates pages from the memory map.\r
	114	\r
	115	@param Type The type of allocation to perform\r
	116	@param MemoryType The type of memory to turn the allocated pages\r
	117	into\r
	118	@param NumberOfPages The number of pages to allocate\r
	119	@param Memory A pointer to receive the base allocated memory\r
	120	address\r
	121	\r
	122	@retval EFI_INVALID_PARAMETER Parameters violate checking rules defined in spec.\r
	123	@retval EFI_NOT_FOUND Could not allocate pages match the requirement.\r
	124	@retval EFI_OUT_OF_RESOURCES No enough pages to allocate.\r
	125	@retval EFI_SUCCESS Pages successfully allocated.\r
	126	\r
	127	**/\r
	128	EFI_STATUS\r
	129	EFIAPI\r
	130	SmmAllocatePages (\r
	131	IN EFI_ALLOCATE_TYPE Type,\r
	132	IN EFI_MEMORY_TYPE MemoryType,\r
	133	IN UINTN NumberOfPages,\r
	134	OUT EFI_PHYSICAL_ADDRESS *Memory\r
	135	);\r
	136	\r
	137	/**\r
	138	Frees previous allocated pages.\r
	139	\r
	140	@param Memory Base address of memory being freed\r
	141	@param NumberOfPages The number of pages to free\r
	142	\r
	143	@retval EFI_NOT_FOUND Could not find the entry that covers the range\r
	144	@retval EFI_INVALID_PARAMETER Address not aligned\r
	145	@return EFI_SUCCESS Pages successfully freed.\r
	146	\r
	147	**/\r
	148	EFI_STATUS\r
	149	EFIAPI\r
	150	SmmFreePages (\r
	151	IN EFI_PHYSICAL_ADDRESS Memory,\r
	152	IN UINTN NumberOfPages\r
	153	);\r
	154	\r
	155	/**\r
	156	Allocate pool of a particular type.\r
	157	\r
	158	@param PoolType Type of pool to allocate\r
	159	@param Size The amount of pool to allocate\r
	160	@param Buffer The address to return a pointer to the allocated\r
	161	pool\r
	162	\r
	163	@retval EFI_INVALID_PARAMETER PoolType not valid\r
	164	@retval EFI_OUT_OF_RESOURCES Size exceeds max pool size or allocation failed.\r
	165	@retval EFI_SUCCESS Pool successfully allocated.\r
	166	\r
	167	**/\r
	168	EFI_STATUS\r
	169	EFIAPI\r
	170	SmmAllocatePool (\r
	171	IN EFI_MEMORY_TYPE PoolType,\r
	172	IN UINTN Size,\r
	173	OUT VOID **Buffer\r
	174	);\r
	175	\r
176	/**\r
177	Frees pool.\r
178	\r
179	@param Buffer The allocated pool entry to free\r
180	\r
181	@retval EFI_INVALID_PARAMETER Buffer is not a valid value.\r
182	@retval EFI_SUCCESS Pool successfully freed.\r
183	\r
184	**/\r
185	EFI_STATUS\r
186	EFIAPI\r
187	SmmFreePool (\r
188	IN VOID *Buffer\r
189	);\r
190	\r
191	#endif\r