spec: Specify kernel input/output support

26 files changed, 1095 insertions, 12 deletions

diff --git a/config.yml b/config.yml
index 73f7d6fd..36e0faae 100644
--- a/config.yml
+++ b/config.yml
@@ -38,6 +38,7 @@ build:
   - testsuites/validation/tc-basedefs-pendant.h
   - testsuites/validation/tr-event-constant.h
   - testsuites/validation/tr-event-send-receive.h
+  - testsuites/validation/tr-io-kernel.h
   - testsuites/validation/tr-model-chains-api.h
   - testsuites/validation/tr-model-events-mgr.h
   - testsuites/validation/tr-object-ident.h
@@ -135,6 +136,9 @@ interface-documentation:
 - directives-target: modules/rtems-docs/c-user/io/directives.rst
   group: /rtems/io/if/group
   introduction-target: modules/rtems-docs/c-user/io/introduction.rst
+- directives-target: modules/rtems-docs/c-user/kernel-character-io/directives.rst
+  group: /rtems/io/if/group-3
+  introduction-target: modules/rtems-docs/c-user/kernel-character-io/introduction.rst
 - directives-target: modules/rtems-docs/c-user/region/directives.rst
   group: /rtems/region/if/group
   introduction-target: modules/rtems-docs/c-user/region/introduction.rst
diff --git a/spec/c/if/stdarg.yml b/spec/c/if/stdarg.yml
new file mode 100644
index 00000000..dd1b0a71
--- /dev/null
+++ b/spec/c/if/stdarg.yml
@@ -0,0 +1,13 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: This is a standard C library header file.
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: header-file
+links:
+- role: interface-placement
+  uid: domain
+path: stdarg.h
+prefix: ''
+type: interface
diff --git a/spec/c/if/va_list.yml b/spec/c/if/va_list.yml
new file mode 100644
index 00000000..f5dd2678
--- /dev/null
+++ b/spec/c/if/va_list.yml
@@ -0,0 +1,13 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-type
+links:
+- role: interface-placement
+  uid: stdarg
+name: va_list
+references:
+  url: https://en.cppreference.com/w/c/variadic/va_list
+type: interface
diff --git a/spec/rtems/io/constraint/no-floating-point.yml b/spec/rtems/io/constraint/no-floating-point.yml
new file mode 100644
index 00000000..b29c53b3
--- /dev/null
+++ b/spec/rtems/io/constraint/no-floating-point.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  Formatting of floating point numbers is not supported.
+type: constraint
diff --git a/spec/rtems/io/if/bsp-output-char-function-type.yml b/spec/rtems/io/if/bsp-output-char-function-type.yml
new file mode 100644
index 00000000..183a034e
--- /dev/null
+++ b/spec/rtems/io/if/bsp-output-char-function-type.yml
@@ -0,0 +1,20 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Polled character output functions shall have this type.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default: void ( *${.:/name} )( char )
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: typedef
+links:
+- role: interface-placement
+  uid: header-3
+- role: interface-ingroup
+  uid: group-3
+name: BSP_output_char_function_type
+notes: null
+type: interface
diff --git a/spec/rtems/io/if/bsp-output-char.yml b/spec/rtems/io/if/bsp-output-char.yml
new file mode 100644
index 00000000..b5844f12
--- /dev/null
+++ b/spec/rtems/io/if/bsp-output-char.yml
@@ -0,0 +1,26 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  This function pointer references the kernel character output implementation.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+definition:
+  default: ${bsp-output-char-function-type:/name} ${.:/name}
+  variants: []
+description: |
+  This function pointer shall never be ${/c/if/null:/name}.  It shall be
+  provided by the ${/glossary/bsp:/term} 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.
+enabled-by: true
+index-entries: []
+interface-type: variable
+links:
+- role: interface-placement
+  uid: header-3
+- role: interface-ingroup
+  uid: group-3
+name: BSP_output_char
+notes: null
+type: interface
diff --git a/spec/rtems/io/if/bsp-poll-char.yml b/spec/rtems/io/if/bsp-poll-char.yml
new file mode 100644
index 00000000..ccfdee60
--- /dev/null
+++ b/spec/rtems/io/if/bsp-poll-char.yml
@@ -0,0 +1,26 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  This function pointer may reference the kernel character input implementation.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+definition:
+  default: ${bsp-polling-getchar-function-type:/name} ${.:/name}
+  variants: []
+description: |
+  This function pointer may be ${/c/if/null:/name}.  It may reference a
+  function provided by the ${/glossary/bsp:/term}.  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.
+enabled-by: true
+index-entries: []
+interface-type: variable
+links:
+- role: interface-placement
+  uid: header-3
+- role: interface-ingroup
+  uid: group-3
+name: BSP_poll_char
+notes: null
+type: interface
diff --git a/spec/rtems/io/if/bsp-polling-getchar-function-type.yml b/spec/rtems/io/if/bsp-polling-getchar-function-type.yml
new file mode 100644
index 00000000..47df4c7e
--- /dev/null
+++ b/spec/rtems/io/if/bsp-polling-getchar-function-type.yml
@@ -0,0 +1,20 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Polled character input functions shall have this type.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default: int (* ${.:/name} )( void )
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: typedef
+links:
+- role: interface-placement
+  uid: header-3
+- role: interface-ingroup
+  uid: group-3
+name: BSP_polling_getchar_function_type
+notes: null
+type: interface
diff --git a/spec/rtems/io/if/getchark.yml b/spec/rtems/io/if/getchark.yml
index 23615c4d..f4f12e36 100644
--- a/spec/rtems/io/if/getchark.yml
+++ b/spec/rtems/io/if/getchark.yml
@@ -1,12 +1,44 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Tries to dequeue a character from the kernel character input device.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+definition:
+  default:
+    attributes: null
+    body: null
+    params: []
+    return: int
+  variants: []
+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:/name} if it is available.
 enabled-by: true
 index-entries: []
