doc: Various corrections to doxygen info for Kernel APIs

Most kernel APIs are now ready for inclusion in the API guide. The APIs largely follow a standard template to provide users of the API guide with a consistent look-and-feel. Change-Id: Ib682c31f912e19f5f6d8545d74c5f675b1741058 Signed-off-by: Allan Stephens <[email protected]>
k0d · Nov 16, 2016 · c98da84 · c98da84
1 parent f880c25
commit c98da84
Show file tree

Hide file tree

Showing 6 changed files with 671 additions and 378 deletions.
diff --git a/arch/x86/core/float.c b/arch/x86/core/float.c
@@ -60,17 +60,12 @@
 /* SSE control/status register default value (used by assembler code) */
 extern uint32_t _sse_mxcsr_default_value;
 
-/**
- *
- * @brief Save a thread's floating point context information.
+/*
+ * Save a thread's floating point context information.
  *
  * This routine saves the system's "live" floating point context into the
  * specified thread control block. The SSE registers are saved only if the
  * thread is actually using them.
- *
- * @param tcs Pointer to thread control block.
- *
- * @return N/A
  */
 static void _FpCtxSave(struct tcs *tcs)
 {
@@ -83,16 +78,11 @@ static void _FpCtxSave(struct tcs *tcs)
 	_do_fp_regs_save(&tcs->arch.preempFloatReg);
 }
 
-/**
- *
- * @brief Initialize a thread's floating point context information.
+/*
+ * Initialize a thread's floating point context information.
  *
  * This routine initializes the system's "live" floating point context.
  * The SSE registers are initialized only if the thread is actually using them.
- *
- * @param tcs Pointer to thread control block.
- *
- * @return N/A
  */
 static inline void _FpCtxInit(struct tcs *tcs)
 {
@@ -104,37 +94,9 @@ static inline void _FpCtxInit(struct tcs *tcs)
 #endif
 }
 
