c-user: Add "Kernel Character I/O Support" chapter

Close #4482.

c-user/fatal-error/directives.rst

@@ -116,10 +116,10 @@ Prints the message and invokes the fatal error handler.
 
 .. rubric:: DESCRIPTION:
 
-This directive prints a message via :c:func:`printk` specified by the ``fmt``
-parameter and optional parameters and then invokes the fatal error handler.
-The fatal source is set to :c:macro:`RTEMS_FATAL_SOURCE_PANIC`.  The fatal code
-is set to the value of the ``fmt`` parameter value.
+This directive prints a message via :ref:`InterfacePrintk` specified by the
+``fmt`` parameter and optional parameters and then invokes the fatal error
+handler.  The fatal source is set to :c:macro:`RTEMS_FATAL_SOURCE_PANIC`.  The
+fatal code is set to the value of the ``fmt`` parameter value.
 
 .. rubric:: CONSTRAINTS:
 
@@ -216,7 +216,7 @@ Prints the exception frame.
 .. rubric:: DESCRIPTION:
 
 The exception frame is printed in an architecture-dependent format using
-:c:func:`printk`.
+:ref:`InterfacePrintk`.
 
 .. Generated from spec:/rtems/fatal/if/source-text
 

c-user/index.rst

@@ -44,6 +44,7 @@ RTEMS Classic API Guide (|version|).
 	region/index
 	dual-ported-memory/index
 	io/index
+	kernel-character-io/index
 	fatal-error/index
 	board_support_packages
 	user-extensions/index

c-user/kernel-character-io/directives.rst

@@ -0,0 +1,372 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+
+.. 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:
+..
+.. https://docs.rtems.org
+
+.. _KernelCharacterIOSupportDirectives:
+
+Directives
+==========
+
+This section details the directives of the Kernel Character I/O Support. A
+subsection is dedicated to each of this manager's directives and lists the
+calling sequence, parameters, description, return values, and notes of the
+directive.
+
+.. Generated from spec:/rtems/io/if/putc
+
+.. raw:: latex
+
+    \clearpage
+
+.. index:: rtems_putc()
+
+.. _InterfaceRtemsPutc:
+
+rtems_putc()
+------------
+
+Outputs the character to the kernel character output device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    void rtems_putc( char c );
+
+.. rubric:: PARAMETERS:
+
+``c``
+    This parameter is the character to output.
+
+.. rubric:: DESCRIPTION:
+
+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.
+
+.. rubric:: CONSTRAINTS:
+
+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.
+
+.. Generated from spec:/rtems/io/if/put-char
+
+.. raw:: latex
+
+    \clearpage
+
+.. index:: rtems_put_char()
+
+.. _InterfaceRtemsPutChar:
+
+rtems_put_char()
+----------------
+
+Puts the character using :ref:`InterfaceRtemsPutc`
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    void rtems_put_char( int c, void *unused );
+
+.. rubric:: PARAMETERS:
+
+``c``
+    This parameter is the character to output.
+
+``unused``
+    This parameter is an unused argument.
+
+.. rubric:: NOTES:
+
+The directive is provided to support the RTEMS Testing Framework.
+
+.. rubric:: CONSTRAINTS:
+
+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.
+
+.. Generated from spec:/rtems/io/if/putk
+
+.. raw:: latex
+
+    \clearpage
+
+.. index:: putk()
+
+.. _InterfacePutk:
+
+putk()
+------
+
+Outputs the characters of the string and a newline character to the kernel
+character output device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    int putk( const char *s );
+
+.. rubric:: PARAMETERS:
+
+``s``
+    This parameter is the string to output.
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of characters output to the kernel character output device.
+
+.. rubric:: NOTES:
+
+The directive may be used to print debug and test information.  It uses
+:ref:`InterfaceRtemsPutc` 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.
+
+.. rubric:: CONSTRAINTS:
+
+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.
+
+.. Generated from spec:/rtems/io/if/printk
+
+.. raw:: latex
+
+    \clearpage
+
+.. index:: printk()
+
+.. _InterfacePrintk:
+
+printk()
+--------
+
+Outputs the characters defined by the format string and the arguments to the
+kernel character output device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    int printk( const char *fmt, ... );
+
+.. rubric:: PARAMETERS:
+
+``fmt``
+    This parameter is a printf()-style format string.
+
+``...``
+    This parameter is a list of optional parameters required by the format
+    string.
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of characters output to the kernel character output device.
+
+.. rubric:: NOTES:
+
+The directive may be used to print debug and test information.  It uses
+:ref:`InterfaceRtemsPutc` 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.
+
+.. rubric:: CONSTRAINTS:
+
+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.
+
+.. Generated from spec:/rtems/io/if/vprintk
+
+.. raw:: latex
+
+    \clearpage
+
+.. index:: vprintk()
+
+.. _InterfaceVprintk:
+
+vprintk()
+---------
+
+Outputs the characters defined by the format string and the variable argument
+list to the kernel character output device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    int vprintk( const char *fmt, va_list ap );
+
+.. rubric:: PARAMETERS:
+
+``fmt``
+    This parameter is a printf()-style format string.
+
+``ap``
+    This parameter is the variable argument list required by the format string.
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of characters output to the kernel character output device.
+
+.. rubric:: NOTES:
+
+The directive may be used to print debug and test information.  It uses
+:ref:`InterfaceRtemsPutc` 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.
+
+.. rubric:: CONSTRAINTS:
+
+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.
+
+.. Generated from spec:/rtems/io/if/printk-printer
+
+.. raw:: latex
+
+    \clearpage
+
+.. index:: rtems_printk_printer()
+
+.. _InterfaceRtemsPrintkPrinter:
+
+rtems_printk_printer()
+----------------------
+
+Outputs the characters defined by the format string and the variable argument
+list to the kernel character output device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    int rtems_printk_printer( void *unused, const char *fmt, va_list ap );
+
+.. rubric:: PARAMETERS:
+
+``unused``
+    This parameter is an unused argument.
+
+``fmt``
+    This parameter is a printf()-style format string.
+
+``ap``
+    This parameter is the variable argument list required by the format string.
+
+.. rubric:: RETURN VALUES:
+
+Returns the number of characters output to the kernel character output device.
+
+.. rubric:: NOTES:
+
+The directive may be used to print debug and test information.  It uses
+:ref:`InterfaceRtemsPutc` 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.
+
+.. rubric:: CONSTRAINTS:
+
+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.
+
+.. Generated from spec:/rtems/io/if/getchark
+
+.. raw:: latex
+
+    \clearpage
+
+.. index:: getchark()
+
+.. _InterfaceGetchark:
+
+getchark()
+----------
+
+Tries to dequeue a character from the kernel character input device.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    int getchark( void );
+
+.. rubric:: DESCRIPTION:
+
+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.
+
+.. rubric:: RETURN VALUES:
+
+``-1``
+    The BSP_poll_char pointer was equal to `NULL
+    <https://en.cppreference.com/w/c/types/NULL>`_.
+
+``-1``
+    There was no character enqueued on the kernel character input device.
+
+Returns the character least recently enqueued on the kernel character input
+device as an unsigned character value.
+
+.. rubric:: CONSTRAINTS:
+
+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.

