diff --git a/.github/workflows/platformio.yml b/.github/workflows/platformio.yml new file mode 100644 index 0000000..6c83781 --- /dev/null +++ b/.github/workflows/platformio.yml @@ -0,0 +1,59 @@ +name: PlatformIO + +# Builds examples/platformio/xallocator-demo for every board in its +# platformio.ini, and runs the native build on the desktop. The example's +# lib_deps points at this checkout, so each push tests the library as +# PlatformIO users consume it (library.json, srcFilter). + +on: + push: + branches: + - master + pull_request: + branches: + - master + +# Least privilege for GITHUB_TOKEN: these jobs only check out code. +permissions: + contents: read + +jobs: + build: + name: ${{ matrix.env }} + runs-on: ubuntu-latest + + strategy: + fail-fast: false + matrix: + env: [esp32dev, esp32-c3, nucleo_f401re, disco_f407vg, pico, native] + + defaults: + run: + working-directory: examples/platformio/xallocator-demo + + steps: + - name: Checkout code + uses: actions/checkout@v7 + + - name: Cache PlatformIO + uses: actions/cache@v4 + with: + path: | + ~/.cache/pip + ~/.platformio + key: pio-${{ matrix.env }}-${{ hashFiles('examples/platformio/xallocator-demo/platformio.ini') }} + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install PlatformIO + run: pip install --upgrade platformio + + - name: Build + run: pio run -e ${{ matrix.env }} + + - name: Run (native) + if: matrix.env == 'native' + run: pio run -e native -t exec diff --git a/.github/workflows/rtos_locks.yml b/.github/workflows/rtos_locks.yml new file mode 100644 index 0000000..989a1bd --- /dev/null +++ b/.github/workflows/rtos_locks.yml @@ -0,0 +1,63 @@ +name: RTOS Locks + +# Compiles xallocator.cpp for Cortex-M4 with each RTOS lock option against the +# real vendor headers (compile only: no link, no run). XALLOC_LOCK_FREERTOS is +# built and run by the PlatformIO workflow (env:disco_f407vg) instead. + +on: + push: + branches: + - master + pull_request: + branches: + - master + +# Least privilege for GITHUB_TOKEN: these jobs only check out code. +permissions: + contents: read + +jobs: + compile: + name: ${{ matrix.lock }} + runs-on: ubuntu-latest + timeout-minutes: 15 + + strategy: + fail-fast: false + matrix: + lock: [XALLOC_LOCK_THREADX, XALLOC_LOCK_CMSIS_RTOS2, XALLOC_LOCK_USER, XALLOC_LOCK_NONE] + + steps: + - name: Checkout code + uses: actions/checkout@v7 + + - name: Install ARM GCC toolchain + uses: carlosperate/arm-none-eabi-gcc-action@v1 + with: + release: '14.2.Rel1' + + # Only the headers the lock needs, from the upstream repositories + - name: Fetch RTOS headers + run: | + mkdir -p /tmp/threadx /tmp/cmsis + curl -sfL -o /tmp/threadx/tx_api.h \ + https://raw.githubusercontent.com/eclipse-threadx/threadx/master/common/inc/tx_api.h + curl -sfL -o /tmp/threadx/tx_port.h \ + https://raw.githubusercontent.com/eclipse-threadx/threadx/master/ports/cortex_m4/gnu/inc/tx_port.h + curl -sfL -o /tmp/cmsis/cmsis_compiler.h \ + https://raw.githubusercontent.com/ARM-software/CMSIS_5/develop/CMSIS/Core/Include/cmsis_compiler.h + curl -sfL -o /tmp/cmsis/cmsis_gcc.h \ + https://raw.githubusercontent.com/ARM-software/CMSIS_5/develop/CMSIS/Core/Include/cmsis_gcc.h + + # Heap blocks and static pools modes. -D__PROGRAM_START=1: cmsis_gcc.h's + # default startup code needs -fpermissive on newer GCC; a real target + # supplies its own startup code. + - name: Compile + run: | + for mode in "" "-DSTATIC_POOLS"; do + arm-none-eabi-g++ xallocator.cpp Allocator.cpp \ + -mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard \ + -std=gnu++11 -c -O2 -Wall -Wextra -Werror --specs=nano.specs -fno-exceptions \ + -D${{ matrix.lock }} -D__PROGRAM_START=1 $mode \ + -I /tmp/threadx -I /tmp/cmsis + done diff --git a/.gitignore b/.gitignore index 171921e..ca07393 100644 --- a/.gitignore +++ b/.gitignore @@ -303,4 +303,6 @@ __pycache__/ *.xsd.cs # OpenCover UI analysis results -OpenCover/ \ No newline at end of file +OpenCover/ +# PlatformIO build output +.pio/ diff --git a/README.md b/README.md index 7fd0327..5e8e89d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ -![License MIT](https://img.shields.io/github/license/BehaviorTree/BehaviorTree.CPP?color=blue) +![License MIT](https://img.shields.io/github/license/endurodave/xallocator?color=blue) [![conan Ubuntu](https://github.com/endurodave/xallocator/actions/workflows/cmake_ubuntu.yml/badge.svg)](https://github.com/endurodave/xallocator/actions/workflows/cmake_ubuntu.yml) [![conan Ubuntu](https://github.com/endurodave/xallocator/actions/workflows/cmake_clang.yml/badge.svg)](https://github.com/endurodave/xallocator/actions/workflows/cmake_clang.yml) [![conan Windows](https://github.com/endurodave/xallocator/actions/workflows/cmake_windows.yml/badge.svg)](https://github.com/endurodave/xallocator/actions/workflows/cmake_windows.yml) +[![PlatformIO](https://github.com/endurodave/xallocator/actions/workflows/platformio.yml/badge.svg)](https://github.com/endurodave/xallocator/actions/workflows/platformio.yml) +[![RTOS Locks](https://github.com/endurodave/xallocator/actions/workflows/rtos_locks.yml/badge.svg)](https://github.com/endurodave/xallocator/actions/workflows/rtos_locks.yml) # Replace malloc/free with a Fast Fixed Block Memory Allocator @@ -11,24 +13,24 @@ Originally published on CodeProject at: Allocator - An efficient C++ fixed-block memory allocator. @@ -121,7 +141,7 @@ strcpy(memory2, "TEST STRING"); memory2 = (char*)xrealloc(memory2, 124); xfree(memory2); -

