[rtems-central commit] spec: Specify kernel input/output support
Sebastian Huber
sebh at rtems.org
Mon Aug 2 05:12:42 UTC 2021
Module: rtems-central
Branch: master
Commit: 1ccc248b03ad639d2bb6aa8d518ee996c24277ad
Changeset: http://git.rtems.org/rtems-central/commit/?id=1ccc248b03ad639d2bb6aa8d518ee996c24277ad
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Thu Jul 29 13:05:40 2021 +0200
spec: Specify kernel input/output support
---
config.yml | 4 +
spec/c/if/stdarg.yml | 13 ++
spec/c/if/va_list.yml | 13 ++
spec/rtems/io/constraint/no-floating-point.yml | 11 ++
spec/rtems/io/if/bsp-output-char-function-type.yml | 20 ++++
spec/rtems/io/if/bsp-output-char.yml | 26 ++++
spec/rtems/io/if/bsp-poll-char.yml | 26 ++++
.../io/if/bsp-polling-getchar-function-type.yml | 20 ++++
spec/rtems/io/if/getchark.yml | 38 +++++-
spec/rtems/io/if/group-3.yml | 51 ++++++++
spec/rtems/io/if/header-3.yml | 6 +-
spec/rtems/io/if/printk-printer.yml | 58 +++++++++
spec/rtems/io/if/printk.yml | 48 +++++++-
spec/rtems/io/if/put-char.yml | 43 +++++++
spec/rtems/io/if/putc.yml | 39 +++++-
spec/rtems/io/if/putk.yml | 47 ++++++++
spec/rtems/io/if/vprintk.yml | 54 +++++++++
spec/rtems/io/req/bsp-output-char.yml | 16 +++
spec/rtems/io/req/bsp-poll-char-dequeue.yml | 17 +++
spec/rtems/io/req/bsp-poll-char-empty.yml | 16 +++
spec/rtems/io/req/getchark.yml | 120 +++++++++++++++++++
spec/rtems/io/req/put-char.yml | 131 +++++++++++++++++++++
spec/rtems/io/req/putc.yml | 131 +++++++++++++++++++++
spec/rtems/io/val/kernel.yml | 63 ++++++++++
spec/testsuites/validation-io-kernel.yml | 94 +++++++++++++++
templates/Doxyfile | 2 +-
26 files changed, 1095 insertions(+), 12 deletions(-)
diff --git a/config.yml b/config.yml
index 73f7d6f..36e0faa 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 0000000..dd1b0a7
--- /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 0000000..f5dd267
--- /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 0000000..b29c53b
--- /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 0000000..183a034
--- /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 0000000..b5844f1
--- /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 0000000..ccfdee6
--- /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 0000000..47df4c7
--- /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 23615c4..f4f12e3 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 0000000..f8f7958
--- /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 c85f4af..0d7528d 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 0000000..0508625
--- /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 4436922..5652b7a 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 0000000..614f730
--- /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 00f6f32..c83cccb 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 0000000..88e3067
--- /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 0000000..eb05598
--- /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 0000000..17b38cc
--- /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 0000000..20b15a3
--- /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 0000000..87d5eb8
--- /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 0000000..94445eb
--- /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 0000000..7713690
--- /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 0000000..673d3b8
--- /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 0000000..9932218
--- /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 0000000..101ba63
--- /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 7db17ca..f1f9b18 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
More information about the vc
mailing list