sw: Improve docs

Author: kbeckmann

sw/n64_cic/include/n64_cic.h

@@ -10,12 +10,41 @@
 #include <stdbool.h>
 #include <stdint.h>
 
-// Callback will be called when the CIC receives a reset command.
-// This happens when the users presses the physical Reset button.
+/**
+ * @brief Callback function type for CIC reset
+ * 
+ * This callback will be called when the CIC receives a reset command.
+ * This happens when the user presses the physical Reset button.
+ */
 typedef void (*cic_reset_cb_t)(void);
 
+/**
+ * @brief Reset the parameters of the N64 CIC
+ */
 void n64_cic_reset_parameters(void);
+
+/**
+ * @brief Set the parameters of the N64 CIC
+ * 
+ * @param args The parameters to set
+ */
 void n64_cic_set_parameters(uint32_t * args);
+
+/**
+ * @brief Enable or disable DD mode in the N64 CIC
+ * 
+ * @param enabled Whether to enable or disable DD mode
+ */
 void n64_cic_set_dd_mode(bool enabled);
+
+/**
+ * @brief Initialize the N64 CIC hardware
+ */
 void n64_cic_hw_init(void);
+
+/**
+ * @brief Run the N64 CIC task
+ * 
+ * @param cic_reset_cb The callback to call when the CIC receives a reset command
+ */
 void n64_cic_task(cic_reset_cb_t cic_reset_cb);

sw/picocart64_shared/include/pc64_rand.h

@@ -8,7 +8,38 @@
 
 #include <stdint.h>
 
+/**
+ * Generate a random 32-bit integer.
+ *
+ * This function generates a random 32-bit integer using a linear congruential generator.
+ *
+ * @return A random 32-bit integer.
+ */
 uint32_t pc64_rand32(void);
+
+/**
+ * Generate a random 16-bit integer.
+ *
+ * This function generates a random 16-bit integer by calling pc64_rand32 and truncating the result.
+ *
+ * @return A random 16-bit integer.
+ */
 uint16_t pc64_rand16(void);
+
+/**
+ * Generate a random 8-bit integer.
+ *
+ * This function generates a random 8-bit integer by calling pc64_rand32 and truncating the result.
+ *
+ * @return A random 8-bit integer.
+ */
 uint8_t pc64_rand8(void);
+
+/**
+ * Seed the random number generator.
+ *
+ * This function sets the seed used by the random number generator.
+ *
+ * @param new_seed The new seed.
+ */
 void pc64_rand_seed(uint32_t new_seed);

sw/picocart64_v1/n64_pi_task.h

@@ -6,4 +6,12 @@
 
 #pragma once
 
+/**
+ * @file n64_pi_task.h
+ * @brief Header file for the N64 PI task
+ */
+
+/**
+ * @brief Executes the N64 PI task.
+ */
 void n64_pi_run(void);

sw/picocart64_v1/utils.h

@@ -8,28 +8,54 @@
 
 #include <stdint.h>
 
+/// @brief Macro to get the size of an array
 #define ARRAY_SIZE(x) (sizeof(x)/sizeof(x[0]))
 
+/**
+ * @brief Swap the lower and upper 16 bits of a 32-bit value
+ * 
+ * @param value The 32-bit value to swap
+ * @return The 32-bit value with the lower and upper 16 bits swapped
+ * 
+ * Example: 0x11223344 => 0x33441122
+ */
 static inline uint32_t swap16(uint32_t value)
 {
-	// 0x11223344 => 0x33441122
 	return (value << 16) | (value >> 16);
 }
 
+/**
+ * @brief Swap the lower and upper 8 bits of a 16-bit value
+ * 
+ * @param value The 16-bit value to swap
+ * @return The 16-bit value with the lower and upper 8 bits swapped
+ * 
+ * Example: 0x1122 => 0x2211
+ */
 static inline uint16_t swap8(uint16_t value)
 {
-	// 0x1122 => 0x2211
 	return (value << 8) | (value >> 8);
 }
 
+/**
+ * @brief Handler for assertion failures
+ * 
+ * @param file The file where the assertion failed
+ * @param line The line number where the assertion failed
+ * @param statement The assertion statement that failed
+ */
 void assert_handler(char *file, int line, char *statement);
 
+/**
+ * @brief Macro for assertions
+ * 
+ * @param _stmt The assertion statement
+ * 
+ * If the assertion statement is false, the assert_handler is called with the file, line, and statement.
+ */
 #define ASSERT(_stmt) do                                                      \
 {                                                                             \
-    if (!(_stmt)) {                                                           \
-        assert_handler(__FILE__, __LINE__, #_stmt);                           \
-    }                                                                         \
+	if (!(_stmt)) {                                                           \
+		assert_handler(__FILE__, __LINE__, #_stmt);                           \
+	}                                                                         \
 } while (0)
-
-#define LIKELY(x)    __builtin_expect ((x), 1)
-#define UNLIKELY(x)  __builtin_expect ((x), 0)