target.txt - raspberry pi 3 specific documentation

Copyright (c) 2019 Wind River Systems, Inc.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

1) Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

2) Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.

3) Neither the name of Wind River Systems nor the names of its contributors may
be used to endorse or promote products derived from this software without specific
prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 modification history
 --------------------
08mar19,hkl  created (F11409)

rpi_3 - Raspberry Pi 3 Family

EXTERNAL DEPENDENCIES
None

INTRODUCTION

This document describes the features of the rpi_3 unsupported BSP, which is
designed to run on the Raspberry Pi 3 Model B/B+ board. This is an
ARM Cortex-A53 processor-based platform.

Verified Boards

The current release of this BSP has been verified on the following boards:

Raspberry Pi 3 Model B/B+

Jumpers & Switches

No jumper or switch needs to be set.

Running VxWorks

This section describes how to run VxWorks on the supported boards.

1. Setting up Raspberry Pi

    Raspberry Pi 3 Model B+ have special hardware design and booting stages,
    before running any other boot loader or operating system, you have to set
    up its official operating system on the board first. Please follow the
    Raspberry Pi official procedure to install it:
    https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up

2. Running U-Boot on Raspberry Pi

    At Raspberry Pi 3 Model B+ power-up, the CPU is offline, and GPU will boot
    the SoC with its specific bootloader in the boot partition of the SD card
    at first. And after the booting done, the CPU is up and start executing the
    user code, such as an operation system or another bootloader. U-Boot is a
    bootloader can be supported by Raspberry Pi 3 Model B+.

    2.1 Get U-Boot source

        Choose your U-Boot version that you want to run on the board, for example,
        v2018.11 is the verified version. The U-Boot released sources can be
        found on the DENX official ftp site:
        ftp://ftp.denx.de/pub/u-boot/, or from git repository using following
        steps:

        cd $HOME
        git clone git://git.denx.de/u-boot.git
        cd u-boot/
        git checkout v2018.11 -b u-boot-2018-11

    2.2 Build U-Boot image

        Use a cross compile tool chain to build the U-Boot image. You may choose
        whatever you prefer. Here is an example we use
        gcc-arm-8.2-2018.08-x86_64-aarch64-linux-gnu to build 64-bit mode U-Boot
        for Raspberry Pi 3 Model B+. It can be download from site:
        https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads

        Following commands show how to build the U-Boot, assuming the cross compiler
        have been download into $HOME folder.

        cd $HOME
        tar -xf gcc-arm-8.2-2018.08-x86_64-aarch64-linux-gnu.tar.xz
        export CROSS_COMPILE=$HOME/gcc-arm-8.2-2018.08-x86_64-aarch64-linux-gnu/bin/aarch64-linux-gnu-
        cd u-boot/
        make rpi_3_defconfig
        make

        u-boot.bin is the final u-boot image.

    2.3 Copy U-Boot image to Raspberry Pi SD card

        On the SD card which had been set up for Raspberry Pi, you can find a
        file partition named 'boot'. For Raspberry Pi 3 Model B+, there may be
        several kernel images in this partition(e.g. kernel.img, kernel7.img)
        and the bootloader will load the highest numbered one. So, if we want
        to run U-Boot on this board, just copy u-boot.bin to a higher numbered
        kernel image.

        For example, the previous highest numbered kernel image is 'kernel7.img',
        so we copy u-boot.bin into the boot partition and rename it to 'kernel8.img'.

    2.4 Enable UART

        For Raspberry Pi 3 Model B+, GPIO 14&15 are used as UART transmit and
        receive pins. They are used by mini UART which is disabled by default.
        In the boot partition of SD card, there is a 'config.txt' file to store
        the system configuration parameters. To enable the UART, add 'enable_uart=1'
        to config.txt. Thus you can start a terminal emulator program such as PuTTY
        or Tera Term on PC and connect to the UART with the following settings:

            Baud Rate   : 115200
            Data        : 8 bit
            Stop        : 1 bit
            Parity      : None
            Flow Control: None

    2.5 Power up Raspberry Pi

        Insert the SD card that contains u-boot image and modified config.txt file
        into the board and power up. Wait for a while, the GPU bootloader will spend
        some time before U-Boot starting.

