BSP Console support (was Re: [PATCH] arm: mx6ulevk: Initial BSP support for i.MX 6UltraLite EVK board.)

[Chris Johns]

On 20/04/2016 15:50, Sebastian Huber wrote:
> Hello Chris,
>
> On 20/04/16 01:24, Chris Johns wrote:
>> On 19/04/2016 19:31, Sebastian Huber wrote:
>>> Please don't use this console driver framework. Use
>>> rtems_termios_device_handler instead.
>>
>> I am not on board with saying we do this and I have a few reasons
>> which I would like to present and discuss.
>>
>> The console support in BSPs is a mess and in general we have no
>> standard rules so any debate on this topic is destined to be related
>> to style, preference and history. We need to sort through these things
>> and get a clear understand of the path we want to take and then
>> support it.
>>
>> To guide us I would like to propose some simple rules and while they
>> specifically address consoles it does relate more broadly to all parts
>> of a BSP.
>>
>> 1. One method to support consoles in a BSP.
>>
>> Currently I think we have 4 or more ways console IO happens. There are
>> direct low level writes to devices, simulator type writes, and
>> termios, and within termios we have a couple of possible paths we can
>> take. Joel, is this correct?
>>
>> We should aim at a single termios solution as preferred. I am not sure
>> if this is possible on low memory foot print targets and if it is not
>> possible we should address that in a supported way.
>
> Termios is nothing for low memory targets.

Does this mean it is not suitable or does it mean termios has a low 
memory overhead and can be used?

> However, my comment refers to
> Termios. We have currently two device interfaces to Termios.

OK.

> We have several console driver frameworks.

We should look to move to one.

>
>>
>> 2. Technical merit.
>>
>> We should base the adoption of a solution on technical merit. This
>> however needs to be in the context of documentation and migration.
>>
>> 3. Documentation.
>>
>> For any solution to be accepted there needs to be documentation.
>> Existing documentation should be given precedence over any technical
>> merit.
>
> The state of the art Termios device interface is documented in the manual:
>
> https://docs.rtems.org/doc-current/share/rtems/html/bsp_howto/Console-Driver-Serial-Driver-Functioning-Overview.html#Console-Driver-Serial-Driver-Functioning-Overview

Great. I will migrate this document to the new format.

>> 4. Migration of existing BSPs.
>>
>> There needs to be a defined and clear migration path. Without such a
>> path the RTEMS Project ends up having to support all implementations
>> for ever. Without a migration plan precedence has to be given to the
>> solution that covers the most number of BSPs.
>>
>> It would be nice to know where we stand with numbers?
>
> I spend some days to convert all BSPs to the new Termios device
> interface. I stopped to work on this once I hit the PC BSP.

Is this covered by ticket #2623? Any other tickets covering this issue?

> So, if
> someone has enough time to clean up this BSP, the rest should be very easy.

In theory it should be but the recent addition of PCI devices has add a 
little bit more to the task. Looks like I am adding it to my list.

>> 5. Tier Status
>>
>>  [ Tier documentation is coming ]
>>
>> Any BPS that does not support the preferred console framework cannot
>> be tier 1. If an architecture does not have a tier 1 BSP it cannot be
>> a tier 1 architecture.
>>
>> In relation to 'rtems_termios_device_handler' termios framework:
>>
>> a) What is the technical reasons we adopt this framework?
>
> Yes, its much easier to write drivers for it since you don't have to
> deal with all the tables. It supports SMP in contrast to the old
> interface. This is the primary reason why we have this new interface.

OK, this is important. That relationship was not apparent to me.

>>
>> b) Is the framework documented anywhere?
>
> Yes, in the manual.

Excellent.

>>
>>  ruru rtems.git $ grep -r rtems_termios_device_handler doc/
>>  ruru rtems.git $
>>
>> while:
>>
>>  ruru rtems.git $ grep -r rtems_termios_handler doc/
>>  doc/bsp_howto/console.t:const rtems_termios_handler
>> my_driver_handler_polled = @{
>>  doc/bsp_howto/console.t:const rtems_termios_handler
>> my_driver_handler_interrupt = @{
>>  doc/bsp_howto/console.t:extern const rtems_termios_handler
>> my_driver_handler_polled;
>>  doc/bsp_howto/console.t:extern const rtems_termios_handler
>> my_driver_handler_interrupt;
>>  doc/bsp_howto/console.t:  const rtems_termios_handler *handler =
>> &my_driver_handler_interrupt;
>>  doc/bsp_howto/console.t:  const rtems_termios_handler *handler =
>> &my_driver_handler_polled;
>>  ruru rtems.git $
>
> This is a typo. I will fix this once the new documentation repository is
> available.

Great. I am waiting on the LICENSE to be added to the repo as this 
resets the repo requiring a new clone. Amar has the text to add, I just 
need a little bit of his time to get this done. After this happens I 
need to add something to each file. I am looking at SPDX but I am not 
sure how to do this.

>> c) What is the migration plan?
>>
>> The PC BSP uses ns16550.c and not ns16550-context.c. This second file
>> is almost a copy of the first. If I find a bug in either file should I
>> attempt to fix both or ignore the one I cannot test?
>
> I copied the ns16550 due to the PC BSP.

It I update the pc386 to the new driver can I then move the 
ns16550-context.c to ns16550.c? Is it the only dependent BSP?

>> If the new 'rtems_termios_device_handler' is adopted the PC BSP may
>> loose its tier 1 status. In the future we should avoid doing this and
>> a migration plan should address tier 1 BSPs first.
>
> I don't think i386 is tier 1 at the moment.
>

I do not think anything would be tier 1 at the moment. The PC and the 
i386 (and at some point x86_64) needs to be to tier 1.

I recently went over the tier structuring with Amar and we are closing 
in on something workable but are stuck on the naming. We have a 
designated tier or the tier we expect a BSP or arch to be at and 
buildbot will generate the actual tier, which I called rank and Amar 
does not like it (which I understand). The detail is related to the 
process to raise and lower a BSP and therefore an architecture's 
designated tier. The end objective is to provide clarity to users.

>>
>> The copied driver change is unfortunate and highlights a concern I
>> have. A change like this may allow a technically better solution to be
>> delivered however it does not account for the time and effort others
>> need to spend to migrate other BSPs.
>
> I really tried to migrate all BSPs (I spent sever days of work into this
> topic), but I didn''t have infinite time for it. At some point I had to
> stop working on this and decided to keep the exiting interface. So,
> existing BSPs work as before and there is no immediate need for a
> migration.

Thanks and your efforts are appreciated.

>> Once a change like this is accepted into the project the project
>> becomes responsible for updating any dependent BSPs. History shows
>> this does not happen and that is understandable, the RTEMS Project has
>> no direct funding to do this work and expecting this to be done
>> unfunded is not reasonable. Asking for a migration plan is a way the
>> project can understand what else is required and how what will be done.
>
> Yes, I missed to provide a migration plan. Sorry for that.

That is fine. The need for migration plans is emerging and not something 
we had clearly understand a few years ago. The need to plan changes will 
become important as we move to buildbot. It will show what we break and 
what we need to fix. With out a plan it becomes difficult to manage the 
designated tier positions.

Chris