[PATCH] user/bsps : Add documentation for Beagle

[Vijay Kumar Banerjee]

On Thu, Jul 18, 2019 at 9:07 PM Gedare Bloom <gedare at rtems.org> wrote:

> On Thu, Jul 18, 2019 at 8:24 AM Vijay Kumar Banerjee
> <vijaykumar9597 at gmail.com> wrote:
> >
> > ---
> >  user/bsps/arm/beagle.rst | 91 +++++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 89 insertions(+), 2 deletions(-)
> >
> > diff --git a/user/bsps/arm/beagle.rst b/user/bsps/arm/beagle.rst
> > index a36efde..84bfe2d 100644
> > --- a/user/bsps/arm/beagle.rst
> > +++ b/user/bsps/arm/beagle.rst
> > @@ -1,8 +1,95 @@
> >  .. 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`
>
> Hi,


> We need a style guide for writing docs. I will send in separate email
> though I wondered if we should set a maximum line length/line breaks
> at 80 char as with code?
>
> Thanks for the review. I have fixed the issues you mentioned below and also
set the line length to 80 characters. I rewrote those areas to make it more
clear
to the reader. Here's the v2 of the patch :
https://lists.rtems.org/pipermail/devel/2019-July/026712.html

> > +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.
> There is always a comma after e.g.
>
> > +
> > +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
> We (American, British) normally put a space before parentheticals such
> as defining an acronym, like "Blob (dtb)".
>
> > +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 dts file is:
> dts should be mentioned before this
>
> > +
> https://github.com/freebsd/freebsd/blob/19a6ceb89dbacf74697d493e48c388767126d418/sys/gnu/dts/arm/am335x-boneblack.dts
> > +
> > +.. code-block:: none
> > +
> > +     #building the dtb
> > +     #We will use the script from
> https://github.com/freebsd/freebsd/blob/19a6ceb89dbacf74697d493e48c388767126d418/sys/tools/fdt/make_dtb.sh
> > +
> > +     export MACHINE='arm' #The make_dtb.sh script uses environment
> variable MACHINE
> > +     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
> > +starting up.
> "during starting" is awkward, try "during start up" or "while starting 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
> > +----------
> > +
> > +This BSP uses the I2C framework and is registered using
> > +``am335x_i2c_bus_register()`` 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
> > +   );
> > +
> > +This function is needed only while registering with custom path with
> custom
> This "registering with custom path" is awkward, maybe it needs
> "registering with a custom path"
>
> > +values. 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`.
> > +
> > +SPI Driver
> > +----------
> > +
> > +The SPI device `/dev/spi-0` can be registered with
> ``bbb_register_spi_0()```
> > --
> Thanks for contributing documentation!
>
> > 2.20.1
> >
> > _______________________________________________
> > devel mailing list
> > devel at rtems.org
> > http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190719/8c3ba02f/attachment-0002.html>