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

[Chris Johns]

On 21/7/19 6:09 pm, Christian Mauderer wrote:
> On 21/07/2019 04:46, Chris Johns wrote:
>> On 20/7/19 4:50 pm, Christian Mauderer wrote:
>>> On 19/07/2019 20:59, Vijay Kumar Banerjee wrote:
 On Fri, Jul 19, 2019 at 10:32 PM Christian Mauderer >>> > wrote:

 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.

 Always glad to contribute. :) 

 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.

 Sure, I can write about creating and overlay and applying it to the base
 tree.
 What would be the right place to write it? 
>>>
>>> Hard to say. You worked with the Beagle BSP so for now maybe adding an
>>> example + the command to apply an overlay there wouldn't be wrong.
>>
>> The rtems-boot-image has support for an FDT blob and I plan to add overlay
>> support when I get time.
> 
> Great.
> 
>>
>> We currently do not cover the FDT source and building blobs and we should if 
>> we
>> want to lower the entry level for someone wanting to pick up RTEMS and an
>> available piece of hardware like a BBB.
>>
>>> I don't think there is a special "device tree" chapter right now.
>>
>> I feel need something. It is part of RTEMS now and we should document how and
>> where it is used. When I returned to using the BBB I need to figure all this 
>> out
>> and it is not apparent or user friendly. For example initialising libbsd 
>> without
>> an FDT results in a crash.
>>
> 
> For BBB Vijays patch should be a big step forward. But I agree that a
> crash isn't user friendly.

Yes the doc patch is an excellent start. I will be updating this section once my
BBB libdebugger patch is posted and merged. It needs a hardware mod to work. I
was waiting for testing feedback.

>>> Maybe an alternative would be to put a "device tree and overlay" chapter
>>> into the README in libbsd. I think you as well as Niels are using
>>> overlays only with libbsd.
>>
>> I think the user manual is the best place. I think it could live in the
>> Executables section.
> 
> OK for me too.

Great.

 I have also wondered if it would be a good idea to keep the overlays in
 RTEMS
 or libBSD repo somewhere along with a script that builds a dtb from the
 freebsd-org
 tree and applies the overlay. 
>>>
>>> If you want you can create a script for libbsd to build the dtb.
>>
>> Scripts are OK for development work and personal projects however it creates 
>> a
>> legacy issue for the project. Scripts are often host and shell specific and
>> while they capture the logic they take a lot of work to useful and a general
>> solution.
>>
> 
> In this case it would be more of an example how to build the dtb.
> Therfore I suggested to add the commands to the README as an alternative
> further below.

Please do this. I was not meaning to say it is one or the other, it was more a
case of not overreaching and keeping in mind we need to look at and work towards
supported solutions. I am pushing hard to streamline our BSP support and using
the BBB as the lead example of what we can do and aim for. My recent BSP build
patches for the RSB are an example.

>>> Although cloning the freebsd-org submodule is optional, it can give a
>>> good hint how to build a target dtb. If you do that, please create it in
>>> a way that it's easy to tell which device tree should be build.
>>
>> I agree cloning FreeBSD as a sub-module is not something we would like to 
>> do. We
>> do need to try and capture this information somehow for a release.
> 
> Currently cloning FreeBSD is the only possibility to get the correct
> device tree files. When experimenting with some alternative sources
> (e.g. the Linux device tree export) I noted that most device trees work
> to a certain degree but sometimes there are problems. So the only
> version that works reliable with libbsd is the one in the matching
> FreeBSD commit.

This makes sense. It also means it is harder for a user to know they have a
suitable and working match for the libbsd we provide.

> If you want to have them archived in a release, maybe it would be
> necessary to import the device tree files into libbsd? But we should
> select which files to import. 

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

[Chris Johns]

On 20/7/19 4:50 pm, Christian Mauderer wrote:
> On 19/07/2019 20:59, Vijay Kumar Banerjee wrote:
>> On Fri, Jul 19, 2019 at 10:32 PM Christian Mauderer > > wrote:
>>
>> 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.
>>
>> Always glad to contribute. :) 
>>
>> 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.
>>
>> Sure, I can write about creating and overlay and applying it to the base
>> tree.
>> What would be the right place to write it? 
> 
> Hard to say. You worked with the Beagle BSP so for now maybe adding an
> example + the command to apply an overlay there wouldn't be wrong.

The rtems-boot-image has support for an FDT blob and I plan to add overlay
support when I get time.

We currently do not cover the FDT source and building blobs and we should if we
want to lower the entry level for someone wanting to pick up RTEMS and an
available piece of hardware like a BBB.

