From 20ef80f7548f94f3424ae81e26e2a6dcfa916802 Mon Sep 17 00:00:00 2001
From: Mathieu Maret <mmaret@prophesee.ai>
Date: Mon, 1 May 2023 17:58:35 +0200
Subject: [PATCH] Add some documentation

---
 core/alloc.h      |  6 ++++++
 core/allocArea.c  |  8 ++++++++
 core/allocArea.h  | 34 ++++++++++++++++++++++------------
 core/mem.h        | 26 +++++++++++++++++++++++++-
 core/uaddrspace.c |  4 +++-
 5 files changed, 64 insertions(+), 14 deletions(-)

diff --git a/core/alloc.h b/core/alloc.h
index 174a325..bba2533 100644
--- a/core/alloc.h
+++ b/core/alloc.h
@@ -3,11 +3,17 @@
 #include "stddef.h"
 #include "types.h"
 
+/** Arbitrary size allocator **/
+
 /*
  * Initialize malloc system
  */
 int allocSetup(size_t sizeOfArea, vaddr_t *areaAddr, vaddr_t *descAddr, vaddr_t *entryAddr);
 
+/*
+ * Add Slice for some simple/commun size
+ */
+
 int allocPopulate();
 /*
  * Allow malloc to allocate elements of this precise size.
diff --git a/core/allocArea.c b/core/allocArea.c
index 9fa4eee..d11a6cf 100644
--- a/core/allocArea.c
+++ b/core/allocArea.c
@@ -7,6 +7,14 @@
 #include "mem.h"
 #include "stdarg.h"
 
+struct memArea {
+    vaddr_t startAddr;
+    uint nbPages;
+
+    struct memArea *next;
+    struct memArea *prev;
+};
+
 static struct memArea *freeArea;
 static struct memArea *usedArea;
 
diff --git a/core/allocArea.h b/core/allocArea.h
index 4ceda6e..edb2135 100644
--- a/core/allocArea.h
+++ b/core/allocArea.h
@@ -9,19 +9,29 @@
 #define AREA_PHY_MAP (1<<0)
 #define AREA_MEM_TOP  PAGING_MIRROR_VADDR
 
-struct memArea {
-    vaddr_t startAddr;
-    uint nbPages;
-
-    struct memArea *next;
-    struct memArea *prev;
-};
-
+/**
+ * Initialize the Area subsystem
+ **/
 void areaInit(vaddr_t firstMemUsed, vaddr_t lastUsed, vaddr_t stack_bottom, vaddr_t stack_top);
+
+/**
+ * Request a virtual memory area of @param nbPages
+ **/
 vaddr_t areaAlloc(unsigned int nbPages, uint32_t flags);
-// Remove an area from the free ones but do not add it into used ones.
-// This area should be latter added woth areaAdd.
-// Used by malloc to avoid recursivity issue
-vaddr_t areaBook(unsigned int nbPages, uint32_t flags);
+
+/**
+ * Free a vietual area
+ **/
 int areaFree(vaddr_t addr);
+
+/**
+ * Remove an area from the "free" ones but do not add it into used ones.
+ * This area should be latter added with areaAdd.
+ * Used by malloc to avoid recursivity issue
+ **/
+vaddr_t areaBook(unsigned int nbPages, uint32_t flags);
+
+/**
+ * Declare a virtual region to be managed by the subsytem
+ */
 int areaAdd(vaddr_t begin, vaddr_t end, int isFree);
diff --git a/core/mem.h b/core/mem.h
index bead0d8..6a226fc 100644
--- a/core/mem.h
+++ b/core/mem.h
@@ -2,7 +2,8 @@
 #include "stdint.h"
 #include "types.h"
 
-/** Physical Page related function
+/**
+ * Physical Page management
  */
 
 #define PAGE_SHIFT 12U
@@ -20,10 +21,33 @@ struct phyMemDesc {
     struct phyMemDesc *next, *prev;
 };
 
+/**
+ * Initi Physical Page management subsystem
+ **/
 int memSetup(paddr_t upperMem, paddr_t * firstUsed, paddr_t *lastUsed);
+
+/**
+ * Declare a physical region to be managed by the physica page subsystem
+ **/
 int memAddBank(paddr_t bottomMem, paddr_t topMem, int isFree);
+
+/**
+ * Request @params nbPage free physical pages
+ **/
 paddr_t allocPhyPage(uint nbPage);
+
+/**
+ * Decrement the nb of user of a given physical page
+ **/
 int unrefPhyPage(paddr_t addr);
+
+/**
+ * Increment the nb of user of a given physical page
+ **/
 int refPhyPage(paddr_t addr);
+
+/**
+ * Return the number of physical allocated pages
+ **/
 unsigned long getNbAllocatedPage(void);
 void memGetStat(uint *free, uint *used);
diff --git a/core/uaddrspace.c b/core/uaddrspace.c
index 6f4a4ee..2ee21e1 100644
--- a/core/uaddrspace.c
+++ b/core/uaddrspace.c
@@ -128,7 +128,9 @@ int uAddrSpaceCheckNAlloc(struct uAddrSpace *as, vaddr_t addr)
     struct uAddrVirtualReg *newReg;
     int right = PAGING_MEM_USER | PAGING_MEM_WRITE | PAGING_MEM_READ;
 
-    pr_devel("Checking 0x%lx inside 0x%lx and 0x%lx\n", addr, as->heapStart, as->heapStart +as->heapSize);
+    pr_devel("Checking 0x%lx inside 0x%lx and 0x%lx\n", addr, as->heapStart,
+             as->heapStart + as->heapSize);
+
     if (addr < as->heapStart || addr >= as->heapStart + as->heapSize) {
         return -1;
     }