-interface-type: unspecified-function
+interface-type: function
 links:
 - role: interface-placement
   uid: header-3
+- role: interface-ingroup
+  uid: group-3
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: getchark
-references: {}
+notes: null
+params: []
+return:
+  return: |
+    Returns the character least recently enqueued on the kernel character input
+    device as an unsigned character value.
+  return-values:
+  - description: |
+      The ${bsp-poll-char:/name} pointer was equal to ${/c/if/null:/name}.
+    value: -1
+  - description: |
+      There was no character enqueued on the kernel character input device.
+    value: -1
 type: interface
diff --git a/spec/rtems/io/if/group-3.yml b/spec/rtems/io/if/group-3.yml
new file mode 100644
index 00000000..f8f79587
--- /dev/null
+++ b/spec/rtems/io/if/group-3.yml
@@ -0,0 +1,51 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  The kernel character input/output support is an extension of the
+  ${group:/name} 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.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+description: |
+  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 ${/acfg/if/appl-needs-console-driver:/name}.  The kernel
+  character input and output device is provided by the ${/glossary/bsp:/term}.
+  Applications may change the device.
+enabled-by: true
+identifier: RTEMSAPIKernelCharIO
+index-entries: []
+interface-type: group
+links:
+- role: interface-placement
+  uid: header-3
+- role: interface-ingroup
+  uid: group
+- role: placement-order
+  uid: bsp-output-char-function-type
+- role: placement-order
+  uid: bsp-output-char
+- role: placement-order
+  uid: putc
+- role: placement-order
+  uid: put-char
+- role: placement-order
+  uid: putk
+- role: placement-order
+  uid: printk
+- role: placement-order
+  uid: vprintk
+- role: placement-order
+  uid: printk-printer
+- role: placement-order
+  uid: bsp-polling-getchar-function-type
+- role: placement-order
+  uid: bsp-poll-char
+- role: placement-order
+  uid: getchark
+name: Kernel Character I/O Support
+text: |
+  The ${group:/name} shall provide an interface group containing functions to
+  input and output characters to a ${/glossary/bsp:/term} defined device using
+  a polled and non-blocking implementation.
+type: interface
diff --git a/spec/rtems/io/if/header-3.yml b/spec/rtems/io/if/header-3.yml
index c85f4af3..0d7528d7 100644
--- a/spec/rtems/io/if/header-3.yml
+++ b/spec/rtems/io/if/header-3.yml
@@ -1,14 +1,16 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  This header file defines the polled character IO driver API.
+  This header file provides the kernel character input/output support API.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 enabled-by: true
 index-entries: []