-/**
- *
- * @brief Enable preservation of floating point context information.
- *
- * This routine informs the kernel that the specified thread (which may be
- * the current thread) will be using the floating point registers.
- * The @a options parameter indicates which floating point register sets
- * will be used by the specified thread:
- *
- *  a) K_FP_REGS  indicates x87 FPU and MMX registers only
- *  b) K_SSE_REGS indicates SSE registers (and also x87 FPU and MMX registers)
- *
- * Invoking this routine initializes the thread's floating point context info
- * to that of an FPU that has been reset. The next time the thread is scheduled
- * by _Swap() it will either inherit an FPU that is guaranteed to be in a "sane"
- * state (if the most recent user of the FPU was cooperatively swapped out)
- * or the thread's own floating point context will be loaded (if the most
- * recent user of the FPU was pre-empted, or if this thread is the first user
- * of the FPU). Thereafter, the kernel will protect the thread's FP context
- * so that it is not altered during a preemptive context switch.
- *
- * @warning
- * This routine should only be used to enable floating point support for a
- * thread that does not currently have such support enabled already.
- *
- * @param tcs Pointer to thread control block.
- * @param options Registers to be preserved (K_FP_REGS or K_SSE_REGS).
- *
- * @return N/A
+/*
+ * Enable preservation of floating point context information.
  *
- * @internal
  * The transition from "non-FP supporting" to "FP supporting" must be done
  * atomically to avoid confusing the floating point logic used by _Swap(), so
  * this routine locks interrupts to ensure that a context switch does not occur.
@@ -232,21 +194,8 @@ void k_float_enable(struct tcs *tcs, unsigned int options)
 }
 
 /**
+ * Disable preservation of floating point context information.
  *
- * @brief Disable preservation of floating point context information.
- *
- * This routine informs the kernel that the specified thread (which may be
- * the current thread) will no longer be using the floating point registers.
- *
- * @warning
- * This routine should only be used to disable floating point support for
- * a thread that currently has such support enabled.
- *
- * @param tcs Pointer to thread control block.
- *
- * @return N/A
- *
- * @internal
  * The transition from "FP supporting" to "non-FP supporting" must be done
  * atomically to avoid confusing the floating point logic used by _Swap(), so
  * this routine locks interrupts to ensure that a context switch does not occur.
@@ -276,20 +225,15 @@ void k_float_disable(struct tcs *tcs)
 	irq_unlock(imask);
 }
 
-/**
- *
- * @brief Handler for "device not available" exception.
+/*
+ * Handler for "device not available" exception.
  *
  * This routine is registered to handle the "device not available" exception
  * (vector = 7).
  *
  * The processor will generate this exception if any x87 FPU, MMX, or SSEx
  * instruction is executed while CR0[TS]=1. The handler then enables the
  * current thread to use all supported floating point registers.
- *
- * @param pEsf This value is not used.
- *
- * @return N/A
  */
 void _FpNotAvailableExcHandler(NANO_ESF *pEsf)
 {

diff --git a/include/arch/x86/arch.h b/include/arch/x86/arch.h
@@ -381,7 +381,7 @@ static ALWAYS_INLINE void _arch_irq_unlock(unsigned int key)
 
 /**
  * The NANO_SOFT_IRQ macro must be used as the value for the @a irq parameter
- * to NANO_CPU_INT_REGSITER when connecting to an interrupt that does not
+ * to NANO_CPU_INT_REGISTER when connecting to an interrupt that does not
  * correspond to any IRQ line (such as spurious vector or SW IRQ)
  */
 #define NANO_SOFT_IRQ	((unsigned int) (-1))
@@ -397,10 +397,62 @@ extern void	_arch_irq_enable(unsigned int irq);
  */
 extern void	_arch_irq_disable(unsigned int irq);
 
-#ifdef CONFIG_FP_SHARING
-extern void k_float_enable(k_tid_t thread_id, unsigned int options);
-extern void k_float_disable(k_tid_t thread_id);
-#endif /* CONFIG_FP_SHARING */
+/**
+ * @defgroup float_apis Floating Point APIs
+ * @ingroup kernel_apis
+ * @{
+ */
+
+/**
+ * @brief Enable preservation of floating point context information.
+ *
+ * This routine informs the kernel that the specified thread (which may be
+ * the current thread) will be using the floating point registers.
+ * The @a options parameter indicates which floating point register sets
+ * will be used by the specified thread:
+ *
+ *  a) K_FP_REGS  indicates x87 FPU and MMX registers only
+ *  b) K_SSE_REGS indicates SSE registers (and also x87 FPU and MMX registers)
+ *
+ * Invoking this routine initializes the thread's floating point context info
+ * to that of an FPU that has been reset. The next time the thread is scheduled
+ * by _Swap() it will either inherit an FPU that is guaranteed to be in a "sane"
+ * state (if the most recent user of the FPU was cooperatively swapped out)
+ * or the thread's own floating point context will be loaded (if the most
+ * recent user of the FPU was pre-empted, or if this thread is the first user
+ * of the FPU). Thereafter, the kernel will protect the thread's FP context
+ * so that it is not altered during a preemptive context switch.
+ *
+ * @warning
+ * This routine should only be used to enable floating point support for a
+ * thread that does not currently have such support enabled already.
+ *
+ * @param thread ID of thread.
+ * @param options Registers to be preserved (K_FP_REGS or K_SSE_REGS).
+ *
+ * @return N/A
+ */
+extern void k_float_enable(k_tid_t thread, unsigned int options);
+
+/**
+ * @brief Disable preservation of floating point context information.
+ *
+ * This routine informs the kernel that the specified thread (which may be
+ * the current thread) will no longer be using the floating point registers.
+ *
+ * @warning
+ * This routine should only be used to disable floating point support for
+ * a thread that currently has such support enabled.
+ *
+ * @param thread ID of thread.
+ *
+ * @return N/A
+ */
+extern void k_float_disable(k_tid_t thread);
+
+/**
+ * @}
+ */
 
 #include <stddef.h>	/* for size_t */