[PATCH rtems-libbsd 0/5] RTEMS LibBSD Documentation

Wed Aug 4 16:22:23 UTC 2021

On 04/08/2021 18:09, Gedare Bloom wrote:
> On Wed, Aug 4, 2021 at 9:05 AM Christian MAUDERER
> <christian.mauderer at embedded-brains.de> wrote:
>>
>> Hello Gedare,
>>
>> Am 04.08.21 um 16:55 schrieb Gedare Bloom:
>>> On Wed, Aug 4, 2021 at 4:18 AM Christian MAUDERER
>>> <christian.mauderer at embedded-brains.de> wrote:
>>>>
>>>> Hello Chris,
>>>>
>>>> Am 04.08.21 um 11:17 schrieb Chris Johns:
>>>>>
>>>>>
>>>>> On 4/8/21 6:34 pm, Christian MAUDERER wrote:
>>>>>> Hello Chris,
>>>>>>
>>>>>> Am 04.08.21 um 09:28 schrieb Chris Johns:
>>>>>>> On 3/8/21 5:00 pm, Christian MAUDERER wrote:
>>>>>>>> Hello,
>>>>>>>>
>>>>>>>> Am 03.08.21 um 04:07 schrieb Chris Johns:
>>>>>>>>> On 3/8/21 3:24 am, Sebastian Huber wrote:
>>>>>>>>>> On 02/08/2021 18:37, Vijay Kumar Banerjee wrote:
>>>>>>>>>>> I think there should be a high-level user manual subsection for
>>>>>>>>>>> networking that describes how the selection of the network stack
>>>>>>>>>>> works. We can then add another subsection about lwip since legacy
>>>>>>>>>>> already has one, and libbsd is getting added now.
>>>>>>>>>>
>>>>>>>>>> This sounds like a good approach.
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>> I agree.
>>>>>>>>>
>>>>>>>>> Chris
>>>>>>>>
>>>>>>>> Just so that we are all on the same page:
>>>>>>>>
>>>>>>>> That would be a number of new subsections in
>>>>>>>> https://docs.rtems.org/branches/master/user/index.html:
>>>>>>>>
>>>>>>>> - 15. Selecting a Network Stack
>>>>>>>> - 16. Add-on: libbsd Stack
>>>>>>>> - 17. Add-on: lwIP
>>>>>>>> - 18. Add-on: Legacy Network Stack
>>>>>>>>
>>>>>>>> Or was it meant to be only a section
>>>>>>>
>>>>>>> I think a single section so all things networking are grouped.
>>>>>>
>>>>>> That will result in either a deep nesting for the chapters or in very hard to
>>>>>> organize information because two levels are used up already.
>>>>>>
>>>>>> For example the current legacy network manual has a
>>>>>>
>>>>>>      5.3.1. Additional include files
>>>>>>
>>>>>> If we make one "networking" group, that would be
>>>>>>
>>>>>>      15. Networking
>>>>>>      15.3 Legacy Network Stack
>>>>>>      15.3.5 Using Networking in an RTEMS application
>>>>>>      15.3.5.3 Initialization
>>>>>>      15.3.5.3.1 Additional include files
>>>>>>
>>>>>> And please also note: I think we should see libbsd more as an Add-on package and
>>>>>> less as a pure network stack.
>>>>>
>>>>> Yes this is true and if your top level is LibBSD you do not see networking and
>>>>> then networking becomes confusing if spread out in pieces. What would LibBSD and
>>>>> Legacy Networking mean if you are new RTEMS? Is Legacy networking some form of
>>>>> old embedded realtime protocol we support? :)
>>>>>
>>>>> Maybe Networking is about the history, features and options available in each
>>>>> package (Selection) and the LibBSD part is a link to the networking section of
>>>>> that package? This would mean the lwIP and Legacy network stack is still under
>>>>> Networking.
>>>>
>>>> Hm. You are right that we have to somehow make it clear what features
>>>> can be provided by the libraries.
>>>>
>>>>>
>>>>> Does "Additional includes" etc need to be a numbered section? Why not just make
>>>>> a heading in the block without it being a section?
>>>>
>>>> It was more or less an example that I just took from the current legacy
>>>> networking manual. I think that manual should be about at the same
>>>> location and I don't think that anyone wants to do a detailed re-write.
>>>> So most likely we will just move the levels down.
>>>>
>>>>>
>>>>>> It provides a lot more than just networking. It
>>>>>> has USB, it can add HDMI (on beagle for example), it includes an OpenSSL
>>>>>> implementation, ...
>>>>>
>>>>> Yes and if you look at the top level you could see something like:
>>>>>
>>>>>     9 Networking
>>>>> 10 USB
>>>>> 11 Graphics
>>>>> 12 FreeBSD On RTEMS
>>> +1
>>>
>>>>>
>>>>> The user manual has clear top level sections and I would like it to stay this
>>>>> way. But yes I understand it is hard to get the breakdown right and it may take
>>>>> a couple more loops until we have something that is clear.
>>>>
>>>> Hm. That would mean that we split up the libbsd documentation to
>>>> multiple sections (at least networking and USB). Where can we put common
>>>> parts like "how to init libbsd"?
>>>>
>>>> We also have multiple options in every section. For example OpenSSL can
>>>> be provided by libbsd or by OpenSSL / LibreSSL / *SSL. Could be
>>>> difficult for a user to find out how and which libs he can combine to
>>>> get what he wants. For example some user could start with lwIP for
>>>> networking and then later wants to add USB and SD/MMC and notes that in
>>>> that case it would have been a better choice to use libbsd for
>>>> networking in that case too.
>>>>
>>>> We could add a chapter "Selecting Add-Ons" or "Selecting Libraries" with
>>>> a short description of the libs and when they are alternatives or when
>>>
>>> I'd like this as well. A library of libraries :) [technically, an
>>> index of libraries]
>>>
>>>> they complement each other. Then we can either add the manual of the
>>>> libs or Add-Ons as subsections (disadvantage: deep nesting) or we can
>>>> add them with some common prefix so that a user knows that he maybe
>>>> should first look into the "Selecting <Prefix>".
>>> +1
>>>
>>>>
>>>
>>> My preference would be to leave the legacy doc where it is,
>>
>> Just a comment for that point: I know that the doc has been moved around
>> a bit. But I think we should try to get all similar options onto the
>> same "level". Otherwise if a user searches for "How to do networking
>> with RTEMS" and he finds https://docs.rtems.org/ the only manual with
>> "Networking" is the legacy stack. If it is on the same page (level,
>> hirarchie, ...) like the headline "libbsd Networking and other cool
>> stuff" or "lwIP", a user instantly can see that there is more than one
>> option.
>>
> 
> That's a good point, but I want to keep the legacy stack separate from
> the rest of the documentation to make it simpler to deprecate/obsolete
> it. I don't see value in moving it, just to kill it in the next
> release. AFAIK, we will strongly discourage anyone from using it in
> rtems-6, and I'd like to kill it off moving forward once we feel
> confident that lwIP is feasible for us to maintain. Your point about
> marketing is well-taken though.

