From c6bfc90bcda4d6426641aac78c7eb554463481a8 Mon Sep 17 00:00:00 2001
From: Francesco Cozzuto <francesco.cozzuto@gmail.com>
Date: Thu, 9 May 2024 22:55:42 +0200
Subject: [PATCH] Add example and readme

---
 .gitignore |  4 +++-
 README.md  | 40 ++++++++++++++++++++++++++++++++++++++++
 example.c  | 33 +++++++++++++++++++++++++++++++++
 makefile   |  5 +++--
 test.c     |  4 ++--
 test2.c    |  2 +-
 6 files changed, 82 insertions(+), 6 deletions(-)
 create mode 100644 README.md
 create mode 100644 example.c

diff --git a/.gitignore b/.gitignore
index 62f902f..d9a28e2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,6 @@
 test
 test.exe
 test2
-test2.exe
\ No newline at end of file
+test2.exe
+example
+example.exe
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..208832c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,40 @@
+# A Buddy Allocator
+This is a general purpose allocator designed for memory-constrained environments. It uses the Buddy System allocation scheme. Only allocations with a size that is a power of 2 are supported. Any size other that's not a power of 2 will be rounded up.
+
+Here's an example:
+
+```c
+#include <stdio.h>
+#include <string.h>
+#include "buddy.h"
+
+int main(void)
+{
+    #define NUM_PAGES 16
+
+    // This is the memory we will allocate from
+    char memory[NUM_PAGES * BUDDY_ALLOC_MAX_BLOCK_SIZE];
+
+    struct page_info info[NUM_PAGES]; // This is required to keep track of allocation state
+    struct buddy_alloc alloc = buddy_startup(memory, sizeof(memory), info, NUM_PAGES);
+
+    // Allocate some memory (NULL is returned on failure)
+    // If the memory pool passed to the allocator was properly aligned,
+    // you can count to allocate any and all bytes of that pool.
+    char *str1 = buddy_malloc(&alloc, 32);
+    char *str2 = buddy_malloc(&alloc, 32);
+
+    strncpy(str1, "Hello", 32);
+    strncpy(str2, "world", 32);
+
+    printf("%s, %s!\n", str1, str2);
+
+    buddy_free(&alloc, 32, str1);
+    buddy_free(&alloc, 32, str2);
+
+    buddy_free(&alloc, 32, str2); // Double frees are caught!
+
+    buddy_cleanup(&alloc);
+    return 0;
+}
+```
diff --git a/example.c b/example.c
new file mode 100644
index 0000000..685eb82
--- /dev/null
+++ b/example.c
@@ -0,0 +1,33 @@
+#include <stdio.h>
+#include <string.h>
+#include "buddy.h"
+
+int main(void)
+{
+    #define NUM_PAGES 16
+
+    // This is the memory we will allocate from
+    char memory[NUM_PAGES * BUDDY_ALLOC_MAX_BLOCK_SIZE];
+
+    struct page_info info[NUM_PAGES]; // This is required to keep track of allocation state
+    struct buddy_alloc alloc = buddy_startup(memory, sizeof(memory), info, NUM_PAGES);
+
+    // Allocate some memory (NULL is returned on failure)
+    // If the memory pool passed to the allocator was properly aligned,
+    // you can count to allocate any and all bytes of that pool.
+    char *str1 = buddy_malloc(&alloc, 32);
+    char *str2 = buddy_malloc(&alloc, 32);
+
+    strncpy(str1, "Hello", 32);
+    strncpy(str2, "world", 32);
+
+    printf("%s, %s!\n", str1, str2);
+
+    buddy_free(&alloc, 32, str1);
+    buddy_free(&alloc, 32, str2);
+
+    buddy_free(&alloc, 32, str2); // Double frees are caught!
+
+    buddy_cleanup(&alloc);
+    return 0;
+}
\ No newline at end of file
diff --git a/makefile b/makefile
index 4f2b688..1d37c3b 100644
--- a/makefile
+++ b/makefile
@@ -1,4 +1,5 @@
 
 all:
-	gcc test.c  buddy.c -o test  -Wall -Wextra -ggdb #-fsanitize=address,undefined
-	gcc test2.c buddy.c -o test2 -Wall -Wextra -ggdb
\ No newline at end of file
+	gcc test.c  buddy.c -o test  -Wall -Wextra -ggdb
+	gcc test2.c buddy.c -o test2 -Wall -Wextra -ggdb
+	gcc example.c buddy.c -o example -Wall -Wextra -ggdb
diff --git a/test.c b/test.c
index 77b41cf..e392e8b 100644
--- a/test.c
+++ b/test.c
@@ -46,7 +46,7 @@ int main(void)
                 int i = rand() % num_current_allocs;
                 struct alloc_info deallocating = current_allocs[i];
                 current_allocs[i] = current_allocs[--num_current_allocs];
-                fprintf(stderr, "buddy_free(%lu, %lu)\n", deallocating.len, (uintptr_t) deallocating.ptr - (uintptr_t) alloc.base);
+                fprintf(stderr, "buddy_free(%d, %d)\n", (int) deallocating.len, (int) ((uintptr_t) deallocating.ptr - (uintptr_t) alloc.base));
                 buddy_free(&alloc, deallocating.len, (void*) deallocating.ptr);
             }
         }
@@ -61,7 +61,7 @@ int main(void)
             //fprintf(stderr, "buddy_malloc(%lu) = NULL\n", len);
         } else {
             //buddy_dump(&alloc, stderr);
-            fprintf(stderr, "buddy_malloc(%lu) = %lu\n", len, (uintptr_t) ptr - (uintptr_t) alloc.base);
+            fprintf(stderr, "buddy_malloc(%d) = %d\n", (int) len, (int) ((uintptr_t) ptr - (uintptr_t) alloc.base));
         }
 
         if (ptr != NULL) {
diff --git a/test2.c b/test2.c
index 0c73607..81eed96 100644
--- a/test2.c
+++ b/test2.c
@@ -56,7 +56,7 @@ int main(void)
         }
     }
 
-    fprintf(stderr, "performed=%lu, expected=%u\n", performed, MAX_ALLOCS);
+    fprintf(stderr, "performed=%d, expected=%d\n", (int) performed, (int) MAX_ALLOCS);
 
     buddy_cleanup(&alloc);
     return 0;