some reformatting, reordering, syntax fixes and minor additions

Signed-off-by: Jan Klare <jan.klare@bisdn.de>

baseline-network-linux-hld.md

@@ -15,22 +15,23 @@ This proposal aims to reduce the fragmentation by providing a common base for
 networking hardware support, without addressing the question of how to abstract
 and control the switch forwarding plane itself.
 
+Support for open networking hardware platforms is currently distributed over
+various different projects. Many platforms, especially older ones, are supported
+by OpenNetworkLinux, many are supported by SONiC, and some are supported by
+DentOS, which is based on OpenNetworkLinux, but targets different devices. The
+open hardware support is usually very tightly integrated in the build systems,
+which makes sharing and reusing the support hard.
+
 The intention of this project is not to replace or compete with any of the
 existing network operating systems, but rather to provide a common and
 extensible layer on which they can be built. Its principles and paradigms are
 largely aligned with and adapted from the
-[OCP OpenNetworkLinux Project](https://github.com/opencomputeproject/OpenNetworkLinux) (which has been moved to maintenance mode, pending archival).
+[OCP OpenNetworkLinux Project](https://github.com/opencomputeproject/OpenNetworkLinux)
+(which has been moved to maintenance mode, pending archival).
 This proposal specifically seeks an agreement between the developers and
 maintainers of the aforementioned network operating system communities, to be
 able to share common implementations to support open networking hardware.
 
-Support for open networking hardware platforms is currently distributed over
-various different projects. Many platforms, especially older ones, are supported
-by OpenNetworkLinux, many are supported by SONiC, and some are supported by
-DentOS, which is based on OpenNetworkLinux, but targets different devices. The
-open hardware support is usually very tightly integrated in the build systems,
-which makes sharing and reusing the support hard.
-
 ## Requirements and Dependencies
 
 ## Design
@@ -41,9 +42,11 @@ and base OS agnostic packages at the bottom](images/layering-example.png "layeri
 ### OS agnostic hardware platform support
 
 To allow sharing the platform support between different operating systems, the
-support is contained in an independent repository. It should allow easy building
-and installation outside of OS distribution build systems, and allow building
-and development on-device.
+sources should be managed in an independent repository. This should allow easy
+building and installation outside of OS distribution build systems, and allow
+building and development on-device. Each OS specific build system should also be
+able to consume and utilise the shared platform support sources from this
+independently managed repository.
 
 Any packaging decisions like if or and how to split up individual platform
 support should be up to the OS distribution packaging it.
@@ -82,14 +85,14 @@ Possible APIs are:
 The base networking hardware support is organized in multiple repositories:
 
 - kernel: Linux fork with required base changes (backports of important
-submissions, etc)
+  submissions, etc)
 - hardware-platform-support: drivers, libraries and userspace code for
   initializing hardware platforms (do we need more?)
 - TBD: organization of platform support
 - TBD: platform initialization
 
-In the first iteration, the platform support is fine in it the state as it is
-in their source repository.
+For the first iteration, the platform support code can be left as is
+in their current source repositories.
 
 Future iterations should focus on improving the platform drivers and support
 code to follow modern code style and compile with as few warnings as possible,
@@ -107,7 +110,7 @@ flexibility in how other projects using the layer can customize the kernel.
 TBD: should we have patches or branches with backport commits? Maybe both?
 
 - patches make required changes due to upstream changes more obvious (provide a
-“conflict diff”) and easier to review
+  “conflict diff”) and easier to review
 - branches are closer to the upstream approach, but may be harder to track
   changes needed due to upstream changes
 
@@ -121,39 +124,31 @@ be split into multiple subpackages:
 
 ### ASIC/dataplane support
 
-ASIC/dataplane support is out of scope for now, but may be provided by a future
-project or extension.
+ASIC/dataplane support is out of scope for this proposal and is intentionally
+left as possible extensions to be implemented by NOS providers (e.g. SONiC or
+DENT) on top of the BSP Layer targeted here.
 
-The only exception are switchdev-enabled platforms like Mellanox or Marvell
-Prestera, where the ASIC support is already provided by the upstream Linux kernel.
+One exception are switchdev-enabled platforms like Mellanox or Marvell Prestera,
+where the ASIC support is already provided by the upstream Linux kernel.
 
 ### Targeted Kernel and Yocto versions
 
 Target Yocto version is scarthgarp, which is the next LTS release, planned for
 April 2024.
 
