From efb8e7c6c3fe534ac36ca44553831c61179fe771 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 30 Jul 2021 08:51:07 +0200 Subject: 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(-) create mode 100644 c-user/kernel-character-io/directives.rst create mode 100644 c-user/kernel-character-io/index.rst create mode 100644 c-user/kernel-character-io/introduction.rst 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 + `_. + +``-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. -- cgit v1.2.3