arm-trusted-firmware: Enable building in AGL build

Leverage the reworked extra_opl_ipt hook in the rcar3 BSP's
arm-trusted-firmware recipe as of BSP v4.7.0 to enable building the
reference hardware flavor of the firmware as an extra firmware
version when building with MACHINE=h3ulcb.  This will then enable
working inside the AGL build which combines the reference hardware
support into its h3ulcb build to avoid needing an extra platform
build.

Support for building standalone with MACHINE=agl-refhw-h3 has been
retained for potential use outside of the full AGL build.  The
firmware documentation has been reworked to document the build and
flashing procedure for both types of build.

Based on initial prototype by Vasyl Vavrychuk at:

https://gerrit.automotivelinux.org/gerrit/c/AGL/meta-agl-refhw/+/26352

Bug-AGL: SPEC-3916

Signed-off-by: Scott Murray <scott.murray@konsulko.com>
Change-Id: I5f74450851aeb4cb015a21e234709eca2014f378

2 files changed, 225 insertions, 154 deletions

diff --git a/meta-agl-refhw-gen3/docs/ReferenceHW_Rcar_gen3.md b/meta-agl-refhw-gen3/docs/ReferenceHW_Rcar_gen3.md
index 1d72c4d..f0a6d99 100644
--- a/meta-agl-refhw-gen3/docs/ReferenceHW_Rcar_gen3.md
+++ b/meta-agl-refhw-gen3/docs/ReferenceHW_Rcar_gen3.md
@@ -2,127 +2,79 @@
 
 - [About](#about)
 - [Difference to Salvator-XS When Flashing Firmware](#difference-to-salvator-xs-when-flashing-firmware)
-- [How to build the Flash Writer](#how-to-build-the-flash-writer)
+- [How to Build the Flash Writer](#how-to-build-the-flash-writer)
 - [How to Flash Firmware](#how-to-flash-firmware)
+- [How to Build the Firmware](#how-to-build-the-firmware)
 
 
 ## About
-Reference hardware board with R-Car H3 SoC is made by Panasonic for AGL community.
+The AGL Reference hardware board with R-Car H3 SoC is made by Panasonic for the
+AGL community.
 
 ## Difference to Salvator-XS When Flashing Firmware
 
-The HyperFlash/QSPI flash switch function is not implemented on reference
-hardware board at present, HyperFlash and QSPI flash are not used.  
-Firmwares (arm-trusted-firmware, U-boot...) are stored into eMMC and updated by
-using serial download.
+The HyperFlash/QSPI flash switch function is not implemented on the reference
+hardware board at present, HyperFlash and QSPI flash are not used.  Firmware
+(arm-trusted-firmware, U-Boot...) is stored in eMMC and updated by using serial
+download.
 
 ## How to build the Flash Writer
 
-1. Gets cross compiler.
-```
-	$ cd ~/
-	$ wget https://releases.linaro.org/components/toolchain/binaries/7.3-2018.05/aarch64-elf/gcc-linaro-7.3.1-2018.05-x86_64_aarch64-elf.tar.xz
-	$ tar xvf gcc-linaro-7.3.1-2018.05-x86_64_aarch64-elf.tar.xz
-```
-
-2. Prepare the source code
-```
-	$ cd ~/
-	$ git clone https://github.com/renesas-rcar/flash_writer.git
-	$ cd flash_writer
-	$ git checkout rcar_gen3
-```
-
+1. Get the prebuilt cross compiler:
+    ```
+    $ cd ~/
+    $ wget https://releases.linaro.org/components/toolchain/binaries/7.3-2018.05/aarch64-elf/gcc-linaro-7.3.1-2018.05-x86_64_aarch64-elf.tar.xz
+    $ tar xvf gcc-linaro-7.3.1-2018.05-x86_64_aarch64-elf.tar.xz
+    ```
+2. Prepare the source code:
+    ```
+    $ cd ~/
+    $ git clone https://github.com/renesas-rcar/flash_writer.git
+    $ cd flash_writer
+    $ git checkout rcar_gen3
+    ```
 3. Build the Flash Writer
-```
-	$ make AArch=64 clean
-	$ CROSS_COMPILE=~/gcc-linaro-7.3.1-2018.05-x86_64_aarch64-elf/bin/aarch64-elf- make AArch=64
-```
-
-Output the following image.
-./AArch64_output/AArch64_Flash_writer_SCIF_DUMMY_CERT_E6300400_salvator-x.mot
+    ```
+    $ make AArch=64 clean
+    $ CROSS_COMPILE=~/gcc-linaro-7.3.1-2018.05-x86_64_aarch64-elf/bin/aarch64-elf- make AArch=64
+    ```
+    The output image is at:
+    ```
+    ./AArch64_output/AArch64_Flash_writer_SCIF_DUMMY_CERT_E6300400_salvator-x.mot
+    ```
 
-## How to build the Firmware
-
-1. In a temporary working directory, clone poky the poky repository and check out the dunfell branch:
-```
-	git clone git://git.yoctoproject.org/poky
-	cd poky
-	git checkout dunfell
-	..
-```
-2.  Clone the Renesas BSP and it's dependent layers:
-```
-	git clone https://github.com/renesas-rcar/meta-renesas
-	cd meta-renesas
-	git checkout dunfell-dev-4.14
-	cd ..
-	git clone git://git.openembedded.org/meta-openembedded
-	cd meta-openembedded
-	git checkout dunfell
-	cd ..
-```
-3. Clone the reference hardware BSP layer:
-```
-	git clone https://gerrit.automotivelinux.org/gerrit/AGL/meta-agl-refhw
-```
-4. Create a build environment:
-```
-	. ./poky/oe-init-build-env build
-```
-5. Add the layers to `conf/bblayers.conf`, the `BBLAYERS` variable definition should look like:
-```
-	BBLAYERS ?= " \
-	  /home/user/workdir/poky/meta \
-	  /home/user/workdir/poky/meta-poky \
-	  /home/user/poky/meta-yocto-bsp \
-	  /home/user/workdir/meta-openembedded/meta-oe \
-	  /home/user/workdir/meta-openembedded/meta-python \
-	  /home/user/workdir/meta-renesas/meta-rcar-gen3 \
-	  /home/user/workdir/meta-agl-refhw/meta-agl-refhw-gen3 \
-	  "
-```
-6. Add the machine setting to `conf/local.conf`, for example:
-```
-	echo MACHINE=agl-refhw-h3 >> conf/local.conf
-```
-7. Build the firmware:
-```
-	bitbake arm-trusted-firmware optee-os u-boot
-```
-8. Afterwards, the firmware files will be in the directory `tmp/deploy/images/agl-refhw-h3`.
 
 ## How to Flash Firmware
 
-1. Connect reference hardware board to the development PC by using USB serial
-   cable.  
+1. Connect reference hardware board to the development PC by using USB serial cable.
+
 2. Open a serial console (like Teraterm in Windows, or gtkterm in Ubuntu that
    can easily send files) with a baudrate of 115200n8.
-3. Set bit2 of SW2221 (on the top of SoC board) to "off"which turns SW2221 to be
+
+4. Set bit2 of SW2221 (on the top of SoC board) to "off"which turns SW2221 to be
 	off,off,off,off.
-4. Power on the reference board, you will find fillowing message outputed on the
-   serial console:
-
-```
-	SCIF Download mode (w/o verification)
-	(C) Renesas Electronics Corp.
-
-	-- Load Program to SystemRAM ---------------
-	please send !
-	
-```
-5. Use console application menu to send the flash writer binary provided:
-
-```
-	AArch64_Flash_writer_SCIF_DUMMY_CERT_E6300400_salvator-x.mot
-```
-6. After file is transferred correctly, following message will be outputed:
-
-```
-	Flash writer for R-Car H3/M3/M3N Series V1.11 Feb.12,2020
-	>
-```
-7. Set reference board to boot from eMMC.
+
+5. Power on the reference board, you will find following message on the serial
+   console:
+    ```
+    SCIF Download mode (w/o verification)
+    (C) Renesas Electronics Corp.
+
+    -- Load Program to SystemRAM ---------------
+    please send !
+    ```
+
+6. Use console application menu to send the flash writer binary:
+    ```
+    AArch64_Flash_writer_SCIF_DUMMY_CERT_E6300400_salvator-x.mot
+    ```
+
+7. After the writer is transferred correctly, the following message will be displayed:
+    ```
+    Flash writer for R-Car H3/M3/M3N Series V1.11 Feb.12,2020
+    >
+    ```
+8. Set reference board to boot from eMMC:
 
     \> **EM_SECSD**  
     Please Input EXT_CSD Index(H'00 - H'1FF) :**b1**  
@@ -172,40 +124,128 @@ Output the following image.
     [  9:  8]  ECC                 0x00  
     [  7:  1]  CRC                 0x00  
 
-
-8. Flash firmware  
-  The firmware are supposed to be stored on eMMC as following:
-
-  Name					| eMMC partition 	| Flash address		| Load address		| Description
-  --------------------------------------|-----------------------|-----------------------|-----------------------|-----------------------------
-  bootparam_sa0-4x2g.srec		| 1			| H'000000		| H'E6320000		| Boot parameter
-  bl2-agl-refhw-h3-4x2g.srec		| 1			| H'00001E		| H'E6304000		| bl2 loader
-  cert_header_sa6-4x2g.srec		| 1			| H'000180		| H'E6320000		| Certification
-  bl31-agl-refhw-h3-4x2g.srec		| 1			| H'000200		| H'44000000		| bl3 loader
-  tee-agl-refhw-h3.srec			| 1			| H'001000		| H'44100000		| OP-Tee
-  u-boot-elf-salvator-xs-4x2g.srec	| 2			| H'000000		| H'50000000		| U-boot
-
-  You can find these firmwares in the AGL build directory $AGL_TOP/build/tmp/deploy/images/salvator-x
-  and you can flash them by using **EM_W** command as following:  
-
-  \> **EM_W**  
-  \---------------------------------------------------------  
-  Please select,eMMC Partition Area.  
-   0:User Partition Area   : 62496768 KBytes  
-    eMMC Sector Cnt : H'0 - H'07733FFF  
-   1:Boot Partition 1      : 32640 KBytes  
-    eMMC Sector Cnt : H'0 - H'0000FEFF  
-   2:Boot Partition 2      : 32640 KBytes  
-    eMMC Sector Cnt : H'0 - H'0000FEFF  
-  \---------------------------------------------------------  
-  Select area(0-2)> **\<Enter the eMMC partition number above, Ex.'1' \>**   
-  -- Boot Partition X Program -----------------------------  
-  Please Input Start Address in sector : **\<Enter the Flash address above, Ex.'1e'\>**  
-  Please Input Program Start Address : **\<Enter the Load address above, Ex. 'e6304000'\>**  
-  Work RAM(H'50000000-H'50FFFFFF) Clear....  
-  please send ! ('.' & CR stop load)  
-  **\<Send the fimware file above by using console appliction, Ex. send 'bl2-salvator-x-4x2g.srec'\>**
+9. Flash the firmware.
+
+    If using an AGL build with the agl-refhw-h3 feature, you can find the firmware
+    files under the build directory in `tmp/deploy/images/h3ulcb`.
+
+    The firmware should be stored on the eMMC as follows:
+
+    | Name                                | eMMC partition | Flash address | Load address | Description
+    |-------------------------------------|:--------------:|:-------------:|:------------:|------------------|
+    | bootparam_sa0-agl-refhw-4x2g.srec   | 1              | H'000000      | H'E6320000   | Boot parameter
+    | bl2-agl-refhw-4x2g.srec             | 1              | H'00001E      | H'E6304000   | bl2 loader
+    | cert_header_sa6-agl-refhw-4x2g.srec | 1              | H'000180      | H'E6320000   | Certification
+    | bl31-agl-refhw-4x2g.srec            | 1              | H'000200      | H'44000000   | bl3 loader
+    | tee-h3ulcb.srec                     | 1              | H'001000      | H'44100000   | OP-Tee
+    | u-boot-elf-agl-refhw-4x2g.srec      | 2              | H'000000      | H'50000000   | U-boot
+
+    If the firmware has been built using a standalone build outside of AGL
+    (see [below](#standalone-build)), then the firmware files can be be found in
+    `tmp/deploy/images/agl-refhw-h3`, and should be stored on the eMMC as follows:
+
+    | Name                                | eMMC partition | Flash address | Load address | Description
+    |-------------------------------------|:--------------:|:-------------:|:------------:|------------------|
+    | bootparam_sa0-4x2g.srec             | 1              | H'000000      | H'E6320000   | Boot parameter
+    | bl2-agl-refhw-h3-4x2g.srec          | 1              | H'00001E      | H'E6304000   | bl2 loader
+    | cert_header_sa6-4x2g.srec           | 1              | H'000180      | H'E6320000   | Certification
+    | bl31-agl-refhw-h3-4x2g.srec         | 1              | H'000200      | H'44000000   | bl3 loader
+    | tee-agl-refhw-h3.srec               | 1              | H'001000      | H'44100000   | OP-Tee
+    | u-boot-elf-salvator-xs-4x2g.srec    | 2              | H'000000      | H'50000000   | U-boot
+
+    The firmware files can be flashed by using **EM_W** command for each of them:
+
+    \> **EM_W**  
+    \---------------------------------------------------------  
+    Please select,eMMC Partition Area.  
+     0:User Partition Area   : 62496768 KBytes  
+      eMMC Sector Cnt : H'0 - H'07733FFF  
+     1:Boot Partition 1      : 32640 KBytes  
+      eMMC Sector Cnt : H'0 - H'0000FEFF  
+     2:Boot Partition 2      : 32640 KBytes  
+      eMMC Sector Cnt : H'0 - H'0000FEFF  
+    \---------------------------------------------------------  
+    Select area(0-2)> **\<Enter the eMMC partition number above, Ex.'1' \>**   
+    -- Boot Partition X Program -----------------------------  
+    Please Input Start Address in sector : **\<Enter the Flash address above, Ex.'1e'\>**  
+    Please Input Program Start Address : **\<Enter the Load address above, Ex. 'e6304000'\>**  
+    Work RAM(H'50000000-H'50FFFFFF) Clear....  
+    please send ! ('.' & CR stop load)  
+    **\<Send the fimware file above by using console appliction, Ex. send 'bl2-agl-refhw-x-4x2g.srec'\>**
 
 9. Power off the board.
 10. Reset bit2 of SW2221 (on the top of SoC board) to "on", which turns SW2221 to be  
-	off,on,off,off
+    off,on,off,off.
+
+
+## How to build the Firmware
+
+### In AGL Build
+
+1. Initialize build environment:
+    ```
+    source meta-agl/scripts/aglsetup.sh -m h3ulcb agl-refhw-h3
+    ```
+    or:
+    ```
+    source meta-agl/scripts/aglsetup.sh -m h3ulcb-nogfx agl-refhw-h3
+    ```
+2. Build the firmware:
+    ```
+    bitbake arm-trusted-firmware optee-os u-boot
+    ```
+3. Afterwards, the firmware files will be in the directory `tmp/deploy/images/agl-refhw-h3`.
+
+
+### Standalone Build
+
+It is also possible to build the firmware outside of the AGL build by using this
+BSP layer on top of the meta-rcar-gen3 layer in meta-renesas.
+
+1. In a temporary working directory, clone poky the poky repository and check out the dunfell branch:
+    ```
+    git clone git://git.yoctoproject.org/poky
+    cd poky
+    git checkout dunfell
+    ..
+    ```
+2.  Clone the Renesas BSP and it's dependent layers:
+    ```
+    git clone https://github.com/renesas-rcar/meta-renesas
+    cd meta-renesas
+    git checkout dunfell-dev-4.14
+    cd ..
+    git clone git://git.openembedded.org/meta-openembedded
+    cd meta-openembedded
+    git checkout dunfell
+    cd ..
+    ```
+3. Clone the reference hardware BSP layer:
+    ```
+    git clone https://gerrit.automotivelinux.org/gerrit/AGL/meta-agl-refhw
+    ```
+4. Create a build environment:
+    ```
+    . ./poky/oe-init-build-env build
+    ```
+5. Add the layers to `conf/bblayers.conf`, the `BBLAYERS` variable definition should look like:
+    ```
+    BBLAYERS ?= " \
+        /home/user/workdir/poky/meta \
+        /home/user/workdir/poky/meta-poky \
+        /home/user/poky/meta-yocto-bsp \
+        /home/user/workdir/meta-openembedded/meta-oe \
+        /home/user/workdir/meta-openembedded/meta-python \
+        /home/user/workdir/meta-renesas/meta-rcar-gen3 \
+        /home/user/workdir/meta-agl-refhw/meta-agl-refhw-gen3 \
+    "
+    ```
+6. Add the machine setting to `conf/local.conf`, for example:
+    ```
+    echo MACHINE=agl-refhw-h3 >> conf/local.conf
+    ```
+7. Build the firmware:
+    ```
+    bitbake arm-trusted-firmware optee-os u-boot
+    ```
+8. Afterwards, the firmware files will be in the directory `tmp/deploy/images/agl-refhw-h3`.
diff --git a/meta-agl-refhw-gen3/recipes-bsp/arm-trusted-firmware/arm-trusted-firmware_%.bbappend b/meta-agl-refhw-gen3/recipes-bsp/arm-trusted-firmware/arm-trusted-firmware_%.bbappend
index bf2874f..962f84e 100644
--- a/meta-agl-refhw-gen3/recipes-bsp/arm-trusted-firmware/arm-trusted-firmware_%.bbappend
+++ b/meta-agl-refhw-gen3/recipes-bsp/arm-trusted-firmware/arm-trusted-firmware_%.bbappend
@@ -1,33 +1,64 @@
 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
 
-SRC_URI += "file://0001-Boot-Normal-World-in-EL2.patch"
+# Apply the patch AGL applies for all rcar3 in meta-agl-bsp when
+# building the standalone agl-refhw-h3 machine.
+SRC_URI_append_agl-refhw-h3 = " file://0001-Boot-Normal-World-in-EL2.patch"
 
 # It is believed the eMMC configuration below makes the result AGL
-# reference hardware specific, mark it as such to try to prevent
-# unintended usage on other boards.
-COMPATIBLE_MACHINE = "agl-refhw-h3"
+# reference hardware specific, mark it as such when building with
+# MACHINE=agl-refhw-h3 to potentially flag this in an incorrectly
+# configured build.
+COMPATIBLE_MACHINE_agl-refhw-h3 = "agl-refhw-h3"
 
 # There are hardware issues in using hyperflash. arm-trusted-firmware, optee and
 # u-boot have to be stored into eMMC by using serial donwload.
 EMMC_BOOT_OPTION = "RCAR_SA6_TYPE=1"
 
-DDR_8G_OPTION= "RCAR_DRAM_LPDDR4_MEMCONF=1"
+# RCAR_DRAM_MEMRANK must be set, since in case of RCAR_DRAM_LPDDR4_MEMCONF=1
+# ddr_rank_judge is called. But for RCAR_DRAM_MEMRANK=0 it can determine values
+# only for Salvator XS and Starter Kit Pre.
+#
+# RCAR_DRAM_MEMRANK=2 is set because for ATF from BSP v4.7.0:
+#
+# https://github.com/renesas-rcar/arm-trusted-firmware/tree/af9f429a48b438e314289f17947ad5d8036f398e
+#
+# _board_judge returns hardcoded 'brd = 8;  /*  8Gbit/2rank */' by default.
+#
+DDR_8G_OPTION = "RCAR_DRAM_LPDDR4_MEMCONF=1 RCAR_DRAM_MEMRANK=2"
 
-ATFW_OPT_append_agl-refhw-h3 = " ${EMMC_BOOT_OPTION}"
+ATFW_OPT_agl-refhw-h3 = "LSI=H3 RCAR_DRAM_SPLIT=1 ${EMMC_BOOT_OPTION} ${DDR_8G_OPTION}"
 
-# In arm-trusted-firmware-control.inc, a "extra_ipl_opt" task is appended to
-# create firmware for 4x2g or 2x2g variation. it is supposed to use
-# EXTRA_ATFW_OPT to customize the compiler opton.
 #
-#EXTRA_ATFW_OPT_append_agl-refhw-h3 = " ${EMMC_BOOT_OPTION} ${DDR_8G_OPTION}"
+# Handle building as extra firmware with MACHINE=h3ulcb
+#
+
+# Build options for building as extra firmware when MACHINE=h3ulcb, based on H3[4x2g]
+H3ULCB[agl-refhw-4x2g] = "LSI=H3 RCAR_DRAM_SPLIT=1 ${EMMC_BOOT_OPTION} ${DDR_8G_OPTION}"
+
 #
-# Unfortunately in do_extra_ipl_opt() it use d.setVar() instead of d.appendVar()
-# to setup EXTRA_ATFW_OPT variable which makes it impossible to customize it properly
-# by others... Override it.
-# 
+# Need to prepend the compile tasks with a distclean that actually cleans
+# out all the platform specific files like the new rcar_layout_tool output,
+# otherwise they do not get rebuilt and board builds can get the wrong
+# version of e.g. cert_headers_sa6.  This needs to be addressed with
+# upstream.
 #
-do_ipl_opt_compile_agl-refhw-h3 () {
-    oe_runmake distclean
-    oe_runmake bl2 bl31 dummytool PLAT=${PLATFORM} ${EXTRA_ATFW_OPT} ${ATFW_OPT_LOSSY} ${EMMC_BOOT_OPTION} ${DDR_8G_OPTION}
+
+do_compile_prepend() {
+    oe_runmake distclean PLAT=${PLATFORM} MBEDTLS_COMMON_MK=1 ${ATFW_OPT}
+}
+
+do_ipl_opt_compile_prepend() {
+    oe_runmake distclean PLAT=${PLATFORM} MBEDTLS_COMMON_MK=1 ${ATFW_OPT}
+}
+
+do_extra_ipl_opt_refhw_fixup() {
+    # Rename agl-refhw-h3 firmware files to drop h3ulcb-
+    for f in ${DEPLOYDIR}/*-h3ulcb-agl-refhw-4x2g*; do
+        n=`basename $f | sed 's/h3ulcb-//'`
+        mv -f $f ${DEPLOYDIR}/$n
+    done
 }
 
+EXTRA_IPL_OPT_POSTFUNCS = ""
+EXTRA_IPL_OPT_POSTFUNCS_h3ulcb = "do_extra_ipl_opt_refhw_fixup"
+do_extra_ipl_opt[postfuncs] += "${EXTRA_IPL_OPT_POSTFUNCS}"