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

Thu Apr 18 06:16:50 UTC 2024

On 18.04.24 04:02, Chris Johns wrote:
> 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?

The RTEMS_NO_WAIT can be used to process an input stream using 
getchark() and then send responses using a non-blocking output char 
variant. This helps to have enough processing time and allows an 
overlapping send/receive.

> 
> Is this change for RTEMS 7?

Yes, this would be good.

> 
> In the context of the change:
> 
> 1. RTEMS_FLUSH etc are too generic.

I added them to <rtems/rtems/options.h>, so they could be reused in 
other directives. A bit less generic names could be:

* RTEMS_IO_FLUSH

* RTEMS_IO_DRAIN

* RTEMS_IO_NO_OUTPUT

This would be in the IO namespace similar to RTEMS_EVENT_ANY and 
RTEMS_EVENT_ALL.

> 
> 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.

This is the documentation of a function pointer type, so there is no 
direct code. With three flags, you have to specify for eight variants 
what should happen. The wording is in EARS. It should be easy to 
translate this into code for a particular device.

https://docs.rtems.org/branches/master/eng/req/req-for-req.html#syntax

> 
> 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 would prefer the EARS variant. This function type should define 
requirements for the associated implementations.

> 
> 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".

The name of this function type is BSP_output_char_function_type and not 
BSP_transmit_char_function_type, so I used "output" here and not 
"transmit". Also, the character may not get immediately transmitted if 
FIFOs are involved (thus the need for the flush). Maybe my understanding 
of transmitted is wrong, but for me transmitting has something to do 
with signals on a medium.

> 
> 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.

The no-output option is used to just flush the device without 
transmitting a new character. For the flush, we could add something like 
this:

Flushing the device should ensure that all characters handed over to the 
device for output are visible to external consumers. For example, the 
device output FIFO and transmit shift registers should be empty.

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

-- 
embedded brains GmbH & Co. KG
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/