-interface-type: container
+interface-type: header-file
 links:
 - role: interface-placement
   uid: /if/domain
+- role: interface-ingroup
+  uid: group-3
 path: rtems/bspIo.h
 prefix: cpukit/include
 type: interface
diff --git a/spec/rtems/io/if/printk-printer.yml b/spec/rtems/io/if/printk-printer.yml
new file mode 100644
index 00000000..0508625c
--- /dev/null
+++ b/spec/rtems/io/if/printk-printer.yml
@@ -0,0 +1,58 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Outputs the characters defined by the format string and the variable argument
+  list to the kernel character output device.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params:
+    - void *${.:/params[0]/name}
+    - const char *${.:/params[1]/name}
+    - ${/c/if/va_list:/name} ${.:/params[2]/name}
+    return: int
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header-3
+- role: interface-ingroup
+  uid: group-3
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: ../constraint/no-floating-point
+name: rtems_printk_printer
+notes: |
+  The directive may be used to print debug and test information.  It uses
+  ${putc:/name} 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.
+params:
+- description: |
+    is an unused argument.
+  dir: null
+  name: unused
+- description: |
+    is a printf()-style format string.
+  dir: null
+  name: fmt
+- description: |
+    is the variable argument list required by the format string.
+  dir: null
+  name: ap
+return:
+  return: |
+    Returns the number of characters output to the kernel character output
+    device.
+  return-values: []
+type: interface
diff --git a/spec/rtems/io/if/printk.yml b/spec/rtems/io/if/printk.yml
index 44369225..5652b7a3 100644
--- a/spec/rtems/io/if/printk.yml
+++ b/spec/rtems/io/if/printk.yml
@@ -1,12 +1,54 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Outputs the characters defined by the format string and the arguments to the
+  kernel character output device.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+definition:
+  default:
+    attributes: ${../../basedefs/if/printflike:/name}( 1, 2 )
+    body: null
+    params:
+    - const char *${.:/params[0]/name}
+    - '...'
+    return: int
+  variants: []
+description: null
 enabled-by: true
 index-entries: []
-interface-type: unspecified-function
+interface-type: function
 links:
 - role: interface-placement
   uid: header-3
+- role: interface-ingroup
+  uid: group-3
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: ../constraint/no-floating-point
 name: printk
-references: {}
+notes: |
+  The directive may be used to print debug and test information.  It uses
+  ${putc:/name} 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.
+params:
+- description: |
+    is a printf()-style format string.
+  dir: null
+  name: fmt
+- description: |
+    is a list of optional parameters required by the format string.
+  dir: null
+  name: '...'
+return:
+  return: |
+    Returns the number of characters output to the kernel character output
+    device.
+  return-values: []
 type: interface
diff --git a/spec/rtems/io/if/put-char.yml b/spec/rtems/io/if/put-char.yml
new file mode 100644
index 00000000..614f7305
--- /dev/null
+++ b/spec/rtems/io/if/put-char.yml
@@ -0,0 +1,43 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Puts the character using ${putc:/name}
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params:
+    - int ${.:/params[0]/name}
+    - void *${.:/params[1]/name}
+    return: void
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header-3
+- role: interface-ingroup
+  uid: group-3
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+name: rtems_put_char
+notes: |
+  The directive is provided to support the RTEMS Testing Framework.
+params:
+- description: |
+    is the character to output.
+  dir: null
+  name: c
+- description: |
+    is an unused argument.
+  dir: null
+  name: unused
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/spec/rtems/io/if/putc.yml b/spec/rtems/io/if/putc.yml
index 00f6f324..c83cccb0 100644
--- a/spec/rtems/io/if/putc.yml
+++ b/spec/rtems/io/if/putc.yml
@@ -1,12 +1,45 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Outputs the character to the kernel character output device.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+definition:
+  default:
+    attributes: null
+    body: null
+    params:
+    - char ${.:/params[0]/name}
+    return: void
+  variants: []
+description: |
+  The directive outputs the character specified by ${.:/params[0]/name} to the
+  kernel character output device using the polled character output
+  implementation provided by ${bsp-output-char:/name}.  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.
 enabled-by: true
 index-entries: []
