1Arm Juno Development Platform
2=============================
3
4Platform-specific build options
5-------------------------------
6
7-  ``JUNO_TZMP1`` : Boolean option to configure Juno to be used for TrustZone
8   Media Protection (TZ-MP1). Default value of this flag is 0.
9
10Running software on Juno
11------------------------
12
13This version of TF-A has been tested on variants r0, r1 and r2 of Juno.
14
15To run TF-A on Juno, you need to first prepare an SD card with Juno software
16stack that includes TF-A. This version of TF-A is tested with pre-built
17`Linaro release software stack`_ version 20.01. You can alternatively
18build the software stack yourself by following the
19`Juno platform software user guide`_. Once you prepare the software stack
20on an SD card, you can replace the ``bl1.bin`` and ``fip.bin``
21binaries in the ``SOFTWARE/`` directory with custom built TF-A binaries.
22
23Preparing TF-A images
24---------------------
25
26This section provides Juno and FVP specific instructions to build Trusted
27Firmware, obtain the additional required firmware, and pack it all together in
28a single FIP binary. It assumes that a Linaro release software stack has been
29installed.
30
31.. note::
32   Pre-built binaries for AArch32 are available from Linaro Release 16.12
33   onwards. Before that release, pre-built binaries are only available for
34   AArch64.
35
36.. warning::
37   Follow the full instructions for one platform before switching to a
38   different one. Mixing instructions for different platforms may result in
39   corrupted binaries.
40
41.. warning::
42   The uboot image downloaded by the Linaro workspace script does not always
43   match the uboot image packaged as BL33 in the corresponding fip file. It is
44   recommended to use the version that is packaged in the fip file using the
45   instructions below.
46
47.. note::
48   For the FVP, the kernel FDT is packaged in FIP during build and loaded
49   by the firmware at runtime.
50
51#. Clean the working directory
52
53   .. code:: shell
54
55       make realclean
56
57#. Obtain SCP binaries (Juno)
58
59   This version of TF-A is tested with SCP version 2.8.0 on Juno. You can
60   download pre-built SCP binaries (``scp_bl1.bin`` and ``scp_bl2.bin``)
61   from `TF-A downloads page`_. Alternatively, you can `build
62   the binaries from source`_.
63
64#. Obtain BL33 (all platforms)
65
66   Use the fiptool to extract the BL33 image from the FIP
67   package included in the Linaro release:
68
69   .. code:: shell
70
71       # Build the fiptool
72       make [DEBUG=1] [V=1] fiptool
73
74       # Unpack firmware images from Linaro FIP
75       ./tools/fiptool/fiptool unpack <path-to-linaro-release>/[SOFTWARE]/fip.bin
76
77   The unpack operation will result in a set of binary images extracted to the
78   current working directory. BL33 corresponds to ``nt-fw.bin``.
79
80   .. note::
81      The fiptool will complain if the images to be unpacked already
82      exist in the current directory. If that is the case, either delete those
83      files or use the ``--force`` option to overwrite.
84
85   .. note::
86      For AArch32, the instructions below assume that nt-fw.bin is a
87      normal world boot loader that supports AArch32.
88
89#. Build TF-A images and create a new FIP for FVP
90
91   .. code:: shell
92
93       # AArch64
94       make PLAT=fvp BL33=nt-fw.bin all fip
95
96       # AArch32
97       make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip
98
99#. Build TF-A images and create a new FIP for Juno
100
101   For AArch64:
102
103   Building for AArch64 on Juno simply requires the addition of ``SCP_BL2``
104   as a build parameter.
105
106   .. code:: shell
107
108       make PLAT=juno BL33=nt-fw.bin SCP_BL2=scp_bl2.bin all fip
109
110   For AArch32:
111
112   Hardware restrictions on Juno prevent cold reset into AArch32 execution mode,
113   therefore BL1 and BL2 must be compiled for AArch64, and BL32 is compiled
114   separately for AArch32.
115
116   -  Before building BL32, the environment variable ``CROSS_COMPILE`` must point
117      to the AArch32 Linaro cross compiler.
118
119      .. code:: shell
120
121          export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
122
123   -  Build BL32 in AArch32.
124
125      .. code:: shell
126
127          make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \
128          RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32
129
130   -  Save ``bl32.bin`` to a temporary location and clean the build products.
131
132      ::
133
134          cp <path-to-build>/bl32.bin <path-to-temporary>
135          make realclean
136
137   -  Before building BL1 and BL2, the environment variable ``CROSS_COMPILE``
138      must point to the AArch64 Linaro cross compiler.
139
140      .. code:: shell
141
142          export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-
143
144   -  The following parameters should be used to build BL1 and BL2 in AArch64
145      and point to the BL32 file.
146
147      .. code:: shell
148
149          make ARCH=aarch64 PLAT=juno JUNO_AARCH32_EL3_RUNTIME=1 \
150          BL33=nt-fw.bin SCP_BL2=scp_bl2.bin \
151          BL32=<path-to-temporary>/bl32.bin all fip
152
153The resulting BL1 and FIP images may be found in:
154
155::
156
157    # Juno
158    ./build/juno/release/bl1.bin
159    ./build/juno/release/fip.bin
160
161    # FVP
162    ./build/fvp/release/bl1.bin
163    ./build/fvp/release/fip.bin
164
165After building TF-A, the files ``bl1.bin``, ``fip.bin`` and ``scp_bl1.bin``
166need to be copied to the ``SOFTWARE/`` directory on the Juno SD card.
167
168Booting Firmware Update images
169------------------------------
170
171The new images must be programmed in flash memory by adding
172an entry in the ``SITE1/HBI0262x/images.txt`` configuration file
173on the Juno SD card (where ``x`` depends on the revision of the Juno board).
174Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory
175programming" for more information. User should ensure these do not
176overlap with any other entries in the file.
177
178::
179
180        NOR10UPDATE: AUTO                       ;Image Update:NONE/AUTO/FORCE
181        NOR10ADDRESS: 0x00400000                ;Image Flash Address [ns_bl2u_base_address]
182        NOR10FILE: \SOFTWARE\fwu_fip.bin        ;Image File Name
183        NOR10LOAD: 00000000                     ;Image Load Address
184        NOR10ENTRY: 00000000                    ;Image Entry Point
185
186        NOR11UPDATE: AUTO                       ;Image Update:NONE/AUTO/FORCE
187        NOR11ADDRESS: 0x03EB8000                ;Image Flash Address [ns_bl1u_base_address]
188        NOR11FILE: \SOFTWARE\ns_bl1u.bin        ;Image File Name
189        NOR11LOAD: 00000000                     ;Image Load Address
190
191The address ns_bl1u_base_address is the value of NS_BL1U_BASE - 0x8000000.
192In the same way, the address ns_bl2u_base_address is the value of
193NS_BL2U_BASE - 0x8000000.
194
195.. _plat_juno_booting_el3_payload:
196
197Booting an EL3 payload
198----------------------
199
200If the EL3 payload is able to execute in place, it may be programmed in flash
201memory by adding an entry in the ``SITE1/HBI0262x/images.txt`` configuration file
202on the Juno SD card (where ``x`` depends on the revision of the Juno board).
203Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory
204programming" for more information.
205
206Alternatively, the same DS-5 command mentioned in the FVP section above can
207be used to load the EL3 payload's ELF file over JTAG on Juno.
208
209For more information on EL3 payloads in general, see
210:ref:`alt_boot_flows_el3_payload`.
211
212Booting a preloaded kernel image
213--------------------------------
214
215The Trusted Firmware must be compiled in a similar way as for FVP explained
216above. The process to load binaries to memory is the one explained in
217`plat_juno_booting_el3_payload`_.
218
219Testing System Suspend
220----------------------
221
222The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend
223to RAM. For more details refer to section 5.16 of `PSCI`_. To test system suspend
224on Juno, at the linux shell prompt, issue the following command:
225
226.. code:: shell
227
228    echo +10 > /sys/class/rtc/rtc0/wakealarm
229    echo -n mem > /sys/power/state
230
231The Juno board should suspend to RAM and then wakeup after 10 seconds due to
232wakeup interrupt from RTC.
233
234Additional Resources
235--------------------
236
237Please visit the `Arm Platforms Portal`_ to get support and obtain any other Juno
238software information. Please also refer to the `Juno Getting Started Guide`_ to
239get more detailed information about the Juno Arm development platform and how to
240configure it.
241
242--------------
243
244*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
245
246.. _Linaro release software stack: http://releases.linaro.org/members/arm/platforms/
247.. _Juno platform software user guide: https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about/docs/juno/user-guide.rst
248.. _TF-A downloads page: https://downloads.trustedfirmware.org/tf-a/css_scp_2.8.0/juno/
249.. _build the binaries from source: https://github.com/ARM-software/SCP-firmware/blob/master/user_guide.md#scp-firmware-user-guide
250.. _Arm Platforms Portal: https://community.arm.com/dev-platforms/
251.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
252.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
253.. _Juno Arm Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php
254