3. Creating VxWorks image

    3.1 Create and config a VSB (VxWorks Source Build)

    A VSB must be created before a VIP could be used, and it could be created
    based on the BSP: rpi_3_0_1_0_0.

        3.1.1 Create a VSB

        In the step of "Project Setup" in WorkBench, select
        rpi_3_0_1_0_0 UNSUPPORTED.

        Or just use one of the following commands in the VxWorks 7 Development
        Shell:

        vxprj vsb create -bsp rpi_3_0_1_0_0 -S ~/myVsb

        The BSP version number "0_1_0_0" may be changed as the BSP updated,
        you may need to choose in the WorkBench or check which version you
        want by below command in the VxWorks 7 Development Shell:

        vxprj vsb listBsps

        3.1.2 Build the VSB

        Build the VSB in the WorkBench or use below command in the
        VxWorks 7 Development Shell:

        vxprj build

    3.2 Create a VIP based on the new VSB

        Please note: Both WorkBench and the VxWorks 7 Development Shell can
        be used for VIP creating and configuring. All below sections will only
        use the VxWorks 7 Development Shell command as an example, and the
        corresponding operation in WorkBench is quite straight forward.

        3.2.1 Create a VIP based on the new VSB

        In the same directory of the new VSB, use below command to create a VIP:

        vxprj vip create -vsb myVsb rpi_3_0_1_0_0 llvm myVip

        3.2.2 Configure and build the VIP

            3.2.2.1 Configure the device tree blob (DTB) loading method

            The VxWorks 7 ARM BSP uses device tree nodes to describe device
            specific information, and there are two methods to load the device
            tree blob:
                - Embedded:     the device tree blob is embedded in the VxWorks
                                image.
                - Independent:  an independent file is created for the device
                                tree blob. And the independent method is used
                                by default.

            To use the embedded method, use below command in the VIP directory:

            vxprj component add INCLUDE_STANDALONE_DTB

            3.2.2.2 Configure the booting method and image type

            The U-Boot can boot up two kinds of VxWorks images: uVxWorks and raw
            bin file vxWorks.bin. The uVxWorks is used for U-Boot "bootm"
            command, and needs an independent or embedded DTB file. The
            vxWorks.bin is used for U-Boot "go" command and needs embedded DTB.

            Use one of the below commands to create different VxWorks image:

            vxprj build uVxWorks
            vxprj build vxWorks.bin
            vxprj build vxWorks

            After building passed, the related DTB files
            (with .dtb suffix) are also created in the "default" subdirectory
            of the VIP. For this BSP, "rpi-3b-plus.dtb" will be created.

4. Runing VxWorks on U-Boot

    4.1 Running U-Boot image

        Following the description of '2. Running U-Boot on Raspberry Pi' section,
        start U-Boot on Raspberry Pi 3 Model B+.

    4.2 Downloading the VxWorks image

        4.2.1 Start a TFTP server

        Open a TFTP server on your host. Make sure the root directory is your
        project directory of the VIP which contains the VxWorks image.

        4.2.2 Configure the U-Boot environment

        When board boots up, the U-Boot will prompt you to enter U-Boot shell,
        press any key then to get into U-Boot shell before count down finished.
        Type the following commands to setup the U-Boot environment.

        setenv ipaddr 192.168.0.3
        setenv netmask 255.255.255.0
        setenv serverip 192.168.0.2
        setenv gatewayip 192.168.0.1
        saveenv

        Note:
        1)  This is just an example, you must change the network parameters
            according to your actual situation.

    4.3 Download and run the vxWorks.bin image for U-Boot

        4.3.1 Download vxWorks.bin image for U-Boot

        The vxWorks.bin image is used for U-Boot "go" command, so the
        downloading address must be the same as "KERNEL_LOAD_ADRS".
        For Raspberry Pi 3 Model B+, it's 0x00100000. Also, it is used along
        with the embedded DTB, so component INCLUDE_STANDALONE_DTB is needed
        for the vxWorks.bin building.

        Use below command to download the vxWorks.bin image for U-Boot:

        tftp $KERNEL_LOAD_ADRS vxWorks.bin

        4.3.2 Running the vxWorks.bin image on U-Boot

        Use "go <image running address>" to run the vxWorks.bin image as below:

        go $KERNEL_LOAD_ADRS

    4.4 Download and run the uVxWorks image for U-Boot

        4.4.1 Download uVxWorks image for U-Boot

        The uVxWorks image can be used along with an independent DTB file. The
        downloading address must not destroy the spaces used by VxWorks.
        Below is an example for Raspberry Pi 3 Model B+:

        In the U-Boot shell, type the following command to download uVxWorks:

        tftp 0x08000000 uVxWorks

        type the following command to download DTB:

        tftp 0x09000000 rpi-3b-plus.dtb

        4.4.2. Running the uVxWorks image on U-Boot

        If the uVxWorks image uses the independent DTB file, use the
        'bootm <image address> - <DTB address>' command to load and run the
        uVxWorks image as follows:

        bootm 0x08000000 - 0x09000000

        If the uVxWorks image uses the embedded DTB file, use the
        'bootm <image address>' command to load and run the uVxWorks image as
        follows:

        bootm 0x08000000

