From a575af82e0ac90a7c4306e35e1f633394132ea02 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 10 Mar 2015 16:55:58 -0500 Subject: cpukit/include/rtems/bspIo.h: Add Doxygen comments --- cpukit/include/rtems/bspIo.h | 136 ++++++++++++++++++++++++++++++++++--------- 1 file 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 /** - * 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 } -- cgit v1.2.3