> I don't think there is a special "device tree" chapter right now.

I feel need something. It is part of RTEMS now and we should document how and
where it is used. When I returned to using the BBB I need to figure all this out
and it is not apparent or user friendly. For example initialising libbsd without
an FDT results in a crash.

> Maybe an alternative would be to put a "device tree and overlay" chapter
> into the README in libbsd. I think you as well as Niels are using
> overlays only with libbsd.

I think the user manual is the best place. I think it could live in the
Executables section.

>> I have also wondered if it would be a good idea to keep the overlays in
>> RTEMS
>> or libBSD repo somewhere along with a script that builds a dtb from the
>> freebsd-org
>> tree and applies the overlay. 
> 
> If you want you can create a script for libbsd to build the dtb.

Scripts are OK for development work and personal projects however it creates a
legacy issue for the project. Scripts are often host and shell specific and
while they capture the logic they take a lot of work to useful and a general
solution.

> Although cloning the freebsd-org submodule is optional, it can give a
> good hint how to build a target dtb. If you do that, please create it in
> a way that it's easy to tell which device tree should be build.

I agree cloning FreeBSD as a sub-module is not something we would like to do. We
do need to try and capture this information somehow for a release.

> An alternative could be to just put the hand full of commands in the
> README in libbsd.
> 
> Keeping overlays in libbsd or RTEMS is maybe not that optimal.

I agree.

> Overlays are quite target / application specific.

Are they application specific or specific to the target hardware and the support
RTEMS has for various parts of the hardware?

Does it matter if I have all the possible overlays loaded for the BBB and I do
not to use any of them? I think it is better to do this than attempting to use a
supported driver and finding I am missing the needed FDT support.

> So I'm a bit afraid of a big
> number of poorly maintained files. I would prefer to have only a small
> number of examples for overlays in the README. Other overlays are more
> target specific.

I am not sure I understand the first part and I agree overs are target specific.
For a publicly available piece of hardware like a BBB there must be a known set
of overlays that RTEMS supports? Custom hardware is not our concern.

The rtems-boot-image tool provides a command line interface to the complexity of
creating an SD image on different hosts. Adding overlay FDT support to this tool
can capture the low level u-boot complexity needed to support overlays.

What if I add support to the RSB to fetch and build the FDT blobs from source
for a specific board?

Chris
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

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

[Chris Johns]

On 20/7/19 3:02 pm, Gedare Bloom wrote:
> Good rules.

Thanks and thanks for raising this.

> If you get a chance please add them to the README for now.

I will.

> #1 should be for contributors, #3 is for Maintainers. #2 is optional.
> :)

Nice, I will include this.

Chris
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

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

[Christian Mauderer]

On 19/07/2019 20:59, Vijay Kumar Banerjee wrote:
> 
> 
> On Fri, Jul 19, 2019 at 10:32 PM Christian Mauderer  > wrote:
> 
> 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.
> 
> Always glad to contribute. :) 
> 
> 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.
> 
> Sure, I can write about creating and overlay and applying it to the base
> tree.
> What would be the right place to write it? 

Hard to say. You worked with the Beagle BSP so for now maybe adding an
example + the command to apply an overlay there wouldn't be wrong. I
don't think there is a special "device tree" chapter right now.

Maybe an alternative would be to put a "device tree and overlay" chapter
into the README in libbsd. I think you as well as Niels are using
overlays only with libbsd.

> I have also wondered if it would be a good idea to keep the overlays in
> RTEMS
> or libBSD repo somewhere along with a script that builds a dtb from the
> freebsd-org
> tree and applies the overlay. 

If you want you can create a script for libbsd to build the dtb.
Although cloning the freebsd-org submodule is optional, it can give a
good hint how to build a target dtb. If you do that, please create it in
a way that it's easy to tell which device tree should be build.

An alternative could be to just put the hand full of commands in the
README in libbsd.

Keeping overlays in libbsd or RTEMS is maybe not that optimal. Overlays
are quite target / application specific. So I'm a bit afraid of a big
number of poorly maintained files. I would prefer to have only a small
number of examples for overlays in the README. Other overlays are more
target specific.

> 
> @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
> > mailto:vijaykumar9...@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 0x8000 -e
> 0x8000 -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:
> >>
> 
> 

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

[Gedare Bloom]

