rtems: Generate <rtems/bspIo.h>

Change license to BSD-2-Clause according to file histories and
documentation re-licensing agreement.

Place the group into the I/O Manager group.  Add all source files to the
group.

Update #3899.
Update #3993.
Update #4482.

8 files changed, 324 insertions, 91 deletions

diff --git a/cpukit/include/rtems/bspIo.h b/cpukit/include/rtems/bspIo.h
index ad196dfd34..b8a48e8237 100644
--- a/cpukit/include/rtems/bspIo.h
+++ b/cpukit/include/rtems/bspIo.h
@@ -1,154 +1,373 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
 /**
  * @file
  *
- * @brief Interface to Kernel Print Methods
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief This header file provides the kernel character input/output support
+ *   API.
+ */
+
+/*
+ * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+ * Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
  *
- * This include file defines the interface to kernel print methods.
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
  */
 
 /*
- *  COPYRIGHT (c) 1998 valette@crf.canon.fr
- *  COPYRIGHT (c) 2011 On-Line Applications Research Corporation.
+ * This file is part of the RTEMS quality process and was automatically
+ * generated.  If you find something that needs to be fixed or
+ * worded better please post a report or patch to an RTEMS mailing list
+ * or raise a bug report:
+ *
+ * https://www.rtems.org/bugs.html
+ *
+ * For information on updating and regenerating please refer to the How-To
+ * section in the Software Requirements Engineering chapter of the
+ * RTEMS Software Engineering manual.  The manual is provided as a part of
+ * a release.  For development sources please refer to the online
+ * documentation at:
  *
- *  The license and distribution terms for this file may be
- *  found in the file LICENSE in this distribution or at
- *  http://www.rtems.org/license/LICENSE.
+ * https://docs.rtems.org
  */
 
+/* Generated from spec:/rtems/io/if/header-3 */
+
 #ifndef _RTEMS_BSPIO_H
 #define _RTEMS_BSPIO_H
 
-#include <rtems/score/basedefs.h>
-
 #include <stdarg.h>
+#include <rtems/score/basedefs.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/* Generated from spec:/rtems/io/if/group-3 */
+
 /**
- * @defgroup BSPIO Kernel Print Support
+ * @defgroup RTEMSAPIKernelCharIO Kernel Character I/O Support
  *
- * @ingroup RTEMSAPIPrintSupport
+ * @ingroup RTEMSAPIClassicIO
  *
- * This module contains all methods and support related to providing
- * kernel level print support.
+ * @brief The kernel character input/output support is an extension of the @ref
+ *   RTEMSAPIClassicIO to output characters to the kernel character output
+ *   device and receive characters from the kernel character input device using
+ *   a polled and non-blocking implementation.
  *
- * 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
+ * The directives may be used to print debug and test information.  The kernel
+ * character input/output support should work even if no Console Driver is
+ * configured, see #CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER.  The kernel
+ * character input and output device is provided by the BSP. Applications may
+ * change the device.
  */
 
+/* Generated from spec:/rtems/io/if/bsp-output-char-function-type */
+
 /**
- * This type defines the prototype for the BSP provided method to
- * print a single character. It is assumed to be polled.
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief Polled character output functions shall have this type.
  */
-typedef void 	(*BSP_output_char_function_type) 	(char c);
+typedef void ( *BSP_output_char_function_type )( char );
+
+/* Generated from spec:/rtems/io/if/bsp-output-char */
 
 /**
- * This type defines the prototype for the BSP provided method to
- * input a single character. It is assumed to be polled.
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief This function pointer references the kernel character output
+ *   implementation.
+ *
+ * This function pointer shall never be NULL.  It shall be provided by the BSP
+ * and statically initialized.  The referenced function shall output exactly
+ * the character specified by the parameter.  In particular, it shall not
+ * perform character translations, for example ``NL`` to ``CR`` followed by
+ * ``NR``.  The function shall not block.
  */
