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

Wed Aug 4 16:09:54 UTC 2021

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.

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