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
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
