Added some documentation

13 files changed, 266 insertions, 15 deletions

diff --git a/src/kernel/acpi/acpi.h b/src/kernel/acpi/acpi.h
index 6db7e72..53c57b4 100644
--- a/src/kernel/acpi/acpi.h
+++ b/src/kernel/acpi/acpi.h
@@ -1,10 +1,20 @@
 #ifndef MELVIX_ACPI_H
 #define MELVIX_ACPI_H
 
+/**
+ * Initialize the ACP interface
+ * @return 0 if successful, otherwise -1
+ */
 int acpi_install();
 
+/**
+ * Activate a ACPI based device reboot
+ */
 void reboot();
 
+/**
+ * Activate a ACPI based device shutdown/poweroff
+ */
 void acpi_poweroff();
 
 #endif
diff --git a/src/kernel/commands/command.h b/src/kernel/commands/command.h
index 2a43416..9e402aa 100644
--- a/src/kernel/commands/command.h
+++ b/src/kernel/commands/command.h
@@ -1,6 +1,11 @@
 #ifndef MELVIX_COMMAND_H
 #define MELVIX_COMMAND_H
 
+/**
+ * Execute a command in the pseudo shell
+ * @deprecated - will be replaced by real shell soon
+ * @param command The desired command
+ */
 void exec_command(char *command);
 
 #endif
diff --git a/src/kernel/gdt/gdt.h b/src/kernel/gdt/gdt.h
index 46d80e2..de8a6ff 100644
--- a/src/kernel/gdt/gdt.h
+++ b/src/kernel/gdt/gdt.h
@@ -1,6 +1,9 @@
 #ifndef MELVIX_GDT_H
 #define MELVIX_GDT_H
 
+/**
+ * Installs the Global Descriptor Table
+ */
 void gdt_install();
 
 #endif
diff --git a/src/kernel/graphics/graphics.h b/src/kernel/graphics/graphics.h
index 3136b1e..e20d1ed 100644
--- a/src/kernel/graphics/graphics.h
+++ b/src/kernel/graphics/graphics.h
@@ -5,21 +5,53 @@
 #include <stdint.h>
 #include "vesa.h"
 
-// VGA
+/**
+ * Linked table of colors and hardware color codes
+ */
 enum vga_color;
 
+/**
+ * Initialize the terminal color and cursor position
+ */
 void terminal_initialize(void);
 
+/**
+ * Set the terminal color to a specified hardware color code
+ * @see enum vga_color
+ * @param color
+ */
 void terminal_set_color(uint8_t color);
 
+/**
+ * Clear the entire terminal screen
+ */
 void terminal_clear();
 
+/**
+ * Write a string to the terminal
+ * @param data The string that should be written
+ */
 void terminal_write_string(const char *data);
 
+/**
+ * Put a new char at the x+1 cursor position and
+ * handle according events (e.g. overflow, linebreak)
+ * @param c The character (can also be \n or \r)
+ */
 void terminal_put_char(char c);
 
+/**
+ * Put a new char at the x+1 cursor position,
+ * handle according events (e.g. overflow, linebreak) and
+ * execute the current command if c is linebreak (\n)
+ * @param c The character (can also be \n or \r)
+ */
 void terminal_put_keyboard_char(char c);
 
+/**
+ * Write a line to the terminal
+ * @param data The line (string) that should be written
+ */
 void terminal_write_line(const char *data);
 
 #endif
\ No newline at end of file
diff --git a/src/kernel/graphics/vesa.h b/src/kernel/graphics/vesa.h
index 203b06b..d163fb3 100644
--- a/src/kernel/graphics/vesa.h
+++ b/src/kernel/graphics/vesa.h
@@ -4,6 +4,10 @@
 #include <stdint.h>
 #include "../system.h"
 
