Comprehensive documentations for Rishka kernel source files.

src/rishka.h

@@ -15,16 +15,28 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file rishka.h
+ * @author [Nathanne Isip](https://github.com/nthnn)
+ * @brief Includes all the necessary headers for Rishka kernel development.
+ *
+ * The rishka.h header file serves as a central point for including all the
+ * necessary headers required for Rishka kernel development. By including this
+ * header file in your Arduino sketch or library, you gain access to essential
+ * components and utilities provided by the Rishka kernel, facilitating the
+ * development of efficient and feature-rich embedded applications.
+ */
+
 #ifndef RISHKA_H
 #define RISHKA_H
 
-#include <rishka_commons.h>
-#include <rishka_errors.h>
-#include <rishka_instructions.h>
-#include <rishka_syscalls.h>
-#include <rishka_types.h>
-#include <rishka_util.h>
-#include <rishka_vm.h>
-#include <rishka_vm_helper.h>
+#include <rishka_commons.h>        ///< Common definitions and macros.
+#include <rishka_errors.h>         ///< Error code definitions and handling.
+#include <rishka_instructions.h>   ///< Instruction set architecture definitions.
+#include <rishka_syscalls.h>       ///< System call interface and implementations.
+#include <rishka_types.h>          ///< Type definitions and aliases.
+#include <rishka_util.h>           ///< Utility functions and macros.
+#include <rishka_vm.h>             ///< Virtual machine core functionalities.
+#include <rishka_vm_helper.h>      ///< Helper functions for virtual machine operations.
 
-#endif
+#endif /* RISHKA_H */

src/rishka_commons.h

@@ -15,13 +15,22 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file rishka_commons.h
+ * @author [Nathanne Isip](https://github.com/nthnn)
+ * @brief Common definitions used across Rishka modules.
+ *
+ * This file contains common definitions and includes commonly
+ * used libraries for Rishka modules.
+ */
+
 #ifndef RISHKA_COMMONS_H
 #define RISHKA_COMMONS_H
 
-#include <Arduino.h>
-#include <SD.h>
-#include <SPI.h>
+#include <Arduino.h>    ///< Include Arduino core library.
+#include <SD.h>         ///< Include SD card library.
+#include <SPI.h>        ///< Include SPI communication library.
 
-#define  RISHKA_VM_STACK_SIZE 32768U
+#define  RISHKA_VM_STACK_SIZE 32768U    ///< Define the stack size for the Rishka virtual machine.
 
 #endif

src/rishka_errors.h

@@ -15,13 +15,41 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file rishka_errors.h
+ * @author [Nathanne Isip](https://github.com/nthnn)
+ * @brief Header file for error handling functions in Rishka.
+ *
+ * This file declares functions for error handling in the Rishka virtual machine.
+ * It provides utilities for printing error messages and handling panics.
+ */
+
 #ifndef RISHKA_ERRORS_H
 #define RISHKA_ERRORS_H
 
 #include <rishka_commons.h>
 #include <rishka_vm.h>
 
+/**
+ * @brief Print an error message to the standard error stream.
+ *
+ * This function prints the specified error message to the standard output stream.
+ *
+ * @param msg The error message to print.
+ * @param len The length of the error message.
+ * @param flush Whether to flush the standard error stream after printing the message.
+ */
 void rishka_perror(const char* msg, uintptr_t len, bool flush);
+
+/**
+ * @brief Handle a panic situation in the virtual machine.
+ *
+ * This function is called to handle a panic situation in the Rishka virtual machine.
+ * It prints the panic message and performs any necessary cleanup before terminating the program.
+ *
+ * @param message The panic message to print.
+ * @param vm A pointer to the virtual machine structure associated with the panic.
+ */
 void rishka_panic(const char* message, rishka_virtual_machine* vm);
 
-#endif
+#endif /* RISHKA_ERRORS_H */

src/rishka_instructions.h

@@ -15,66 +15,123 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file rishka_instructions.h
+ * @author [Nathanne Isip](https://github.com/nthnn)
+ * @brief Header file defining enumerations for Rishka instructions and their formats.
+ *
+ * This file defines several enumerations related to Rishka instructions and their formats.
+ * The Rishka architecture utilizes these enumerations to represent various types of instructions,
+ * such as load, store, immediate arithmetic/logical, integer arithmetic/logical, branch, and other types of instructions.
+ * Each enumeration provides symbolic names for specific opcode or funct3 field values, making the code more readable and maintainable.
+ */
+
 #ifndef RISHKA_INSTRUCTIONS_H
 #define RISHKA_INSTRUCTIONS_H
 
+/**
+ * @enum rishka_instruction
+ * @brief Enumeration of Rishka instruction opcodes.
+ *
+ * This enumeration defines symbolic names for each instruction opcode supported by the Rishka architecture.
+ * Each opcode represents a specific instruction that can be executed by the Rishka processor.
+ */
 enum rishka_instruction {
-    RISHKA_OPINST_LOAD   = 0x03,
-    RISHKA_OPINST_STORE  = 0x23,
-    RISHKA_OPINST_IMM    = 0x13,
-    RISHKA_OPINST_IALU   = 0x1b,
-    RISHKA_OPINST_RT32   = 0x3b,
-    RISHKA_OPINST_RT64   = 0x33,
-    RISHKA_OPINST_LUI    = 0x37,
-    RISHKA_OPINST_AUIPC  = 0x17,
-    RISHKA_OPINST_JAL    = 0x6f,
-    RISHKA_OPINST_JALR   = 0x67,
-    RISHKA_OPINST_BRANCH = 0x63,
-    RISHKA_OPINST_FENCE  = 0x0f,
-    RISHKA_OPINST_CALL   = 0x73,
+    RISHKA_OPINST_LOAD   = 0x03,    /**< Load instruction. */
+    RISHKA_OPINST_STORE  = 0x23,    /**< Store instruction. */
+    RISHKA_OPINST_IMM    = 0x13,    /**< Immediate arithmetic/logical instruction. */
+    RISHKA_OPINST_IALU   = 0x1b,    /**< Integer arithmetic/logical instruction. */
+    RISHKA_OPINST_RT32   = 0x3b,    /**< 32-bit register transfer instruction. */
+    RISHKA_OPINST_RT64   = 0x33,    /**< 64-bit register transfer instruction. */
+    RISHKA_OPINST_LUI    = 0x37,    /**< Load upper immediate instruction. */
+    RISHKA_OPINST_AUIPC  = 0x17,    /**< Add upper immediate to PC instruction. */
+    RISHKA_OPINST_JAL    = 0x6f,    /**< Jump and link instruction. */
+    RISHKA_OPINST_JALR   = 0x67,    /**< Jump and link register instruction. */
+    RISHKA_OPINST_BRANCH = 0x63,    /**< Branch instruction. */
+    RISHKA_OPINST_FENCE  = 0x0f,    /**< Fence instruction. */
+    RISHKA_OPINST_CALL   = 0x73,    /**< Call instruction. */
 };
 
+/**
+ * @enum rishka_load_fc3
+ * @brief Enumeration of Rishka load instruction funct3 values.
+ *
+ * This enumeration defines symbolic names for the funct3 field
+ * values used in load instructions in the Rishka architecture.
+ */
 enum rishka_load_fc3 {
-    RISHKA_FC3_LB,
-    RISHKA_FC3_LHW,
-    RISHKA_FC3_LW,
-    RISHKA_FC3_LDW,
-    RISHKA_FC3_LBU,
-    RISHKA_FC3_LHU,
-    RISHKA_FC3_LRES,
+    RISHKA_FC3_LB,     /**< Load byte. */
+    RISHKA_FC3_LHW,    /**< Load half-word. */
+    RISHKA_FC3_LW,     /**< Load word. */
+    RISHKA_FC3_LDW,    /**< Load double-word. */
+    RISHKA_FC3_LBU,    /**< Load byte unsigned. */
+    RISHKA_FC3_LHU,    /**< Load half-word unsigned. */
+    RISHKA_FC3_LRES    /**< Reserved load format. */
 };
 
+/**
+ * @enum rishka_store_fc3
+ * @brief Enumeration of Rishka store instruction funct3 values.
+ *
+ * This enumeration defines symbolic names for the funct3
+ * field values used in store instructions in the Rishka
+ * architecture.
+ */
 enum rishka_store_fc3 {
-    RISHKA_FC3_SB,
-    RISHKA_FC3_SHW,
-    RISHKA_FC3_SW,
-    RISHKA_FC3_SDW
+    RISHKA_FC3_SB,     /**< Store byte. */
+    RISHKA_FC3_SHW,    /**< Store half-word. */
+    RISHKA_FC3_SW,     /**< Store word. */
+    RISHKA_FC3_SDW     /**< Store double-word. */
 };
 
+/**
+ * @enum rishka_immediate_fc3
+ * @brief Enumeration of Rishka immediate arithmetic/logical instruction funct3 values.
+ *
+ * This enumeration defines symbolic names for the funct3 field
+ * values used in immediate arithmetic/logical instructions in
+ * the Rishka architecture.
+ */
 enum rishka_immediate_fc3 {
-    RISHKA_FC3_ADDI,
-    RISHKA_FC3_SLLI,
-    RISHKA_FC3_SLTI,
-    RISHKA_FC3_SLTIU,
-    RISHKA_FC3_XORI,
-    RISHKA_FC3_SRLI,
-    RISHKA_FC3_ORI,
-    RISHKA_FC3_ANDI
+    RISHKA_FC3_ADDI,    /**< Add immediate. */
+    RISHKA_FC3_SLLI,    /**< Shift left logical immediate. */
+    RISHKA_FC3_SLTI,    /**< Set less than immediate. */
+    RISHKA_FC3_SLTIU,   /**< Set less than immediate unsigned. */
+    RISHKA_FC3_XORI,    /**< XOR immediate. */
+    RISHKA_FC3_SRLI,    /**< Shift right logical immediate. */
+    RISHKA_FC3_ORI,     /**< OR immediate. */
+    RISHKA_FC3_ANDI     /**< AND immediate. */
 };
 
+/**
+ * @enum rishka_ialu_fc3
+ * @brief Enumeration of Rishka integer arithmetic/logical instruction funct3 values.
+ *
+ * This enumeration defines symbolic names for the funct3
+ * field values used in integer arithmetic/logical instructions
+ * in the Rishka architecture.
+ */
 enum rishka_ialu_fc3 {
-    RISHKA_FC3_SLLIW,
-    RISHKA_FC3_SRLIW,
-    RISHKA_FC3_SRAIW
+    RISHKA_FC3_SLLIW,  /**< Shift left logical immediate word. */
+    RISHKA_FC3_SRLIW,  /**< Shift right logical immediate word. */
+    RISHKA_FC3_SRAIW   /**< Shift right arithmetic immediate word. */
 };
 
+/**
+ * @enum rishka_branch_fc3
+ * @brief Enumeration of Rishka branch instruction funct3 values.
+ *
+ * This enumeration defines symbolic names for the funct3
+ * field values used in branch instructions in the Rishka
+ * architecture.
+ */
 enum rishka_branch_fc3 {
-    RISHKA_FC3_BEQ,
-    RISHKA_FC3_BNE,
-    RISHKA_FC3_BLT,
-    RISHKA_FC3_BGE,
-    RISHKA_FC3_BLTU,
-    RISHKA_FC3_BGEU
+    RISHKA_FC3_BEQ,    /**< Branch if equal. */
+    RISHKA_FC3_BNE,    /**< Branch if not equal. */
+    RISHKA_FC3_BLT,    /**< Branch if less than. */
+    RISHKA_FC3_BGE,    /**< Branch if greater than or equal. */
+    RISHKA_FC3_BLTU,   /**< Branch if less than unsigned. */
+    RISHKA_FC3_BGEU    /**< Branch if greater than or equal unsigned. */
 };
 
-#endif
+#endif /* RISHKA_INSTRUCTIONS_H */

src/rishka_syscalls.h

@@ -15,11 +15,31 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file rishka_syscalls.h
+ * @brief Defines system calls for the Rishka kernel.
+ *
+ * This header file provides declarations for various
+ * system calls used within the Rishka kernel. These
+ * system calls enable communication and interaction between
+ * user programs and the kernel, allowing access to hardware
+ * resources, filesystem operations, and other kernel
+ * functionalities.
+ */
+
 #ifndef RISHKA_SYSCALLS_H
 #define RISHKA_SYSCALLS_H
 
 #include <rishka_vm.h>
 
+/**
+ * @enum rishka_syscall
+ * @brief Enumeration of system call codes for the Rishka kernel.
+ *
+ * This enumeration defines symbolic names for each system call supported by the Rishka kernel.
+ * Each system call has a unique code associated with it, which is used to identify the specific
+ * operation requested by the user program.
+ */
 enum rishka_syscall {
     RISHKA_SC_IO_PRINTS,
     RISHKA_SC_IO_PRINTN,
@@ -260,4 +280,4 @@ void rishka_syscall_spi_write_pattern(rishka_virtual_machine* vm);
 char rishka_syscall_rt_strpass();
 void rishka_syscall_rt_yield();
 
-#endif
+#endif /* RISHKA_TYPES_H */