From 1f61db551bab98b5f2f8c5fe80aa59c8a2fc0111 Mon Sep 17 00:00:00 2001
From: barter-simsum <barter-simsum@protonmail.com>
Date: Thu, 30 Nov 2023 11:35:10 -0500
Subject: [PATCH] pma: fix external routine stubs. add comments to header

---
 rust/ares_pma/c-src/btree.c | 24 ++++++-----------
 rust/ares_pma/c-src/btree.h | 54 +++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+), 16 deletions(-)

diff --git a/rust/ares_pma/c-src/btree.c b/rust/ares_pma/c-src/btree.c
index 50cc165..596c445 100644
--- a/rust/ares_pma/c-src/btree.c
+++ b/rust/ares_pma/c-src/btree.c
@@ -12,13 +12,13 @@
 #include <string.h>
 #include <inttypes.h>
 
+#include "btree.h"
 #include "lib/checksum.h"
 
 typedef uint32_t pgno_t;        /* a page number */
 typedef uint32_t vaof_t;        /* a virtual address offset */
 typedef uint32_t flag_t;
 typedef unsigned char BYTE;
-typedef unsigned long ULONG;
 
 //// ===========================================================================
 ////                              tmp tmp tmp tmp tmp
@@ -2415,7 +2415,7 @@ bt_meta_set(BT_state *state, size_t idx, uint64_t val)
 }
 
 int
-bt_range_of(void *p, void **lo, void **hi)
+bt_range_of(BT_state *state, void *p, void **lo, void **hi)
 {
   /* traverse tree looking for lo <= p and hi > p. return that range as a pair
      of pointers NOT as two vaof_t
@@ -2426,37 +2426,29 @@ bt_range_of(void *p, void **lo, void **hi)
 }
 
 int
-bt_dirty(void *lo, void *hi)
+bt_dirty(BT_state *state, void *lo, void *hi)
 {
   /* takes a range and ensures that entire range is CoWed */
   /* if part of the range is free then return 1 */
 }
 
 int
-bt_next_alloc(void *p, void **lo, void **hi)
+bt_next_alloc(BT_state *state, void *p, void **lo, void **hi)
 {
   /* if p is in the mlist, return the next hole in the mlist */
 
   /* if p is allocated, then return the hole that it is contained in */
 }
 
-/* also: accessors for the virtual memory of the pma low and high */
-
-/* #define BT_MAPADDR  ((void *) S(0x1000,0000,0000)) */
-/* #define BT_ADDRSIZE (BT_PAGESIZE << BT_PAGEWORD) */
-
-/* i.e. MAP_ADDDR - MAP_ADDR + ADDRSIZE */
-
-/* and a function that given a pointer tests if in range */
-
 void
-bt_bounds(void **lo, void **hi)
+bt_bounds(BT_state *state, void **lo, void **hi)
 {
-
+  *lo = BT_MAPADDR;
+  *hi = (void *)((uintptr_t)BT_MAPADDR + BT_ADDRSIZE);
 }
 
 int
-bt_inbounds(void *p)
+bt_inbounds(BT_state *state, void *p)
 {
   /* 1: if in bounds of PMA (those returned by bt_bounds) */
 }
diff --git a/rust/ares_pma/c-src/btree.h b/rust/ares_pma/c-src/btree.h
index 1e53eec..94b964b 100644
--- a/rust/ares_pma/c-src/btree.h
+++ b/rust/ares_pma/c-src/btree.h
@@ -11,20 +11,74 @@ typedef unsigned long ULONG;
 //// ===========================================================================
 ////                            btree external routines
 
+/**
+ * instantiate an opaque BT_state handle
+ */
 int bt_state_new(BT_state **state);
 
+/**
+ * Open the persistent state or create if one doesn't exist
+ */
 int bt_state_open(BT_state *state, const char *path, ULONG flags, mode_t mode);
 
+/**
+ * Close the persistent state
+ */
 int bt_state_close(BT_state *state);
 
+/**
+ * Allocate persistent memory space
+ */
 void * bt_malloc(BT_state *state, size_t pages);
 
+/**
+ * Free persistent memory space
+ */
 void bt_free(BT_state *state, void *lo, void *hi);
 
+/**
+ * Sync a snapshot of the persistent memory to disk
+ * This will **exit the process** on failure to avoid data corruption
+ */
 int bt_sync(BT_state *state);
 
+/**
+ * Get a metadata entry
+ */
 uint64_t bt_meta_get(BT_state *state, size_t idx);
 
+/**
+ * Set a metadata entry
+ */
 void bt_meta_set(BT_state *state, size_t idx, uint64_t val);
 
+/**
+ * Give the allocation range in the btree that a pointer lives in
+ */
+int bt_range_of(BT_state *state, void *p, void **lo, void **hi);
+
+/**
+ * Ensure a region of memory is "dirty" i.e. can be mutated
+ *
+ * A successful call to bt_dirty ensures that the memory range can be mutated
+ * until the next call to `bt_sync()`
+ */
+int bt_dirty(BT_state *state, void *lo, void *hi);
+
+/**
+ * Given a pointer, give the containing region of allocated memory, or the next
+ * highest if the pointer is to free memory
+ */
+int bt_next_alloc(BT_state *state, void *p, void **lo, void **hi);
+
+/**
+ * Return the memory bounds of the persistent-memory B-tree
+ */
+void bt_bounds(BT_state *state, void **lo, void **hi);
+
+/**
+ * Return whether a pointer is within the persistent-memory B-tree
+ */
+int bt_inbounds(BT_state *state, void *p);
+
 #endif