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

[Peter Dufault]

> On Apr 18, 2024, at 6:32 PM, Chris Johns <chrisj at rtems.org> wrote:
> 
> 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 like EARS.  I've used it for my own use, and refer to it when I create a specification that will be reviewed by multiple people outside of HDA.

With no other definition of a format, and no one working on one, I don't think there is a drawback to use EARS unless and until something else is adopted.  I'd make it a recommended (not required) format so more people try it out.

Or is "recommended not required" too weak to even bother with?

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


Peter
-----------------
Peter Dufault
HD Associates, Inc.      Software and System Engineering