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

Wed Aug 4 14:55:36 UTC 2021

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, 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/