memkit/include/memkit_config.h at main · NetKit-Labs/memkit · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
#ifndef MEMKIT_CONFIG_H
#define MEMKIT_CONFIG_H

/*
 * memkit build-time memory and platform policy.
 *
 * Targets
 *   MCU (bare-metal): zero-cost STL only; no heap, no mmap, no heap STL via memkit.
 *   MPU (embedded Linux, macOS, Windows host): heap and optional virtual backing;
 *     heap STL optional (MEMKIT_USE_STL). EMBEDDED_LINUX=1 on Linux; optional elsewhere.
 *
 * Zero-cost STL (std::array, std::span, std::optional, std::less, …) is always
 * available via include/memkit/stl.hpp on both MCU and MPU.
 *
 * Memory models
 *   MEMKIT_MEMORY_FIXED_BUFFER  caller-owned static storage
 *   MEMKIT_MEMORY_FIXED_POOL    fixed-size object slab
 *   MEMKIT_MEMORY_ARENA         bump allocator (default backing for both targets)
 *   MEMKIT_MEMORY_HEAP          malloc/free (MPU only)
 *   MEMKIT_MEMORY_MMAP          virtual-memory arena backing (MPU only: mmap or VirtualAlloc)
 *
 * Design rationale: docs/DESIGN_PHILOSOPHY.md
 */

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef enum memkit_memory_model {
    MEMKIT_MEMORY_FIXED_BUFFER = 0,
    MEMKIT_MEMORY_FIXED_POOL   = 1,
    MEMKIT_MEMORY_ARENA        = 2,
    MEMKIT_MEMORY_HEAP         = 3,
    MEMKIT_MEMORY_MMAP         = 4,
} memkit_memory_model_t;

#ifdef __cplusplus
}
#endif

/* --- Platform detection --------------------------------------------------- */

#if (defined(MEMKIT_MPU) && MEMKIT_MPU) || (defined(EMBEDDED_LINUX) && EMBEDDED_LINUX)
#define MEMKIT_TARGET_MPU 1
#define MEMKIT_TARGET_MCU 0
#else
#define MEMKIT_TARGET_MPU 0
#define MEMKIT_TARGET_MCU 1
#endif

/* --- Feature gates -------------------------------------------------------- */

#if MEMKIT_TARGET_MPU

#ifndef MEMKIT_ALLOW_HEAP
#define MEMKIT_ALLOW_HEAP 1
#endif

#ifndef MEMKIT_ALLOW_MMAP
#define MEMKIT_ALLOW_MMAP 1
#endif

#ifndef MEMKIT_DEFAULT_ARENA_BACKING
#define MEMKIT_DEFAULT_ARENA_BACKING MEMKIT_MEMORY_MMAP
#endif

#ifndef MEMKIT_USE_STL
#define MEMKIT_USE_STL 0
#endif

#else /* MEMKIT_TARGET_MCU */

#ifndef MEMKIT_ALLOW_HEAP
#define MEMKIT_ALLOW_HEAP 0
#endif

#ifndef MEMKIT_ALLOW_MMAP
#define MEMKIT_ALLOW_MMAP 0
#endif

#ifndef MEMKIT_DEFAULT_ARENA_BACKING
#define MEMKIT_DEFAULT_ARENA_BACKING MEMKIT_MEMORY_FIXED_BUFFER
#endif

#ifndef MEMKIT_USE_STL
#define MEMKIT_USE_STL 0
#endif

#endif /* MEMKIT_TARGET_MPU / MEMKIT_TARGET_MCU */

/* --- C API tiering -------------------------------------------------------- */
/*
 * The C API is split into two tiers to keep MCU firmware images small.
 *
 * Tier 1 (MEMKIT_C_API_FULL): always enabled on every target.
 *   ring, vector, stack, queue, bitset, objpool, handle_pool, arena
 *
 * Tier 2 (MEMKIT_C_API_EXTENDED): enabled on MPU; stubbed on MCU.
 *   hashmap, btree, pqueue, list, dlist, lrucache, deque
 *
 * When MEMKIT_C_API_EXTENDED is 0, tier-2 headers still declare the API but
 * init/create return *_ERR_UNSUPPORTED and accessors are no-ops so links succeed.
 *
 * C++ users: include <memkit/memkit.hpp> for all containers on any target.
 * C users on MCU firmware: use tier-1 C API only; prefer C++ memkit.hpp when
 * you need tier-2 containers.
 */
#define MEMKIT_C_API_FULL 1

#if MEMKIT_TARGET_MPU
#define MEMKIT_C_API_EXTENDED 1
#else
#define MEMKIT_C_API_EXTENDED 0
#endif

/* --- STL policy ----------------------------------------------------------- */
/*
 * MCU: zero-cost STL only (array, span, optional, less, …). Heap STL is not
 * exposed via memkit. Programmers may use std::vector/string on their own.
 * MPU: optional heap STL aliases when MEMKIT_USE_STL=1.
 */
#if MEMKIT_TARGET_MCU
#if MEMKIT_USE_STL
#error "MEMKIT_USE_STL is not supported on MCU; memkit exposes zero-cost STL only"
#endif
#undef MEMKIT_USE_STL
#define MEMKIT_USE_STL 0
#define MEMKIT_ALLOW_HEAP_STL 0
#elif MEMKIT_TARGET_MPU && MEMKIT_USE_STL
#define MEMKIT_ALLOW_HEAP_STL 1
#else
#define MEMKIT_ALLOW_HEAP_STL 0
#endif

#ifndef MEMKIT_ALLOW_HEAP_STL
#define MEMKIT_ALLOW_HEAP_STL 0
#endif

#endif /* MEMKIT_CONFIG_H */