LiteOS-Reading/src/doc/LiteOS_Kernel_Developer_Guide_en/development-guidelines-1.md

Development Guidelines

Usage Scenarios

The main task of memory management is to dynamically partition and manage user allocated memory intervals.

Dynamic memory management is used when users have different demands on memory blocks. When a user needs memory, the system calls the LOS_MemAlloc API to allocate the requested amount of memory. When the user no longer needs the memory, the system calls the LOS_MemFree API to free it up.

Functions

The dynamic memory management module of Huawei LiteOS provides the following functions. For details about the APIs, see the API reference.

Function Category	API	Description
Memory pool initialization and deletion	LOS_MemInit	Initializes a dynamic memory pool of the required size.
	LOS_MemDeInit	Deletes a memory pool. This function takes effect only when LOSCFG_MEM_MUL_POOL is enabled.
Dynamic memory application and free-up	LOS_MemAlloc	Applies for a memory block of the required size from a dynamic memory pool.
	LOS_MemFree	Frees up the applied memory.
	LOS_MemRealloc	Re-allocates a memory block of the required size and copies content from the original block. If the new memory block is successfully applied for, the original one will be freed up.
	LOS_MemAllocAlign	Applies for a memory block of the required size whose address is aligned based on boundary, from a dynamic memory pool.
Memory pool information obtainment	LOS_MemPoolSizeGet	Obtains the total size of a dynamic memory pool.
	LOS_MemTotalUsedGet	Obtains the total usage of a dynamic memory pool.
	LOS_MemInfoGet	Obtains the structure of a memory pool, including the size of idle memory, size of used memory, number of idle memory blocks, number of used memory blocks, and maximum size of idle memory blocks.
	LOS_MemPoolList	Prints information about all initialized memory pools in the system, including the start addresses of the memory pools, size of the memory pools, total size of idle memory, total size of used memory, maximum size of idle memory blocks, number of idle memory blocks, and number of used memory blocks. This function takes effect only when LOSCFG_MEM_MUL_POOL is enabled.
Memory block information obtainment	LOS_MemFreeBlksGet	Obtains the number of idle memory blocks in a memory pool.
	LOS_MemUsedBlksGet	Obtains the number of used memory blocks in a memory pool.
	LOS_MemTaskIdGet	Obtains the ID of the task to which a memory block is allocated.
	LOS_MemLastUsedGet	Obtains the end address of the last used memory block in a memory pool.
	LOS_MemNodeSizeCheck	Obtains the total size of a memory block and the size of idle memory in it. This function takes effect only when LOSCFG_BASE_MEM_NODE_SIZE_CHECK is enabled.
	LOS_MemFreeNodeShow	Prints the size and number of idle memory blocks in a memory pool.
Memory pool integrity check	LOS_MemIntegrityCheck	Checks the integrity of a memory pool. This function takes effect only when LOSCFG_BASE_MEM_NODE_INTEGRITY_CHECK is enabled.
Sets and obtains the memory check level. This function takes effect only when LOSCFG_BASE_MEM_NODE_SIZE_CHECK is enabled.	LOS_MemCheckLevelSet	Sets the memory check level.
	LOS_MemCheckLevelGet	Obtains the memory check level.
Dynamic memory application and free-up for a module (effective only when LOSCFG_MEM_MUL_MODULE is enabled)	LOS_MemMalloc	Takes memory out of a specified dynamic memory pool and allocates the memory to a specified module, and records the amount of memory allocated to the module.
	LOS_MemMfree	Frees up a memory block that has been allocated to a specified module and records the amount of memory that is freed up.
	LOS_MemMallocAlign	Applies for a memory block of the required size whose address is aligned based on boundary, from a dynamic memory pool, and records the amount of the applied memory.
	LOS_MemMrealloc	Re-allocates a memory block of the required size and copies content from the original block, and records the amount of the re-allocated memory. If the new memory block is successfully applied for, the original one will be freed up.
