Skip to content

Commit 43cb00d

Browse files
carlocaionenashif
carlocaione
authored and
nashif
committed
multi_heap: Introduce shared multi-heap memory pool manager
The shared multi-heap memory pool manager uses the multi-heap allocator to manage a set of reserved memory regions with different capabilities / attributes (cacheable, non-cacheable, etc...) defined in the DT. The user can request allocation from the shared pool specifying the capability / attribute of interest for the memory (cacheable / non-cacheable memory, etc...) Signed-off-by: Carlo Caione <ccaione@baylibre.com>
1 parent 863600c commit 43cb00d

File tree

13 files changed

+564
-0
lines changed

13 files changed

+564
-0
lines changed

‎doc/reference/memory_management/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ The following contains various topics regarding memory management.
99
:maxdepth: 1
1010

1111
demand_paging.rst
12+
shared_multi_heap.rst

‎doc/reference/memory_management/shared_multi_heap.rst

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
.. _memory_management_shared_multi_heap:
2+
3+
Shared Multi Heap
4+
#################
5+
6+
The shared multi-heap memory pool manager uses the multi-heap allocator to
7+
manage a set of reserved memory regions with different capabilities /
8+
attributes (cacheable, non-cacheable, etc...) defined in the DT.
9+
10+
The user can request allocation from the shared pool specifying the capability
11+
/ attribute of interest for the memory (cacheable / non-cacheable memory,
12+
etc...).
13+
14+
The different heaps with their attributes available in the shared pool are
15+
defined into the DT file leveraging the ``reserved-memory`` nodes.
16+
17+
This is a DT example declaring three different memory regions with different
18+
cacheability attributes: ``cacheable`` and ``non-cacheable``
19+
20+
.. code-block:: devicetree
21+
22+
/ {
23+
reserved-memory {
24+
compatible = "reserved-memory";
25+
#address-cells = <1>;
26+
#size-cells = <1>;
27+
28+
res0: reserved@42000000 {
29+
compatible = "shared-multi-heap";
30+
reg = <0x42000000 0x1000>;
31+
capability = "cacheable";
32+
label = "res0";
33+
};
34+
35+
res1: reserved@43000000 {
36+
compatible = "shared-multi-heap";
37+
reg = <0x43000000 0x2000>;
38+
capability = "non-cacheable";
39+
label = "res1";
40+
};
41+
42+
res2: reserved2@44000000 {
43+
compatible = "shared-multi-heap";
44+
reg = <0x44000000 0x3000>;
45+
capability = "cacheable";
46+
label = "res2";
47+
};
48+
};
49+
50+
The user can then request 4K from heap memory ``cacheable`` or
51+
``non-cacheable`` using the provided APIs:
52+
53+
.. code-block:: c
54+
55+
// Allocate 4K from cacheable memory
56+
shared_multi_heap_alloc(SMH_REG_ATTR_CACHEABLE, 0x1000);
57+
58+
// Allocate 4K from non-cacheable
59+
shared_multi_heap_alloc(SMH_REG_ATTR_NON_CACHEABLE, 0x1000);
60+
61+
The backend implementation will allocate the memory region from the heap with
62+
the correct attribute and using the region able to accommodate the required size.
63+
64+
Special handling for MMU/MPU
65+
****************************
66+
67+
For MMU/MPU enabled platform sometimes it is required to setup and configure
68+
the memory regions before these are added to the managed pool. This is done at
69+
init time using the :c:func:`shared_multi_heap_pool_init()` function that is
70+
accepting a :c:type:`smh_init_reg_fn_t` callback function. This callback will
71+
be called for each memory region at init time and it can be used to correctly
72+
map the region before this is considered valid and accessible.
73+
74+
Adding new attributes
75+
*********************
76+
77+
Currently only two memory attributes are supported: ``cacheable`` and
78+
``non-cacheable``. To add a new attribute:
79+
80+
1. Add the new ``enum`` for the attribute in the :c:enum:`smh_reg_attr`
81+
2. Add the corresponding attribute name in :file:`shared-multi-heap.yaml`
82+
83+
.. doxygengroup:: shared_multi_heap
84+
:project: Zephyr

‎dts/bindings/multi_heap_manager/shared-multi-heap.yaml

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
description: Shared multi-heap memory pool manager
2+
3+
compatible: "shared-multi-heap"
4+
5+
include:
6+
- name: base.yaml
7+
property-allowlist: ['reg', 'label']
8+
9+
properties:
10+
# Keep this is sync with shared_multi_heap.h
11+
capability:
12+
type: string
13+
required: false
14+
description: memory region capability
15+
enum:
16+
- "cacheable"
17+
- "non-cacheable"
18+
19+
label:
20+
required: true

‎include/multi_heap/shared_multi_heap.h

+122
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
/*
2+
* Copyright (c) 2021 Carlo Caione, <ccaione@baylibre.com>
3+
*
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
7+
#ifndef ZEPHYR_INCLUDE_MULTI_HEAP_MANAGER_SMH_H_
8+
#define ZEPHYR_INCLUDE_MULTI_HEAP_MANAGER_SMH_H_
9+
10+
11+
#ifdef __cplusplus
12+
extern "C" {
13+
#endif
14+
15+
/**
16+
* @brief Shared multi-heap interface
17+
* @defgroup shared_multi_heap Shared multi-heap interface
18+
* @ingroup multi_heap
19+
* @{
20+
*
21+
* The shared multi-heap manager uses the multi-heap allocator to manage a set
22+
* of reserved memory regions with different capabilities / attributes
23+
* (cacheable, non-cacheable, etc...) defined in the DT.
24+
*
25+
* The user can request allocation from the shared pool specifying the
26+
* capability / attribute of interest for the memory (cacheable / non-cacheable
27+
* memory, etc...)
28+
*
29+
*/
30+
31+
/**
32+
* @brief Memory region attributes / capabilities
33+
*
34+
* ** This list needs to be kept in sync with shared-multi-heap.yaml **
35+
*/
36+
enum smh_reg_attr {
37+
/** cacheable */
38+
SMH_REG_ATTR_CACHEABLE,
39+
40+
/** non-cacheable */
41+
SMH_REG_ATTR_NON_CACHEABLE,
42+
43+
/** must be the last item */
44+
SMH_REG_ATTR_NUM,
45+
};
46+
47+
/**
48+
* @brief SMH region struct
49+
*
50+
* This struct is carrying information about the memory region to be added in
51+
* the multi-heap pool. This is filled by the manager with the information
52+
* coming from the reserved memory children nodes in the DT.
53+
*/
54+
struct shared_multi_heap_region {
55+
enum smh_reg_attr attr;
56+
uintptr_t addr;
57+
size_t size;
58+
};
59+
60+
/**
61+
* @brief Region init function
62+
*
63+
* This is a user-provided function whose responsibility is to setup or
64+
* initialize the memory region passed in input before this is added to the
65+
* heap pool by the shared multi-heap manager. This function can be used by
66+
* architectures using MMU / MPU that must correctly map the region before this
67+
* is considered valid and accessible.
68+
*
69+
* @param reg Pointer to the SMH region structure.
70+
* @param v_addr Virtual address obtained after mapping. For non-MMU
71+
* architectures this value is the physical address of the
72+
* region.
73+
* @param size Size of the region after mapping.
74+
*
75+
* @return True if the region is ready to be added to the heap pool.
76+
* False if the region must be skipped.
77+
*/
78+
typedef bool (*smh_init_reg_fn_t)(struct shared_multi_heap_region *reg,
79+
uint8_t **v_addr, size_t *size);
80+
81+
82+
/**
83+
* @brief Init the pool
84+
*
85+
* Initialize the shared multi-heap pool and hook-up the region init function.
86+
*
87+
* @param smh_init_reg_fn The function pointer to the region init function. Can
88+
* be NULL for non-MPU / non-MMU architectures.
89+
*/
90+
int shared_multi_heap_pool_init(smh_init_reg_fn_t smh_init_reg_fn);
91+
92+
/**
93+
* @brief Allocate memory from the memory shared multi-heap pool
94+
*
95+
* Allocate a block of memory of the specified size in bytes and with a
96+
* specified capability / attribute.
97+
*
98+
* @param attr Capability / attribute requested for the memory block.
99+
* @param bytes Requested size of the allocation in bytes.
100+
*
101+
* @return A valid pointer to heap memory or NULL if no memory is available.
102+
*/
103+
void *shared_multi_heap_alloc(enum smh_reg_attr attr, size_t bytes);
104+
105+
/**
106+
* @brief Free memory from the shared multi-heap pool
107+
*
108+
* Free the passed block of memory.
109+
*
110+
* @param block Block to free.
111+
*/
112+
void shared_multi_heap_free(void *block);
113+
114+
/**
115+
* @}
116+
*/
117+
118+
#ifdef __cplusplus
119+
}
120+
#endif
121+
122+
#endif /* ZEPHYR_INCLUDE_MULTI_HEAP_MANAGER_SMH_H_ */