xalloc_stats() outputs allocator usage statistics to the standard output stream. The output provides insight into how many Allocator instances are being used, blocks in use, block sizes, and more.

+

xalloc_stats() outputs allocator usage statistics with printf(). The output provides insight into how many Allocator instances are being used, blocks in use, block sizes, and more.

xalloc_init() must be called one time before any worker threads start, or in the case of an embedded system, before the OS starts. On a C++ application, this function is called automatically for you. However, it is desirable to call xalloc_init() manually is some cases, typically on an embedded system to avoid the small memory overhead involved with the automatic xalloc_init()/xalloc_destroy() call mechanism.

@@ -281,7 +301,7 @@ static Allocator* _allocators[MAX_ALLOCATORS]; extern "C" void xalloc_init() { #ifdef STATIC_POOLS - get_mutex().lock(); + XLockState lock = xlock(); // For STATIC_POOLS mode, the allocators must be initialized before any other // static user class constructor is run. Therefore, use placement new to initialize @@ -291,7 +311,7 @@ extern "C" void xalloc_init() // ... _allocators[9] = new (&_allocator4096) AllocatorPool<char[4096], MAX_BLOCKS>(); - get_mutex().unlock(); + xunlock(lock); #endif } @@ -300,7 +320,7 @@ extern "C" void xalloc_init()
 extern "C" void xalloc_destroy()
 {
-    get_mutex().lock();
+    XLockState lock = xlock();
 
 #ifdef STATIC_POOLS
     for (int i=0; i<MAX_ALLOCATORS; i++)
@@ -319,7 +339,7 @@ extern "C" void xalloc_destroy()
     }
 #endif
 
-    get_mutex().unlock();
+    xunlock(lock);
 }
# Hiding the Allocator Pointer @@ -336,11 +356,11 @@ extern "C" void *xmalloc(size_t size) return NULL; // Reuse a freed block if there is one - get_mutex().lock(); + XLockState lock = xlock(); void* blockMemoryPtr = allocator->Pop(); if (blockMemoryPtr != NULL) allocator->AccountAlloc(false); - get_mutex().unlock(); + xunlock(lock); if (blockMemoryPtr == NULL) { @@ -348,9 +368,9 @@ extern "C" void *xmalloc(size_t size) blockMemoryPtr = new (std::nothrow) char[allocator->GetBlockSize()]; if (blockMemoryPtr != NULL) { - get_mutex().lock(); + XLockState lock2 = xlock(); allocator->AccountAlloc(true); - get_mutex().unlock(); + xunlock(lock2); } } @@ -375,12 +395,12 @@ extern "C" void xfree(void* ptr) // Convert the client pointer into the original raw block pointer void* blockPtr = get_block_ptr(ptr); - get_mutex().lock(); + XLockState lock = xlock(); // Deallocate the block allocator->Deallocate(blockPtr); - get_mutex().unlock(); + xunlock(lock); } # Out of Memory @@ -389,9 +409,26 @@ extern "C" void xfree(void* ptr) # Porting Issues -