c-user/kernel-character-io/index.rst

@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: Kernel Character I/O Support
+
+.. _RTEMSAPIKernelCharIO:
+
+Kernel Character I/O Support
+****************************
+
+.. toctree::
+
+    introduction
+    directives

c-user/kernel-character-io/introduction.rst

@@ -0,0 +1,69 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+
+.. 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:
+..
+.. https://docs.rtems.org
+
+.. Generated from spec:/rtems/io/if/group-3
+
+.. _KernelCharacterIOSupportIntroduction:
+
+Introduction
+============
+
+.. The following list was generated from:
+.. spec:/rtems/io/if/putc
+.. spec:/rtems/io/if/put-char
+.. spec:/rtems/io/if/putk
+.. spec:/rtems/io/if/printk
+.. spec:/rtems/io/if/vprintk
+.. spec:/rtems/io/if/printk-printer
+.. spec:/rtems/io/if/getchark
+
+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 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 :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`.  The kernel
+character input and output device is provided by the :term:`BSP`. Applications
+may change the device. The directives provided by the Kernel Character I/O
+Support are:
+
+* :ref:`InterfaceRtemsPutc` - Outputs the character to the kernel character
+  output device.
+
+* :ref:`InterfaceRtemsPutChar` - Puts the character using
+  :ref:`InterfaceRtemsPutc`
+
+* :ref:`InterfacePutk` - Outputs the characters of the string and a newline
+  character to the kernel character output device.
+
+* :ref:`InterfacePrintk` - Outputs the characters defined by the format string
+  and the arguments to the kernel character output device.
+
+* :ref:`InterfaceVprintk` - Outputs the characters defined by the format string
+  and the variable argument list to the kernel character output device.
+
+* :ref:`InterfaceRtemsPrintkPrinter` - Outputs the characters defined by the
+  format string and the variable argument list to the kernel character output
+  device.
+
+* :ref:`InterfaceGetchark` - Tries to dequeue a character from the kernel
+  character input device.

c-user/rate-monotonic/directives.rst

@@ -652,7 +652,7 @@ The following constraints apply to this directive:
 rtems_rate_monotonic_report_statistics()
 ----------------------------------------
 
-Reports the period statistics using the :c:func:`printk` printer.
+Reports the period statistics using the :ref:`InterfacePrintk` printer.
 
 .. rubric:: CALLING SEQUENCE:
 
@@ -663,7 +663,7 @@ Reports the period statistics using the :c:func:`printk` printer.
 .. rubric:: DESCRIPTION:
 
 This directive prints a report on all active periods which have executed at
-least one period using the :c:func:`printk` printer.
+least one period using the :ref:`InterfacePrintk` printer.
 
 .. rubric:: CONSTRAINTS:
 

c-user/rate-monotonic/introduction.rst

@@ -70,7 +70,7 @@ by the Rate-Monotonic Manager are:
   of all periods.
 
 * :ref:`InterfaceRtemsRateMonotonicReportStatistics` - Reports the period
-  statistics using the :c:func:`printk` printer.
+  statistics using the :ref:`InterfacePrintk` printer.
 
 * :ref:`InterfaceRtemsRateMonotonicReportStatisticsWithPlugin` - Reports the
   period statistics using the printer plugin.