[PATCH v2] user/bsps : Add documentation for Beagle

[Gedare Bloom]

Looks good to me. I'm currently not able to apply it, verify the doc
build, and push it though. (Workstation issues.)

On Fri, Jul 19, 2019 at 2:07 AM Vijay Kumar Banerjee
<vijaykumar9597 at gmail.com> wrote:
>
> ---
>  user/bsps/arm/beagle.rst | 110 ++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 108 insertions(+), 2 deletions(-)
>
> diff --git a/user/bsps/arm/beagle.rst b/user/bsps/arm/beagle.rst
> index a36efde..eb4ecfb 100644
> --- a/user/bsps/arm/beagle.rst
> +++ b/user/bsps/arm/beagle.rst
> @@ -1,8 +1,114 @@
>  .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> -.. Copyright (C) 2019 TBD
> +.. Copyright (C) 2019 Vijay Kumar Banerjee
>
>  beagle
>  ======
>
> -TODO.
> +This BSP supports four variants, `beagleboardorig`, `beagleboardxm`,
> +`beaglebonewhite` and `beagleboneblack`. 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.
> +
> +TODO(These drivers are present but not documented yet):
> +
> + *  Clock driver.
> + *  Network Interface Driver.
> + *  SDcard driver.
> + *  GPIO Driver.
> + *  Console driver.
> + *  PWM Driver.
> + *  RTC driver.
> +
> +Boot via U-Boot
> +---------------
> +To boot via uboot, the ELF must be converted to a U-Boot image like below:
> +
> +.. code-block:: none
> +
> +    arm-rtems5-objcopy hello.exe -O app.bin
> +    gzip 9 app.bin
> +    mkimage -A arm -O linux -T kernel -a 0x80000000 -e 0x80000000 -n RTEMS -d app.bin.gz rtems-app.img
> +
> +Getting the Device Tree Blob
> +----------------------------
> +
> +The Device Tree Blob (DTB) is needed to load the device tree while starting up
> +the kernel. We build the dtb from the FreeBSD source matching the commit hash
> +from the libbsd HEAD of freebsd-org. For example if the HEAD is at
> +"19a6ceb89dbacf74697d493e48c388767126d418"
> +Then the right Device Tree Source (DTS) file is:
> +https://github.com/freebsd/freebsd/blob/19a6ceb89dbacf74697d493e48c388767126d418/sys/gnu/dts/arm/am335x-boneblack.dts
> +
> +.. code-block:: shell
> +   :linenos:
> +
> +     #building the dtb
> +     #We will use the script from https://github.com/freebsd/freebsd/blob/19a6ceb89dbacf74697d493e48c388767126d418/sys/tools/fdt/make_dtb.sh
> +
> +     #The make_dtb.sh script uses environment variable MACHINE
> +     export MACHINE='arm'
> +
> +     SCRIPT_DIR=$HOME/freebsd/sys/tools/fdt
> +
> +     #The arguments to the script are
> +     # $1 -> Build Tree
> +     # $2 -> DTS source file
> +     # $3 -> output path of the DTB file
> +
> +     ${SCRIPT_DIR}/make_dtb.sh ${SCRIPT_DIR}/../../ \
> +     ${SCRIPT_DIR}/../../gnu/dts/arm/am335x-boneblack.dts \
> +     $(pwd)
> +
> +Writing the uEnv.txt file
> +-------------------------
> +
> +The uEnv.txt file is needed to set any environment variable before the kernel is
> +loaded. Each line is a u-boot command that the uboot will execute during start
> +up.
> +
> +Add the following to a file named uEnv.txt:
> +
> +.. code-block:: none
> +
> +     setenv bootdelay 5
> +     uenvcmd=run boot
> +     boot=fatload mmc 0 0x80800000 rtems-app.img ; fatload mmc 0 0x88000000 am335x-boneblack.dtb ; bootm 0x80800000 - 0x88000000
> +
> +I2C Driver
> +----------
> +
> +For registering the `/dev/i2c-0` device, a wrapper function is provided,
> +``bbb_register_i2c_0()`` similarly ``bbb_register_i2c_1()`` and
> +``bbb_register_i2c_2()`` are respectively used to register `i2c-1` and `i2c-2`.
> +
> +For registering an I2C device with a custom path (say `/dev/i2c-3`) the
> +function ``am335x_i2c_bus_register()`` has to be used.
> +
> +The function prototype is given below:
> +
> +.. code-block:: C
> +
> +   int am335x_i2c_bus_register(
> +   const char         *bus_path,
> +   uintptr_t           register_base,
> +   uint32_t            input_clock,
> +   rtems_vector_number irq
> +   );
> +
> +SPI Driver
> +----------
> +
> +The SPI device `/dev/spi-0` can be registered with ``bbb_register_spi_0()``
> +
> +For registering with a custom path, the ``bsp_register_spi()`` can be used.
> +
> +The function prototype is given below:
> +
> +.. code-block:: C
> +
> +    rtems_status_code bsp_register_spi(
> +       const char         *bus_path,
> +       uintptr_t           register_base,
> +       rtems_vector_number irq
> +    );
> --
> 2.20.1
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel