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