[RFC] rtems: Add options to kernel output char handler

[Sebastian Huber]

Make the kernel I/O output character device processing configurable
through an option set parameter.  Add RTEMS_NO_OUTPUT and RTEMS_FLUSH
options.  The goal of this API change is to enable flushing the kernel
output device in the system termination process before a reset is
issued.  A use case for using RTEMS_NO_WAIT is the polled processing of
an input and output stream from and to the I/O device.
---
 cpukit/include/rtems/bspIo.h         | 50 ++++++++++++++++++++++++++--
 cpukit/include/rtems/rtems/options.h | 20 ++++++++++-
 2 files changed, 67 insertions(+), 3 deletions(-)

diff --git a/cpukit/include/rtems/bspIo.h b/cpukit/include/rtems/bspIo.h
index 31580cd800..09a3c47243 100644
--- a/cpukit/include/rtems/bspIo.h
+++ b/cpukit/include/rtems/bspIo.h
@@ -10,7 +10,7 @@
  */
 
 /*
- * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG
+ * Copyright (C) 2020, 2024 embedded brains GmbH & Co. KG
  * Copyright (C) 2015 On-Line Applications Research Corporation (OAR)
  *
  * Redistribution and use in source and binary forms, with or without
@@ -58,6 +58,8 @@
 #define _RTEMS_BSPIO_H
 
 #include <stdarg.h>
+#include <rtems/rtems/options.h>
+#include <rtems/rtems/status.h>
 #include <rtems/score/basedefs.h>
 
 #ifdef __cplusplus
@@ -89,8 +91,42 @@ extern "C" {
  * @ingroup RTEMSAPIKernelCharIO
  *
  * @brief Polled character output functions shall have this type.
+ *
+ * @param out is the character to output.
+ *
+ * @param option_set is the option set.
+ *
+ * While the #RTEMS_NO_WAIT option is set in the option_set parameter, while
+ * the device cannot immediately accept a character for output, the character
+ * in out shall not be hand over to the device for output, optionally the
+ * device output shall be flushed, and ::RTEMS_UNSATISFIED shall be returned.
+ *
+ * While the #RTEMS_NO_OUTPUT option is set in the option_set parameter, the
+ * character in the out parameter shall not be handed over to the device for
+ * output.
+ *
+ * While the #RTEMS_NO_WAIT option is cleared in the option_set parameter,
+ * while the #RTEMS_NO_OUTPUT option is cleared in the option_set parameter,
+ * the character in the out parameter shall be hand over to the device for
+ * output.
+ *
+ * While the #RTEMS_NO_WAIT option is set in the option_set parameter, while
+ * the #RTEMS_NO_OUTPUT option is cleared in the option_set parameter, while
+ * the device can immediately accept a character for output, the character in
+ * out shall be hand over to the device for output.
+ *
+ * While the #RTEMS_FLUSH option is set in the option_set parameter, the device
+ * output shall be flushed before the function returns.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_UNSATISFIED The device is was not ready to output a
+ *   character.
  */
-typedef void ( *BSP_output_char_function_type )( char );
+typedef rtems_status_code ( *BSP_output_char_function_type )(
+  char out,
+  rtems_option option_set
+);
 
 /* Generated from spec:/rtems/io/if/bsp-output-char */
 
@@ -333,6 +369,16 @@ int rtems_printk_printer( void *unused, const char *fmt, va_list ap );
  * @ingroup RTEMSAPIKernelCharIO
  *
  * @brief Polled character input functions shall have this type.
+ *
+ * While a character is available in the device, a polled character input
+ * function shall return the least recently received character as an unsigned
+ * character.  While no character is available in the device, a polled
+ * character input functions shall return minus one.
+ *
+ * @retval -1 There was no input character available in the device.
+ *
+ * @return Returns the least recently received character available in the
+ *   device as an unsigned character.
  */
 typedef int (* BSP_polling_getchar_function_type )( void );
 
diff --git a/cpukit/include/rtems/rtems/options.h b/cpukit/include/rtems/rtems/options.h
index 44a8d6ccb8..3522fc4fcd 100644
--- a/cpukit/include/rtems/rtems/options.h
+++ b/cpukit/include/rtems/rtems/options.h
@@ -9,7 +9,7 @@
  */
 
 /*
- * Copyright (C) 2020 embedded brains GmbH & Co. KG
+ * Copyright (C) 2020, 2024 embedded brains GmbH & Co. KG
  * Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR)
  *
  * Redistribution and use in source and binary forms, with or without
@@ -103,6 +103,24 @@ extern "C" {
  */
 #define RTEMS_EVENT_ANY 0x00000002
 
+/* Generated from spec:/rtems/option/if/flush */
+
+/**
+ * @ingroup RTEMSAPIClassicOptions
+ *
+ * @brief This option constant indicates that something shall be flushed.
+ */
+#define RTEMS_FLUSH 0x00000008
+
+/* Generated from spec:/rtems/option/if/no-output */
+
+/**
+ * @ingroup RTEMSAPIClassicOptions
+ *
+ * @brief This option constant indicates that the nothing shall be output.
+ */
+#define RTEMS_NO_OUTPUT 0x00000004
+
 /* Generated from spec:/rtems/option/if/no-wait */
 
 /**
-- 
2.35.3