doxygen: Cleanup arch.h comments

Change-Id: I0c5743ab2db3cb1bc584ced4fa9d91c84da971b8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>

include/arch/x86/arch.h

@@ -1,5 +1,3 @@
-/* arch.h - IA-32 specific nanokernel interface header */
-
 /*
  * Copyright (c) 2010-2014 Wind River Systems, Inc.
  *
@@ -31,9 +29,10 @@
  */
 
 /*
-DESCRIPTION
+ * @file
-This header contains the IA-32 specific nanokernel interface.  It is included
+ * @brief IA-32 specific nanokernel interface header
-by the generic nanokernel interface header (nanokernel.h)
+ * This header contains the IA-32 specific nanokernel interface.  It is included
+ * by the generic nanokernel interface header (nanokernel.h)
  */
 
 #ifndef _ARCH_IFACE_H
@@ -48,7 +47,7 @@ by the generic nanokernel interface header (nanokernel.h)
 #define OCTET_TO_SIZEOFUNIT(X) (X)
 #define SIZEOFUNIT_TO_OCTET(X) (X)
 
-/*
+/**
  * Macro used internally by NANO_CPU_INT_REGISTER and NANO_CPU_INT_REGISTER_ASM.
  * Not meant to be used explicitly by BSP, driver or application code.
  */
@@ -59,7 +58,7 @@ by the generic nanokernel interface header (nanokernel.h)
 /* interrupt/exception/error related definitions */
 
 #define _INT_STUB_SIZE		0x2b
-/*
+/**
  * Performance optimization
  *
  * Macro PERF_OPT is defined if project is compiled with option other than
@@ -74,7 +73,7 @@ by the generic nanokernel interface header (nanokernel.h)
 #define _INT_STUB_ALIGN	1
 #endif
 
-/*
+/**
  * Floating point register set alignment.
  *
  * If support for SSEx extensions is enabled a 16 byte boundary is required,
@@ -100,13 +99,15 @@ by the generic nanokernel interface header (nanokernel.h)
 typedef unsigned char __aligned(_INT_STUB_ALIGN) NANO_INT_STUB[_INT_STUB_SIZE];
 
 typedef struct s_isrList {
-	void		*fnc;    /* Address of ISR/stub */
+	/** Address of ISR/stub */
-	unsigned int    vec;    /* Vector number associated with ISR/stub */
+	void		*fnc;
-	unsigned int    dpl;    /* Privilege level associated with ISR/stub */
+	/** Vector number associated with ISR/stub */
+	unsigned int    vec;
+	/** Privilege level associated with ISR/stub */
+	unsigned int    dpl;
 } ISR_LIST;
 
 /**
- *
  * @brief Connect a routine to an interrupt vector
  *
  * This macro "connects" the specified routine, <r>, to the specified interrupt
@@ -121,6 +122,9 @@ typedef struct s_isrList {
  * The <d> argument specifies the privilege level for the interrupt-gate
  * descriptor; (hardware) interrupts and exceptions should specify a level of 0,
  * whereas handlers for user-mode software generated interrupts should specify 3.
+ * @param r Routine to be connected
+ * @param v Interrupt Vector
+ * @param d Descriptor Privilege Level
  *
  * @return N/A
  *
@@ -130,22 +134,30 @@ typedef struct s_isrList {
 	 ISR_LIST __attribute__((section(".intList"))) MK_ISR_NAME(r) = {&r, v, d}
 
 /*
+ * @brief Declare a dynamic interrupt stub
+ *
  * Macro to declare a dynamic interrupt stub. Using the macro places the stub
  * in the .intStubSection which is located in the image according to the kernel
  * configuration.
+ * @param s Stub to be declared
  */
-  #define NANO_CPU_INT_STUB_DECL(s) \
+#define NANO_CPU_INT_STUB_DECL(s) \
 	_NODATA_SECTION(.intStubSect) NANO_INT_STUB(s)
 
 
 /**
- *
  * @brief Connect a routine to interrupt number
  *
  * For the device <device> associates IRQ number <irq> with priority
  * <priority> with the interrupt routine <isr>, that receives parameter
  * <parameter>
  *
+ * @param device Device
+ * @param iqr IRQ number
+ * @param priority IRQ Priority
+ * @param isr Interrupt Service Routine
+ * @param parameter ISR parameter
+ *
  * @return N/A
  *
  */
