michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Edit microkernel_memory_pools.rst for consistency in structure.

Browse source 
Much of this doc is comparable to memory_maps, so edits make the overall
language and structure consistent among files. Added heading syntax to
APIs, make imperative verbs on API notes, as discussed in code reviews and
on previous edits.

Change-Id: I8e14b44007acdf5422d75810dde78aef1a9c653a
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2016-02-26 10:22:25 -08:00 • committed by Gerrit Code Review
commit 96a2d2e199
1 changed files with 52 additions and 53 deletions
Download patch file Download diff file Expand all files Collapse all files

105
doc/kernel/microkernel/microkernel_memory_pools.rst
View file

@ -6,64 +6,62 @@ Memory Pools
Concepts Concepts
******** ********
The microkernel's memory pool objects provide dynamic allocation and The microkernel's :dfn:`memory pool` objects provide dynamic allocation and
release of variable-size memory blocks. release of variable-size memory blocks.
Unlike a memory map, which only supports memory blocks of a single size, Unlike :ref:`memory map <microkernel_memory_map>` objects, which support
a memory pool has the ability to support multiple memory block sizes. memory blocks of only a *single* size, a memory pool can support memory blocks
It does this by subdividing blocks into smaller chunks whenever possible of *various* sizes. The memory pool does this by subdividing blocks into smaller
to more closely match the actual needs of the requesting task. chunks, where possible, to more closely match the actual needs of a requesting
task.
Any number of memory pools can be defined in a microkernel system. Any number of memory pools can be defined in a microkernel system. Each memory
Each memory pool has a name that uniquely identifies it. pool has:
In addition, a memory pool defines minimum and maximum memory block sizes
in bytes and the number of maximum size blocks that the memory pool
contains.
A task that needs to use a memory block simply allocates it from a * A **name** that uniquely identifies it.
memory pool. If a block of the desired size is unavailable, the task * A **minimum** and **maximum** block size, in bytes, of memory blocks
may choose to wait for one to become available. Following a successful within the pool.
allocation the :c:data:`pointer_to_data` field of the block descriptor * The **number of maximum-size memory blocks** initially available.
supplied by the task indicates the starting address of the memory block.
When the task is finished with a memory block, it must release the block
back to the memory pool that allocated it so that the block can be
reused.
Any number of tasks may wait on a memory pool simultaneously; A task that needs to use a memory block simply allocates it from a memory
when a memory block becomes available it is given to the highest pool. When a block of the desired size is unavailable, the task can wait
priority task that has waited the longest. for one to become available. Following a successful allocation, the
:c:data:`pointer_to_data` field of the block descriptor supplied by the
task indicates the starting address of the memory block. When the task is
finished with a memory block, it must release the block back to the memory
pool that allocated it so that the block can be reused.
Any number of tasks can wait on a memory pool simultaneously; when a
memory block becomes available, it is given to the highest-priority task
that has waited the longest.
When a request for memory is sufficiently smaller than an available When a request for memory is sufficiently smaller than an available
memory pool block, the memory pool will automatically split the memory pool block, the memory pool will automatically split the block into
block into 4 smaller blocks. The resulting smaller 4 smaller blocks. The resulting smaller blocks can also be split repeatedly,
blocks can also be split repeatedly, until a block just larger until a block just larger than the needed size is available, or the minimum
than the needed size is available, or the minimum block size, block size, as specified in the MDEF, is reached.
as specified in the MDEF, is reached.
If the memory pool is unable to find an available block If the memory pool cannot find an available block that is at least
that is at least the requested size, it will attempt to create the requested size, it will attempt to create one by merging adjacent
one by merging adjacent free blocks; if it is unable to create free blocks. If a suitable block can't be created, the request fails.
a suitable block the request fails.
Although a memory pool uses efficient algorithms to manage its Although a memory pool uses efficient algorithms to manage its blocks,
blocks, splitting available blocks and merging free blocks the splitting of available blocks and merging of free blocks takes time
takes time and increases the overhead involved in allocating and increases overhead block allocation. The larger the allowable
a block. The larger the allowable number of splits, the larger number of splits, the larger the overhead. However, the minimum and maximum
the overhead. The minimum and maximum block size parameters block-size parameters specified for a pool can be used to control the amount
specified for a pool can be used to control the amount of of splitting, and thus the amount of overhead.
splitting, and thus the amount of overhead.
Unlike a heap, more than one memory pool can be defined, if Unlike a heap, more than one memory pool can be defined, if needed. For
needed. For example, different applications can utilize example, different applications can utilize different memory pools; this
different memory pools so that one application does not can help prevent one application from hijacking resources to allocate all
allocate all of the available blocks. of the available blocks.
Purpose Purpose
******* *******
Use memory pools to allocate memory in variable-size blocks. Use memory pools to allocate memory in variable-size blocks.
Use memory pool blocks when sending data to a mailbox Use memory pool blocks when sending data to a mailbox asynchronously.
asynchronously.
Usage Usage
***** *****
@ -77,7 +75,7 @@ The following parameters must be defined:
This specifies a unique name for the memory pool. This specifies a unique name for the memory pool.
*min_block_size* *min_block_size*
This specifies the minimimum memory block size in bytes. This specifies the minimum memory block size in bytes.
It should be a multiple of the processor's word size. It should be a multiple of the processor's word size.
*max_block_size* *max_block_size*
@ -92,7 +90,7 @@ The following parameters must be defined:
Public Memory Pool Public Memory Pool
------------------ ------------------
Define the memory pool in the application's MDEF using the following Define the memory pool in the application's MDEF with the following
syntax: syntax:
.. code-block:: console .. code-block:: console
@ -146,7 +144,7 @@ in that time.
printf('Memory allocation timeout'); printf('Memory allocation timeout');
} }
Example: Requesting a Memory Block from a Pool with a No Blocking Condition Example: Requesting a Memory Block from a Pool with a No-Blocking Condition
=========================================================================== ===========================================================================
This code gives an immediate warning when it can not satisfy the request for This code gives an immediate warning when it can not satisfy the request for
@ -180,9 +178,9 @@ Example: Manually Defragmenting a Memory Pool
This code instructs the memory pool to concatenate any unused memory blocks This code instructs the memory pool to concatenate any unused memory blocks
that can be merged. Doing a full defragmentation of the entire memory pool that can be merged. Doing a full defragmentation of the entire memory pool
before allocating a number of memory blocks may be more efficient before allocating a number of memory blocks may be more efficient than doing
than having to do an implicit partial defragmentation of the memory pool an implicit partial defragmentation of the memory pool each time a memory
each time a memory block allocation occurs. block allocation occurs.
.. code-block:: c .. code-block:: c
@ -191,14 +189,15 @@ each time a memory block allocation occurs.
APIs APIs
**** ****
The following Memory Pools APIs are provided by :file:`microkernel.h`: Memory Pools APIs provided by :file:`microkernel.h`
===================================================
:cpp:func:`task_mem_pool_alloc()` :cpp:func:`task_mem_pool_alloc()`
Waits for a block of memory for the time period defined by the time-out Wait for a block of memory; wait the period of time defined by the time-out
parameter. parameter.
:cpp:func:`task_mem_pool_free()` :cpp:func:`task_mem_pool_free()`
Returns a block of memory to a memory pool. Return a block of memory to a memory pool.
:cpp:func:`task_mem_pool_defragment()` :cpp:func:`task_mem_pool_defragment()`
Defragments a memory pool. Defragment a memory pool.