-The initial Kernel version target could be 5.15 (minimum kernel version of Yocto)
-or 6.6 (the latest LTS version of the Linux kernel). The kernel patch version will
-be a moving target, and regularly updated (ideally weekly).
+The initial Kernel version target could be 5.15 (minimum kernel version of
+Yocto) or 6.6 (the latest LTS version of the Linux kernel). The kernel patch
+version will be a moving target, and regularly updated (ideally weekly).
 
 Since there will be many out-of-tree drivers for the platform support, required
-API updates should be done via [coccinelle semantic patches](https://coccinelle.gitlabpages.inria.fr/website/). This should ensure that the
-amount of work needed for keeping drivers building and working with newer
-kernels stays manageable.
+API updates should be done via
+[coccinelle semantic patches](https://coccinelle.gitlabpages.inria.fr/website/).
+This should ensure that the amount of work needed for keeping drivers building
+and working with newer kernels stays manageable.
 
 The semantic patches will also help vendors quickly updating their drivers when
 submitting new platforms based on older releases.
 
-### DentOS as a layer extending the base platform support layer
-
-The base platform support will be already provided by the base platform layer
-(i.e. custom hardware drivers, platform initialization, etc).
-
-Since DentOS uses a customized version of the prestera driver that contains
-several features not included in the upstream driver, the custom prestera
-driver will be provided as an external kernel module package, while the
-in-kernel driver will be disabled.
-
 ## Milestones
 
 - M1:
@@ -171,10 +166,12 @@ in-kernel driver will be disabled.
   - import missing platforms from ONL (convert them to PDDF?)
   - import missing platforms from DentOS (convert them to PDDF?)
   - kernel 6.6 support(?)
-  - coccinelle semantic patches for upgrading drivers to supprot linux 6.6 APIs
+  - coccinelle semantic patches for upgrading drivers to support Linux 6.6 APIs
   - ONLP adapter(?)
   - extensible ONIE NOS installer
-- M4: get accepted as [official yocto layer](https://www.yoctoproject.org/development/yocto-project-compatible-layers/)
+- M4:
+  - get accepted as
+    [official yocto layer](https://www.yoctoproject.org/development/yocto-project-compatible-layers/)
   - are we fine with LTS kernels, or do we need to support non-LTS ones?
   - figure out long-term maintenance strategy
 
@@ -198,6 +195,16 @@ To allow verifying that various drivers and libraries work, it would be good
 to have some frameworks or testing utilities for OEMs to ensure that everything
 works from the API side.
 
+### DentOS as a layer extending the base platform support layer
+
+The base platform support will be already provided by the base platform layer
+(i.e. custom hardware drivers, platform initialization, etc).
+
+Since DentOS uses a customized version of the Prestera driver that contains
+several features not included in the upstream driver, the custom Prestera
+driver will be provided as an external kernel module package, while the
+in-kernel driver will be disabled.
+
 ### Improved driver/platform architecture
 
 Currently the need for platform initialization code in user space is due to
@@ -212,14 +219,15 @@ layout fully. Any configuration values set by the platform init script should be
 configurable via appropriate node attributes.
 
 For ACPI platforms, devices should be described in their appropriate tables like
-described in [The Linux kernel firwmware guide](https://docs.kernel.org/firmware-guide/acpi/enumeration.html).
+described in
+[The Linux kernel firwmware guide](https://docs.kernel.org/firmware-guide/acpi/enumeration.html).
 
 A similar approach to the device tree properties can even be done using
 [\_DSD Device Properties](https://docs.kernel.org/firmware-guide/acpi/DSD-properties-rules.html).
 
 These ACPI platform device descriptions do not necessarily need to live in the
-BIOS itself, and may be loaded from userspace as Linux [support upgrading ACPI
-tables on boot](https://docs.kernel.org/admin-guide/acpi/initrd_table_override.html).
+BIOS itself, and may be loaded from userspace as Linux
+[support upgrading ACPI tables on boot](https://docs.kernel.org/admin-guide/acpi/initrd_table_override.html).
 
 Describing all devices and their layout in the firmware (device tree or ACPI)
 will simplify the platform initialization by userspace, and avoid any ambiguity