Proposal: Add BSP documentation to BSP build specification

[Gedare Bloom]

Hi Sebastian,

What is the advantage of doing this?

I don't immediately see the rationale.

Gedare


On Wed, Nov 11, 2020 at 2:25 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> 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/
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel