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

[Chris Johns]

On 18/4/2024 4:16 pm, Sebastian Huber wrote:
> 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.

Great, I think it is too late for 6.

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

Sure, that is better.

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

Yeap

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

I think EARS is too specialised for RTEMS and here in this small isolated case.
If it was taught in first year undergrad courses and widely adopted it would be
a different. It is not used in RTEMS and starting here and now only makes this
piece of code harder to maintain.

>> 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 do not agree and until EARS is agreed to at the project level this will not
change.

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

The function outputs data, the device transmits. If the requirement is to output
the data it does not cover the transmission and the transmission is the
important part.

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

I have never heard of a device that has data loaded into a FIFO to transmit has
a mode that transmits sooner or faster? I would have assumed outputting the data
to the FIFO would sent it. There is a distinct difference between output and
transmit and I would like to see the transmit aspect be specified and met.

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

Like what flush does?

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

Lets just say transmitted. The devices we manage are embedded and so we receive
and transmit data. Lets not introduce new or custom terms.

Chris