[PATCH rtems-libbsd] CONTRIBUTING: Sharpen priority development goals

[Chris Johns]

On 3/2/2023 6:31 pm, Christian Mauderer wrote:
> This patch tries to make the most important goals of LibBSD development
> more clear based on the results of the discussion on the mailing list:
> 
> https://lists.rtems.org/pipermail/devel/2023-January/074164.html
> ---
>  CONTRIBUTING.rst | 39 ++++++++++++++++++++++++++++++---------
>  1 file changed, 30 insertions(+), 9 deletions(-)
> 
> diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
> index 0b6fc7a0..31561f6a 100644
> --- a/CONTRIBUTING.rst
> +++ b/CONTRIBUTING.rst
> @@ -21,15 +21,36 @@ RTEMS specific support files, general guidelines on what modifications to the
>  FreeBSD source are permitted, and some other topics.  For building the library,
>  see the `README <README.rst>`_.
>  
> -Goals of the LibBSD activity are
> -
> -* provide functionality from FreeBSD to RTEMS,
> -* ease updating to future FreeBSD versions,
> -* ease tracking changes in FreeBSD code,
> -* minimize manual changes in FreeBSD code.
> -
> -We will work to push our changes upstream to the FreeBSD Project and minimize
> -changes required at each update point.
> +Every change to LibBSD has to consider the following points in groups of
> +descending priority:
> +
> +#. Real-time Impacts + Maintainability Loss
> +   * LibBSD itself doesn't make any real time claims because it is basically
> +     FreeBSD and they don't make any real time claims either.  But all
> +     development in LibBSD must make sure that the real time ability of the
> +     RTEMS core system or the application is not affected.
> +   * It's utterly important that LibBSD is simple to maintain.  One of the most
> +     important points for that is that upgrades to newer FreeBSD versions have
> +     to be easy.

Correct and it is important we adopt and use what FreeBSD provides rather than
adding extra complexity. I wrote about this in the FreeBSD journal years ago.
The bespoke handing of fd and file objects is something I consider an unneeded
complexity for specific system related reasons. We need NFSv4 and that uses VFS
and that in turn uses the FreeBSD fd and file objects.

Source transparency is what matters and as a test of what is acceptable it must
be preferred between competing implementations.

> +#. Transparency Loss + Modularity Loss + Code/RAM Size Increase
> +   * LibBSD code should be easy to read and easy to debug.  Changes should be
> +     integrated in a way that are easy to understand.  Of course that's a
> +     subjective goal.  As a general rule: If it adds lot's of extra code or even
> +     more layers than already exist in FreeBSD, it's harder to understand.
> +   * There are a number of methods used in LibBSD to make it modular.  If you
> +     add new functionality, use one of the existing methods to allow enabling or
> +     disabling your module.  For example make sure that the linker can remove
> +     unused modules.  If that doesn't work for your feature, try to use the
> +     buildsets to allow to switch a module on or off.
> +   * A lot of different hardware uses LibBSD as network or USB stack or maybe in
> +     the future even only for other subsystems.  Some of the targets have
> +     hundreds of megabytes memory.  Others can only have a few megabytes (like
> +     the ATSAMV71).  Make sure that changes don't increase the RAM / Flash size
> +     of the default build so that it can't be used on the small targets.

This is not realistic or achievable and I find confusing the reasons it is being
pushed over and over. I would have not have agreed to this being added before
now and nothing has changed. The central reason for rejecting this statement is
a change in FreeBSD may add a few meg of memory to the footprint and this type
of statement would conflict with that addition and that in turn would conflict
with the need for transparency of source. And as stated before transparency must
be preferred.

System requirements are for the developers of those systems and not RTEMS.
Derating designs is an important part of system design and not the domain of
this project. Memory constrained systems can consider another networking stack
option or bespoke changes internally maintained. That is a cost trade off no one
here can help make.

> +#. Performance Loss
> +   * There are applications, that require (for example) a high network
> +     throughput or a fast storage access.  Make sure to take that into account
> +     if adding changes.

I prefer we do not add statements that have no definition or boundaries someone
could use to test against. Selection of RTEMS in a systems is the choice of the
system designer. There are systems RTEMS is not a good fit for.

Chris