[UMM-53] Implement umm_init_heap() for Rust

README.md

@@ -44,13 +44,31 @@ in umm_malloc.
 
 ## Usage
 
-This library is designed to be included in your application as you
-see fit - but it's easiest if you do NOT touch the `umm_malloc_cfg.h`
-file and use the `-D` directive in your compiler to configure the
-library for different modes. Read the notes in `umm_malloc_cfg.h` for
-details.
+This library is designed to be included in your application as a
+submodule that has default configuration that can be overridden
+as needed by your application code.
 
-Note that `umm_malloc` is also designed to be testable in standalone
+The `umm_malloc` library can be initialized two ways. The first is
+at link time:
+
+- Set `UMM_MALLOC_CFG_HEAP_ADDR` to the symbol representing
+  the starting address of the heap. The heap must be
+  aligned on the natural boundary size of the processor.
+- Set `UMM_MALLOC_CFG_HEAP_SIZE` to the size of the heap in bytes.
+  The heap size must be a multiple of the natural boundary size of
+  the processor.
+
+This is how the `umm_init()` call handles initializing the heap.
+
+We can also call `umm_init_heap(void *pheap, size_t size)` where the
+heap details are passed in manually. This is useful in systems where
+you can allocate a block of memory at run time - for example in Rust.
+
+> :black_square_button: Future development may allow for multiple heaps
+
+## Automated Testing
+
+`umm_malloc` is designed to be testable in standalone
 mode using `ceedling`. To run the test suite, just make sure you have
 `ceedling` installed and then run:
 
@@ -59,15 +77,22 @@ ceedling clean
 ceedling test:all
 ```
 
-The following `#define`s must be set to something useful for the
-library to work at all
+## Configuration
 
-- `UMM_MALLOC_CFG_HEAP_ADDR` must be set to the symbol representing
-  the starting address of the heap. The heap must be
-  aligned on the natural boundary size of the processor.
-- `UMM_MALLOC_CFG_HEAP_SIZE` must be set to the size of the heap.
-  The heap size must be a multiple of the natural boundary size of
-  the processor.
+> :warning: **You MUST provide a file called `umm_malloc_cfgport.h`
+> somewhere in your app, even if it's blank**
+
+The reason for this is the way the configuration override heirarchy
+works. The priority for configuration overrides is as follows:
+
+1. Command line defines using `-D UMM_xxx`
+2. A custom config filename using `-D UMM_CFGFILE="<filename.cfg>"`
+3. The default config filename `umm_malloc_cfgport.h`
+4. The default configuration in `src/umm_malloc_cfg.h`
+
+
+The following `#define`s are set to useful defaults in
+`src/umm_malloc_cfg.h` and can be overridden as needed.
 
 The fit algorithm is defined as either:
 
@@ -83,9 +108,6 @@ testing allocation errors (which are normally due to bugs in
 the application code) or for running the test suite when
 making changes to the code.
 
-You can define them in your compiler command line or uncomment
-the corresponding entries is `umm_malloc_cfg.h`:
-
 - `UMM_INFO` is used to include code that allows dumping
   the entire heap structure (helpful when there's a problem).
 
@@ -111,6 +133,11 @@ The following functions are available for your application:
 
 They have exactly the same semantics as the corresponding standard library
 functions.
+
+To initialize the library there are two options:
+
+- `void *umm_malloc( size_t size );`
+
 
 ## Background
 

src/umm_malloc.c

@@ -33,6 +33,7 @@
  * R.Hempel 2020-01-20 - Move metric functions back to umm_info - See Issue 29
  * R.Hempel 2020-02-01 - Macro functions are uppercased - See Issue 34
  * R.Hempel 2020-06-20 - Support alternate body size - See Issue 42
+ * R.Hempel 2021-05-02 - Support explicit memory umm_init_heap() - See Issue 53
  * ----------------------------------------------------------------------------
  */
 
@@ -244,11 +245,13 @@ static uint16_t umm_assimilate_down(uint16_t c, uint16_t freemask) {
 
 /* ------------------------------------------------------------------------- */
 
-void umm_init(void) {
+void umm_init_heap(void *ptr, size_t size)
+{
     /* init heap pointer and size, and memset it to 0 */
-    UMM_HEAP = (umm_block *)UMM_MALLOC_CFG_HEAP_ADDR;
-    UMM_NUMBLOCKS = (UMM_MALLOC_CFG_HEAP_SIZE / UMM_BLOCKSIZE);
-    memset(UMM_HEAP, 0x00, UMM_MALLOC_CFG_HEAP_SIZE);
+    UMM_HEAP = (umm_block *)ptr;
+    UMM_HEAPSIZE = size;
+    UMM_NUMBLOCKS = (UMM_HEAPSIZE / UMM_BLOCKSIZE);
+    memset(UMM_HEAP, 0x00, UMM_HEAPSIZE);
 
     /* setup initial blank heap structure */
     UMM_FRAGMENTATION_METRIC_INIT();
@@ -294,6 +297,12 @@ void umm_init(void) {
 
 }
 
+void umm_init(void) {
+    /* Initialize the heap from linker supplied values */
+
+    umm_init_heap(UMM_MALLOC_CFG_HEAP_ADDR, UMM_MALLOC_CFG_HEAP_SIZE);
+}
+
 /* ------------------------------------------------------------------------
  * Must be called only from within critical sections guarded by
  * UMM_CRITICAL_ENTRY() and UMM_CRITICAL_EXIT().

src/umm_malloc.h

@@ -16,7 +16,9 @@ extern "C" {
 
 /* ------------------------------------------------------------------------ */
 
+extern void  umm_init_heap(void *ptr, size_t size);
 extern void  umm_init(void);
+
 extern void *umm_malloc(size_t size);
 extern void *umm_calloc(size_t num, size_t size);
 extern void *umm_realloc(void *ptr, size_t size);