@@ -161,6 +173,8 @@ typedef struct s_isrList {
  *
  * For the given device do the neccessary configuration steps.
  * For x86 platform configure APIC and mark interrupt vector allocated
+ * @param device Device
+ * @param irq IRQ
  *
  * @return N/A
  *
@@ -172,7 +186,8 @@ typedef struct s_isrList {
 	} while(0)
 
 
-/*
+/**
+ * @brief Nanokernel Exception Stack Frame
  * A pointer to an "exception stack frame" (ESF) is passed as an argument
  * to exception handlers registered via nanoCpuExcConnect().  When an exception
  * occurs while PL=0, then only the EIP, CS, and EFLAGS are pushed onto the stack.
@@ -195,8 +210,8 @@ typedef struct s_isrList {
  */
 
 typedef struct nanoEsf {
-	unsigned int cr2; /* putting cr2 here allows discarding it and pEsf in
+	/** putting cr2 here allows discarding it and pEsf in one instruction */
-			   * one instruction */
+	unsigned int cr2;
 #ifdef CONFIG_GDB_INFO
 	unsigned int ebp;
 	unsigned int ebx;
@@ -215,6 +230,7 @@ typedef struct nanoEsf {
 } NANO_ESF;
 
 /*
+ * @brief Nanokernel "interrupt stack frame" (ISF)
  * An "interrupt stack frame" (ISF) as constructed by the processor
  * and the interrupt wrapper function _IntExit().  When an interrupt
  * occurs while PL=0, only the EIP, CS, and EFLAGS are pushed onto the stack.
@@ -250,12 +266,18 @@ typedef struct nanoIsf {
  * and _SysFatalErrorHandler().
  */
 
-#define _NANO_ERR_SPURIOUS_INT		 (0)	/* Unhandled exception/interrupt */
+/** Unhandled exception/interrupt */
-#define _NANO_ERR_PAGE_FAULT		 (1)	/* Page fault */
+#define _NANO_ERR_SPURIOUS_INT		 (0)
-#define _NANO_ERR_GEN_PROT_FAULT	 (2)	/* General protection fault */
+/** Page fault */
-#define _NANO_ERR_INVALID_TASK_EXIT  (3)	/* Invalid task exit */
+#define _NANO_ERR_PAGE_FAULT		 (1)
-#define _NANO_ERR_STACK_CHK_FAIL	 (4)	/* Stack corruption detected */
+/** General protection fault */
-#define _NANO_ERR_ALLOCATION_FAIL    (5)    /* Kernel Allocation Failure */
+#define _NANO_ERR_GEN_PROT_FAULT	 (2)
+/** Invalid task exit */
+#define _NANO_ERR_INVALID_TASK_EXIT  (3)
+/** Stack corruption detected */
+#define _NANO_ERR_STACK_CHK_FAIL	 (4)
+/** Kernel Allocation Failure */
+#define _NANO_ERR_ALLOCATION_FAIL    (5)
 
 #ifndef _ASMLANGUAGE
 
@@ -275,7 +297,6 @@ void _int_latency_stop(void);
 #endif
 
 /**
- *
  * @brief Disable all interrupts on the CPU (inline)
  *
  * This routine disables interrupts.  It can be called from either interrupt,
@@ -347,23 +368,23 @@ static inline __attribute__((always_inline))
 }
 #endif /* CONFIG_NO_ISRS */
 
-/* interrupt/exception/error related definitions */
+/** interrupt/exception/error related definitions */
-
 typedef void (*NANO_EOI_GET_FUNC) (void *);
 
-/*
+/**
  * The NANO_SOFT_IRQ macro must be used as the value for the <irq> parameter
  * to irq_connect() when connecting to a software generated interrupt.
  */
-
 #define NANO_SOFT_IRQ	((unsigned int) (-1))
 
 #ifdef CONFIG_FP_SHARING
 /* Definitions for the 'options' parameter to the fiber_fiber_start() API */
 
-#define USE_FP		0x10	/* context uses floating point unit */
+/** context uses floating point unit */
+#define USE_FP		0x10
 #ifdef CONFIG_SSE
-#define USE_SSE		0x20	/* context uses SSEx instructions */
+/** context uses SSEx instructions */
+#define USE_SSE		0x20
 #endif /* CONFIG_SSE */
 #endif /* CONFIG_FP_SHARING */
 
@@ -381,28 +402,36 @@ extern int	irq_connect(unsigned int irq,
 					 void (*routine)(void *parameter),
 					 void *parameter);
 
-/*
+/**
- * irq_enable()  : enable a specific IRQ
+ * @brief Enable a specific IRQ
- * irq_disable() : disable a specific IRQ
+ * @param irq IRQ
- * irq_lock()	: lock out all interrupts
- * irq_unlock()  : unlock all interrupts
  */
-
 extern void	irq_enable(unsigned int irq);
+/**
+ * @brief Disable a specific IRQ
+ * @param irq IRQ
+ */
 extern void	irq_disable(unsigned int irq);
 
 #ifndef CONFIG_NO_ISRS
+/**
+ * @brief Lock out all interrupts
+ */
 extern int	irq_lock(void);
+
+/**
+ * @brief Unlock all interrupts
+ */
 extern void	irq_unlock(int key);
 #endif /* CONFIG_NO_ISRS */
 
 #ifdef CONFIG_FP_SHARING
-/*
+/**
+ * @brief Enable floating point hardware resources sharing
  * Dynamically enable/disable the capability of a context to share floating
  * point hardware resources.  The same "floating point" options accepted by
  * fiber_fiber_start() are accepted by these APIs (i.e. USE_FP and USE_SSE).
  */
-
 extern void	fiber_float_enable(nano_context_id_t ctx, unsigned int options);
 extern void	task_float_enable(nano_context_id_t ctx, unsigned int options);
 extern void	fiber_float_disable(nano_context_id_t ctx);
@@ -415,31 +444,33 @@ extern void	task_float_disable(nano_context_id_t ctx);
 extern void	nano_cpu_idle(void);
 #endif
 
-/* Nanokernel provided routine to report any detected fatal error. */
+/** Nanokernel provided routine to report any detected fatal error. */
 extern FUNC_NORETURN void _NanoFatalErrorHandler(unsigned int reason,
 						 const NANO_ESF *pEsf);
-/* User provided routine to handle any detected fatal error post reporting. */
+/** User provided routine to handle any detected fatal error post reporting. */
 extern FUNC_NORETURN void _SysFatalErrorHandler(unsigned int reason,
 						const NANO_ESF *pEsf);
-/* Dummy ESF for fatal errors that would otherwise not have an ESF */
+/** Dummy ESF for fatal errors that would otherwise not have an ESF */
 extern const NANO_ESF _default_esf;
 
 /*
+ * @brief Configure an interrupt vector of the specified priority
+ *
  * BSP provided routine which kernel invokes to configure an interrupt vector
  * of the specified priority; the BSP allocates an interrupt vector, programs
  * hardware to route interrupt requests on the specified irq to that vector,
  * and returns the vector number along with its associated BOI/EOI information
+ *
  */
-
+extern int _SysIntVecAlloc(unsigned int irq,
-extern int	_SysIntVecAlloc(unsigned int irq,
+			 unsigned int priority,
-					 unsigned int priority,
+			 NANO_EOI_GET_FUNC *boiRtn,
-					 NANO_EOI_GET_FUNC *boiRtn,
+			 NANO_EOI_GET_FUNC *eoiRtn,
-					 NANO_EOI_GET_FUNC *eoiRtn,
+			 void **boiRtnParm,
-					 void **boiRtnParm,
+			 void **eoiRtnParm,
-					 void **eoiRtnParm,
+			 unsigned char *boiParamRequired,
-					 unsigned char *boiParamRequired,
+			 unsigned char *eoiParamRequired
-					 unsigned char *eoiParamRequired
+			 );
-					 );
 
 /* functions provided by the kernel for usage by the BSP's _SysIntVecAlloc() */