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

Wed Aug 4 10:18:50 UTC 2021

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

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/