-typedef int 	(*BSP_polling_getchar_function_type) 	(void);
+extern BSP_output_char_function_type BSP_output_char;
+
+/* Generated from spec:/rtems/io/if/putc */
 
 /**
- * This variable points to the BSP provided method to output a
- * character for the purposes of debug output.
+ * @ingroup RTEMSAPIKernelCharIO
  *
- * It must output only the specific character.  It must not perform character
- * translations, e.g. "\n" to "\r\n".
+ * @brief Outputs the character to the kernel character output device.
+ *
+ * @param c is the character to output.
+ *
+ * The directive outputs the character specified by ``c`` to the kernel
+ * character output device using the polled character output implementation
+ * provided by #BSP_output_char.  The directive performs a character
+ * translation from ``NL`` to ``CR`` followed by ``NR``.
+ *
+ * If the kernel character output device is concurrently accessed, then
+ * interleaved output may occur.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within any runtime context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ * @endparblock
  */
-extern 	BSP_output_char_function_type 		BSP_output_char;
+void rtems_putc( char c );
+
+/* Generated from spec:/rtems/io/if/put-char */
 
 /**
- * This variable points to the BSP provided method to input a
- * character for the purposes of debug input.
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief Puts the character using rtems_putc()
+ *
+ * @param c is the character to output.
+ *
+ * @param unused is an unused argument.
+ *
+ * @par Notes
+ * The directive is provided to support the RTEMS Testing Framework.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within any runtime context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ * @endparblock
  */
-extern 	BSP_polling_getchar_function_type 	BSP_poll_char;
+void rtems_put_char( int c, void *unused );
+
+/* Generated from spec:/rtems/io/if/putk */
 
 /**
- * @brief Get Character (kernel I/O)
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief Outputs the characters of the string and a newline character to the
+ *   kernel character output device.
+ *
+ * @param s is the string to output.
+ *
+ * @return Returns the number of characters output to the kernel character
+ *   output device.
+ *
+ * @par Notes
+ * @parblock
+ * The directive may be used to print debug and test information.  It uses
+ * rtems_putc() to output the characters.  This directive performs a character
+ * translation from ``NL`` to ``CR`` followed by ``NR``.
+ *
+ * If the kernel character output device is concurrently accessed, then
+ * interleaved output may occur.
+ * @endparblock
  *
- * This method polls for a key in the simplest possible fashion
- * from whatever the debug console device is.
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
  *
- * @return If a character is available, it is returned.  Otherwise
- *         this method returns -1.
+ * * The directive may be called from within any runtime context.
  *
- * @note This method uses the BSP_poll_char pointer to a BSP
- *       provided method.
+ * * The directive will not cause the calling task to be preempted.
+ * @endparblock
  */
-extern int getchark(void);
+int putk( const char *s );
+
+/* Generated from spec:/rtems/io/if/printk */
 
 /**
- * @brief Variable Argument printk()
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief Outputs the characters defined by the format string and the arguments
+ *   to the kernel character output device.
+ *
+ * @param fmt is a printf()-style format string.
+ *
+ * @param ... is a list of optional parameters required by the format string.
+ *
+ * @return Returns the number of characters output to the kernel character
+ *   output device.
  *
- * This method allows the user to access printk() functionality
- * with a va_list style argument.
+ * @par Notes
+ * @parblock
+ * The directive may be used to print debug and test information.  It uses
+ * rtems_putc() to output the characters.  This directive performs a character
+ * translation from ``NL`` to ``CR`` followed by ``NR``.
  *
- * @param[in] fmt is a printf()-style format string
- * @param[in] ap is a va_list pointer to arguments
+ * If the kernel character output device is concurrently accessed, then
+ * interleaved output may occur.
+ * @endparblock
  *
- * @return The number of characters output.
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within any runtime context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ *
+ * * Formatting of floating point numbers is not supported.
+ * @endparblock
  */
-extern int vprintk(const char *fmt, va_list ap);
+RTEMS_PRINTFLIKE( 1, 2 ) int printk( const char *fmt, ... );
 
-int rtems_printk_printer(
-  void *ignored,
-  const char *format,
-  va_list ap
-);
+/* Generated from spec:/rtems/io/if/vprintk */
 
 /**
- * @brief Kernel Print
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief Outputs the characters defined by the format string and the variable
+ *   argument list to the kernel character output device.
+ *
+ * @param fmt is a printf()-style format string.
  *
- * This method allows the user to perform a debug printk().  It performs a
- * character translation from "\n" to "\r\n".
+ * @param ap is the variable argument list required by the format string.
  *
- * @param[in] fmt is a printf()-style format string
+ * @return Returns the number of characters output to the kernel character
+ *   output device.
  *
- * @return The number of characters output.
+ * @par Notes
+ * @parblock
+ * The directive may be used to print debug and test information.  It uses
+ * rtems_putc() to output the characters.  This directive performs a character
+ * translation from ``NL`` to ``CR`` followed by ``NR``.
+ *
+ * If the kernel character output device is concurrently accessed, then
+ * interleaved output may occur.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within any runtime context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ *
+ * * Formatting of floating point numbers is not supported.
+ * @endparblock
  */
-extern int printk(const char *fmt, ...) RTEMS_PRINTFLIKE(1, 2);
+int vprintk( const char *fmt, va_list ap );
+
+/* Generated from spec:/rtems/io/if/printk-printer */
 
 /**
- * @brief Kernel Put String
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief Outputs the characters defined by the format string and the variable
+ *   argument list to the kernel character output device.
+ *
+ * @param unused is an unused argument.
+ *
+ * @param fmt is a printf()-style format string.
+ *
+ * @param ap is the variable argument list required by the format string.
  *
- * This method allows the user to perform a debug puts().
+ * @return Returns the number of characters output to the kernel character
+ *   output device.
  *
- * @param[in] s is the string to print
+ * @par Notes
+ * @parblock
+ * The directive may be used to print debug and test information.  It uses
+ * rtems_putc() to output the characters.  This directive performs a character
+ * translation from ``NL`` to ``CR`` followed by ``NR``.
  *
- * @return The number of characters output.
+ * If the kernel character output device is concurrently accessed, then
+ * interleaved output may occur.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within any runtime context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ *
+ * * Formatting of floating point numbers is not supported.
+ * @endparblock
  */
-extern int putk(const char *s);
+int rtems_printk_printer( void *unused, const char *fmt, va_list ap );
+
+/* Generated from spec:/rtems/io/if/bsp-polling-getchar-function-type */
 
 /**
- * @brief Kernel Put Character
+ * @ingroup RTEMSAPIKernelCharIO
  *
- * This method allows the user to perform a debug putc().  It performs a
- * character translation from "\n" to "\r\n".
- *
- * @param[in] c is the character to print
+ * @brief Polled character input functions shall have this type.
  */
-extern void rtems_putc(char c);
+typedef int (* BSP_polling_getchar_function_type )( void );
+
+/* Generated from spec:/rtems/io/if/bsp-poll-char */
 
 /**
- * @brief Puts the character via rtems_putc().
+ * @ingroup RTEMSAPIKernelCharIO
  *
- * This is a compatibility function to support an internal API.
+ * @brief This function pointer may reference the kernel character input
+ *   implementation.
  *
- * @param c The character to put.
- * @param arg Ignored.
+ * This function pointer may be NULL.  It may reference a function provided by
+ * the BSP.  Referenced functions shall dequeue the least recently received
+ * character from the device and return it as an unsigned character.  If no
+ * character is enqueued on the device, then the function shall immediately
+ * return the value minus one.
  */
-void rtems_put_char( int c, void *arg );
+extern BSP_polling_getchar_function_type BSP_poll_char;
 
