Documented GDT and IDT files and optimized doxygen-output by fixing

__attribute__ misparsings as structure names

Doxyfile

@@ -1384,13 +1384,13 @@ ENABLE_PREPROCESSING   = YES
 # compilation will be performed. Macro expansion can be done in a controlled
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
 # then the macro expansion is limited to the macros specified with the
 # PREDEFINED and EXPAND_AS_DEFINED tags.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
 # in the INCLUDE_PATH (see below) will be search if a #include is found.
@@ -1418,7 +1418,11 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             =
+# Doxygen messes up the attribute lines as c-structure names
+PREDEFINED             = __attribute__ (x)= \
+												 __attribute__(x)= \
+												 __attribute__ ((x))= \
+												 __attribute__((x))=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.

arch/x86/include/asm/gdt.h

@@ -17,6 +17,15 @@
  * This file is part of MetalSVM.
  */
 
+/**
+ * @file arch/x86/include/asm/gdt.h
+ * @brief Definitions and functions related to segmentation
+ * @author Stefan Lankes
+ *
+ * This file defines the interface for segmentation as like structures to describe segments.\n
+ * There are also some other gdt-private functions in the gdt.c file defined.
+ */
+
 #ifndef __ARCH_GDT_H__
 #define __ARCH_GDT_H__
 
