[PATCH v2] rtems: Generate <rtems/bspIo.h>
Sebastian Huber
sebastian.huber at embedded-brains.de
Fri Jul 30 06:11:11 UTC 2021
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.
---
v2:
* Add constraints.
* Reorder the directives.
cpukit/include/rtems/bspIo.h | 364 +++++++++++++++++++-----
cpukit/libcsupport/src/getchark.c | 2 +-
cpukit/libcsupport/src/printk.c | 7 +-
cpukit/libcsupport/src/printk_plugin.c | 9 +-
cpukit/libcsupport/src/putk.c | 7 +-
cpukit/libcsupport/src/rtems_put_char.c | 8 +
cpukit/libcsupport/src/rtems_putc.c | 2 +-
cpukit/libcsupport/src/vprintk.c | 7 +-
8 files changed, 315 insertions(+), 91 deletions(-)
diff --git a/cpukit/include/rtems/bspIo.h b/cpukit/include/rtems/bspIo.h
index ad196dfd34..6b0325932b 100644
--- a/cpukit/include/rtems/bspIo.h
+++ b/cpukit/include/rtems/bspIo.h
@@ -1,154 +1,364 @@
+/* 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 at 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 input and output characters to a BSP defined 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.
*/
+/* 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 "\n" to "\r\n". 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
+ *
+ * @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 "\n" to "\r\n".
+ *
+ * If the kernel character output device is concurrently accessed, then
+ * interleaved output may occur.
*
- * It must output only the specific character. It must not perform character
- * translations, e.g. "\n" to "\r\n".
+ * @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.
*
- * This method polls for a key in the simplest possible fashion
- * from whatever the debug console device is.
+ * @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 "\n" to "\r\n".
*
- * @return If a character is available, it is returned. Otherwise
- * this method returns -1.
+ * If the kernel character output device is concurrently accessed, then
+ * interleaved output may occur.
+ * @endparblock
*
- * @note This method uses the BSP_poll_char pointer to a BSP
- * provided method.
+ * @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 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.
*
- * This method allows the user to access printk() functionality
- * with a va_list style argument.
+ * @param ... is a list of optional parameters required by the format string.
*
- * @param[in] fmt is a printf()-style format string
- * @param[in] ap is a va_list pointer to arguments
+ * @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 "\n" to "\r\n".
+ *
+ * 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.
+ * @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.
*
- * This method allows the user to perform a debug printk(). It performs a
- * character translation from "\n" to "\r\n".
+ * @param fmt is a printf()-style format string.
*
- * @param[in] fmt is a printf()-style format string
+ * @param ap is the variable argument list required by the format string.
*
- * @return The number of characters 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 "\n" to "\r\n".
+ *
+ * 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.
+ * @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.
*
- * This method allows the user to perform a debug puts().
+ * @param ap is the variable argument list required by the format string.
*
- * @param[in] s is the string to print
+ * @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 "\n" to "\r\n".
+ *
+ * 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.
+ * @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().
*/
/*
--
2.26.2
More information about the devel
mailing list