-/**@}*/
+/* Generated from spec:/rtems/io/if/getchark */
+
+/**
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief Tries to dequeue a character from the kernel character input device.
+ *
+ * The directive tries to dequeue a character from the kernel character input
+ * device using the polled character input implementation referenced by
+ * #BSP_poll_char if it is available.
+ *
+ * @retval -1 The #BSP_poll_char pointer was equal to NULL.
+ *
+ * @retval -1 There was no character enqueued on the kernel character input
+ *   device.
+ *
+ * @return Returns the character least recently enqueued on the kernel
+ *   character input device as an unsigned character value.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within any runtime context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ * @endparblock
+ */
+int getchark( void );
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif
+#endif /* _RTEMS_BSPIO_H */
diff --git a/cpukit/libcsupport/src/getchark.c b/cpukit/libcsupport/src/getchark.c
index cfe9c022d6..2bb8bc64d2 100644
--- a/cpukit/libcsupport/src/getchark.c
+++ b/cpukit/libcsupport/src/getchark.c
@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * @ingroup BSPIO
+ * @ingroup RTEMSAPIKernelCharIO
  *
  * @brief This source file contains the implementation of getchark().
  */
diff --git a/cpukit/libcsupport/src/printk.c b/cpukit/libcsupport/src/printk.c
index 444efab1f2..a93cd46cc1 100644
--- a/cpukit/libcsupport/src/printk.c
+++ b/cpukit/libcsupport/src/printk.c
@@ -1,8 +1,9 @@
 /**
- *  @file
+ * @file
  *
- *  @brief Kernel Printf Function
- *  @ingroup libcsupport
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief This source file contains the implementation of printk().
  */
 
 /*
diff --git a/cpukit/libcsupport/src/printk_plugin.c b/cpukit/libcsupport/src/printk_plugin.c
index 839a76e9c9..3ef3919732 100644
--- a/cpukit/libcsupport/src/printk_plugin.c
+++ b/cpukit/libcsupport/src/printk_plugin.c
@@ -1,8 +1,11 @@
 /**
- *  @file
+ * @file
  *
- *  @brief Plugin Printk
- *  @ingroup libcsupport
+ * @ingroup RTEMSAPIKernelCharIO
+ * @ingroup RTEMSPrintSupport
+ *
+ * @brief This source file contains the implementation of
+ *   rtems_printk_printer() and rtems_print_printer_printk().
  */
 
 /*
diff --git a/cpukit/libcsupport/src/putk.c b/cpukit/libcsupport/src/putk.c
index 87da29667d..4407405a22 100644
--- a/cpukit/libcsupport/src/putk.c
+++ b/cpukit/libcsupport/src/putk.c
@@ -1,8 +1,9 @@
 /**
- *  @file
+ * @file
  *
- *  @brief Write Character to Stream
- *  @ingroup libcsupport
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief This source file contains the implementation of putk().
  */
 
 /*
diff --git a/cpukit/libcsupport/src/rtems_put_char.c b/cpukit/libcsupport/src/rtems_put_char.c
index 53b368fd18..5836bcb9dc 100644
--- a/cpukit/libcsupport/src/rtems_put_char.c
+++ b/cpukit/libcsupport/src/rtems_put_char.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief This source file contains the implementation of rtems_put_char().
+ */
+
 /*
  * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
  *
diff --git a/cpukit/libcsupport/src/rtems_putc.c b/cpukit/libcsupport/src/rtems_putc.c
index e27b1e4544..726893c2f1 100644
--- a/cpukit/libcsupport/src/rtems_putc.c
+++ b/cpukit/libcsupport/src/rtems_putc.c
@@ -3,7 +3,7 @@
 /**
  * @file
  *
- * @ingroup BSPIO
+ * @ingroup RTEMSAPIKernelCharIO
  *
  * @brief This source file contains the implementation of rtems_putc().
  */
diff --git a/cpukit/libcsupport/src/vprintk.c b/cpukit/libcsupport/src/vprintk.c
index 308872f71e..3131390372 100644
--- a/cpukit/libcsupport/src/vprintk.c
+++ b/cpukit/libcsupport/src/vprintk.c
@@ -1,8 +1,9 @@
 /**
- *  @file
+ * @file
  *
- *  @brief Print Formatted Output
- *  @ingroup libcsupport
+ * @ingroup RTEMSAPIKernelCharIO
+ *
+ * @brief This source file contains the implementation of vprintk().
  */
 
 /*