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
Anas Nashif
parent
ac3fdf0be1
commit
1e6e8fb8ee
1 changed files with 155 additions and 4 deletions
|
|
@ -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. |
|
||||
+---------------------------------------------+-----------------------------------+
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue