include/rtems/bspIo.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSAPIKernelCharIO
0007  *
0008  * @brief This header file provides the kernel character input/output support
0009  *   API.
0010  */
0011
0012 /*
0013  * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG
0014  * Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
0015  *
0016  * Redistribution and use in source and binary forms, with or without
0017  * modification, are permitted provided that the following conditions
0018  * are met:
0019  * 1. Redistributions of source code must retain the above copyright
0020  *    notice, this list of conditions and the following disclaimer.
0021  * 2. Redistributions in binary form must reproduce the above copyright
0022  *    notice, this list of conditions and the following disclaimer in the
0023  *    documentation and/or other materials provided with the distribution.
0024  *
0025  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0026  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0027  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0028  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0029  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0030  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0031  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0032  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0033  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0034  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0035  * POSSIBILITY OF SUCH DAMAGE.
0036  */
0037
0038 /*
0039  * This file is part of the RTEMS quality process and was automatically
0040  * generated.  If you find something that needs to be fixed or
0041  * worded better please post a report or patch to an RTEMS mailing list
0042  * or raise a bug report:
0043  *
0044  * https://www.rtems.org/bugs.html
0045  *
0046  * For information on updating and regenerating please refer to the How-To
0047  * section in the Software Requirements Engineering chapter of the
0048  * RTEMS Software Engineering manual.  The manual is provided as a part of
0049  * a release.  For development sources please refer to the online
0050  * documentation at:
0051  *
0052  * https://docs.rtems.org
0053  */
0054
0055 /* Generated from spec:/rtems/io/if/header-3 */
0056
0057 #ifndef _RTEMS_BSPIO_H
0058 #define _RTEMS_BSPIO_H
0059
0060 #include <stdarg.h>
0061 #include <rtems/score/basedefs.h>
0062
0063 #ifdef __cplusplus
0064 extern "C" {
0065 #endif
0066
0067 /* Generated from spec:/rtems/io/if/group-3 */
0068
0069 /**
0070  * @defgroup RTEMSAPIKernelCharIO Kernel Character I/O Support
0071  *
0072  * @ingroup RTEMSAPIClassicIO
0073  *
0074  * @brief The kernel character input/output support is an extension of the @ref
0075  *   RTEMSAPIClassicIO to output characters to the kernel character output
0076  *   device and receive characters from the kernel character input device using
0077  *   a polled and non-blocking implementation.
0078  *
0079  * The directives may be used to print debug and test information.  The kernel
0080  * character input/output support should work even if no Console Driver is
0081  * configured, see @ref CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER.  The kernel
0082  * character input and output device is provided by the BSP. Applications may
0083  * change the device.
0084  */
0085
0086 /* Generated from spec:/rtems/io/if/bsp-output-char-function-type */
0087
0088 /**
0089  * @ingroup RTEMSAPIKernelCharIO
0090  *
0091  * @brief Polled character output functions shall have this type.
0092  */
0093 typedef void ( *BSP_output_char_function_type )( char );
0094
0095 /* Generated from spec:/rtems/io/if/bsp-output-char */
0096
0097 /**
0098  * @ingroup RTEMSAPIKernelCharIO
0099  *
0100  * @brief This function pointer references the kernel character output
0101  *   implementation.
0102  *
0103  * This function pointer shall never be NULL.  It shall be provided by the BSP
0104  * and statically initialized.  The referenced function shall output exactly
0105  * the character specified by the parameter.  In particular, it shall not
0106  * perform character translations, for example ``NL`` to ``CR`` followed by
0107  * ``NR``.  The function shall not block.
0108  */
0109 extern BSP_output_char_function_type BSP_output_char;
0110
0111 /* Generated from spec:/rtems/io/if/putc */
0112
0113 /**
0114  * @ingroup RTEMSAPIKernelCharIO
0115  *
0116  * @brief Outputs the character to the kernel character output device.
0117  *
0118  * @param c is the character to output.
0119  *
0120  * The directive outputs the character specified by ``c`` to the kernel
0121  * character output device using the polled character output implementation
0122  * provided by #BSP_output_char.  The directive performs a character
0123  * translation from ``NL`` to ``CR`` followed by ``NR``.
0124  *
0125  * If the kernel character output device is concurrently accessed, then
0126  * interleaved output may occur.
0127  *
0128  * @par Constraints
0129  * @parblock
0130  * The following constraints apply to this directive:
0131  *
0132  * * The directive may be called from within any runtime context.
0133  *
0134  * * The directive will not cause the calling task to be preempted.
0135  * @endparblock
0136  */
0137 void rtems_putc( char c );
0138
0139 /* Generated from spec:/rtems/io/if/put-char */
0140
0141 /**
0142  * @ingroup RTEMSAPIKernelCharIO
0143  *
0144  * @brief Puts the character using rtems_putc()
0145  *
0146  * @param c is the character to output.
0147  *
0148  * @param unused is an unused argument.
0149  *
0150  * @par Notes
0151  * The directive is provided to support the RTEMS Testing Framework.
0152  *
0153  * @par Constraints
0154  * @parblock
0155  * The following constraints apply to this directive:
0156  *
0157  * * The directive may be called from within any runtime context.
0158  *
0159  * * The directive will not cause the calling task to be preempted.
0160  * @endparblock
0161  */
0162 void rtems_put_char( int c, void *unused );
0163
0164 /* Generated from spec:/rtems/io/if/putk */
0165
0166 /**
0167  * @ingroup RTEMSAPIKernelCharIO
0168  *
0169  * @brief Outputs the characters of the string and a newline character to the
0170  *   kernel character output device.
0171  *
0172  * @param s is the string to output.
0173  *
0174  * @return Returns the number of characters output to the kernel character
0175  *   output device.
0176  *
0177  * @par Notes
0178  * @parblock
0179  * The directive may be used to print debug and test information.  It uses
0180  * rtems_putc() to output the characters.  This directive performs a character
0181  * translation from ``NL`` to ``CR`` followed by ``NR``.
0182  *
0183  * If the kernel character output device is concurrently accessed, then
0184  * interleaved output may occur.
0185  * @endparblock
0186  *
0187  * @par Constraints
0188  * @parblock
0189  * The following constraints apply to this directive:
0190  *
0191  * * The directive may be called from within any runtime context.
0192  *
0193  * * The directive will not cause the calling task to be preempted.
0194  * @endparblock
0195  */
0196 int putk( const char *s );
0197
0198 /* Generated from spec:/rtems/io/if/printk */
0199
0200 /**
0201  * @ingroup RTEMSAPIKernelCharIO
0202  *
0203  * @brief Outputs the characters defined by the format string and the arguments
0204  *   to the kernel character output device.
0205  *
0206  * @param fmt is a printf()-style format string.
0207  *
0208  * @param ... is a list of optional parameters required by the format string.
0209  *
0210  * @return Returns the number of characters output to the kernel character
0211  *   output device.
0212  *
0213  * @par Notes
0214  * @parblock
0215  * The directive may be used to print debug and test information.  It uses
0216  * rtems_putc() to output the characters.  This directive performs a character
0217  * translation from ``NL`` to ``CR`` followed by ``NR``.
0218  *
0219  * If the kernel character output device is concurrently accessed, then
0220  * interleaved output may occur.
0221  * @endparblock
0222  *
0223  * @par Constraints
0224  * @parblock
0225  * The following constraints apply to this directive:
0226  *
0227  * * The directive may be called from within any runtime context.
0228  *
0229  * * The directive will not cause the calling task to be preempted.
0230  *
0231  * * Formatting of floating point numbers is not supported.
0232  * @endparblock
0233  */
0234 RTEMS_PRINTFLIKE( 1, 2 ) int printk( const char *fmt, ... );
0235
0236 /* Generated from spec:/rtems/io/if/vprintk */
0237
0238 /**
0239  * @ingroup RTEMSAPIKernelCharIO
0240  *
0241  * @brief Outputs the characters defined by the format string and the variable
0242  *   argument list to the kernel character output device.
0243  *
0244  * @param fmt is a printf()-style format string.
0245  *
0246  * @param ap is the variable argument list required by the format string.
0247  *
0248  * @return Returns the number of characters output to the kernel character
0249  *   output device.
0250  *
0251  * @par Notes
0252  * @parblock
0253  * The directive may be used to print debug and test information.  It uses
0254  * rtems_putc() to output the characters.  This directive performs a character
0255  * translation from ``NL`` to ``CR`` followed by ``NR``.
0256  *
0257  * If the kernel character output device is concurrently accessed, then
0258  * interleaved output may occur.
0259  * @endparblock
0260  *
0261  * @par Constraints
0262  * @parblock
0263  * The following constraints apply to this directive:
0264  *
0265  * * The directive may be called from within any runtime context.
0266  *
0267  * * The directive will not cause the calling task to be preempted.
0268  *
0269  * * Formatting of floating point numbers is not supported.
0270  * @endparblock
0271  */
0272 int vprintk( const char *fmt, va_list ap );
0273
0274 /* Generated from spec:/rtems/io/if/printk-printer */
0275
0276 /**
0277  * @ingroup RTEMSAPIKernelCharIO
0278  *
0279  * @brief Outputs the characters defined by the format string and the variable
0280  *   argument list to the kernel character output device.
0281  *
0282  * @param unused is an unused argument.
0283  *
0284  * @param fmt is a printf()-style format string.
0285  *
0286  * @param ap is the variable argument list required by the format string.
0287  *
0288  * @return Returns the number of characters output to the kernel character
0289  *   output device.
0290  *
0291  * @par Notes
0292  * @parblock
0293  * The directive may be used to print debug and test information.  It uses
0294  * rtems_putc() to output the characters.  This directive performs a character
0295  * translation from ``NL`` to ``CR`` followed by ``NR``.
0296  *
0297  * If the kernel character output device is concurrently accessed, then
0298  * interleaved output may occur.
0299  * @endparblock
0300  *
0301  * @par Constraints
0302  * @parblock
0303  * The following constraints apply to this directive:
0304  *
0305  * * The directive may be called from within any runtime context.
0306  *
0307  * * The directive will not cause the calling task to be preempted.
0308  *
0309  * * Formatting of floating point numbers is not supported.
0310  * @endparblock
0311  */
0312 int rtems_printk_printer( void *unused, const char *fmt, va_list ap );
0313
0314 /* Generated from spec:/rtems/io/if/bsp-polling-getchar-function-type */
0315
0316 /**
0317  * @ingroup RTEMSAPIKernelCharIO
0318  *
0319  * @brief Polled character input functions shall have this type.
0320  */
0321 typedef int (* BSP_polling_getchar_function_type )( void );
0322
0323 /* Generated from spec:/rtems/io/if/bsp-poll-char */
0324
0325 /**
0326  * @ingroup RTEMSAPIKernelCharIO
0327  *
0328  * @brief This function pointer may reference the kernel character input
0329  *   implementation.
0330  *
0331  * This function pointer may be NULL.  It may reference a function provided by
0332  * the BSP.  Referenced functions shall dequeue the least recently received
0333  * character from the device and return it as an unsigned character.  If no
0334  * character is enqueued on the device, then the function shall immediately
0335  * return the value minus one.
0336  */
0337 extern BSP_polling_getchar_function_type BSP_poll_char;
0338
0339 /* Generated from spec:/rtems/io/if/getchark */
0340
0341 /**
0342  * @ingroup RTEMSAPIKernelCharIO
0343  *
0344  * @brief Tries to dequeue a character from the kernel character input device.
0345  *
0346  * The directive tries to dequeue a character from the kernel character input
0347  * device using the polled character input implementation referenced by
0348  * #BSP_poll_char if it is available.
0349  *
0350  * @retval -1 The #BSP_poll_char pointer was equal to NULL.
0351  *
0352  * @retval -1 There was no character enqueued on the kernel character input
0353  *   device.
0354  *
0355  * @return Returns the character least recently enqueued on the kernel
0356  *   character input device as an unsigned character value.
0357  *
0358  * @par Constraints
0359  * @parblock
0360  * The following constraints apply to this directive:
0361  *
0362  * * The directive may be called from within any runtime context.
0363  *
0364  * * The directive will not cause the calling task to be preempted.
0365  * @endparblock
0366  */
0367 int getchark( void );
0368
0369 #ifdef __cplusplus
0370 }
0371 #endif
0372
0373 #endif /* _RTEMS_BSPIO_H */