{"id":13812231,"url":"https://github.com/embeddedartistry/libmemory","last_synced_at":"2025-04-07T12:03:59.895Z","repository":{"id":20091165,"uuid":"88765847","full_name":"embeddedartistry/libmemory","owner":"embeddedartistry","description":"Embedded systems memory management library. Implementations for malloc(), free(), and other useful memory management functions","archived":false,"fork":false,"pushed_at":"2024-05-21T17:17:10.000Z","size":371,"stargazers_count":248,"open_issues_count":8,"forks_count":50,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-31T11:04:10.201Z","etag":null,"topics":["bringup","c","embedded-systems","freelist","heap","libc","malloc","malloc-free","memory-allocation","portability","rtos","threadx"],"latest_commit_sha":null,"homepage":"https://embeddedartistry.com","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/embeddedartistry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-19T16:18:54.000Z","updated_at":"2025-03-24T02:26:35.000Z","dependencies_parsed_at":"2024-05-21T18:44:51.958Z","dependency_job_id":null,"html_url":"https://github.com/embeddedartistry/libmemory","commit_stats":null,"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/embeddedartistry%2Flibmemory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/embeddedartistry%2Flibmemory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/embeddedartistry%2Flibmemory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/embeddedartistry%2Flibmemory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/embeddedartistry","download_url":"https://codeload.github.com/embeddedartistry/libmemory/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648976,"owners_count":20972945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bringup","c","embedded-systems","freelist","heap","libc","malloc","malloc-free","memory-allocation","portability","rtos","threadx"],"created_at":"2024-08-04T04:00:49.524Z","updated_at":"2025-04-07T12:03:59.863Z","avatar_url":"https://github.com/embeddedartistry.png","language":"C","funding_links":[],"categories":["Memory","memory manager"],"sub_categories":["Memory management","dynamic malloc"],"readme":"# Embedded Artistry libmemory\n\nEmbedded Artistry's `libmemory` is a memory management library for embedded systems. If you have a bare metal system and want to use `malloc()`, this library is for you!\n\n`libmemory` provides various implementations of the `malloc()` and `free()` functions. The primary `malloc` implementation is a free-list allocator which can be used on a bare-metal system. Wrappers for some RTOSes are also provided (and can be added if not already). You will also find other useful memory functions, such as `aligned_malloc()`.\n\nThis library is meant to be coupled with a `libc` implementation (such as the [Embedded Artistry `libc`](https://github.com/embeddedartistry/libc)). `malloc()` and `free()` are not redefined in these headers, so you can safely use this library with your platform's existing `libc`.\n\n## Table of Contents\n\n1. [About the Project](#about-the-project)\n2. [Project Status](#project-status)\n3. [Getting Started](#getting-started)\n\t1. [Requirements](#requirements)\n\t\t1. [git-lfs](#git-lfs)\n\t\t1. [Meson Build System](#meson-build-system)\n\t2. [Getting the Source](#getting-the-source)\n\t3. [Building](#building)\n\t4. [Installation](#installation)\n4. [Configuration Options](#configuration-options)\n5. [Library Variants](#library-variants)\n\t1. [Native Targets](#native-targets)\n5. [Usage](#usage)\n\t1. [Thread Safety](#thread-safety)\n\t1. [Aligned `malloc`](#aligned-malloc)\n5. [Using a Custom Libc](#using-a-custom-libc)\n1. [Testing](#testing)\n5. [Documentation](#documentation)\n6. [Need Help?](#need-help)\n7. [Contributing](#contributing)\n8. [Further Reading](#further-reading)\n9. [Authors](#authors)\n10. [License](#license)\n11. [Acknowledgments](#Acknowledgments)\n\n\n## About the Project\n\nThis library is meant to allow developers of embedded systems to utilize the `malloc()` and `free()` functions if their platform does not currently support it. The baseline `malloc()` implementation can be used without an RTOS or any other supporting software. Only a block of memory needs to be assigned.\n\nMany RTOSes provide dynamic memory allocation functionality, but these functions are not typically called `malloc()` and `free()`. Wrappers can be provided for these RTOSes to improve code portability.\n\nA block of memory needs to be initially assigned using the `malloc_addblock()` function. This tells the `malloc` implementation what memory address and size to use for the heap.\n\n```\n// Allocate 4MB to the heap starting at memory address 0xDEADBEEF\nmalloc_addblock(0xDEADBEEF, 4 * 1024 * 1024);\n```\n\nOne memory has been allocated to the heap, you can use `malloc()` and `free()` as expected.\n\n## Project Status\n\n* Basic memory allocation is implemented using the free-list strategy\n* x86, x86_64, ARM, and ARM64 compilation is supported\n* Example RTOS implementations are provided for FreeRTOS and ThreadX\n* An implementation exists that can be used with the Embedded Virtual Machine framework\n* Tests are currently in place for `malloc()`, `free()`, `aligned_malloc()`, and `aligned_free()`\n* No test for overlapping memory blocks currently exists\n\n## Getting Started\n\n### Requirements\n\nThis project uses [Embedded Artistry's standard Meson build system](https://embeddedartistry.com/fieldatlas/embedded-artistrys-standardized-meson-build-system/), and dependencies are described in detail [on our website](https://embeddedartistry.com/fieldatlas/embedded-artistrys-standardized-meson-build-system/).\n\nAt a minimum you will need:\n\n* [`git-lfs`](https://git-lfs.github.com), which is used to store binary files in this repository\n* [Meson](#meson-build-system) is the build system\n* Some kind of compiler for your target system.\n\t- This repository has been tested with:\n\t\t- gcc-7, gcc-8, gcc-9\n\t\t- arm-none-eabi-gcc\n\t\t- Apple clang\n\t\t- Mainline clang\n\n#### git-lfs\n\nThis project stores some files using [`git-lfs`](https://git-lfs.github.com).\n\nTo install `git-lfs` on Linux:\n\n```\nsudo apt install git-lfs\n```\n\nTo install `git-lfs` on OS X:\n\n```\nbrew install git-lfs\n```\n\nAdditional installation instructions can be found on the [`git-lfs` website](https://git-lfs.github.com).\n\n#### Meson Build System\n\nThe [Meson](https://mesonbuild.com) build system depends on `python3` and `ninja-build`.\n\nTo install on Linux:\n\n```\nsudo apt-get install python3 python3-pip ninja-build\n```\n\nTo install on OSX:\n\n```\nbrew install python3 ninja\n```\n\nMeson can be installed through `pip3`:\n\n```\npip3 install meson\n```\n\nIf you want to install Meson globally on Linux, use:\n\n```\nsudo -H pip3 install meson\n```\n\n### Getting the Source\n\nThis project uses [`git-lfs`](https://git-lfs.github.com), so please install it before cloning. If you cloned prior to installing `git-lfs`, simply run `git lfs pull` after installation.\n\nThis project is [hosted on GitHub](https://github.com/embeddedartistry/libmemory). You can clone the project directly using this command:\n\n```\ngit clone --recursive git@github.com:embeddedartistry/libmemory.git\n```\n\nIf you don't clone recursively, be sure to run the following command in the repository or your build will fail:\n\n```\ngit submodule update --init\n```\n\n### Building\n\nIf Make is installed, the library can be built by issuing the following command:\n\n```\nmake\n```\n\nThis will build all targets for your current architecture.\n\nYou can clean builds using:\n\n```\nmake clean\n```\n\nYou can eliminate the generated `buildresults` folder using:\n\n```\nmake distclean\n```\n\nYou can also use  `meson` directly for compiling.\n\nCreate a build output folder:\n\n```\nmeson buildresults\n```\n\nAnd build all targets by running\n\n```\nninja -C buildresults\n```\n\nCross-compilation is handled using `meson` cross files. Example files are included in the [`build/cross`](build/cross/) folder. You can write your own cross files for your specific processor by defining the toolchain, compilation flags, and linker flags. These settings will be used to compile `libc`. (or open an issue and we can help you).\n\nCross-compilation must be configured using the meson command when creating the build output folder. For example:\n\n```\nmeson buildresults --cross-file build/cross/gcc_arm_cortex-m4.txt\n```\n\nFollowing that, you can run `make` (at the project root) or `ninja` to build the project.\n\nTests will not be cross-compiled. They will only be built for the native platform.\n\n**Full instructions for building the project, using alternate toolchains, and running supporting tooling are documented in [Embedded Artistry's Standardized Meson Build System](https://embeddedartistry.com/fieldatlas/embedded-artistrys-standardized-meson-build-system/) on our website.**\n\n### Installation\n\nIf you don't use `meson` for your project, the best method to use this project is to build it separately and copy the headers and desired library contents into your source tree.\n\n* Copy the `include/` directory contents into your source tree.\n* Library artifacts are stored in the `buildresults/src` folder\n* Copy the desired library to your project and add the library to your link step.\n\nExample linker flags:\n\n```\n-Lpath/to/libmemory_freelist.a -lmemory_freelist\n```\n\nIf you're using `meson`, you can use `libmemory` as a subproject. Place it into your subproject directory of choice and add a `subproject` statement:\n\n```\nlibmemory = subproject('libmemory')\n```\n\nYou will need to promote the subproject dependencies to your project in order to use them in your build targets:\n\n```\nlibmemory = subproject('libmemory')\n\nlibmemory_native_dep = libmemory.get_variable('libmemory_native_dep')\nlibmemory_hosted_dep = libmemory.get_variable('libmemory_hosted_dep')\nlibmemory_freelist_dep = libmemory.get_variable('libmemory_freelist_dep')\nlibmemory_threadx_dep = libmemory.get_variable('libmemory_threadx_dep')\nlibmemory_freertos_dep = libmemory.get_variable('libmemory_freertos_dep')\nlibmemory_header_include =  libmemory.get_variable('libmemory_system_includes')\nlibmemory_framework_rtos_dep = libmemory.get_variable('libmemory_framework_rtos_dep')\n```\n\nYou can use the dependency for your target library configuration in your `executable` declarations(s) or other dependencies. For example:\n\n```\nfwdemo_sim_platform_dep = declare_dependency(\n\tinclude_directories: fwdemo_sim_platform_inc,\n\tdependencies: [\n\t\tfwdemo_simulator_hw_platform_dep,\n\t\tposix_os_dep,\n\t\tlibmemory_native_dep, # \u003c----- libmemory dependency added here\n\t\tlibc_native_dep, \n\t\tlibcxxabi_native_dep,\n\t\tlibcxx_full_native_dep,\n\t\tlogging_subsystem_dep\n\t],\n\tsources: files('platform.cpp'),\n)\n```\n\nThis will add the proper include paths, library targets, and build dependency rules to your application.\n\n## Configuration Options\n\nThe following meson project options can be set for this library when creating the build results directory with `meson`, or by using `meson configure`:\n\n* `enable-pedantic`: Enable `pedantic` warnings\n* `enable-pedantic-error`: Turn on `pedantic` warnings and errors\n* `use-libc-subproject`: When true, use the subproject defined in the libc-subproject option. An alternate approach is to override c_stdlib in your cross files.\n* `libc-subproject`: This array is used in combination with `use-libc-subproject`. The first entry is the subproject name. The second is the cross-compilation dependency to use. The third value is optional. If used, it is a native dependency to use with native library targets.\n\nOptions can be specified using `-D` and the option name:\n\n```\nmeson buildresults -Denable-pedantic=true\n```\n\nThe same style works with `meson configure`:\n\n```\ncd buildresults\nmeson configure -Denable-pedantic=true\n```\n\n## Library Variants\n\nThis build provides a number of library variations. Many of these variants support different allocation strategies. Our recommended implementation for embedded systems without an RTOS is `libmemory_freelist`.`\n\n- `libmemory_assert`\n\t+ Calls to `malloc`/`free` will assert at runtime\n\t+ This implementation is portable\n- `libmemory_freelist` \n\t+ Allocates memory from a freelist\n\t+ Works with one or more blocks of memory\n\t+ Memory must be initialized with `malloc_addblock`\n\t+ The implementation can be made threadsafe by supplying implementations for `malloc_lock` and `malloc_unlock` in your application\n\t+ This implementation is portable\n- `libmemory_freertos` \n\t+ Provides a sample FreeRTOS implementation that wraps the heap_5 FreeRTOS strategy\n\t+ Memory must be initialized with `malloc_addblock`\n\t+ Note that headers will need to be updated for your particular project prior to compilation (dependencies/rtos/freertos), or simply include the source code within your own project\n- `libmemory_threadx` \n\t+ Provides a sample ThreadX implementation that wraps the ThreadX memory allocators\n\t+ Memory must be initialized with `malloc_addblock`\n\t+ Note that headers will need to be updated for your particular project prior to compilation (dependencies/rtos/threadx), or simply include the source code within your own project\n\nWe also have variants that provide supplementary functions (e.g., `aligned_malloc`) without providing an implementation for `malloc`/`free`. This is primarily used for providing source code compatibility with systems that do provide a suitable `malloc` implementation (e.g., running a test program on your build machine).\n\n- `libmemory`\n\t+ Picks up extra libmemory functions but does not implement `malloc`/`free`\n\t+ Will use an alternative `libc` implementation if specified\n\t`malloc_addblock` and `malloc_init` will assert at runtime\n- `libmemory_hosted`\n\t+ Picks up extra libmemory functions but does not implement `malloc`/`free`\n\t+ Will use the compiler's `libc` implementation _unless other specified flags override that setting_ (e.g., within your own build rules)\n\t+ `malloc_addblock` and `malloc_init` will assert at runtime.\n\n### Native Targets\n\nIn addition, every library variant has a corresponding `_native` target. When cross-compilation builds are enabled, the target with the `_native` suffix will be compiled for your build machine, while the target without the suffix will be cross-compiled. This enables your application to use the appropriate variant for both cross-compilation targets and `native: true` targets (e.g., a unit test program or simulator application) in the same build.\n\n## Usage\n\nA block of memory needs to be initially assigned using the `malloc_addblock()` function:\n\n```\nvoid malloc_addblock(void* addr, size_t size);\n```\n\n\nThis tells the `malloc` implementation what memory address and size to use for the heap.\n\n```\n// Allocate 4MB to the heap starting at memory address 0xDEADBEEF\nmalloc_addblock(0xDEADBEEF, 4 * 1024 * 1024);\n```\n\n`malloc()` and `free()` will fail (return `NULL`) if no memory has been allocated. Once memory has been allocated to the heap, you can use `malloc()` and `free()` as expected.\n\nMultiple blocks of memory can be added using `malloc_addblock()`. The memory blocks do not have to be contiguous.\n\n### Thread Safety\n\nRTOS-based implementations are thread-safe depending on the RTOS and heap configuration.\n\nThe freelist implementation is not thread-safe by default. If you are using this version on a threaded system, you need to define two functions within your program:\n\n```\nvoid malloc_lock();\nvoid malloc_unlock();\n```\n\nThese should lock and unlock a mutex that is designed to protect `malloc`.\n\n```\nmutex_t malloc_mutex;\n\nvoid malloc_lock() \n{\n\tmutex_lock(\u0026malloc_mutex);\n}\n\nvoid malloc_unlock()\n{\n\tmutex_unlock(\u0026malloc_mutex);\n}\n```\n\nThese functions are defined as weakly linked in the library, so the default no-op condition will not be used if your functions is found by the linker. If you're doubtful that your calls are being included, check the disassembly for the functions - your version will not be no-ops!\n\n### Aligned malloc\n\nYou can allocate aligned memory using `aligned_malloc()`:\n\n```\nvoid* aligned_malloc(size_t align, size_t size);\n```\n\nAlignment must be a power of two!\n\nAligned memory can only be free'd using `aligned_free()`:\n\n```\nvoid aligned_free(void* ptr);\n```\n\nFor more information, see `aligned_memory.h`and [the documentation](https://embeddedartistry.github.io/libmemory/d6/dfa/aligned__malloc_8h.html).\n\n## Using a Custom Libc\n\nThis project is designed to be used along with a `libc` implementation. If you are using this library, you may not be using the standard `libc` that ships with you compiler. This library needs to know about the particular `libc` implementation during its build, in case there are important differences in definitions.\n\nThere are two ways to tell this library about a `libc`:\n\n1. [Override `c_stdlib` in a cross-file](https://mesonbuild.com/Cross-compilation.html#using-a-custom-standard-library), which will be automatically used when building this library.\n2. Set `use-libc-subproject` to `true`\n\t1. By default, this will use the [Embedded Artistry libc](https://github.com/embeddedartistry/libc)\n\t2. You can specify another Meson subproject by configuring `libc-subproject`. This is an array: the first value is the subproject name, the second the libc dependency variable, and the third is an optional native dependency that will be used with native library variants.\n\nNOTE: External libc dependencies are only used for building the library. They are not forwarded through dependencies. You are expected to handle that with the rest of your program.\n\n## Testing\n\nThe tests for this library are written with CMocka, which is included as a subproject and does not need to be installed on your system. You can run the tests by issuing the following command:\n\n```\nmake test\n```\n\nBy default, test results are generated for use by the CI server and are formatted in JUnit XML. The test results XML files can be found in `buildresults/test/`.\n\n# Documentation\n\n[Documentation for the latest release can always be found here](https://embeddedartistry.github.io/libmemory/index.html).\n\nDocumentation can be built locally by running the following command:\n\n```\nmake docs\n```\n\nDocumentation can be found in `buildresults/docs`, and the root page is `index.html`.\n\n# Need help?\n\nIf you need further assistance or have any questions, please [file a GitHub Issue](https://github.com/embeddedartistry/libmemory/issues/new) or send us an email using the [Embedded Artistry Contact Form](http://embeddedartistry.com/contact).\n\nYou can also reach out on Twitter: [\\@mbeddedartistry](https://twitter.com/mbeddedartistry/).\n\n# Contributing\n\nIf you are interested in contributing to this project, please read our [contributing guidelines](docs/CONTRIBUTING.md).\n\n# Further Reading\n\n* [`libmemory` Documentation](https://embeddedartistry.github.io/libmemory/index.html)\n* [CONTRIBUTING guide](docs/CONTRIBUTING.md)\n\n# Authors\n\n* **[Phillip Johnston](https://github.com/phillipjohnston)** - original library author - [Embedded Artistry](https://github.com/embeddedartistry)\n\n# License\n\nCopyright (c) 2017 Embedded Artistry LLC\n\nThis project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.\n\n# Acknowledgments\n\n**[Back to top](#table-of-contents)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fembeddedartistry%2Flibmemory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fembeddedartistry%2Flibmemory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fembeddedartistry%2Flibmemory/lists"}