Module memory usage obtainment	LOS_MemMusedGet	Obtains the memory usage of a module. This function takes effect only when LOSCFG_MEM_MUL_MODULE is enabled.

NOTICE:

• Debugging functions are provided for dynamic memory. For details, see Memory Debugging.
• For the bestfit_little algorithm, only Multi-Memory Pool Mechanism and Memory Validity Check are supported. Other memory debugging functions are not supported.
• Among the preceding APIs, the ones controlled through macro are all related to memory debugging.
• After the LOS_MemRealloc or LOS_MemMrealloc operation is performed on the memory applied using LOS_MemAllocAlign or LOS_MemMallocAlign, the new start address of memory may become unaligned.
• For the bestfit_little algorithm, the LOS_MemRealloc operation cannot be performed on the memory applied using LOS_MemAllocAlign. Otherwise, failure will be returned.

Development Process

This section describes the development process of dynamic memory in typical scenarios.

1. Configure the start address and size of a dynamic memory pool in the los_config.h file.

   Configuration Item	Description	Value Range	Default Value	Dependency
   OS_SYS_MEM_ADDR	Start address of the system dynamic memory pool.	[0, n)	&m_aucSysMem1[0]	None
   OS_SYS_MEM_SIZE	Size (in bytes) of the system dynamic memory pool (DDR adaptive).	[0, n)	From the end of the BSS segment to the end of the system DDR	None

   • OS_SYS_MEM_ADDR: In most cases, retain the default value.
   • OS_SYS_MEM_SIZE: In most cases, retain the default value.

2. Run the make menuconfig command and choose Kernel > Memory Management to configure the dynamic memory management module.

   Configuration Item	Description	Value Range	Default Value	Dependency
   LOSCFG_KERNEL_MEM_BESTFIT	Whether to use the bestfit algorithm for memory management.	YES/NO	YES	None
   LOSCFG_KERNEL_MEM_BESTFIT_LITTLE	Whether to use the bestfit_little algorithm for memory management.	YES/NO	NO	None
   LOSCFG_KERNEL_MEM_SLAB_EXTENTION	Whether to enable the slab function to reduce memory fragments at runtime.	YES/NO	NO	None
   LOSCFG_KERNEL_MEM_SLAB_AUTO_EXPANSION_MODE	Whether to automatically expand slabs by applying for new space from the system memory pool, when their memory space is insufficient.	YES/NO	NO	LOSCFG_KERNEL_MEM_SLAB_EXTENTION
   LOSCFG_MEM_TASK_STAT	Whether to enable task memory statistics.	YES/NO	YES	LOSCFG_KERNEL_MEM_BESTFIT or LOSCFG_KERNEL_MEM_BESTFIT_LITTLE

3. Call the LOS_MemInit API to initialize a memory pool.

   As shown in the figure below, an EndNode is generated after the initialization, and all the remaining memory is marked as a FreeNode. EndNode is the last node in the memory pool, and its size is 0.

   

4. Call the LOS_MemAlloc API to apply for dynamic memory of any size.

   The system determines whether the dynamic memory pool has sufficient memory. If yes, it takes the required size out of the memory pool and returns a pointer. If no, it returns "NULL" instead.

   The LOS_MemAlloc function can be called three times to create three nodes, namely, UsedA, UsedB, and UsedC with sizeA, sizeB, and sizeC, respectively. There is only one large FreeNode when the memory pool is initialized, so these memory blocks are divided from the FreeNode.

   

   If there are multiple FreeNodes in the memory pool, the one of the most appropriate size will be used to create a memory block during malloc, which can reduce memory fragments. If the created memory block is not the size of the selected FreeNode, the remaining memory will be marked as a new FreeNode.

5. Call the LOS_MemFree API to free up dynamic memory.

   The reclaimed memory block can be used next time.

   Assume that LOS_MemFree is called to free up UsedB. The reclaimed UsedB block will be marked as a FreeNode. When memory blocks are reclaimed, adjacent FreeNodes are automatically merged.

   

Platform Differences

None