[rtems-docs commit] c-user: Add "Kernel Character I/O Support" chapter
Sebastian Huber
sebh at rtems.org
Tue Aug 3 08:39:59 UTC 2021
Module: rtems-docs
Branch: master
Commit: efb8e7c6c3fe534ac36ca44553831c61179fe771
Changeset: http://git.rtems.org/rtems-docs/commit/?id=efb8e7c6c3fe534ac36ca44553831c61179fe771
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Fri Jul 30 08:51:07 2021 +0200
c-user: Add "Kernel Character I/O Support" chapter
Close #4482.
---
c-user/fatal-error/directives.rst | 10 +-
c-user/index.rst | 1 +
c-user/kernel-character-io/directives.rst | 372 ++++++++++++++++++++++++++++
c-user/kernel-character-io/index.rst | 15 ++
c-user/kernel-character-io/introduction.rst | 69 ++++++
c-user/rate-monotonic/directives.rst | 4 +-
c-user/rate-monotonic/introduction.rst | 2 +-
7 files changed, 465 insertions(+), 8 deletions(-)
diff --git a/c-user/fatal-error/directives.rst b/c-user/fatal-error/directives.rst
index 98ce209..6aa4b20 100644
--- a/c-user/fatal-error/directives.rst
+++ b/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
diff --git a/c-user/index.rst b/c-user/index.rst
index 5cd87af..ae782f0 100644
--- a/c-user/index.rst
+++ b/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
diff --git a/c-user/kernel-character-io/directives.rst b/c-user/kernel-character-io/directives.rst
new file mode 100644
index 0000000..f13010e
--- /dev/null
+++ b/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.
diff --git a/c-user/kernel-character-io/index.rst b/c-user/kernel-character-io/index.rst
new file mode 100644
index 0000000..c6a9b6b
--- /dev/null
+++ b/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
diff --git a/c-user/kernel-character-io/introduction.rst b/c-user/kernel-character-io/introduction.rst
new file mode 100644
index 0000000..ef3512b
--- /dev/null
+++ b/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.
diff --git a/c-user/rate-monotonic/directives.rst b/c-user/rate-monotonic/directives.rst
index 02b8898..2e48aac 100644
--- a/c-user/rate-monotonic/directives.rst
+++ b/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:
diff --git a/c-user/rate-monotonic/introduction.rst b/c-user/rate-monotonic/introduction.rst
index 5b0c094..9e3c6f0 100644
--- a/c-user/rate-monotonic/introduction.rst
+++ b/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.
More information about the vc
mailing list