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

Wed Aug 4 15:05:12 UTC 2021

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.

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/