[PATCH rtems-docs v2] raspberrypi4.rst: Added Documentation for the new AArch64 Raspberry pi 4B BSP

Wed Oct 5 22:44:02 UTC 2022

Thanks for the documentation. It is great to have this.

My comments are below.

On 5/10/2022 4:41 pm, Mohd Noor Aman wrote:
> This patch adds the relevant documentations required for booting the new BSP.
> JTAG support is added for debugging. I have built the HTML docs and verified
> them.
> ---
>  user/bsps/aarch64/raspberrypi4.rst | 99 ++++++++++++++++++++++++++++++
>  user/bsps/bsps-aarch64.rst         |  1 +
>  2 files changed, 100 insertions(+)
>  create mode 100644 user/bsps/aarch64/raspberrypi4.rst
> 
> diff --git a/user/bsps/aarch64/raspberrypi4.rst b/user/bsps/aarch64/raspberrypi4.rst
> new file mode 100644
> index 0000000..5a45c65
> --- /dev/null
> +++ b/user/bsps/aarch64/raspberrypi4.rst
> @@ -0,0 +1,99 @@
> +.. SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. Copyright (C) 2022 Mohd Noor Aman
> +
> +.. _BSP_aarch64_Raspberrypi_4:
> +
> +Raspberry Pi 4B
> +===============
> +
> +The 'raspberrypi4b' BSP currently supports only the LP64 ABI. ILP32 is not

Should this be ``raspberrypi4b``?

> +supported. Raspberry pi 4B all variants and Raspberry Pi 400  are supported. 

Maybe:

All variants of the Raspberry pi 4B  and Raspberry Pi 400 are supported.

> The
> +default bootloader which is used by the Raspbian OS or other OS can be used to
> +boot the RTEMS. 

I think it would help to explain what the default bootloader is? I am not sure
what this means.

> Currently, QEMU emulation is not supported. 
> +
> +Clock Driver
> +------------
> +
> +The clock driver uses the `ARM Generic Timer`.
> +
> +Console Driver
> +--------------
> +
> +Raspberry pi 4B has 2 types of UARTs, ARM PL011 and Mini-uart. The PL011 is a
> +capable, broadly 16550-compatible UART, while the mini UART has a reduced
> +feature set. The console driver supports the default Qemu emulated ARM PL011
> +PrimeCell UART as well as the physical ARM PL011 PrimeCell UART in the
> +raspberrypi hardware. Mini-uart is not supported.

What are the configuration options?

> +
> +Preparing to boot

Please change to:

Preparing to Boot

> +------------------
> +
> +Raspberry Pi uses a different mechanism to boot. First the GPU initializes,
> +loads the bootloader and then looks for the kernel img. By default the arm64

img should be image

> +mode looks for the ``kernel8.img``. Any other kernel can be loaded by adding
> +`kernel=<img_name>` to the ``config.txt``.

Is config.txt explained, ie a text file in the root directory of the SD card?

> +
> +The Firmware files are required in order to boot RTEMS. The latest firmware can
> +be downloaded from the `Raspberry Pi Firmware Repository
> +<https://github.com/raspberrypi/firmware/>`_. USB boot is supported. All the
> +files (Firmwares and kernel) must be place in the FAT32 partition only. Add
> +``arm_64bit=1`` in the config.txt file in order to boot the BSP in 64bit kernel
> +mode. 
> +
> +
> +UART Setup
> +^^^^^^^^^^
> +
> +Connect your serial device to the GPIO15 and GPIO14. Add the following to the
> +config.txt file in order to use the PL011 UART0 and thus disabling the default
> +Mini-uart.
> +
> +.. code-block:: none
> +
> +  dtoverlay = disable-bt
> +  enable_uart=1
> +
> +.. note:: 
> +  The Raspberry Pi 4B and 400 have an additional four PL011 UARTs. They are not 
> +  supported.
> +
> +Generating kernel image 

Change to:

Generating Kernel Image

> +^^^^^^^^^^^^^^^^^^^^^^^
> +
> +The following steps show how to run ``hello.exe`` on the BSP. Other executables
> +can be processed in a similar way.
> +
> +To create the kernel image:
> +
> +.. code-block:: shell
> +
> +  $ aarch64-rtems at rtems-ver-major@-objcopy -Obinary hello.exe kernel8.img
> +
> +Copy the kernel image to the SD card.

To the root directory of the SD card?

> +
> +JTAG Setup

Change to:

JTAG Set-up

> +----------
> +
> +The Raspberry Pi 4 doesn't have dedicated JTAG pins. Instead, you must configure
> +the GPIO pins (GPIO22-GPIO27) to activate the JTAG functionality. The RPi 4
> +documentation refers to this as Alt4 functions of those pins. Alt5 does exist
> +too, which goes from GPIO4, 5, 6, 12 and 13. you can check this out from
> +`pinout.xyz <https://pinout.xyz/pinout/jtag#>`_ or `eLinux
> +<https://elinux.org/RPi_BCM2835_GPIOs>`_
> +

What about:

The Raspberry Pi 4 doesn't have dedicated JTAG pins. To use JTAG configure
the GPIO pins (GPIO22-GPIO27) to activate the JTAG functionality. The RPi 4
documentation refers to this as Alt4 functions of those pins. Alt5 does exist
and goes from GPIO4, 5, 6, 12 and 13. You can check this out from
`pinout.xyz <https://pinout.xyz/pinout/jtag#>`_ or `eLinux
> +<https://elinux.org/RPi_BCM2835_GPIOs>`_

Also what does Alt5 offer? I see it mentioned but I do not know why?

> +One more thing to note on JTAG with Raspberry pi 4B is that, by default, All the
> +GPIO pins are pulled down, according to the `BCM2711 documentation
> +<https://datasheets.raspberrypi.com/bcm2711/bcm2711-peripherals.pdf>`_. This
> +wasn't the case in the earlier models. So in order to let the data flow freely,
> +we will have to disable them.

What about:

Note, the Raspberry Pi 4B JTAG GPIO pins are by default pulled down,
according to the `BCM2711 documentation
+<https://datasheets.raspberrypi.com/bcm2711/bcm2711-peripherals.pdf>`_. This
wasn't the case in the earlier models.
In order to let the data flow freely, we have to disable the pull down mode.

?

> +
> +.. code-block:: none
> +
> +  # Disable pull downs
> +  gpio=22-27=np
> +
> +  # Enable jtag pins (i.e. GPIO22-GPIO27)
> +  enable_jtag_gpio=1
> +

Where does this go?

Chris

> +
> diff --git a/user/bsps/bsps-aarch64.rst b/user/bsps/bsps-aarch64.rst
> index 933370f..f3aa15c 100644
> --- a/user/bsps/bsps-aarch64.rst
> +++ b/user/bsps/bsps-aarch64.rst
> @@ -9,3 +9,4 @@ aarch64 (AArch64)
>  .. include:: aarch64/a72.rst
>  .. include:: aarch64/xilinx-versal.rst
>  .. include:: aarch64/xilinx-zynqmp.rst
> +.. include:: aarch64/raspberrypi4.rst
> \ No newline at end of file