xallocator is thread-safe: a single std::mutex guards the allocator table and each Allocator. For a target without std::mutex, replace get_mutex() in xallocator.cpp with the fastest OS lock available. If your system is single threaded, the lock can do nothing.

+

xallocator is thread-safe: a single lock guards the allocator table and each Allocator. The lock is held only for a table search and a free-list push or pop; new blocks come from the heap outside it. On an RTOS, a short critical section therefore suits it better than a mutex: no kernel object, no priority inversion, and it works before the scheduler starts and inside interrupts.

+ +

The lock is selected at compile time. Define at most one option for the whole build (e.g. build_flags in platformio.ini, or add_compile_definitions() in CMake):

+ + + + + + + + + + +
OptionLock
(default)std::mutex when the C++ library provides it (Windows, Linux, macOS, ESP32); otherwise none
XALLOC_LOCK_FREERTOSFreeRTOS critical section: taskENTER_CRITICAL(), or taskENTER_CRITICAL_FROM_ISR() inside an interrupt on Cortex-M; a portENTER_CRITICAL_SAFE() spinlock on ESP32. No lock before the scheduler starts.
XALLOC_LOCK_THREADXtx_interrupt_control() interrupt masking
XALLOC_LOCK_ZEPHYRirq_lock()/irq_unlock()
XALLOC_LOCK_CMSIS_RTOS2Cortex-M PRIMASK interrupt masking (CMSIS-Core), for any CMSIS-RTOS2 kernel
XALLOC_LOCK_USERYour extern "C" void xalloc_lock() and void xalloc_unlock(). They may be called before main() and before the RTOS starts, so they must work then too.
XALLOC_LOCK_NONENo lock, for single-threaded systems
+ +

Bare-metal toolchains without threads support (e.g. arm-none-eabi as used by STM32duino and the Raspberry Pi Pico cores) have no std::mutex, so there the default is no lock: pick an RTOS option if xallocator is called from more than one task. In a DelegateMQ build, DMQ_THREAD_FREERTOS, DMQ_THREAD_THREADX, DMQ_THREAD_ZEPHYR and DMQ_THREAD_CMSIS_RTOS2 select the matching option automatically.

+ +

Calling xmalloc()/xfree() from an interrupt is possible only in STATIC_POOLS mode (heap blocks mode calls operator new) with an interrupt-masking option: FreeRTOS on Cortex-M or ESP32, ThreadX, Zephyr or CMSIS-RTOS2.

-

The mutex is created on first use and intentionally never destroyed. xallocator may be called before main() and after it returns, from static constructors and destructors, so the lock must exist before any static object uses it and still exist when the last one is destroyed.

+

The std::mutex is created on first use and intentionally never destroyed. xallocator may be called before main() and after it returns, from static constructors and destructors, so the lock must exist before any static object uses it and still exist when the last one is destroyed.

New blocks are taken from the heap outside the lock. Holding it while calling the heap risks a lock-order deadlock with the C++ library’s own heap locks.

