diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-07-29 14:48:40 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-08-02 07:14:05 +0200 |
commit | d999f865eaef44b887b5c40799572e849ac4ca78 (patch) | |
tree | 56e8ddc7a80921e18f676f33a9fe663293b77627 /cpukit/include/rtems | |
parent | sptests: CONFIGURE_MEMORY_PER_TASK_FOR_SCHEDULER (diff) | |
download | rtems-d999f865eaef44b887b5c40799572e849ac4ca78.tar.bz2 |
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.
Diffstat (limited to '')
-rw-r--r-- | cpukit/include/rtems/bspIo.h | 373 |
1 files changed, 296 insertions, 77 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 */ |