cpukit/include/rtems/bspIo.h: Add Doxygen comments

1 files changed, 107 insertions, 29 deletions

diff --git a/cpukit/include/rtems/bspIo.h b/cpukit/include/rtems/bspIo.h
index df068a1671..dde8d942e8 100644
--- a/cpukit/include/rtems/bspIo.h
+++ b/cpukit/include/rtems/bspIo.h
@@ -14,6 +14,7 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.org/license/LICENSE.
  */
+
 #ifndef _RTEMS_BSPIO_H
 #define _RTEMS_BSPIO_H
 
@@ -21,59 +22,136 @@
 extern "C" {
 #endif
 
-/*
- * All the functions declared as extern after this comment
- * MUST be implemented in each BSP. Using this function,
- * this directory contains shared code that export higher level
- * functionnality described after the next command.
+/**
+ * @defgroup BSPIO Kernel Print Support
+ *
+ * This module contains all methods and support related to providing
+ * kernel level print support.
+ *
+ * The following variables below are declared as extern and
+ * MUST be declared and initialized in each BSP. Using this indirect
+ * function, the functionality in this group is tailored for the BSP.
+ *
+ *  - BSP_output_char
+ *  - BSP_poll_char
+ */
+
+/**
+ * This type defines the prototype for the BSP provided method to
+ * print a single character. It is assumed to be polled.
  */
 typedef void 	(*BSP_output_char_function_type) 	(char c);
+
+/**
+ * This type defines the prototype for the BSP provided method to
+ * input a single character. It is assumed to be polled.
+ */
 typedef int 	(*BSP_polling_getchar_function_type) 	(void);
 
+/**
+ * This variable points to the BSP provided method to output a
+ * character for the purposes of debug output.
+ */
 extern 	BSP_output_char_function_type 		BSP_output_char;
-extern 	BSP_polling_getchar_function_type 	BSP_poll_char;
 
-/*
- * All the function declared as extern after this comment
- * are available for each BSP by compiling and linking
- * the files contained in this directory PROVIDED definition
- * and initialisation of the previous variable are done.
+/**
+ * This variable points to the BSP provided method to input a
+ * character for the purposes of debug input.
  */
+extern 	BSP_polling_getchar_function_type 	BSP_poll_char;
+
 #include <stdarg.h>
 
 /**
- *  This method polls for a key in the simplest possible fashion
- *  from whatever the debug console device is.
+ * @brief Get Character (kernel I/O)
  *
- *  @return If a character is available, it is returned.  Otherwise
- *          this method returns -1.
+ * This method polls for a key in the simplest possible fashion
+ * from whatever the debug console device is.
  *
- *  @note This method uses the BSP_poll_char pointer to a BSP
- *        provided method.
+ * @return If a character is available, it is returned.  Otherwise
+ *         this method returns -1.
+ *
+ * @note This method uses the BSP_poll_char pointer to a BSP
+ *       provided method.
  */
 extern int getchark(void);
+
+/**
+ * @brief Variable Argument printk()
+ *
+ * This method allows the user to access printk() functionality
+ * with a va_list style argument.
+ *
+ * @param[in] fmt is a printf()-style format string
+ * @param[in] ap is a va_list pointer to arguments
+ */
 extern void vprintk(const char *fmt, va_list ap);
+
+/**
+ * @brief Kernel Print
+ *
+ * This method allows the user to perform a debug printk().
+ *
+ * @param[in] fmt is a printf()-style format string
+ */
 extern void printk(const char *fmt, ...);
+
+/**
+ * @brief Kernel Put String
+ *
+ * This method allows the user to perform a debug puts().
+ *
+ * @param[in] s is the string to print
+ */
 extern void putk(const char *s);
+
+/**
+ * @brief Kernel Put Character
+ *
+ * This method allows the user to perform a debug putc().
+ *
+ * @param[in] c is the character to print
+ */
 extern void rtems_putc(char c);
 
-/*
- *  This routine is passed into RTEMS reporting functions
- *  that may have their output redirected.  In particular,
- *  the cpu usage, period usage, and stack usage reporting
- *  functions use this.  If the user provides their
- *  own "printf plugin", then they may redirect those reports
- *  as they see fit.
+/**
+ * Type definition for function which can be plugged in to
+ * certain reporting routines to redirect the output.
+ *
+ * Methods following this prototype may be passed into RTEMS reporting
+ * functions that allow their output to be redirected.  In particular,
+ * the cpu usage, period usage, and stack usage reporting
+ * functions use this.
+ *
+ * If the user provides their own "printf plugin", then they may
+ * redirect those reports as they see fit.
+ */
+typedef int (*rtems_printk_plugin_t)(void *, const char *format, ...);
+
+/**
+ * @brief Reporting Methods printk() Plugin
+ *
+ * @param[in] context points to a user defined context.
+ * @param[in] fmt is a printf()-style format string
+ *
+ * @return The number of characters printed.
  */
 extern int printk_plugin(void *context, const char *fmt, ...);
 
+/**
+ * @brief Reporting Methods printf() Plugin
+ *
+ * This is a standard plug-in to support using printf() for output
+ * instead of printk().
+ *
+ * @param[in] context points to a user defined context.
+ * @param[in] fmt is a printf()-style format string
+ *
+ * @return The number of characters printed.
+ */
 extern int rtems_printf_plugin(void *context, const char *fmt, ...);
 
-/*
- *  Type definition for function which can be plugged in to
- *  certain reporting routines to redirect the output
- */
-typedef int (*rtems_printk_plugin_t)(void *, const char *format, ...);
+/**@}*/
 
 #ifdef __cplusplus
 }