[PATCH v3] doc/raspberrypi: Added instructions for raspberrypi

[Christian Mauderer]

Hello Niteesh,

you had two different "v3" patches. Therefore I missed this one. I
thought there was still a review comment from Gedare pending (which he
added at the v2 patch but after the first v3 has been sent).

On 12/01/2020 19:47, G S Niteesh wrote:
> Added instructions to run examples on raspberrypi.
> ---
>  user/bsps/arm/raspberrypi.rst | 85 ++++++++++++++++++++++++++++++++++-
>  1 file changed, 84 insertions(+), 1 deletion(-)
> 
> diff --git a/user/bsps/arm/raspberrypi.rst b/user/bsps/arm/raspberrypi.rst
> index 4ef75bd..8e4b38c 100644
> --- a/user/bsps/arm/raspberrypi.rst
> +++ b/user/bsps/arm/raspberrypi.rst
> @@ -5,4 +5,87 @@
>  raspberrypi
>  ===========
>  
> -TODO.
> +This BSP supports `Raspberry Pi 1` and `Raspberry Pi 2` currently.
> +The support for `Raspberry Pi 3` is work under progress.
> +The default bootloader on the Raspberry Pi which is used to boot Raspbian
> +or other OS can be also used to boot RTEMS. U-boot can also be used.
> +
> +Setup SD card
> +----------------
> +
> +The Raspberry Pis have an unconventional booting mechanism. The GPU
> +boots first, initializes itself, runs the bootloader and starts the CPU.
> +The bootloader looks for a kernel image, by default the kernel images must
> +have a name of the form ``kernel*.img`` but this can be changed by adding
> +`kernel=<img_name>` to ``config.txt``.
> +
> +You must provide the required files for the GPU to proceed. These files
> +can be downloaded from
> +`the Raspberry Pi Firmware Repository <https://github.com/raspberrypi/firmware/tree/master/boot>`_.
> +You can remove the ``kernel*.img`` files if you want too, but don't touch the other files.

This line seems a bit long. Please break at 80 chars. The link above it
is OK to violate that rule because it would most likely not work with a
line break.

> +
> +Copy these files in to a SD card with FAT filesystem.
> +
> +Kernel image
> +------------
> +
> +The following steps show how to run ``hello.exe`` on a Raspberry Pi 2.
> +The same instructions can be applied to Raspberry Pi 1 also.
> +Other executables can be processed in a similar way.
> +
> +To create the kernel image:
> +
> +.. code-block:: none
> +
> +     arm-rtems5-objcopy -Obinary hello.exe kernel.img
> +
> +Copy the kernel image to the SD card.
> +
> +Make sure you have these lines below, in your ``config.txt``.
> +
> +.. code-block:: none
> +
> +     enable-uart=1
> +     kernel_address=0x200000
> +     kernel=kernel.img
> +
> +Testing using QEMU
> +------------------
> +
> +QEMU can be built using RSB. Navigate to ``<SOURCE_BUILDER_DIR>/rtems``
> +and run this command.
> +
> +.. code-block:: none
> +
> +     ../source-builder/sb-set-builder --prefix=<TOOLCHAIN_DIR> devel/qemu4.bset
> +
> +**Note**: Replace ``<SOURCE_BUILDER_DIR>`` and ``<TOOLCHAIN_DIR>`` with the correct
> +path of the directories. For example, if you used quick-start section as your reference, these
> +two will be ``$HOME/quick-start/src/rsb`` and ``$HOME/quick-start/rtems/5`` respectively,

Again: Please use a 80 char limit (except for the code block).

> +
> +QEMU along with GDB can be used for debugging, but it only supports
> +Raspberry Pi 2 and the emulation is also incomplete. So some of the
> +features might not work as expected.
> +
> +Make sure your version of QEMU > v2.6, because older ones don't support

"...of QEMU is newer than v2.6 ..."

For most readers it's much faster to read a text without cryptic
abbreviations.

> +Raspberry Pi's.

I have to be honest: I'm not sure here. As far as I know the apostroph
(') is a sign that you left something out. I'm not sure whether there
are cases in English where you use it other than that case. But I would
say that you didn't leave anything out in "Pi's" and therefore the
plural should be "Pis" even if it looks odd.

Some comment from a native speaker?

> +
> +.. code-block:: none
> +
> +     qemu-system-arm -M raspi2 -m 1G -kernel hello.exe -serial mon:stdio -nographic -S -s
> +
> +This starts QEMU and creates a socket at port ``localhost:1234`` for GDB to
> +connect.
> +
> +In a new terminal, run GDB using
> +
> +.. code-block:: none
> +
> +     arm-rtems5-gdb hello.exe
> +     tar remote:1234
> +     load
> +
> +This will connect GDB to QEMU and will load the application.
> +
> +**Note**: Add ``set scheduler-locking on`` in GDB if you have any issues
> +running the examples.
>