OK. I didn't expect that we are that far that we already plan to (maybe) 
remove it in the next release. In that case I agree: It's not worth the 
effort to move it.

> 
>> Of course, I'm open for discussion regarding that point.
>>
>> Best regards
>>
>> Christian
>>
>>> and add a
>>> new libbsd section in the user manual, and cross-reference to it from
>>> other sections with clear high-level names (like Networking, USB,
>>> etc.) That is much the same way as we treated the RSB documentation.
>>> We need to refer to the libbsd too much for it to be in a separate
>>> manual, since cross-doc linking doesn't work, but we also should try
>>> not to split up the libbsd content and spread it around too much. I
>>> think that might be what Chris meant by his listing, with 12. FreeBSD
>>> on RTEMS.
>>>
>>> I'm open to suggestions though.
>>>
>>> Gedare
>>>
>>>> Best regards
>>>>
>>>> Christian
>>>>
>>>>>
>>>>> Chris
>>>>>
>>>>
>>>> --
>>>> --------------------------------------------
>>>> embedded brains GmbH
>>>> Herr Christian MAUDERER
>>>> Dornierstr. 4
>>>> 82178 Puchheim
>>>> Germany
>>>> email: christian.mauderer at embedded-brains.de
>>>> phone: +49-89-18 94 741 - 18
>>>> 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/
>>
>> --
>> --------------------------------------------
>> embedded brains GmbH
>> Herr Christian MAUDERER
>> Dornierstr. 4
>> 82178 Puchheim
>> Germany
>> email: christian.mauderer at embedded-brains.de
>> phone: +49-89-18 94 741 - 18
>> 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/
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
> 