5. Summary

    Below is a summary about configuring and running VxWorks 7:

                | uVxWorks      | vxWorks.bin
--------------------------------------------------------
Boot Loader     | U-Boot        | U-Boot
DTB Mode        | independent   | embedded
Component Needed|               | INCLUDE_STANDALONE_DTB
Boot Method     | bootm         | go

DEVICE TREE

This BSP uses device tree nodes to describe the device specific information
on the board. The supported drivers will get configuration data from
the device tree source files (with suffix .dts) under the BSP directory.
For the structure of the device tree source file, please refer to the
ePAPR specification here:
http://www.power.org/technology-introduction/standards-specifications/

The supported boards and the corresponding device tree source (DTS) files for
this BSP are mapped as follows:

Board                                | Device Tree Source          | Boot Loader
--------------------------------------------------------------------------------
Raspberry Pi 3 Model B/B+            | rpi-3b-plus.dtb             | U-Boot

Based on the following device tree blob (DTB) loading methods, these DTS files
are used in different ways:

- Embedded:     A VIP parameter, DTS_FILE, designates which DTS file is used for
                the current VIP. The default value is set to support the correct
                board according to the table above.

- Independent:  The corresponding DTB files (with suffix .dtb) are created in
                the 'default' subdirectory of the VIP as part of the build
                process. These DTB files are used by the U-Boot 'bootm' command.

FEATURES

This section describes all features of the board, supported or not.

It documents all configurations of the board and the interaction between
features and configuration items.

List of hardware features (Raspberry Pi 3 Model B/B+)

Hardware Interface | Controller | Driver/Component                | Status
-------------------------------------------------------------------------------
Mini UART          | on-chip    | DRV_SIO_FDT_NS16550             | SUPPORTED
BCM2837 L1 INTCTLR | on-chip    | DRV_INTCTLR_FDT_BCM2837_L1_INTC | SUPPORTED
BCM2837 INTCTLR    | on-chip    | DRV_INTCTLR_FDT_BCM2837_INTC    | SUPPORTED
ARM Generic Timer  | on-chip    | DRV_ARM_GEN_TIMER               | SUPPORTED
System Timer       | on-chip    | DRV_TIMER_FDT_BCM2837_SYSTIMER  | SUPPORTED
Clock              | on-chip    |                                 | UNSUPPORTED
GPIO               | on-chip    | DRV_GPIO_FDT_BCM2837            | SUPPORTED
I2C                | on-chip    | DRV_I2C_FDT_BCM2837             | SUPPORTED
PinMux             | on-chip    |                                 | UNSUPPORTED
SPI                | on-chip    | DRV_SPI_FDT_BCM2837             | SUPPORTED
USB HOST           | on-chip    | USB Host Stack(DWC2DR)          | SUPPORTED
USB ETHERNET       | on-chip    | INCLUDE_USB_GEN2_LAN78XX        | SUPPORTED
Audio              | on-chip    |                                 | UNSUPPORTED
HDMI               | on-chip    |                                 | UNSUPPORTED
Watchdog Module    | on-chip    |                                 | UNSUPPORTED
EMMC               | on-chip    |                                 | UNSUPPORTED
Wireless LAN       | unknown    |                                 | UNSUPPORTED
Bluetooth          | unknown    |                                 | UNSUPPORTED

Feature Interactions

Refer to the board vendor's documentation.

HARDWARE DETAILS

This section documents the details of the device drivers and board hardware
elements.

Verified Hardware

This BSP had been verified on below boards:

Board                          | Type                   | Revision
------------------------------------------------------------------
Raspberry Pi 3 Model B  board  | N/A                    | N/A
Raspberry Pi 3 Model B+ board  | N/A                    | N/A

Note: all the other revisions of the same board might work with this
      BSP, but it is not officially supported.

Serial Configuration

No special serial configuration is required. The serial configuration is
supported by the DRV_SIO_FDT_NS16550 component and is enabled by default.

The default serial configuration is:
    Baud Rate   : 115200
    Data        : 8 bit
    Stop        : 1 bit
    Parity      : None
    Flow Control: None

Timer

There are various hardware timers either in processor core or in SOC. The
description about these timers is as follows:

Arm Generic Timer
    This support refers to the generic timer in the ARM core. This feature is
    supported by the DRV_ARM_GEN_TIMER component. In this BSP, it is used as the
    system clock by default.

