Proposal: Add BSP documentation to BSP build specification

[Sebastian Huber]

Hello,

currently, we have a hand crafted chapter with the BSPs and some 
documentation in the User Manual:

https://docs.rtems.org/branches/master/user/bsps/index.html

I would like to generate this chapter using the BSP build specification 
items, for example:

https://git.rtems.org/rtems/tree/spec/build/bsps/sparc/erc32/bsperc32.yml

For this I would introduce a BSP family item which includes the name of 
the family and a description in Sphinx format with sections related to 
all BSPs of the family. For example:

documentation-introduction: |
   This BSP offers only one variant, the `altcycv_devkit`.  This variant 
supports
   the Intel Cyclone V system on chip.  The basic hardware 
initialization is not
   performed by the BSP.  A boot loader with device tree support must be 
used to
   start the BSP, e.g. U-Boot.

   The BSP is known to run on these boards:

   * `Cyclone V SoC Development Kit 
<https://www.intel.com/content/www/us/en/programmable/products/boards_and_kits/dev-kits/altera/kit-cyclone-v-soc.html>`_

   * `Enclustra Mars MA3 SoC Module 
<https://www.enclustra.com/en/products/system-on-chip-modules/mars-ma3/>`_

   * `Terasic DE10-Standard Development Kit 
<https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=165&No=1081>`_
documentation-sections:
- header: Boot via U-Boot
   section: |
     The application executable file (ELF file) must be converted to an 
U-Boot
     image.  Use the following commands:

     .. code-block:: none

         arm-rtems5-objcopy -O binary app.exe app.bin
         gzip -9 -f -c app.bin > app.bin.gz
         mkimage -A arm -O linux -T kernel -a 0x00300000 -e 0x00300000 
-n RTEMS -d app.bin.gz app.img

     Use the following U-Boot commands to boot an application via TFTP 
download:

     .. code-block:: none

         tftpboot ${loadaddr} app.img && run loadfdt && bootm 
${loadaddr} - ${fdt_addr} ; reset

     The ``loadfdt`` command may be not defined in your U-Boot 
environment.  Just
     replace it with the appropriate commands to load the device tree at
     ``${fdt_addr}``.
- header: Clock Driver
   section: |
     The clock driver uses the `Cortex-A9 MPCore Global Timer`.

The BSP items would link to the family item using the new role 
"build-family". This replaces the "family" attribute of the BSP items. 
The BSP items would get a "description" attribute with an optional 
documentation section for this variant.

-- 
embedded brains GmbH
Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
Phone: +49-89-18 94 741 - 16
Fax:   +49-89-18 94 741 - 08
PGP: Public key available on request.

embedded brains GmbH
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/