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

[Christian Mauderer]

On 19/07/2019 18:21, Gedare Bloom wrote:
> Looks good to me. I'm currently not able to apply it, verify the doc
> build, and push it though. (Workstation issues.)
> 

I agree that it looks OK. Thanks from me too for contributing to the
documentation. It's something that most developers don't like to do
therefore it's really great that you wrote that.

I didn't find any bugs in the instructions while reading through it. I
can create a PDF out of it on my Arch Linux machine so I think it should
be OK to merge it.

You have tried quite a bit till you get an overlay working. If you feel
like writing some more documentation, it might would be a good addition
to add some notes regarding that too. I think this patch is fine as it
is so if you add something please create a second patch.

@Gedare: I don't touch the docs repo that often: Is there some defined
test process before a commit is added? Or is building a PDF on some
random machine enough?

Best regards

Christian

> 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
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>