@@ -26,41 +35,84 @@
 extern "C" {
 #endif
 
+/// This segment is a data segment
 #define GDT_FLAG_DATASEG        0x02
+/// This segment is a code segment
 #define GDT_FLAG_CODESEG        0x0a
 #define GDT_FLAG_TSS            0x09
 #define GDT_FLAG_TSS_BUSY	0x02
 
 #define GDT_FLAG_SEGMENT        0x10
+/// Privilege level: Ring 0 
 #define GDT_FLAG_RING0          0x00
+/// Privilege level: Ring 1
 #define GDT_FLAG_RING1          0x20
+/// Privilege level: Ring 2 
 #define GDT_FLAG_RING2          0x40
+/// Privilege level: Ring 3 
 #define GDT_FLAG_RING3          0x60
+/// Segment is present
 #define GDT_FLAG_PRESENT        0x80
-
+/** 
+ * @brief Granularity of segment limit 
+ * - set: segment limit unit is 4 KB (page size)
+ * - not set: unit is bytes
+ */
 #define GDT_FLAG_4K_GRAN        0x80
+/**
+ * @brief Default operand size 
+ * - set: 32 bit
+ * - not set: 16 bit
+ */
 #define GDT_FLAG_32_BIT         0x40
 
-/* Defines a GDT entry */
+/** @brief Defines a GDT entry 
+ *
+ * A global descriptor table entry consists of:
+ * - 32 bit base address (chunkwise embedded into this structure)
+ * - 20 bit limit
+ */
 typedef struct {
+	/// Lower 16 bits of limit range
 	unsigned short limit_low;
+	/// Lower 16 bits of base address
 	unsigned short base_low;
+	/// middle 8 bits of base address
 	unsigned char base_middle;
+	/// Access bits
 	unsigned char access;
+	/// Granularity bits
 	unsigned char granularity;
+	/// Higher 8 bits of base address
 	unsigned char base_high;
 } __attribute__ ((packed)) gdt_entry_t;
 
+/** @brief defines the GDT pointer structure
+ *
+ * This structure tells the address and size of the table.
+ */
 typedef struct {
+	/// Size of the table in bytes (not the number of entries!)
 	unsigned short limit;
+	/// Address of the table
 	unsigned int base;
 } __attribute__ ((packed)) gdt_ptr_t;
 
+/// Defines the maximum number of GDT entries
 #define GDT_ENTRIES     (5+MAX_TASKS)
 #if GDT_ENTRIES > 8192
 #error Too many GDT entries!
 #endif
 
+/** @brief Installs the global descriptor table
+ *
+ * The installation involves the following steps:
+ * - set up the special GDT pointer 
+ * - set up the entries in our GDT
+ * - finally call gdt_flush() in our assembler file 
+ *   in order to tell the processor where the new GDT is
+ * - update the new segment registers 
+ */
 void gdt_install(void);
 
 #ifdef __cplusplus

arch/x86/include/asm/idt.h

@@ -17,22 +17,45 @@
  * This file is part of MetalSVM.
  */
 
+/**
+ * @author Stefan Lankes
+ * @file arch/x86/include/asm/idt.h
+ * @brief Definition of IDT flags and functions to set interrupts
+ *
+ * This file contains define-constants for interrupt flags
+ * and installer functions for interrupt gates.\n
+ * See idt.c for structure definitions.
+ */
+
 #ifndef __ARCH_IDT_H__
 #define __ARCH_IDT_H__
 
 #include <metalsvm/stddef.h>
 
+/// This bit shall be set to 0 if the IDT slot is empty
 #define IDT_FLAG_PRESENT 	0x80
+/// Interrupt can be called from within RING0
 #define IDT_FLAG_RING0		0x00
+/// Interrupt can be called from within RING1 and lower
 #define IDT_FLAG_RING1		0x20
+/// Interrupt can be called from within RING2 and lower
 #define IDT_FLAG_RING2		0x40
+/// Interrupt can be called from within RING3 and lower
 #define IDT_FLAG_RING3		0x60
+/// Size of gate is 16 bit
 #define IDT_FLAG_16BIT		0x00
+/// Size of gate is 32 bit
 #define IDT_FLAG_32BIT		0x08
+/// The entry describes an interrupt gate
 #define IDT_FLAG_INTTRAP	0x06
+/// The entry describes a trap gate
 #define IDT_FLAG_TRAPGATE	0x07
+/// The entry describes a task gate
 #define IDT_FLAG_TASKGATE	0x05
 
+/* 
+ * This is not IDT-flag related. It's the segment selectors for kernel code and data.
+ */
 #define KERNEL_CODE_SELECTOR	0x08
 #define KERNEL_DATA_SELECTOR	0x10
 
@@ -40,7 +63,22 @@
 extern "C" {
 #endif
 
+/** @brief Installs IDT
+ *
+ * The installation involves the following steps:
+ * - Set up the IDT pointer
+ * - Set up int 0x80 for syscalls
+ * - process idt_load()
+ */
 void idt_install(void);
+
+/** @brief Set an entry in the IDT
+ *
+ * @param num index in the IDT
+ * @param base base-address of the handler function being installed
+ * @param sel Segment the IDT will use
+ * @param flags Flags this entry will have
+ */
 void idt_set_gate(unsigned char num, unsigned long base, unsigned short sel,
 		  unsigned char flags);
 

arch/x86/include/asm/kb.h

@@ -17,6 +17,15 @@
  * This file is part of MetalSVM.
  */
 
+/**
+ * @file arch/x86/include/asm/kb.h
+ * @brief Keyboard initialization and handling of keystrokes
+ * @author Stefan Lankes
+ *
+ * This file defines the keyboard initialization (if enabled in config) and
+ * keystroke-handling (the most interesting part is in the kb.c-file)
+ */
+
 #ifndef __ARCH_KB_H__
 #define __ARCH_KB_H__
 
@@ -27,7 +36,13 @@ extern "C" {
 #endif
 
 #ifdef CONFIG_KEYBOARD
+
+/** @brief Keyboard initialization procedure
+ *
+ * Installs Keyboard-interrupt into IRQ1
+ */
 void keyboard_init(void);
+
 #endif
 
 #ifdef __cplusplus

arch/x86/kernel/idt.c

@@ -17,20 +17,49 @@
  * This file is part of MetalSVM.
  */
 
+/**
+ * @author Stefan Lankes
+ * @file arch/x86/kernel/idt.c
+ * @brief Definitions and functions related to IDTs
+ *
+ *
+ * This file defines the interface for interrupts as like 
+ * structures to describe interrupt descriptor table entries.\n
+ * See idt.h for flag definitions.
+ */
+
 #include <metalsvm/string.h>
 #include <asm/idt.h>
 
-/* Defines an IDT entry */
+/** @brief Defines an IDT entry
+ *
+ * This structure defines interrupt descriptor table entries.\n
+ * They consist of the handling function's base address, some flags 
+ * and a segment selector.
+ */
 typedef struct {
+	/// Handler function's lower 16 address bits
 	unsigned short base_lo;
+	/// Handler function's segment selector.
 	unsigned short sel;
+	/// These bits are reserved by Intel
 	unsigned char always0;
+	/// These 8 bits contain flags. Exact use depends on the type of interrupt gate.
 	unsigned char flags;
+	/// Higher 16 bits of handler function's base address
 	unsigned short base_hi;
 } __attribute__ ((packed)) idt_entry_t;
 
+
+/** @brief Defines the idt pointer structure.
+ *
+ * This structure keeps information about 
+ * base address and size of the interrupt descriptor table.
+ */
 typedef struct {
+	/// Size of the IDT in bytes (not the number of entries!)
 	unsigned short limit;
+	/// Base address of the IDT
 	unsigned int base;
 } __attribute__ ((packed)) idt_ptr_t;
 
@@ -45,7 +74,10 @@ typedef struct {
 static idt_entry_t idt[256] = {[0 ... 255] = {0, 0, 0, 0, 0}};
 idt_ptr_t idtp;
 
-/* This exists in 'start.asm', and is used to load our IDT */
+/** @brief Loads the IDT
+ *
+ * The true definition lives in 'start.asm'
+ */
 extern void idt_load(void);
 
 /*