1.. _memory_slabs_v2:
2
3Memory Slabs
4############
5
6A :dfn:`memory slab` is a kernel object that allows memory blocks
7to be dynamically allocated from a designated memory region.
8All memory blocks in a memory slab have a single fixed size,
9allowing them to be allocated and released efficiently
10and avoiding memory fragmentation concerns.
11
12.. contents::
13    :local:
14    :depth: 2
15
16Concepts
17********
18
19Any number of memory slabs can be defined (limited only by available RAM). Each
20memory slab is referenced by its memory address.
21
22A memory slab has the following key properties:
23
24* The **block size** of each block, measured in bytes.
25  It must be at least 4N bytes long, where N is greater than 0.
26
27* The **number of blocks** available for allocation.
28  It must be greater than zero.
29
30* A **buffer** that provides the memory for the memory slab's blocks.
31  It must be at least "block size" times "number of blocks" bytes long.
32
33The memory slab's buffer must be aligned to an N-byte boundary, where
34N is a power of 2 larger than 2 (i.e. 4, 8, 16, ...). To ensure that
35all memory blocks in the buffer are similarly aligned to this boundary,
36the block size must also be a multiple of N.
37
38A memory slab must be initialized before it can be used. This marks all of
39its blocks as unused.
40
41A thread that needs to use a memory block simply allocates it from a memory
42slab. When the thread finishes with a memory block,
43it must release the block back to the memory slab so the block can be reused.
44
45If all the blocks are currently in use, a thread can optionally wait
46for one to become available.
47Any number of threads may wait on an empty memory slab simultaneously;
48when a memory block becomes available, it is given to the highest-priority
49thread that has waited the longest.
50
51Unlike a heap, more than one memory slab can be defined, if needed. This
52allows for a memory slab with smaller blocks and others with larger-sized
53blocks. Alternatively, a memory pool object may be used.
54
55Internal Operation
56==================
57
58A memory slab's buffer is an array of fixed-size blocks,
59with no wasted space between the blocks.
60
61The memory slab keeps track of unallocated blocks using a linked list;
62the first 4 bytes of each unused block provide the necessary linkage.
63
64Implementation
65**************
66
67Defining a Memory Slab
68======================
69
70A memory slab is defined using a variable of type :c:type:`k_mem_slab`.
71It must then be initialized by calling :c:func:`k_mem_slab_init`.
72
73The following code defines and initializes a memory slab that has 6 blocks
74that are 400 bytes long, each of which is aligned to a 4-byte boundary..
75
76.. code-block:: c
77
78    struct k_mem_slab my_slab;
79    char __aligned(4) my_slab_buffer[6 * 400];
80
81    k_mem_slab_init(&my_slab, my_slab_buffer, 400, 6);
82
83Alternatively, a memory slab can be defined and initialized at compile time
84by calling :c:macro:`K_MEM_SLAB_DEFINE`.
85
86The following code has the same effect as the code segment above. Observe
87that the macro defines both the memory slab and its buffer.
88
89.. code-block:: c
90
91    K_MEM_SLAB_DEFINE(my_slab, 400, 6, 4);
92
93Similarly, you can define a memory slab in private scope:
94
95.. code-block:: c
96
97    K_MEM_SLAB_DEFINE_STATIC(my_slab, 400, 6, 4);
98
99Allocating a Memory Block
100=========================
101
102A memory block is allocated by calling :c:func:`k_mem_slab_alloc`.
103
104The following code builds on the example above, and waits up to 100 milliseconds
105for a memory block to become available, then fills it with zeroes.
106A warning is printed if a suitable block is not obtained.
107
108.. code-block:: c
109
110    char *block_ptr;
111
112    if (k_mem_slab_alloc(&my_slab, &block_ptr, 100) == 0)) {
113        memset(block_ptr, 0, 400);
114	...
115    } else {
116        printf("Memory allocation time-out");
117    }
118
119Releasing a Memory Block
120========================
121
122A memory block is released by calling :c:func:`k_mem_slab_free`.
123
124The following code builds on the example above, and allocates a memory block,
125then releases it once it is no longer needed.
126
127.. code-block:: c
128
129    char *block_ptr;
130
131    k_mem_slab_alloc(&my_slab, &block_ptr, K_FOREVER);
132    ... /* use memory block pointed at by block_ptr */
133    k_mem_slab_free(&my_slab, &block_ptr);
134
135Suggested Uses
136**************
137
138Use a memory slab to allocate and free memory in fixed-size blocks.
139
140Use memory slab blocks when sending large amounts of data from one thread
141to another, to avoid unnecessary copying of the data.
142
143Configuration Options
144*********************
145
146Related configuration options:
147
148* :kconfig:option:`CONFIG_MEM_SLAB_TRACE_MAX_UTILIZATION`
149
150API Reference
151*************
152
153.. doxygengroup:: mem_slab_apis
154