From 84028dab79bc42bb4aa01e59dac57294ef816649 Mon Sep 17 00:00:00 2001
From: Aryadev Chavali <aryadev@aryadevchavali.com>
Date: Tue, 9 Apr 2024 15:15:00 +0630
Subject: Done TODO: Comment coverage > lib > base.h
Pretty simple
---
lib/base.h | 73 ++++++++++++++++++++++++++++++++++++++++++++++++--------------
todo.org | 4 ++--
2 files changed, 59 insertions(+), 18 deletions(-)
diff --git a/lib/base.h b/lib/base.h
index 1eaf9ba..3b2d50b 100644
--- a/lib/base.h
+++ b/lib/base.h
@@ -15,6 +15,7 @@
#include <stdint.h>
+/* Basic macros for a variety of uses. Quite self explanatory. */
#define ARR_SIZE(xs) (sizeof(xs) / sizeof(xs[0]))
#define MAX(a, b) ((a) > (b) ? (a) : (b))
#define MIN(a, b) ((a) > (b) ? (b) : (a))
@@ -23,7 +24,7 @@
#define TERM_RED "\e[0;31m"
#define TERM_RESET "\e[0;0m"
-// Flags
+// Flags for program behaviour (usually related to printing)
#ifndef VERBOSE
#define VERBOSE 0
#endif
@@ -31,6 +32,7 @@
#define PRINT_HEX 0
#endif
+/* Ease of use aliases for numeric types */
typedef uint8_t u8;
typedef int8_t i8;
typedef uint32_t u32;
@@ -48,6 +50,14 @@ typedef i32 s_hword;
typedef u64 word;
typedef i64 s_word;
+/* Macros for the sizes of common base data types. */
+#define HWORD_SIZE sizeof(hword)
+#define SHWORD_SIZE sizeof(s_hword)
+#define WORD_SIZE sizeof(word)
+#define SWORD_SIZE sizeof(s_word)
+
+/** Union for all basic data types in the virtual machine.
+ */
typedef union
{
byte as_byte;
@@ -58,6 +68,8 @@ typedef union
s_word as_long;
} data_t;
+/** Enum of type tags for the data_t structure to provide context.
+ */
typedef enum
{
DATA_TYPE_NIL = 0,
@@ -66,25 +78,54 @@ typedef enum
DATA_TYPE_WORD,
} data_type_t;
-#define DBYTE(BYTE) ((data_t){.as_byte = (BYTE)})
-#define DHWORD(HWORD) ((data_t){.as_hword = (HWORD)})
-#define DWORD(WORD) ((data_t){.as_word = (WORD)})
+/* Some macros for constructing data_t instances quickly. */
+#define DBYTE(BYTE) ((data_t){.as_byte = (BYTE)})
+#define DHWORD(HWORD) ((data_t){.as_hword = (HWORD)})
+#define DWORD(WORD) ((data_t){.as_word = (WORD)})
+
+/** Safely subtract SUB from W, where both are words (64 bit integers).
+ *
+ * In case of underflow (i.e. where W - SUB < 0) returns 0 instead of
+ * the underflowed result.
+ */
#define WORD_SAFE_SUB(W, SUB) ((W) > (SUB) ? ((W) - (SUB)) : 0)
-#define HWORD_SIZE sizeof(hword)
-#define SHWORD_SIZE sizeof(s_hword)
-#define WORD_SIZE sizeof(word)
-#define SWORD_SIZE sizeof(s_word)
+/** Return the Nth byte of WORD
+ * N should range from 0 to 7 as there are 8 bytes in a word.
+ */
+#define WORD_NTH_BYTE(WORD, N) (((WORD) >> ((N) * 8)) & 0xFF)
-// Macros to extract the nth byte or nth hword from a word
-#define WORD_NTH_BYTE(WORD, N) (((WORD) >> ((N)*8)) & 0xFF)
-#define WORD_NTH_HWORD(WORD, N) (((WORD) >> ((N)*2)) & 0xFFFFFFFF)
+/** Return the Nth half word of WORD
+ * N should range from 0 to 1 as there are 2 half words in a word
+ */
+#define WORD_NTH_HWORD(WORD, N) (((WORD) >> ((N) * 2)) & 0xFFFFFFFF)
+
+/** Convert a buffer of bytes to a half word
+ * We assume the buffer of bytes are in virtual machine byte code
+ * format (big endian) and that they are at least HWORD_SIZE in
+ * size.
+ */
+hword convert_bytes_to_hword(byte *buffer);
-// Assume array contains 4 bytes.
-hword convert_bytes_to_hword(byte *);
-void convert_hword_to_bytes(hword, byte *);
-// Assume array contains 8 bytes.
+/** Convert a half word into a VM byte code format bytes (big endian)
+ * @param h: Half word to convert
+ * @param buffer: Buffer to store into. We assume the buffer has at
+ * least HWORD_SIZE space.
+ */
+void convert_hword_to_bytes(hword h, byte *buffer);
+
+/** Convert a buffer of bytes to a word
+ * We assume the buffer of bytes are in virtual machine byte code
+ * format (big endian) and that they are at least WORD_SIZE in
+ * size.
+ */
word convert_bytes_to_word(byte *);
-void convert_word_to_bytes(word, byte *);
+
+/** Convert a word into a VM byte code format bytes (big endian)
+ * @param w: Word to convert
+ * @param buffer: Buffer to store into. We assume the buffer has at
+ * least WORD_SIZE space.
+ */
+void convert_word_to_bytes(word w, byte *buffer);
#endif
diff --git a/todo.org b/todo.org
index fd9cac4..bf15bb2 100644
--- a/todo.org
+++ b/todo.org
@@ -4,8 +4,8 @@
* TODO Better documentation [0%] :DOC:
** TODO Comment coverage [0%]
-*** WIP Lib [0%]
-**** WIP lib/base.h
+*** WIP Lib [25%]
+**** DONE lib/base.h
**** TODO lib/darr.h
**** TODO lib/heap.h
**** TODO lib/inst.h
--
cgit v1.2.3-13-gbd6f