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

Thu Apr 18 02:02:00 UTC 2024

On 17/4/2024 11:06 pm, Sebastian Huber wrote:
> 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.

Thanks for providing this overview.

I am still confused about the differences in terms of why you would need the
RTEMS_NO_WAIT. Do you have a specific application where this is required? It
might help me understand the need for the change? Examples are need to reset in
a specific period, a test mode you are running in a system, etc?

Is this change for RTEMS 7?

In the context of the change:

1. RTEMS_FLUSH etc are too generic.

2. The language used needs some work, maybe fewer "while"s. For example:

 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.

This is difficult to read and when it is probability easier to read the code it
is of questionable value. I appreciate it is not always easy to write but I feel
clarity would be a good to have here.

Another example:

 While no character is available in the device, a polled
 character input functions shall return minus one.

It could be written as:

 A polled character input function shall return a character if the device
 has successfully received one else the function returns minus one.

I think receive and transmit is better than for example "be hand over to the
device for output", maybe "shall be transmitted by the device".

3. Flush needs to be worded in terms of successfully transmitted by the device
to avoid the case of data being written to the device is held in FIFOs awaiting
transmission and reset is asserted. Maybe FLUSH is the wrong term because it is
so overloaded in what it means? An alternative could be
RTEMS_BSP_IO_TRANSMISSION_COMPLETE? And following on you could have
RTEMS_BSP_IO_NO_TRANSMISSION? The key point is "transmission" relates to the
external data pin of the interface.

Chris

> ---
>  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 */
>  
>  /**