[PATCH rtems-libbsd] CONTRIBUTING: Sharpen priority development goals
christian.mauderer at embedded-brains.de
Fri Feb 3 07:31:46 UTC 2023
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:
CONTRIBUTING.rst | 39 ++++++++++++++++++++++++++++++---------
1 file changed, 30 insertions(+), 9 deletions(-)
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 0b6fc7a0..31561f6a 100644
@@ -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
+#. 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.
+#. 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.
+#. 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.
What is in the Git Repository
More information about the devel