-interface-type: unspecified-function
+interface-type: function
 links:
 - role: interface-placement
   uid: header-3
+- role: interface-ingroup
+  uid: group-3
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_putc
-references: {}
+notes: null
+params:
+- description: |
+    is the character to output.
+  dir: null
+  name: c
+return:
+  return: null
+  return-values: []
 type: interface
diff --git a/spec/rtems/io/if/putk.yml b/spec/rtems/io/if/putk.yml
new file mode 100644
index 00000000..88e3067a
--- /dev/null
+++ b/spec/rtems/io/if/putk.yml
@@ -0,0 +1,47 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Outputs the characters of the string and a newline character to the kernel
+  character output device.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+definition:
+  default:
+    attributes: null
+    body: null
+    params:
+    - const char *${.:/params[0]/name}
+    return: int
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header-3
+- role: interface-ingroup
+  uid: group-3
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+name: putk
+notes: |
+  The directive may be used to print debug and test information.  It uses
+  ${putc:/name} 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.
+params:
+- description: |
+    is the string to output.
+  dir: null
+  name: s
+return:
+  return: |
+    Returns the number of characters output to the kernel character output
+    device.
+  return-values: []
+type: interface
diff --git a/spec/rtems/io/if/vprintk.yml b/spec/rtems/io/if/vprintk.yml
new file mode 100644
index 00000000..eb055989
--- /dev/null
+++ b/spec/rtems/io/if/vprintk.yml
@@ -0,0 +1,54 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Outputs the characters defined by the format string and the variable argument
+  list to the kernel character output device.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
+definition:
+  default:
+    attributes: null
+    body: null
+    params:
+    - const char *${.:/params[0]/name}
+    - ${/c/if/va_list:/name} ${.:/params[1]/name}
+    return: int
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header-3
+- role: interface-ingroup
+  uid: group-3
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: ../constraint/no-floating-point
+name: vprintk
+notes: |
+  The directive may be used to print debug and test information.  It uses
+  ${putc:/name} 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.
+params:
+- description: |
+    is a printf()-style format string.
+  dir: null
+  name: fmt
+- description: |
+    is the variable argument list required by the format string.
+  dir: null
+  name: ap
+return:
+  return: |
+    Returns the number of characters output to the kernel character output
+    device.
+  return-values: []
+type: interface
diff --git a/spec/rtems/io/req/bsp-output-char.yml b/spec/rtems/io/req/bsp-output-char.yml
new file mode 100644
index 00000000..17b38cc2
--- /dev/null
+++ b/spec/rtems/io/req/bsp-output-char.yml
@@ -0,0 +1,16 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: interface-function
+  uid: ../if/bsp-output-char
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  When the function referenced by ${../if/bsp-output-char:/name} is called, it
+  shall output the character specified by the parameter to the kernel character
+  output device.
+type: requirement
diff --git a/spec/rtems/io/req/bsp-poll-char-dequeue.yml b/spec/rtems/io/req/bsp-poll-char-dequeue.yml
new file mode 100644
index 00000000..20b15a3d
--- /dev/null
+++ b/spec/rtems/io/req/bsp-poll-char-dequeue.yml
@@ -0,0 +1,17 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: interface-function
+  uid: ../if/bsp-poll-char
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  While the ${../if/bsp-poll-char:/name} pointer references a function, while
+  the kernel character input device used by the function has a character
+  enqueued, the function shall dequeue the least recently enqueued character
+  and return it as an unsigned character value.
+type: requirement
diff --git a/spec/rtems/io/req/bsp-poll-char-empty.yml b/spec/rtems/io/req/bsp-poll-char-empty.yml
new file mode 100644
index 00000000..87d5eb83
--- /dev/null
+++ b/spec/rtems/io/req/bsp-poll-char-empty.yml
@@ -0,0 +1,16 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: interface-function
+  uid: ../if/bsp-poll-char
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  While the ${../if/bsp-poll-char:/name} pointer references a function, while
+  the kernel character input device used by the function has no character
+  enqueued, the function shall return minus one.
+type: requirement
diff --git a/spec/rtems/io/req/getchark.yml b/spec/rtems/io/req/getchark.yml
new file mode 100644
index 00000000..94445eb0
--- /dev/null
+++ b/spec/rtems/io/req/getchark.yml
@@ -0,0 +1,120 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+functional-type: action
+links:
+- role: interface-function
+  uid: ../if/getchark
+post-conditions:
+- name: Result
+  states:
+  - name: PollChar
+    test-code: |
+      T_eq_int( ctx->result, 123 );
+    text: |
+      The return value of ${../if/getchark:/name} shall be the return value of
+      the function referenced by ${../if/bsp-poll-char:/name}.
+  - name: MinusOne
+    test-code: |
+      T_eq_int( ctx->result, -1 );
+      T_eq_u32( ctx->input_count, 0 );
+    text: |
+      The return value of ${../if/getchark:/name} shall be minus one.
+  test-epilogue: null
+  test-prologue: null
+- name: Calls
+  states:
+  - name: Once
+    test-code: |
+      T_eq_u32( ctx->input_count, 1 );
+    text: |
+      The function referenced by ${../if/bsp-poll-char:/name} shall be called
+      exactly once to get the return value for ${../if/getchark:/name}.
+  test-epilogue: null
+  test-prologue: null
+pre-conditions:
+- name: PollChar
+  states:
+  - name: Valid
+    test-code: |
+      ctx->poll_char = PollChar;
+    text: |
+      While ${../if/bsp-poll-char:/name} references a function.
+  - name: 'Null'
+    test-code: |
+      ctx->poll_char = NULL;
+    text: |
+      While ${../if/bsp-poll-char:/name} is equal to ${/c/if/null:/name}.
+  test-epilogue: null
+  test-prologue: null
+rationale: null
+references: []
+requirement-type: functional
+skip-reasons: {}
+test-action: |
+  BSP_polling_getchar_function_type poll_char;
+
+  ctx->input_count = 0;
+  poll_char = BSP_poll_char;
+  BSP_poll_char = ctx->poll_char;
+  ctx->result = getchark();
+  BSP_poll_char = poll_char;
+test-brief: null
+test-cleanup: null
+test-context:
+- brief: |
+    This member contains the character input count.
+  description: null
+  member: |
+    size_t input_count
+- brief: |
+    This member specifies the value for ${../if/bsp-poll-char:/name}.
+  description: null
+  member: |
+    BSP_polling_getchar_function_type poll_char
+- brief: |
+    This member contains the return value of the ${../if/getchark:/name} call.
+  description: null
+  member: |
+    int result
+test-context-support: null
+test-description: null
+test-header: null
+test-includes:
+- rtems/bspIo.h
+test-local-includes: []
+test-prepare: null
+test-setup: null
+test-stop: null
+test-support: |
+  typedef RtemsIoReqGetchark_Context Context;
+
+  static int PollChar( void )
+  {
+    Context *ctx;
+
+    ctx = T_fixture_context();
+    ++ctx->input_count;
+
+    return 123;
+  }
+test-target: testsuites/validation/tc-io-getchark.c
+test-teardown: null
+text: ${.:text-template}
+transition-map:
+- enabled-by: true
+  post-conditions:
+    Result: PollChar
+    Calls: Once
+  pre-conditions:
+    PollChar:
+    - Valid
+- enabled-by: true
+  post-conditions:
+    Result: MinusOne
+    Calls: N/A
+  pre-conditions:
+    PollChar:
+    - 'Null'
+type: requirement
diff --git a/spec/rtems/io/req/put-char.yml b/spec/rtems/io/req/put-char.yml
new file mode 100644
index 00000000..7713690b
--- /dev/null
+++ b/spec/rtems/io/req/put-char.yml
@@ -0,0 +1,131 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+functional-type: action
+links:
+- role: interface-function
+  uid: ../if/put-char
+post-conditions:
+- name: Output
+  states:
+  - name: CrNl
+    test-code: |
+      T_eq_int( ctx->output[ 0 ], (unsigned char) '\r' );
+      T_eq_int( ctx->output[ 1 ], (unsigned char) '\n' );
+      T_eq_sz( ctx->output_count, 2 );
+    text: |
+      The function referenced by ${../if/bsp-output-char:/name} shall be called
+      with a ``CR`` character followed by a call with a ``NL`` character.
+  - name: Other
+    test-code: |
+      T_eq_int( ctx->output[ 0 ], 0xff );
+      T_eq_sz( ctx->output_count, 1 );
+    text: |
+      The function referenced by ${../if/bsp-output-char:/name} shall be called
+      with the character specified by ${../if/put-char:/params[0]/name}.
+  test-epilogue: null
+  test-prologue: null
+pre-conditions:
+- name: Char
+  states:
+  - name: Nl
+    test-code: |
+      ctx->character = '\n';
+    text: |
+      While the ${../if/put-char:/params[0]/name} parameter is
+      equal to ``NL``.
+  - name: Other
+    test-code: |
+      ctx->character = 0xff;
+    text: |
+      While the ${../if/put-char:/params[0]/name} parameter is
+      not equal to ``NL``.
+  test-epilogue: null
+  test-prologue: null
+rationale: null
+references: []
+requirement-type: functional
+skip-reasons: {}
+test-action: |
+  BSP_output_char_function_type output_char;
+
+  ctx->output[ 0 ] = -1;
+  ctx->output[ 1 ] = -1;
+  ctx->output_count = 0;
+  output_char = BSP_output_char;
+  BSP_output_char = OutputChar;
+  rtems_put_char( ctx->character, NULL );
+  BSP_output_char = output_char;
+test-brief: null
+test-cleanup: null
+test-context:
+- brief: |
+    This member contains the character output.
+  description: null
+  member: |
+    int output[ 2 ]
+- brief: |
+    This member contains the character output count.
+  description: null
+  member: |
+    size_t output_count
+- brief: |
+    This member specifies if the ${../if/put-char:/params[0]/name}
+    parameter value.
+  description: null
+  member: |
+    int character
+test-context-support: null
+test-description: null
+test-header: null
+test-includes:
+- rtems/bspIo.h
+test-local-includes: []
+test-prepare: null
+test-setup: null
+test-stop: null
+test-support: |
+  typedef RtemsIoReqPutChar_Context Context;
+
+  static void Output( int value )
+  {
+    Context *ctx;
+
+    ctx = T_fixture_context();
+
+    if ( ctx->output_count < RTEMS_ARRAY_SIZE( ctx->output ) ) {
+      ctx->output[ ctx->output_count ] = value;
+    }
+
+    ++ctx->output_count;
+  }
+
+  static void WrongOutput( char c )
+  {
+    (void) c;
+    Output( -1 );
+  }
+
+  static void OutputChar( char c )
+  {
+    BSP_output_char = WrongOutput;
+    Output( (unsigned char) c );
+  }
+test-target: testsuites/validation/tc-io-put-char.c
+test-teardown: null
+text: ${.:text-template}
+transition-map:
+- enabled-by: true
+  post-conditions:
+    Output: CrNl
+  pre-conditions:
+    Char:
+    - Nl
+- enabled-by: true
+  post-conditions:
+    Output: Other
+  pre-conditions:
+    Char:
+    - Other
+type: requirement
diff --git a/spec/rtems/io/req/putc.yml b/spec/rtems/io/req/putc.yml
new file mode 100644
index 00000000..673d3b81
--- /dev/null
+++ b/spec/rtems/io/req/putc.yml
@@ -0,0 +1,131 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+functional-type: action
+links:
+- role: interface-function
+  uid: ../if/putc
+post-conditions:
+- name: Output
+  states:
+  - name: CrNl
+    test-code: |
+      T_eq_int( ctx->output[ 0 ], (unsigned char) '\r' );
+      T_eq_int( ctx->output[ 1 ], (unsigned char) '\n' );
+      T_eq_sz( ctx->output_count, 2 );
+    text: |
+      The function referenced by ${../if/bsp-output-char:/name} shall be called
+      with a ``CR`` character followed by a call with a ``NL`` character.
+  - name: Other
+    test-code: |
+      T_eq_int( ctx->output[ 0 ], 0xff );
+      T_eq_sz( ctx->output_count, 1 );
+    text: |
+      The function referenced by ${../if/bsp-output-char:/name} shall be called
+      with the character specified by ${../if/putc:/params[0]/name}.
+  test-epilogue: null
+  test-prologue: null
+pre-conditions:
+- name: Char
+  states:
+  - name: Nl
+    test-code: |
+      ctx->character = '\n';
+    text: |
+      While the ${../if/putc:/params[0]/name} parameter is
+      equal to ``NL``.
+  - name: Other
+    test-code: |
+      ctx->character = (char) 0xff;
+    text: |
+      While the ${../if/putc:/params[0]/name} parameter is
+      not equal to ``NL``.
+  test-epilogue: null
+  test-prologue: null
+rationale: null
+references: []
+requirement-type: functional
+skip-reasons: {}
+test-action: |
+  BSP_output_char_function_type output_char;
+
+  ctx->output[ 0 ] = -1;
+  ctx->output[ 1 ] = -1;
+  ctx->output_count = 0;
+  output_char = BSP_output_char;
+  BSP_output_char = OutputChar;
+  rtems_putc( ctx->character );
+  BSP_output_char = output_char;
+test-brief: null
+test-cleanup: null
+test-context:
+- brief: |
+    This member contains the character output.
+  description: null
+  member: |
+    int output[ 2 ]
+- brief: |
+    This member contains the character output count.
+  description: null
+  member: |
+    size_t output_count
+- brief: |
+    This member specifies if the ${../if/putc:/params[0]/name}
+    parameter value.
+  description: null
+  member: |
+    char character
+test-context-support: null
+test-description: null
+test-header: null
+test-includes:
+- rtems/bspIo.h
+test-local-includes: []
+test-prepare: null
+test-setup: null
+test-stop: null
+test-support: |
+  typedef RtemsIoReqPutc_Context Context;
+
+  static void Output( int value )
+  {
+    Context *ctx;
+
+    ctx = T_fixture_context();
+
+    if ( ctx->output_count < RTEMS_ARRAY_SIZE( ctx->output ) ) {
+      ctx->output[ ctx->output_count ] = value;
+    }
+
+    ++ctx->output_count;
+  }
+
+  static void WrongOutput( char c )
+  {
+    (void) c;
+    Output( -1 );
+  }
+
+  static void OutputChar( char c )
+  {
+    BSP_output_char = WrongOutput;
+    Output( (unsigned char) c );
+  }
+test-target: testsuites/validation/tc-io-putc.c
+test-teardown: null
+text: ${.:text-template}
+transition-map:
+- enabled-by: true
+  post-conditions:
+    Output: CrNl
+  pre-conditions:
+    Char:
+    - Nl
+- enabled-by: true
+  post-conditions:
+    Output: Other
+  pre-conditions:
+    Char:
+    - Other
+type: requirement
diff --git a/spec/rtems/io/val/kernel.yml b/spec/rtems/io/val/kernel.yml
new file mode 100644
index 00000000..99322182
--- /dev/null
+++ b/spec/rtems/io/val/kernel.yml
@@ -0,0 +1,63 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+test-actions:
+- action-brief: |
+    Call the function referenced by ${../if/bsp-output-char:/name}.
+  action-code: |
+    ( *BSP_output_char )( 'X' );
+    ( *BSP_output_char )( '\n' );
+  checks: []
+  links:
+  - role: validation
+    uid: ../req/bsp-output-char
+- action-brief: |
+    If ${../if/bsp-poll-char:/name} references a function, then call it.
+  action-code: |
+    BSP_polling_getchar_function_type poll_char;
+    int c;
+
+    poll_char = BSP_poll_char;
+
+    if ( poll_char != NULL ) {
+      c = ( *poll_char )();
+    } else {
+      c = -1;
+    }
+  checks:
+  - brief: |
+      Check that the returned value is minus one or an unsigned character
+      value.
+    code: |
+      T_step_true( ${step}, c == -1 || ( c & ~0xff ) == 0 );
+    links:
+    - role: validation
+      uid: ../req/bsp-poll-char-empty
+    - role: validation
+      uid: ../req/bsp-poll-char-dequeue
+  links: []
+test-brief: |
+  Tests the functions referenced by ${../if/bsp-output-char:/name} and
+  ${../if/bsp-poll-char:/name}.
+test-context: []
+test-context-support: null
+test-description: null
+test-header:
+  code: null
+  freestanding: true
+  includes: []
+  local-includes: []
+  run-params: []
+  target: testsuites/validation/tr-io-kernel.h
+test-includes:
+- rtems/bspIo.h
+test-local-includes:
+- tr-io-kernel.h
+test-setup: null
+test-stop: null
+test-support: null
+test-target: testsuites/validation/tr-io-kernel.c
+test-teardown: null
+type: test-case
diff --git a/spec/testsuites/validation-io-kernel.yml b/spec/testsuites/validation-io-kernel.yml
new file mode 100644
index 00000000..101ba638
--- /dev/null
+++ b/spec/testsuites/validation-io-kernel.yml
@@ -0,0 +1,94 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/test-suites
+test-brief: |
+  This validation test suite contains test cases which test the kernel
+  character input/output device provided by the ${/glossary/bsp:/term} before
+  the system initialization is performed.
+test-code: |
+  const char rtems_test_name[] = "${.:/test-suite-name}";
+
+  static char buffer[ 512 ];
+
+  static const T_action actions[] = {
+    T_report_hash_sha256
+  };
+
+  static const T_config test_config = {
+    .name = rtems_test_name,
+    .buf = buffer,
+    .buf_size = sizeof( buffer ),
+    .putchar = rtems_put_char,
+    .verbosity = RTEMS_TEST_VERBOSITY,
+    .now = T_now_dummy,
+    .action_count = T_ARRAY_SIZE( actions ),
+    .actions = actions
+  };
+
+  void boot_card( const char *cmdline )
+  {
+    uint32_t exit_code;
+
+    (void) cmdline;
+
+    rtems_test_begin( rtems_test_name, TEST_STATE );
+    T_run_initialize( &test_config );
+    RtemsIoValKernel_Run();
+
+    if ( T_run_finalize() ) {
+      rtems_test_end( rtems_test_name );
+      exit_code = 0;
+    } else {
+      exit_code = 1;
+    }
+
+    rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, exit_code );
+  }
+
+  static void *IdleBody( uintptr_t ignored )
+  {
+    (void) ignored;
+
+    while ( true ) {
+      /* Do nothing */
+    }
+
+    return NULL;
+  }
+
+  #define CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
+
+  #define CONFIGURE_MAXIMUM_FILE_DESCRIPTORS 0
+
+  #define CONFIGURE_DISABLE_NEWLIB_REENTRANCY
+
+  #define CONFIGURE_APPLICATION_DISABLE_FILESYSTEM
+
+  #define CONFIGURE_SCHEDULER_USER
+
+  #define CONFIGURE_SCHEDULER
+
+  #define CONFIGURE_SCHEDULER_TABLE_ENTRIES { }
+
+  #define CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION
+
+  #define CONFIGURE_IDLE_TASK_BODY IdleBody
+
+  #define CONFIGURE_INIT
+
+  #include <rtems/confdefs.h>
+test-description: null
+test-includes:
+- bsp/bootcard.h
+- rtems/test.h
+- rtems/test-info.h
+- rtems/testopts.h
+test-local-includes:
+- tr-io-kernel.h
+test-suite-name: ValidationIoKernel
+test-target: testsuites/validation/ts-validation-io-kernel.c
+type: test-suite
diff --git a/templates/Doxyfile b/templates/Doxyfile
index 7db17ca5..f1f9b185 100644
--- a/templates/Doxyfile
+++ b/templates/Doxyfile
@@ -2098,7 +2098,7 @@ PREDEFINED             = __GNUC__ __asm__(x)= RTEMS_SMP __attribute__(x)= __rtem
 # definition found in the source code.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_AS_DEFINED      = RTEMS_INLINE_ROUTINE RTEMS_SYSINIT_ITEM OBJECTS_INFORMATION_DEFINE_ZERO
+EXPAND_AS_DEFINED      = RTEMS_INLINE_ROUTINE RTEMS_SYSINIT_ITEM OBJECTS_INFORMATION_DEFINE_ZERO RTEMS_PRINTFLIKE
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
 # remove all references to function-like macros that are alone on a line, have