‎lib/os/CMakeLists.txt

+2
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ zephyr_sources_ifdef(CONFIG_SCHED_DEADLINE p4wq.c)
4343

4444
zephyr_sources_ifdef(CONFIG_REBOOT reboot.c)
4545

46+
zephyr_sources_ifdef(CONFIG_SHARED_MULTI_HEAP shared_multi_heap.c)
47+
4648
zephyr_library_include_directories(
4749
${ZEPHYR_BASE}/kernel/include
4850
${ZEPHYR_BASE}/arch/${ARCH}/include

‎lib/os/Kconfig

+8
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,14 @@ config MPSC_PBUF
6363
storing variable length packets in a circular way and operate directly
6464
on the buffer memory.
6565

66+
config SHARED_MULTI_HEAP
67+
bool "Shared multi-heap manager"
68+
help
69+
Enable support for a shared multi-heap manager that uses the
70+
multi-heap allocator to manage a set of reserved memory regions with
71+
different capabilities / attributes (cacheable, non-cacheable,
72+
etc...) defined in the DT.
73+
6674
if MPSC_PBUF
6775
config MPSC_CLEAR_ALLOCATED
6876
bool "Clear allocated packet"

‎lib/os/shared_multi_heap.c

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
/*
2+
* Copyright (c) 2021 Carlo Caione, <ccaione@baylibre.com>
3+
*
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
7+
#include <zephyr.h>
8+
#include <device.h>
9+
#include <sys/sys_heap.h>
10+
#include <sys/multi_heap.h>
11+
#include <linker/linker-defs.h>
12+
13+
#include <multi_heap/shared_multi_heap.h>
14+
15+
#define DT_DRV_COMPAT shared_multi_heap
16+
17+
#define NUM_REGIONS DT_NUM_INST_STATUS_OKAY(DT_DRV_COMPAT)
18+
19+
static struct sys_multi_heap shared_multi_heap;
20+
static struct sys_heap heap_pool[SMH_REG_ATTR_NUM][NUM_REGIONS];
21+
22+
static smh_init_reg_fn_t smh_init_reg;
23+
24+
#define FOREACH_REG(n) \
25+
{ .addr = (uintptr_t) LINKER_DT_RESERVED_MEM_GET_PTR(DT_DRV_INST(n)), \
26+
.size = LINKER_DT_RESERVED_MEM_GET_SIZE(DT_DRV_INST(n)), \
27+
.attr = DT_ENUM_IDX(DT_DRV_INST(n), capability), \
28+
},
29+
30+
static struct shared_multi_heap_region dt_region[NUM_REGIONS] = {
31+
DT_INST_FOREACH_STATUS_OKAY(FOREACH_REG)
32+
};
33+
34+
static void *smh_choice(struct sys_multi_heap *mheap, void *cfg, size_t align, size_t size)
35+
{
36+
enum smh_reg_attr attr;
37+
struct sys_heap *h;
38+
void *block;
39+
40+
attr = (enum smh_reg_attr) cfg;
41+
42+
if (attr >= SMH_REG_ATTR_NUM || size == 0) {
43+
return NULL;
44+
}
45+
46+
for (size_t reg = 0; reg < NUM_REGIONS; reg++) {
47+
h = &heap_pool[attr][reg];
48+
49+
if (h->heap == NULL) {
50+
return NULL;
51+
}
52+
53+
block = sys_heap_aligned_alloc(h, align, size);
54+
if (block != NULL) {
55+
break;
56+
}
57+
}
58+
59+
return block;
60+
}
61+
62+
static void smh_init_with_attr(enum smh_reg_attr attr)
63+
{
64+
unsigned int slot = 0;
65+
uint8_t *mapped;
66+
size_t size;
67+
68+
for (size_t reg = 0; reg < NUM_REGIONS; reg++) {
69+
if (dt_region[reg].attr == attr) {
70+
71+
if (smh_init_reg != NULL) {
72+
smh_init_reg(&dt_region[reg], &mapped, &size);
73+
} else {
74+
mapped = (uint8_t *) dt_region[reg].addr;
75+
size = dt_region[reg].size;
76+
}
77+
78+
sys_heap_init(&heap_pool[attr][slot], mapped, size);
79+
sys_multi_heap_add_heap(&shared_multi_heap, &heap_pool[attr][slot]);
80+
81+
slot++;
82+
}
83+
}
84+
}
85+
86+
void shared_multi_heap_free(void *block)
87+
{
88+
sys_multi_heap_free(&shared_multi_heap, block);
89+
}
90+
91+
void *shared_multi_heap_alloc(enum smh_reg_attr attr, size_t bytes)
92+
{
93+
return sys_multi_heap_alloc(&shared_multi_heap, (void *) attr, bytes);
94+
}
95+
96+
int shared_multi_heap_pool_init(smh_init_reg_fn_t smh_init_reg_fn)
97+
{
98+
smh_init_reg = smh_init_reg_fn;
99+
100+
sys_multi_heap_init(&shared_multi_heap, smh_choice);
101+
102+
for (size_t attr = 0; attr < SMH_REG_ATTR_NUM; attr++) {
103+
smh_init_with_attr(attr);
104+
}
105+
106+
return 0;
107+
}
108+
109+
static int shared_multi_heap_init(const struct device *dev)
110+
{
111+
__ASSERT_NO_MSG(NUM_REGIONS <= MAX_MULTI_HEAPS);
112+
113+
/* Nothing to do here. */
114+
115+
return 0;
116+
}
117+
SYS_INIT(shared_multi_heap_init, POST_KERNEL, CONFIG_KERNEL_INIT_PRIORITY_DEFAULT);

‎tests/kernel/mem_heap/shared_multi_heap/CMakeLists.txt

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# SPDX-License-Identifier: Apache-2.0
2+
3+
cmake_minimum_required(VERSION 3.20.0)
4+
5+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
6+
project(shared_multi_heap_pool)
7+
8+
target_sources(app PRIVATE src/main.c)

0 commit comments

Comments
 (0)