From d999f865eaef44b887b5c40799572e849ac4ca78 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 29 Jul 2021 14:48:40 +0200 Subject: rtems: Generate 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. --- cpukit/include/rtems/bspIo.h | 373 +++++++++++++++++++++++++------- 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, 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 - #include +#include #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(). */ /* -- cgit v1.2.3