On Fri, Jul 19, 2019 at 7:27 PM Chris Johns  wrote:
>
> On 20/7/19 6:41 am, Gedare Bloom wrote:
> > On Fri, Jul 19, 2019 at 11:02 AM Christian Mauderer  
> > wrote:
> >>
> >> 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.
>
> Pushed.
>
> >>
> >> 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?
> >>
> > I don't think the process is well-defined for the docs. However, if
> > you built the PDF and it looks good (can you build HTML too?) then go
> > ahead and push it.
>
> HTML is the default and always built. You need install to get a suitable
> directory tree to review with a `file://` URL. Details are here but 
> nothing
> is specifically said about HTML being always built:
>
> https://git.rtems.org/rtems-docs/tree/README.txt#n336
>
> The rules are not defined and maybe they should be.
>
> 1. HTML is always built and must build. Checking HTML is a requirement for
> posting a patch for review.
>
> 2. PDF is optional because the latex support is not consistent across all 
> build
> hosts.
>
> 3. Please check the automatically built docs after a push to make sure all
> formats look suitable. Post a follow up patch if adjustments are needed.
>
> Comments?
>
Good rules. If you get a chance please add them to the README for now.
#1 should be for contributors, #3 is for Maintainers. #2 is optional.
:)

> Chris
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

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

[Chris Johns]

On 20/7/19 6:41 am, Gedare Bloom wrote:
> On Fri, Jul 19, 2019 at 11:02 AM Christian Mauderer  
> wrote:
>>
>> 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.

Pushed.

>>
>> 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?
>>
> I don't think the process is well-defined for the docs. However, if
> you built the PDF and it looks good (can you build HTML too?) then go
> ahead and push it.

HTML is the default and always built. You need install to get a suitable
directory tree to review with a `file://` URL. Details are here but nothing
is specifically said about HTML being always built:

https://git.rtems.org/rtems-docs/tree/README.txt#n336

The rules are not defined and maybe they should be.

1. HTML is always built and must build. Checking HTML is a requirement for
posting a patch for review.

2. PDF is optional because the latex support is not consistent across all build
hosts.

3. Please check the automatically built docs after a push to make sure all
formats look suitable. Post a follow up patch if adjustments are needed.

Comments?

Chris
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

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

[Gedare Bloom]

On Fri, Jul 19, 2019 at 11:02 AM Christian Mauderer  wrote:
>
> 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?
>
I don't think the process is well-defined for the docs. However, if
you built the PDF and it looks good (can you build HTML too?) then go
ahead and push it.

> Best regards
>
> Christian
>
> > On Fri, Jul 19, 2019 at 2:07 AM Vijay Kumar Banerjee
> >  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 0x8000 -e 0x8000 -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 0x8080 rtems-app.img ; fatload mmc 0 
> >> 0x8800 am335x-boneblack.dtb ; bootm 0x8080 - 0x8800
> >> +
> >> +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
> >> 

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

[Vijay Kumar Banerjee]

On Fri, Jul 19, 2019 at 10:32 PM Christian Mauderer 
wrote:

> 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.
>
> Always glad to contribute. :)

> 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.
>
> Sure, I can write about creating and overlay and applying it to the base
tree.
What would be the right place to write it?
I have also wondered if it would be a good idea to keep the overlays in
RTEMS
or libBSD repo somewhere along with a script that builds a dtb from the
freebsd-org
tree and applies the overlay.

> @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
> >  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 0x8000 -e 0x8000 -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 0x8080 rtems-app.img ; fatload mmc 0
> 0x8800 am335x-boneblack.dtb ; bootm 0x8080 - 0x8800
> >> +
> >> +I2C Driver
> >> +--
> >> +
> >> +For registering the `/dev/i2c-0` device, a wrapper function is
> provided,
> >> +``bbb_register_i2c_0()`` similarly ``bbb_register_i2c_1()`` and
> >> 

Re: [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
>  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 0x8000 -e 0x8000 -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 0x8080 rtems-app.img ; fatload mmc 0 0x8800 
>> am335x-boneblack.dtb ; bootm 0x8080 - 0x8800
>> +
>> +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_tinput_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 

Re: [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
 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 0x8000 -e 0x8000 -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 0x8080 rtems-app.img ; fatload mmc 0 0x8800 
> am335x-boneblack.dtb ; bootm 0x8080 - 0x8800
> +
> +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_tinput_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@rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

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

[Vijay Kumar Banerjee]

---
 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 0x8000 -e 0x8000 -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 0x8080 rtems-app.img ; fatload mmc 0 0x8800 
am335x-boneblack.dtb ; bootm 0x8080 - 0x8800
+
+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_tinput_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@rtems.org
http://lists.rtems.org/mailman/listinfo/devel