Adds Memory Map documentation

Memory Map text and examples added to current Objects documentation.
Code-block type changed from console to c and syntax error with file
tag.

Change-Id: Ib350425b3512e0d19d3e6a4c66ca73120a622a97
Signed-off-by: Carol Lee <carol.lee@windriver.com>
This commit is contained in:
Carol Lee 2015-06-19 17:53:47 -04:00 committed by Anas Nashif
commit 1e6e8fb8ee

View file

@ -555,7 +555,7 @@ Example: Locking a Mutex with No Conditions
This code waits indefinitely for the mutex to become available if the
mutex is in use.
.. code-block:: console
.. code-block:: c
task_mutex_lock_wait(XYZ);
moveto(100,100);
@ -569,7 +569,7 @@ This code waits for a mutex to become available for a specified
time, and gives a warning if the mutex does not become available
in the specified amount of time.
.. code-block:: console
.. code-block:: c
if (task_mutex_lock_wait_timeout(XYZ, 100) == RC_OK)
{
@ -588,7 +588,7 @@ Example: Locking a Mutex with a No Blocking Condition
-----------------------------------------------------
This code gives an immediate warning when a mutex is in use.
.. code-block:: console
.. code-block:: c
if (task_mutex_lock(XYZ) == RC_OK);
{
@ -604,7 +604,7 @@ This code gives an immediate warning when a mutex is in use.
APIs
====
The following Mutex APIs are provided by microkernel.h.
The following Mutex APIs are provided by :file:`microkernel.h`.
+------------------------------------------+-----------------------------------+
| Call | Description |
@ -629,3 +629,154 @@ The following Mutex APIs are provided by microkernel.h.
| | and unlocks the mutex when the |
| | count reaches zero. |
+------------------------------------------+-----------------------------------+
MEMORY MAPS
***********
Concepts
========
The microkernel's memory map objects provide dynamic allocation and
release of fixed-size memory blocks.
Any number of memory maps can be defined in a microkernel system.
Each memory map has a name that uniquely identifies it.
In addition, a memory map defines the number of blocks it contains
and the size of each block in bytes.
The number of blocks and block size values cannot be zero.
The block size must be a multiple of the word size on most processors.
A task that needs to use a memory block simply allocates it from
a memory map. When all the blocks are currently in use, the task may
choose to wait for one to become available. When the task is finished
with a memory block, it must release the block back to the memory map
that allocated it so that the block can be reused.
Any number of tasks may wait on an empty memory map simultaneously;
when a memory block becomes available it is given to the
highest priority task that has waited the longest.
The microkernel manages memory blocks in an efficient and deterministic
manner that eliminates the risk of memory fragmentation problems
which can arise when using variable-size blocks.
Unlike a heap, more than one memory map can be defined, if needed. This
allows for a memory map with smaller blocks and others with larger-sized
blocks. (Alternatively, a memory pool object may be used.)
Purpose
=======
Use a memory map to allocate and free memory in fixed-size blocks.
Usage
=====
Defining a Memory Map
---------------------
Add an entry for one or more memory maps in the project file using the
following syntax:
.. code-block:: console
MAP %name %numBlocks %blockSize
For example, the file :file:`projName.mdef` defines a single memory map
as follows:
.. code-block:: console
% MAP NAME NUMBLOCKS BLOCKSIZE
% ======================================
MAP MYMAP 4 1024
MAP YOURMAP 6 200
Example: Requesting a Memory Block from a Map with No Conditions
----------------------------------------------------------------
This code waits indefinitely for a memory block to become
available if all the memory blocks are in use.
.. code-block:: c
char *block_ptr;
task_mem_map_alloc_wait(MYMAP, &block_ptr);
Example: Requesting a Memory Block from a Map with a Conditional Time-out
-------------------------------------------------------------------------
This code waits a specified amount of time for a memory block to become
available and gives a warning if the memory block does not become available
in the specified time.
.. code-block:: c
char *block_ptr;
if (task_mem_map_alloc_wait_timeout(MYMAP, &block_ptr, 5) == RC_OK)) {
/* utilize memory block */
} else {
printf("Memory allocation time-out");
}
Example: Requesting a Memory Block from a Map with a No Blocking Condition
--------------------------------------------------------------------------
This code gives an immediate warning when all memory blocks are in use.
.. code-block:: c
char *block_ptr;
if (task_mem_map_alloc(MYMAP, &block_ptr) == RC_OK) {
/* utilize memory block */
} else {
display_warning(); /* and do not allocate memory block*/
}
Example: Freeing a Memory Block back to a Map
---------------------------------------------
This code releases a memory block back when it is no longer needed.
.. code-block:: c
char *block_ptr;
task_mem_map_alloc_wait(MYMAP, &block_ptr);
/* use memory block */
task_mem_map_free(&block_ptr);
APIs
====
The following Memory Map APIs are provided by :file:`microkernel.h`.
+---------------------------------------------+-----------------------------------+
| Call | Description |
+=============================================+===================================+
| :c:func:`task_mem_map_alloc()` | Requests a block from a memory |
| | map. |
+---------------------------------------------+-----------------------------------+
| :c:func:`task_mem_map_alloc_wait()` | Waits on a block of memory until |
| | it is available. |
+---------------------------------------------+-----------------------------------+
| :c:func:`task_mem_map_alloc_wait_timeout()` | Waits on a block of memory for |
| | the period of time defined by the |
| | time-out parameter. |
+---------------------------------------------+-----------------------------------+
| :c:func:`task_mem_map_free()` | Returns a block to a memory map. |
+---------------------------------------------+-----------------------------------+
| :c:func:`task_mem_map_used_get()` | Returns the number of used blocks |
| | in a memory map. |
+---------------------------------------------+-----------------------------------+