System Timer
    This feature is supported by the DRV_TIMER_FDT_BCM2837_SYSTIMER component.
    The System Timer peripheral provides four 32-bit timer channels and a single
    64-bit free running counter. Each channel has an output compare register,
    which is compared against the 32 least significant bits of the free running
    counter values. When the two values match, The match signal is then fed into
    the interrupt controller, The interrupt service routine then reads the
    output compare register and adds the appropriate offset for the next timer
    tick. Only one channel is supported in this BSP, and it is used as the
    auxiliary clock by default.

To include these support, add the following components to your VIP:

    vxprj vip component add DRV_ARM_GEN_TIMER
    vxprj vip component add DRV_TIMER_FDT_BCM2837_SYSTIMER

GPIO

The GPIO module which supplies general purpose input/output is supported in
this release of BSP. It is supported by component DRV_GPIO_FDT_BCM2837.

To include this support, add the following component to your VIP:

    vxprj component add DRV_GPIO_FDT_BCM2837

SPI

The SPI module which supplies a high-speed serial input/output port is supported
in this release of BSP. It is supported by component DRV_SPI_FDT_BCM2837.

To include this support, add the following component to your VIP:

    vxprj component add DRV_SPI_FDT_BCM2837

I2C

The Broadcom Serial Controller (BSC) on the processor is supported
in this BSP. It is supported by component DRV_I2C_FDT_BCM2837.

To include this support, add the following component to your VIP:

    vxprj component add DRV_I2C_FDT_BCM2837

USB

Raspberry Pi 3 Model B+ SOC has one USB controller(Synopsys DesignWare USB2.0
OTG). The controller supports USB 1.1 and USB 2.0 standard.

Currently, the driver only support "Pure Host" mode in this BSP.

The USB layer must be added to the created VSB.

    vxprj vsb add USB

While in the created VIP, components for DWC2DR and ALT5 PHY need be
enabled. To use different USB devices, USB class drivers need be enabled too.
Please refer to USB programmer guide for more detail to enable kinds of USB
class driver. For example, following component will add USB mass storage class
driver to support USB mass storage devices:

    vxprj component add INCLUDE_SYNOPSYSHCI_INIT
    vxprj component add INCLUDE_USB_PHY_ALT5
    vxprj component add INCLUDE_USB_GEN2_STORAGE_INIT

USB ETHERNET

Raspberry Pi 3 Model B+ board use one USB Ethernet card to provide network. To
use Ethernet port, need to add the USB controller and USB Ethernet card components.

The USB layer must be added to the created VSB first.

    vxprj vsb add USB

And the following componets will add USB controller and USB ethernet card drivers
to support USB network devices:

    vxprj component add INCLUDE_SYNOPSYSHCI_INIT
    vxprj component add INCLUDE_USB_PHY_ALT5
    vxprj component add INCLUDE_USB_GEN2_LAN78XX
    vxprj component add INCLUDE_USB_GEN2_END_INIT

If you want o change the default IP address&netmask, could set the following
parameters, for example:

    vxprj parameter set USB_GEN2_END_IP_ADDRESS {'"192.168.100.10"'}
    vxprj parameter set USB_GEN2_END_NET_MASK {0xffffff00}

Currently, The Ethernet MAC address can only be set by the device tree node.
To change the address, open the device tree source (DTS) file, locate the
required property, and modify it manually. For example:

    local-mac-address = [ b8 27 eb d7 23 ac ​];

    NOTE: each Raspberry Pi 3 Model B+ board have its own MAC address,
          and can find it in U-boot environment variable "ethaddr".

Limitations and Known Issues

Feature     Note
-----------+--------------------------------------------------------------------
N/A        |N/A

BOARD LAYOUT

Raspberry Pi 3 Model B+:
+----------------------------------+--------------------+----+
| GPIO/UART/I2C/SPI                |                    |    |
|----------------------------------+                    |USB |
+-----+                                                 |    |
|WIFI&|                                                 |    |
|BT   |      +-------+                                  |    |
+-----+      |BCM2837|                                  |    |
|            |       |                                  |    |
|            +-------+                                  +----+
+-----+                                                      |
|Micro|                                                      |
|SD   |                                                      |
|Slot |                                             +--------+
+-----+                                             |Ethernet|
|(underneath)             +------+                  |Port    |
|                         |Camera|    +-----+       |        |
+-----+      +----+       |Module|    |Audio|       +--------+
|Power|      |HDMI|       |Port  |    |Jack |                |
+-----+------+----+-------+------+----+-----+----------------+

SEE ALSO

Workbench User's Guide
VxWorks 7 Programmer's Guide
VxWorks 7 Configuration and Build Guide
VxWorks 7 ARM Architecture Guide
VxWorks 7 BSP and Driver Guide