diff --git a/examples/platformio/xallocator-demo/platformio.ini b/examples/platformio/xallocator-demo/platformio.ini new file mode 100644 index 0000000..937180a --- /dev/null +++ b/examples/platformio/xallocator-demo/platformio.ini @@ -0,0 +1,59 @@ +; xallocator PlatformIO example, also the board build matrix. +; +; pio run build every board below +; pio run -e esp32dev build one board +; pio run -e esp32dev -t upload -t monitor +; pio run -e native -t exec build and run on the desktop +; +; Copying this example into your own project? Change lib_deps to +; lib_deps = endurodave/xallocator@^1.1.0 +; (here it points at this repository so every commit is tested). + +[env] +lib_deps = symlink://../../.. +monitor_speed = 115200 + +; ESP32 (Xtensa, FreeRTOS): std::mutex is available, so xallocator locks with it +[env:esp32dev] +platform = espressif32 +board = esp32dev +framework = arduino + +; ESP32-C3 (RISC-V, FreeRTOS) +[env:esp32-c3] +platform = espressif32 +board = esp32-c3-devkitm-1 +framework = arduino + +; STM32 Nucleo-F401RE (Cortex-M4, bare metal): no std::mutex, so no lock +; (single-threaded). With an RTOS, add e.g. -DXALLOC_LOCK_FREERTOS. +[env:nucleo_f401re] +platform = ststm32 +board = nucleo_f401re +framework = arduino + +; STM32F4 Discovery (STM32F407VG Cortex-M4, FreeRTOS): two tasks share +; xallocator, locked by a FreeRTOS critical section (XALLOC_LOCK_FREERTOS). +; FreeRTOS comes from the STM32duino FreeRTOS library. +; Flashed over its ST-LINK/V2, which has no USB serial port: Serial goes to +; USART6 (TX PC6, RX PC7), 115200 8N1, through a 3.3 V USB-UART adapter. +[env:disco_f407vg] +platform = ststm32 +board = disco_f407vg +framework = arduino +upload_protocol = stlink +lib_deps = ${env.lib_deps} + stm32duino/STM32duino FreeRTOS@^10.3.2 +build_flags = -DXALLOC_LOCK_FREERTOS + -DSERIAL_UART_INSTANCE=6 -DPIN_SERIAL_TX=PC6 -DPIN_SERIAL_RX=PC7 + +; Raspberry Pi Pico (RP2040 Cortex-M0+, bare metal): no std::mutex, so no lock +[env:pico] +platform = https://github.com/maxgerhardt/platform-raspberrypi.git +board = pico +board_build.core = earlephilhower +framework = arduino + +; Desktop (Linux, macOS, or Windows with MinGW): locks with std::mutex +[env:native] +platform = native diff --git a/examples/platformio/xallocator-demo/src/main.cpp b/examples/platformio/xallocator-demo/src/main.cpp new file mode 100644 index 0000000..295b72d --- /dev/null +++ b/examples/platformio/xallocator-demo/src/main.cpp @@ -0,0 +1,167 @@ +// xallocator PlatformIO example: replace malloc/free and new/delete with +// fixed block allocations. Runs on Arduino boards and the desktop (native). +// +// @see https://github.com/endurodave/xallocator + +#include "xallocator.h" +#include +#include +#include + +#ifdef ARDUINO +#include +#endif + +#if defined(XALLOC_LOCK_FREERTOS) && defined(ARDUINO_ARCH_STM32) +// XALLOC_LOCK_FREERTOS: xallocator guards its data with a FreeRTOS critical +// section, so tasks can share it (see platformio.ini, env:disco_f407vg) +#include +#define USE_FREERTOS_TASKS +#endif + +static void Log(const char* msg) +{ +#ifdef ARDUINO + Serial.println(msg); +#else + printf("%s\n", msg); +#endif +} + +// XALLOCATOR routes this class's new/delete to xmalloc/xfree +class Point +{ + XALLOCATOR +public: + Point(int x, int y) : x(x), y(y) {} + int x, y; +}; + +// Allocate, fill, check and free blocks of many sizes. Returns false if a +// block was corrupted or an allocation failed. +static bool Stress(uint8_t pattern, int loops) +{ + const int COUNT = 16; + void* blocks[COUNT]; + for (int loop = 0; loop < loops; loop++) + { + for (int i = 0; i < COUNT; i++) + { + size_t size = 1 + (size_t)((loop * 7 + i * 13) % 200); + blocks[i] = xmalloc(size); + if (blocks[i] == NULL) + return false; + memset(blocks[i], pattern, size); + } + for (int i = 0; i < COUNT; i++) + { + size_t size = 1 + (size_t)((loop * 7 + i * 13) % 200); + const uint8_t* p = static_cast(blocks[i]); + for (size_t b = 0; b < size; b++) + if (p[b] != pattern) + return false; + xfree(blocks[i]); + } + } + return true; +} + +static bool Demo() +{ + char buf[80]; + + // xmalloc/xrealloc/xfree work like malloc/realloc/free + char* str = static_cast(xmalloc(16)); + if (str == NULL) + return false; + strcpy(str, "xallocator"); + str = static_cast(xrealloc(str, 64)); + if (str == NULL) + return false; + strcat(str, " fixed blocks"); + snprintf(buf, sizeof(buf), "xrealloc: \"%s\"", str); + Log(buf); + bool ok = strcmp(str, "xallocator fixed blocks") == 0; + xfree(str); + + // new/delete on an XALLOCATOR class + Point* pt = new Point(3, 4); + snprintf(buf, sizeof(buf), "new Point: (%d, %d)", pt->x, pt->y); + Log(buf); + ok = ok && pt->x == 3 && pt->y == 4; + delete pt; + + // A freed block is kept for reuse, not returned to the heap + void* a = xmalloc(40); + xfree(a); + void* b = xmalloc(40); + snprintf(buf, sizeof(buf), "Block reused: %s", a == b ? "yes" : "no"); + Log(buf); + ok = ok && a == b; + xfree(b); + + return ok; +} + +#ifdef USE_FREERTOS_TASKS +static volatile bool g_taskOk[2] = { true, true }; +static volatile int g_taskDone = 0; + +// Two of these run at once, sharing xallocator's blocks +static void StressTask(void* arg) +{ + int id = (int)(intptr_t)arg; + for (int round = 0; round < 50; round++) + { + if (!Stress((uint8_t)(0xA0 + id), 10)) + g_taskOk[id] = false; + vTaskDelay(1); + } + taskENTER_CRITICAL(); + g_taskDone = g_taskDone + 1; + taskEXIT_CRITICAL(); + vTaskDelete(NULL); +} + +static void MainTask(void*) +{ + bool ok = Demo(); + xTaskCreate(StressTask, "Stress0", 512, (void*)0, 1, NULL); + xTaskCreate(StressTask, "Stress1", 512, (void*)1, 1, NULL); + while (g_taskDone < 2) + vTaskDelay(10); + bool tasksOk = g_taskOk[0] && g_taskOk[1]; + Log(tasksOk ? "Two task stress test: passed" : "Two task stress test: FAILED"); + Log(ok && tasksOk ? "xallocator demo PASSED" : "xallocator demo FAILED"); + vTaskDelete(NULL); +} +#endif + +#ifdef ARDUINO +void setup() +{ + Serial.begin(115200); + delay(1000); + Log("xallocator demo"); +#ifdef USE_FREERTOS_TASKS + xTaskCreate(MainTask, "Main", 1024, NULL, 2, NULL); + vTaskStartScheduler(); +#else + bool ok = Demo() && Stress(0x5A, 100); + Log(ok ? "xallocator demo PASSED" : "xallocator demo FAILED"); +#endif +} + +void loop() +{ +} +#else +int main() +{ + Log("xallocator demo"); + bool ok = Demo() && Stress(0x5A, 100); + xalloc_stats(); + Log(ok ? "xallocator demo PASSED" : "xallocator demo FAILED"); + return ok ? 0 : 1; +} +#endif diff --git a/library.json b/library.json new file mode 100644 index 0000000..8167348 --- /dev/null +++ b/library.json @@ -0,0 +1,33 @@ +{ + "name": "xallocator", + "version": "1.1.0", + "description": "Fast fixed block memory allocator replacing malloc/free and new/delete. Prevents heap fragmentation; thread-safe; optional static pools for heap-free embedded systems.", + "keywords": ["allocator", "memory", "memory pool", "fixed block", "malloc", "heap", "embedded", "cpp"], + "repository": { "type": "git", "url": "https://github.com/endurodave/xallocator.git" }, + "authors": [{ "name": "David Lafreniere", "url": "https://github.com/endurodave", "maintainer": true }], + "license": "MIT", + "homepage": "https://github.com/endurodave/xallocator", + "frameworks": "*", + "platforms": "*", + "headers": "xallocator.h", + "export": { + "include": [ + "xallocator.cpp", "xallocator.h", "Allocator.cpp", "Allocator.h", + "LICENSE", "README.md", "library.json", + "examples/platformio/xallocator-demo/platformio.ini", + "examples/platformio/xallocator-demo/src/main.cpp" + ] + }, + "build": { + "srcDir": ".", + "includeDir": ".", + "srcFilter": ["-<*>", "+", "+"] + }, + "examples": [ + { + "name": "xallocator-demo", + "base": "examples/platformio/xallocator-demo", + "files": ["platformio.ini", "src/main.cpp"] + } + ] +} diff --git a/xallocator.cpp b/xallocator.cpp index 936b357..209a6c6 100644 --- a/xallocator.cpp +++ b/xallocator.cpp @@ -2,8 +2,7 @@ #include "xallocator.h" #include #include -#include -#include +#include #include using namespace std; @@ -91,15 +90,175 @@ T nexthigher(T k) return k+1; } -static std::mutex& get_mutex() +// Lock guarding the allocator table and each Allocator. It is held only for a +// table search and a free-list push or pop (heap calls are made outside it), so +// on an RTOS a short critical section fits better than a mutex: no kernel +// object, no priority inversion, and it works before the scheduler starts. +// Selected at compile time; define at most one option for the whole build: +// +// (default) std::mutex, when the C++ library provides it +// (Windows, Linux, macOS, ESP32); otherwise none. +// XALLOC_LOCK_FREERTOS FreeRTOS critical section (taskENTER_CRITICAL, or +// the _FROM_ISR form inside an interrupt on Cortex-M; +// portENTER_CRITICAL_SAFE spinlock on ESP32). +// XALLOC_LOCK_THREADX ThreadX tx_interrupt_control() interrupt masking. +// XALLOC_LOCK_ZEPHYR Zephyr irq_lock()/irq_unlock(). +// XALLOC_LOCK_CMSIS_RTOS2 Cortex-M PRIMASK interrupt masking (CMSIS-Core), +// for any CMSIS-RTOS2 kernel (RTX5, FreeRTOS, ...). +// XALLOC_LOCK_USER you define extern "C" void xalloc_lock() and +// void xalloc_unlock(). They may be called before +// main() and before the RTOS starts, so they must +// work then too. +// XALLOC_LOCK_NONE no lock: single-threaded use only. +// +// DelegateMQ's DMQ_THREAD_FREERTOS, _THREADX, _ZEPHYR and _CMSIS_RTOS2 select +// the matching option. Bare-metal toolchains without threads support (e.g. +// arm-none-eabi as used by STM32duino and Arduino-Pico) have no std::mutex, so +// there the default is XALLOC_LOCK_NONE: pick an RTOS option if xallocator is +// called from more than one task. +// +// Calling xmalloc()/xfree() from an interrupt: only with STATIC_POOLS (heap +// blocks mode calls operator new) and an interrupt-masking option (FreeRTOS on +// Cortex-M or ESP32, ThreadX, Zephyr, CMSIS-RTOS2). +#if !defined(XALLOC_LOCK_FREERTOS) && !defined(XALLOC_LOCK_THREADX) && \ + !defined(XALLOC_LOCK_ZEPHYR) && !defined(XALLOC_LOCK_CMSIS_RTOS2) && \ + !defined(XALLOC_LOCK_USER) && !defined(XALLOC_LOCK_NONE) + #if defined(DMQ_THREAD_FREERTOS) + #define XALLOC_LOCK_FREERTOS + #elif defined(DMQ_THREAD_THREADX) + #define XALLOC_LOCK_THREADX + #elif defined(DMQ_THREAD_ZEPHYR) + #define XALLOC_LOCK_ZEPHYR + #elif defined(DMQ_THREAD_CMSIS_RTOS2) + #define XALLOC_LOCK_CMSIS_RTOS2 + #elif defined(__GLIBCXX__) && !defined(_GLIBCXX_HAS_GTHREADS) + #define XALLOC_LOCK_NONE + #endif +#endif + +#if (defined(XALLOC_LOCK_FREERTOS) + defined(XALLOC_LOCK_THREADX) + \ + defined(XALLOC_LOCK_ZEPHYR) + defined(XALLOC_LOCK_CMSIS_RTOS2) + \ + defined(XALLOC_LOCK_USER) + defined(XALLOC_LOCK_NONE)) > 1 + #error "Define only one XALLOC_LOCK_ option" +#endif + +/// State saved by xlock() and restored by xunlock(), e.g. the interrupt mask. +/// Kept on the caller's stack, so nested and interrupt-context locks each +/// restore their own state. +struct XLockState { - // Intentionally never destroyed. A function-local static mutex would be - // destroyed during static destruction, and a static object destroyed after - // it that calls xfree() or xalloc_destroy() would lock a destroyed mutex. - // The OS reclaims the memory at process exit. - static std::mutex* _mutex = new std::mutex(); - return *_mutex; -} + unsigned long saved; + int mode; +}; + +#if defined(XALLOC_LOCK_FREERTOS) + #if defined(ESP_PLATFORM) + #include "freertos/FreeRTOS.h" + #include "freertos/task.h" + // ESP32 cores share one spinlock; the _SAFE forms work in tasks and ISRs + static portMUX_TYPE _xallocMux = portMUX_INITIALIZER_UNLOCKED; + static inline XLockState xlock() + { + portENTER_CRITICAL_SAFE(&_xallocMux); + XLockState state = { 0, 0 }; + return state; + } + static inline void xunlock(XLockState) { portEXIT_CRITICAL_SAFE(&_xallocMux); } + #else + #include "FreeRTOS.h" + #include "task.h" + enum { XLOCK_NONE, XLOCK_TASK, XLOCK_ISR }; + static inline XLockState xlock() + { + XLockState state = { 0, XLOCK_NONE }; + #if (INCLUDE_xTaskGetSchedulerState == 1) || (configUSE_TIMERS == 1) + // Before the scheduler starts there is one thread of execution. + // A FreeRTOS critical section here would leave interrupts disabled + // until the scheduler starts, stalling e.g. Arduino delay() and Serial. + if (xTaskGetSchedulerState() == taskSCHEDULER_NOT_STARTED) + return state; + #endif + #if defined(__arm__) || defined(__ARM_ARCH) + if (xPortIsInsideInterrupt() != pdFALSE) + { + state.saved = (unsigned long)taskENTER_CRITICAL_FROM_ISR(); + state.mode = XLOCK_ISR; + return state; + } + #endif + taskENTER_CRITICAL(); + state.mode = XLOCK_TASK; + return state; + } + static inline void xunlock(XLockState state) + { + if (state.mode == XLOCK_ISR) + taskEXIT_CRITICAL_FROM_ISR((UBaseType_t)state.saved); + else if (state.mode == XLOCK_TASK) + taskEXIT_CRITICAL(); + } + #endif +#elif defined(XALLOC_LOCK_THREADX) + #include "tx_api.h" + static inline XLockState xlock() + { + XLockState state = { (unsigned long)tx_interrupt_control(TX_INT_DISABLE), 0 }; + return state; + } + static inline void xunlock(XLockState state) { tx_interrupt_control((UINT)state.saved); } +#elif defined(XALLOC_LOCK_ZEPHYR) + #include + static inline XLockState xlock() + { + XLockState state = { (unsigned long)irq_lock(), 0 }; + return state; + } + static inline void xunlock(XLockState state) { irq_unlock((unsigned int)state.saved); } +#elif defined(XALLOC_LOCK_CMSIS_RTOS2) + #include "cmsis_compiler.h" + static inline XLockState xlock() + { + XLockState state = { (unsigned long)__get_PRIMASK(), 0 }; + __disable_irq(); + return state; + } + static inline void xunlock(XLockState state) { __set_PRIMASK((uint32_t)state.saved); } +#elif defined(XALLOC_LOCK_USER) + extern "C" void xalloc_lock(); + extern "C" void xalloc_unlock(); + static inline XLockState xlock() + { + xalloc_lock(); + XLockState state = { 0, 0 }; + return state; + } + static inline void xunlock(XLockState) { xalloc_unlock(); } +#elif defined(XALLOC_LOCK_NONE) + static inline XLockState xlock() + { + XLockState state = { 0, 0 }; + return state; + } + static inline void xunlock(XLockState) {} +#else + #include + static std::mutex& get_mutex() + { + // Intentionally never destroyed. A function-local static mutex would be + // destroyed during static destruction, and a static object destroyed after + // it that calls xfree() or xalloc_destroy() would lock a destroyed mutex. + // The OS reclaims the memory at process exit. + static std::mutex* _mutex = new std::mutex(); + return *_mutex; + } + static inline XLockState xlock() + { + get_mutex().lock(); + XLockState state = { 0, 0 }; + return state; + } + static inline void xunlock(XLockState) { get_mutex().unlock(); } +#endif /// Stored a pointer to the allocator instance within the block region. /// a pointer to the client's area within the block. @@ -130,7 +289,7 @@ static inline void *get_block_ptr(void* block) return static_cast(block) - BLOCK_HEADER_SIZE; } -/// Returns an allocator instance matching the size provided. Caller holds get_mutex(). +/// Returns an allocator instance matching the size provided. Caller holds the lock. /// @param[in] size - allocator block size /// @return Allocator instance handling requested block size or NULL /// if no allocator exists. @@ -149,7 +308,7 @@ static inline Allocator* find_allocator(size_t size) } #ifndef STATIC_POOLS -/// Insert an allocator instance into the array. Caller holds get_mutex(). +/// Insert an allocator instance into the array. Caller holds the lock. /// @param[in] allocator - An allocator instance /// @return true if inserted, false if the array is full. static inline bool insert_allocator(Allocator* allocator) @@ -172,7 +331,7 @@ static inline bool insert_allocator(Allocator* allocator) extern "C" void xalloc_init() { #ifdef STATIC_POOLS - get_mutex().lock(); + XLockState lock = xlock(); // For STATIC_POOLS mode, the allocators must be initialized before any other // static user class constructor is run. Therefore, use placement new to initialize @@ -188,7 +347,7 @@ extern "C" void xalloc_init() _allocators[8] = new (&_allocator2048) AllocatorPool(); _allocators[9] = new (&_allocator4096) AllocatorPool(); - get_mutex().unlock(); + xunlock(lock); #endif } @@ -196,7 +355,7 @@ extern "C" void xalloc_init() /// ~XallocInitDestroy destructor calls this function automatically. extern "C" void xalloc_destroy() { - get_mutex().lock(); + XLockState lock = xlock(); #ifdef STATIC_POOLS for (int i=0; i(size + BLOCK_HEADER_SIZE); - get_mutex().lock(); + XLockState lock = xlock(); Allocator* allocator = find_allocator(blockSize); - get_mutex().unlock(); + xunlock(lock); #ifndef STATIC_POOLS // If there is not an allocator already created to handle this block size @@ -252,11 +411,11 @@ Allocator* xallocator_get_allocator(size_t size) // Re-check and insert under one lock, so two threads can't both add // an allocator for the same size - get_mutex().lock(); + XLockState lock2 = xlock(); allocator = find_allocator(blockSize); if (allocator == NULL && insert_allocator(created)) allocator = created; - get_mutex().unlock(); + xunlock(lock2); // Another thread inserted one first, or the table is full if (allocator != created) @@ -281,16 +440,16 @@ extern "C" void *xmalloc(size_t size) #ifdef STATIC_POOLS // The pool hands out its slots and tracks its stats; NULL when exhausted - get_mutex().lock(); + XLockState lock = xlock(); blockMemoryPtr = allocator->Allocate(allocator->GetBlockSize()); - get_mutex().unlock(); + xunlock(lock); #else // Reuse a freed block if there is one - get_mutex().lock(); + XLockState lock = xlock(); blockMemoryPtr = allocator->Pop(); if (blockMemoryPtr != NULL) allocator->AccountAlloc(false); - get_mutex().unlock(); + xunlock(lock); if (blockMemoryPtr == NULL) { @@ -299,9 +458,9 @@ extern "C" void *xmalloc(size_t size) blockMemoryPtr = new (std::nothrow) char[allocator->GetBlockSize()]; if (blockMemoryPtr != NULL) { - get_mutex().lock(); + XLockState lock2 = xlock(); allocator->AccountAlloc(true); - get_mutex().unlock(); + xunlock(lock2); } } #endif @@ -327,12 +486,12 @@ extern "C" void xfree(void* ptr) // Convert the client pointer into the original raw block pointer void* blockPtr = get_block_ptr(ptr); - get_mutex().lock(); + XLockState lock = xlock(); // Deallocate the block allocator->Deallocate(blockPtr); - get_mutex().unlock(); + xunlock(lock); } /// Reallocates a memory block previously allocated with xalloc. @@ -374,20 +533,20 @@ extern "C" void *xrealloc(void *oldMem, size_t size) /// Output xallocator usage statistics extern "C" void xalloc_stats() { - get_mutex().lock(); + XLockState lock = xlock(); for (int i=0; iGetName() != NULL) - cout << _allocators[i]->GetName(); - cout << " Block Size: " << _allocators[i]->GetBlockSize(); - cout << " Block Count: " << _allocators[i]->GetBlockCount(); - cout << " Blocks In Use: " << _allocators[i]->GetBlocksInUse(); - cout << endl; + const char* name = _allocators[i]->GetName(); + printf("%s Block Size: %lu Block Count: %lu Blocks In Use: %lu\n", + name != NULL ? name : "", + (unsigned long)_allocators[i]->GetBlockSize(), + (unsigned long)_allocators[i]->GetBlockCount(), + (unsigned long)_allocators[i]->GetBlocksInUse()); } - get_mutex().unlock(); + xunlock(lock); }