zephyr/doc/kernel/microkernel/microkernel_memory_maps.rst

.. _memory_maps:

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 in MDEF File
==================================

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


Defining Memory Map in the Source Code
======================================

In addition to defining memory maps in MDEF file, it is also possible
to define memory maps inside code. The macro ``DEFINE_MEMORY_MAP(...)``
can be used for this purpose.

For example, the following code can be used to define a global memory
map ``PRIV_MEM_MAP``.

.. code-block:: c

   DEFINE_MEMORY_MAP(PRIV_MEM_MAP, num_blocks, block_size);

where the parameters are the same as memory maps defined in MDEF file.
The memory map ``PRIV_MEM_MAP`` can be used in the same style as those
defined in MDEF file.

It is possible to utilize this memory map in another source file, simply
add:

.. code-block:: c

   extern const kmemory_map_t PRIV_MEM_MAP;

to that file. The memory map ``PRIV_MEM_MAP`` can be then used there.


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.                  |
+---------------------------------------------+-----------------------------------+