+/**
+ * The CPUs response to the 0x4F00 call
+ * Used to receive the supported video modes
+ */
 struct vbe_info {
     char signature[4];
     uint32_t version;
@@ -19,6 +23,10 @@ struct vbe_info {
     char oem_data[256];
 } __attribute__ ((packed));
 
+/**
+ * The CPUs response to the 0x4F01 call
+ * Used to get information about a specific video mode code
+ */
 struct vbe_mode_info {
     uint16_t attributes;
     uint8_t window_a;
@@ -57,14 +65,43 @@ struct vbe_mode_info {
     uint8_t reserved1[206];
 } __attribute__ ((packed));
 
+/**
+ * Set the video mode to a specified resolution using
+ * a video mode code
+ * @param mode The requested video mode code from 0x4F00 call
+ * @return A structure with information about the video mode
+ */
 struct vbe_mode_info *vbe_set_mode(unsigned short mode);
 
+/**
+ * Find the highest resolution using 0x4F00 and call
+ * vbe_set_mode using the video_modes far_ptr
+ */
 void set_optimal_resolution();
 
+/**
+ * The current video mode
+ */
 int vbe_current_mode;
+
+/**
+ * The width of the current video mode
+ */
 int vbe_width;
+
+/**
+ * The height of the current video mode
+ */
 int vbe_height;
+
+/**
+ * The bits per pixel of the current video mode
+ */
 int vbe_bpp;
+
+/**
+ * The pitch (bytes per line) of the current video mode
+ */
 int vbe_pitch;
 
 #endif
diff --git a/src/kernel/input/input.h b/src/kernel/input/input.h
index 45ecf5e..063eee2 100644
--- a/src/kernel/input/input.h
+++ b/src/kernel/input/input.h
@@ -1,8 +1,15 @@
 #ifndef MELVIX_INPUT_H
 #define MELVIX_INPUT_H
 
+/**
+ * Initialize the mouse IRQ handler
+ */
 void mouse_install();
 
+/**
+ * Initialize the us keyboard layout,
+ * keyboard rate and IRQ handler
+ */
 void keyboard_install();
 
 #endif
diff --git a/src/kernel/interrupts/interrupts.h b/src/kernel/interrupts/interrupts.h
index 755a633..80c9b27 100644
--- a/src/kernel/interrupts/interrupts.h
+++ b/src/kernel/interrupts/interrupts.h
@@ -1,14 +1,28 @@
 #ifndef MELVIX_INTERRUPTS_H
 #define MELVIX_INTERRUPTS_H
 
-// IDT
+/**
+ * Initialize the Interrupt Descriptor Table with 256 entries
+ */
 void idt_install();
 
+/**
+ * Add new gate (Interrupt Service Routine) to the Interrupt Descriptor Table
+ * @param num The index of the routine in the IDT
+ * @param base The base address of the ISR
+ * @param sel The kernel code segment (0x08)
+ * @param flags The IDT access byte entry (P DPL 01110)
+ */
 void idt_set_gate(unsigned char num, unsigned long base, unsigned short sel, unsigned char flags);
 
-// ISRS
+/**
+ * Install 32 exception ISRs into the IDT
+ */
 void isrs_install();
 
+/**
+ * Registers that get passed into an IRQ handler
+ */
 struct regs {
     unsigned int gs, fs, es, ds;
     unsigned int edi, esi, ebp, esp, ebx, edx, ecx, eax;
@@ -16,15 +30,36 @@ struct regs {
     unsigned int eip, cs, eflags, useresp, ss;
 };
 
-// IRQ
+/**
+ * Initialize the Interrupt Requests by mapping the ISRs to the correct
+ * entries in the IDT (install the exception handlers)
+ */
 void irq_install();
 
+/**
+ * Add a new Interrupt Request Handler
+ * @param irq The index of the IRQ routine
+ * @param handler The interrupt handler function
+ */
 void irq_install_handler(int irq, void (*handler)(struct regs *r));
 
+/**
+ * Uninstall a handler by index
+ * @param irq The index of the IRQ routine that should be removed
+ */
 void irq_uninstall_handler(int irq);
 
+/**
+ * Execute the handler of the IRQ
+ * @param r The ISR that should be handled
+ */
 void irq_handler(struct regs *r);
 
+/**
+ * Check if an IRQ is installed
+ * @param irq The index of the IRQ routine that should be checked
+ * @return 1 if installed, 0 if not
+ */
 int irq_is_installed(int irq);
 
 #endif
diff --git a/src/kernel/io/io.h b/src/kernel/io/io.h
index 22776ee..8e39f84 100644
--- a/src/kernel/io/io.h
+++ b/src/kernel/io/io.h
@@ -3,16 +3,46 @@
 
 #include <stdint.h>
 
+/**
+ * Receive from specified hardware port
+ * @param port The hardware port
+ * @return The hardware response
+ */
 uint8_t receive_b(uint16_t port);
 
+/**
+ * Receive from specified hardware port
+ * @param port The hardware port
+ * @return The hardware response
+ */
 uint16_t receive_w(uint16_t port);
 
+/**
+ * Receive from specified hardware port
+ * @param port The hardware port
+ * @return The hardware response
+ */
 uint32_t receive_l(uint16_t port);
 
+/**
+ * Send data to the specified hardware port
+ * @param port The hardware port
+ * @param data The data that should be sent
+ */
 void send_b(uint16_t port, uint8_t data);
 
+/**
+ * Send data to the specified hardware port
+ * @param port The hardware port
+ * @param data The data that should be sent
+ */
 void send_w(uint16_t port, uint16_t data);
 
+/**
+ * Send data to the specified hardware port
+ * @param port The hardware port
+ * @param data The data that should be sent
+ */
 void send_l(uint16_t port, uint32_t data);
 
 #endif
diff --git a/src/kernel/lib/lib.h b/src/kernel/lib/lib.h
index f83c7d5..d6cc09e 100644
--- a/src/kernel/lib/lib.h
+++ b/src/kernel/lib/lib.h
@@ -3,20 +3,70 @@
 
 #include <stddef.h>
 
+/**
+ * Find the length of a string
+ * @param str The string pointer which size should be calculated
+ * @return The length of str
+ */
 size_t strlen(const char *str);
 
+/**
+ * Compare two strings
+ * @param s1 The first string pointer
+ * @param s2 The second string pointer
+ * @return The length difference between s1 and s2
+ */
 size_t strcmp(const char *s1, const char *s2);
 
-char *strcat(char *dst, const char *src);
+/**
+ * Append the data of src to dest
+ * @param dest The string destination pointer
+ * @param src The string pointer that will get appended
+ * @return The modified dest pointer
+ */
+char *strcat(char *dest, const char *src);
 
-char *strcpy(char *dst, const char *src);
+/**
+ * Copy the data of src to dest
+ * @param dest The copying destination pointer (gets replaced)
+ * @param src The string pointer that will get copied
+ * @return The modified dest pointer
+ */
+char *strcpy(char *dest, const char *src);
 
+/**
+ * Copy n data from src to dest
+ * @param dest The destination array pointer
+ * @param src The source array pointer of the data
+ * @param count The number of bytes to be copied (src)
+ * @return The modified dest pointer
+ */
 void *memory_copy(void *dest, const void *src, size_t count);
 
+/**
+ * Replace n bytes of dest by val
+ * @param dest The destination array pointer
+ * @param val The replacing chracater
+ * @param count The number of times val should replace dest entry
+ * @return The modified dest pointer
+ */
 void *memory_set(void *dest, char val, size_t count);
 
+/**
+ * Compare the first n bytes of a and b
+ * @param a_ptr The first memory area pointer
+ * @param b_ptr The second memory area pointer
+ * @param size The number of bytes to be compared
+ * @return -1 if a < b, 0 if a = b and 1 if a > b
+ */
 int memory_compare(const void *a_ptr, const void *b_ptr, size_t size);
 
+/**
+ * Convert an int into a string
+ * @param i The integer which should be converted
+ * @param b The converted int as string
+ * @return The converted string (b)
+ */
 char *itoa(int i, char b[]);
 
 #endif
diff --git a/src/kernel/lib/string.c b/src/kernel/lib/string.c
index 2b8cdfb..f07697d 100644
--- a/src/kernel/lib/string.c
+++ b/src/kernel/lib/string.c
@@ -15,24 +15,24 @@ size_t strcmp(const char *s1, const char *s2) {
     return *(const unsigned char *) s1 - *(const unsigned char *) s2;
 }
 
-char *strcat(char *dst, const char *src) {
+char *strcat(char *dest, const char *src) {
     unsigned int i = 0;
     unsigned int j = 0;
-    for (i = 0; dst[i] != 0; i++) {}
+    for (i = 0; dest[i] != 0; i++) {}
     for (j = 0; src[j] != 0; j++) {
-        dst[i + j] = src[j];
+        dest[i + j] = src[j];
     }
-    dst[i + j] = 0;
-    return dst;
+    dest[i + j] = 0;
+    return dest;
 }
 
-char *strcpy(char *dst, const char *src) {
+char *strcpy(char *dest, const char *src) {
     unsigned int i = 0;
     for (i = 0; src[i] != 0; i++) {
-        dst[i] = src[i];
+        dest[i] = src[i];
     }
-    dst[i] = 0;
-    return dst;
+    dest[i] = 0;
+    return dest;
 }
 
 char *itoa(int i, char b[]) {
diff --git a/src/kernel/sound/sound.h b/src/kernel/sound/sound.h
index 15c67c5..312f0d8 100644
--- a/src/kernel/sound/sound.h
+++ b/src/kernel/sound/sound.h
@@ -3,6 +3,11 @@
 
 #include <stdint.h>
 
+/**
+ * Beep in specific frequency for amount of ticks
+ * @param frequency The frequency of the beep
+ * @param ticks The duration in ticks
+ */
 void beep(uint32_t frequency, uint32_t ticks);
 
 #endif
diff --git a/src/kernel/system.h b/src/kernel/system.h
index 47d902c..c7ed2fd 100644
--- a/src/kernel/system.h
+++ b/src/kernel/system.h
@@ -1,15 +1,29 @@
 #ifndef MELVIX_SYSTEM_H
 #define MELVIX_SYSTEM_H
 
+/**
+ * Initialize the basic features of the OS
+ */
 void init();
 
+/**
+ * The ASM registers as packed structure
+ */
 typedef struct __attribute__ ((packed)) {
     unsigned short di, si, bp, sp, bx, dx, cx, ax;
     unsigned short gs, fs, es, ds, eflags;
 } regs16_t;
 
+/**
+ * Execute BIOS interrupts by switching to real mode
+ * @param intnum The interrupt number (e.g. 0x10)
+ * @param regs The ASM registers
+ */
 extern void int32(unsigned char intnum, regs16_t *regs);
 
+/**
+ * ASM segment:offset pointer
+ */
 struct far_ptr {
     union {
         uint32_t ptr;
@@ -19,14 +33,25 @@ struct far_ptr {
     };
 } __attribute__ ((packed));
 
+/**
+ * Get offset from ASM segment:offset pointer
+ */
 static inline uint16_t get_offset(const volatile void *p) {
     return (uint16_t) (uintptr_t) p & 0x000F;
 }
 
+/**
+ * Get segment from ASM segment:offset pointer
+ */
 static inline uint16_t get_segment(const volatile void *p) {
     return (uint16_t) (((uintptr_t) p) >> 4);
 }
 
+/**
+ * Convert pointer to far_ptr
+ * @param __ptr The ASM segment:offset pointer
+ * @return The new far pointer
+ */
 static inline struct far_ptr FAR_PTR(void *__ptr) {
     struct far_ptr __fptr;
     __fptr.offset = get_offset(__ptr);
@@ -34,6 +59,11 @@ static inline struct far_ptr FAR_PTR(void *__ptr) {
     return __fptr;
 }
 
+/**
+ * Get pointer from ASM segment:offset far pointer
+ * @param fptr The ASM far pointer
+ * @return The normalized pointer
+ */
 static inline void *get_ptr(struct far_ptr fptr) {
     return (void *) (unsigned long) ((fptr.segment << 4) + fptr.offset);
 }
diff --git a/src/kernel/timer/timer.h b/src/kernel/timer/timer.h
index 66b3c95..635c996 100644
--- a/src/kernel/timer/timer.h
+++ b/src/kernel/timer/timer.h
@@ -1,8 +1,15 @@
 #ifndef MELVIX_TIMER_H
 #define MELVIX_TIMER_H
 
+/**
+ * Install the timer and set the timer phase to 100
+ */
 void timer_install();
 
+/**
+ * Stop processing for specific duration
+ * @param ticks The duration of sleeping in ticks
+ */
 void timer_wait(int ticks);
 
 #endif