user-guide.rst 14.3 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
User Guide
==========

.. section-numbering::
    :suffix: .

.. contents::


Notice
------

The Total Compute 2020 (TC0) software stack uses the `Yocto project <https://www.yoctoproject.org/>`__
to build a Board Support Package (BSP) and a choice of Poky Linux distribution or Android userspace.
The Yocto project uses `Bitbake <https://www.yoctoproject.org/docs/1.6/bitbake-user-manual/bitbake-user-manual.html>`__
to build the software stack.


Prerequisites
-------------

These instructions assume that:
 * Your host PC is running Ubuntu Linux 18.04 LTS.
 * You are running the provided scripts in a ``bash`` shell environment.

The following utilities must be available on your host PC:
 * chrpath
 * compression library
 * diffstat
 * gawk
 * makeinfo
 * openssl headers
 * pip
 * repo

To resolve these dependencies, run:

::

    sudo apt-get update
    sudo apt-get install chrpath gawk texinfo libssl-dev diffstat wget git-core unzip gcc-multilib \
     build-essential socat cpio python python3 python3-pip python3-pexpect xz-utils debianutils \
     iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 xterm git-lfs openssl \
44
     curl lib32ncurses5-dev libz-dev python-pip repo u-boot-tools m4
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335

If syncing and building android, the minimum requirements for the host machine can be found at https://source.android.com/setup/build/requirements, These include:
 * At least 250GB of free disk space to check out the code and an extra 150 GB to build it. If you conduct multiple builds, you need additional space.
 * At least 16 GB of available RAM/swap.
 * Git configured properly else it may throw error while fetching the code.

Syncing and building the source code
------------------------------------

There are two distros supported in the TC0 software stack: poky (a minimal distro containing busybox) and android.

To sync code for poky, please follow the steps in "Syncing code" section for BSP only. To sync code for android, please follow the steps for syncing both BSP and Android.

To build the required binaries for poky, please follow the steps in "Board Support Package build" section only. To build the binaries for Android, please follow the steps in both "Board Support Package build" and "Android OS build" sections.

Syncing code
#####################

Create a new folder that will be your workspace, which will henceforth be referred to as ``<tc0_workspace>``
in these instructions.

::

    mkdir <tc0_workspace>
    cd <tc0_workspace>
    export TC0_RELEASE=refs/tags/TC0-2021.02.09

To sync BSP only without Android, execute the repo command.

::

    repo init -u https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-manifest -m tc0.xml -b ${TC0_RELEASE} -g bsp
    repo sync -j$(nproc)

To sync both the BSP and Android, execute the repo command.

::

    repo init -u https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-manifest -m tc0.xml -b ${TC0_RELEASE} -g android
    repo sync -j$(nproc)


Board Support Package build
############################

::

    cd <tc0_workspace>/bsp
    export DISTRO="poky"
    export MACHINE="tc0"
    source setup-environment
    bitbake tc0-artifacts-image

The initial clean build will be lengthy, given that all host utilities are to be built as well as
the target images. This includes host executables (python, cmake, etc.) and the required toolchain(s).

Once the build is successful, all images will be placed in the ``<tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0``
directory.

Note that the BSP includes the Poky Linux distribution, which offers BusyBox-like utilities.


Android OS build
#################

Two profiles are supported:

#. tc0_swr  : This supports Android display with swiftshader (software rendering).
#. tc0_nano : This supports headless Android and provides a good runtime environment for testing shell-based applications.

The android images can be built with or without authentication enabled using Android Verified Boot(AVB).
AVB build is done in userdebug mode and takes a longer time to boot as the images are verified.

The ``build-scripts/tc0/build_android.sh`` script in ``<tc0_workspace>/android`` will patch and build android. This can be passed 2 parameters, ``-d`` for deciding which profile to build and ``-a`` for enabling AVB. The following command shows the help menu for the script:

::

    cd <tc0_workspace>/android
    ./build-scripts/tc0/build_android.sh  -h
    Incorrect script use, call script as:
    <path to build_android.sh> [OPTIONS]
    OPTIONS:
    -d, --distro                            distro version, values supported [android-nano, android-swr]
    -a, --avb                               [OPTIONAL] avb boot, values supported [true, false], DEFAULT: false

As an example, to build android with software rendering and AVB enabled, execute the command:

::

  ./build-scripts/tc0/build_android.sh -d android-swr -a true

To build headless android without AVB, execute the command:

::

  ./build-scripts/tc0/build_android.sh -d android-nano

Provided components
-------------------

Within the Yocto project, each component included in the TC0 software stack is specified as
a `Bitbake recipe <https://www.yoctoproject.org/docs/1.6/bitbake-user-manual/bitbake-user-manual.html#recipes>`__.
The TC0 recipes are located at ``<tc0_workspace>/bsp/layers/meta-arm/``.

Yocto allows modifying the fetched source code of each recipe component in the
workspace, by applying patches. This is however not a convenient approach for
developers, since creating patches and updating recipes is time-consuming.
To make that easier, Yocto provides the `devtool <https://wiki.yoctoproject.org/wiki/TipsAndTricks/Patching_the_source_for_a_recipe>`__ utility. Devtool creates a
new workspace, in which you can edit the fetched source code and bake images
with the modifications

::

    cd <tc0_workspace>/bsp
    MACHINE=tc0 DISTRO=poky . ./conf/setup-environment
    # create a workspace for a given recipe component
    # recipe-component-name can be of:
    # trusted-firmware-a / scp-firmware / u-boot / linux-arm64-ack
    devtool modify <recipe-component-name>
    # This creates a new workspace for recipe-component-name and fetches source code
    # into "build-poky/workspace/sources/{trusted-firmware-a,scp-firmware,u-boot,linux-arm64-ack}"
    # edit the source code in the newly created workspace
    # build images with changes on workspace
    # recipe-component-name can be of: trusted-firmware-a / scp-firmware / u-boot / linux-arm64-ack
    bitbake <recipe-component-name>

Firmware Components
###################

Trusted Firmware-A
******************

Based on `Trusted Firmware-A <https://trustedfirmware-a.readthedocs.io/en/latest/>`__

+--------+------------------------------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-bsp/trusted-firmware-a/trusted-firmware-a-tc0.inc |
+--------+------------------------------------------------------------------------------------------------------------+
| Files  | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/bl1-tc0.bin                                    |
|        | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/fip-tc0.bin                                    |
+--------+------------------------------------------------------------------------------------------------------------+


System Control Processor (SCP)
******************************

Based on `SCP Firmware <https://github.com/ARM-software/SCP-firmware>`__

+--------+------------------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-bsp/scp-firmware/scp-firmware-tc0.inc |
+--------+------------------------------------------------------------------------------------------------+
| Files  | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/scp_ramfw.bin                      |
|        | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/scp_romfw.bin                      |
+--------+------------------------------------------------------------------------------------------------+


U-Boot
******

Based on `U-Boot gitlab <https://gitlab.denx.de/u-boot/u-boot>`__

+--------+------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-bsp/u-boot/u-boot-tc0.inc |
+--------+------------------------------------------------------------------------------------+
| Files  | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/u-boot.bin             |
+--------+------------------------------------------------------------------------------------+


Hafnium
*******

Based on `Hafnium <https://www.trustedfirmware.org/projects/hafnium>`__

+--------+--------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-bsp/hafnium/hafnium-tc0.inc |
+--------+--------------------------------------------------------------------------------------+
| Files  | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/hafnium.bin              |
+--------+--------------------------------------------------------------------------------------+


OP-TEE
******

Based on `OP-TEE <https://github.com/OP-TEE/optee_os>`__

+--------+------------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-security/optee/optee-os-tc0.inc |
+--------+------------------------------------------------------------------------------------------+
| Files  | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/optee/tee-pager_v2.bin       |
+--------+------------------------------------------------------------------------------------------+


Linux
*****

The recipe responsible for building a 4.19 version of the Android Common kernel (`ACK <https://android.googlesource.com/kernel/common/>`__).

+--------+-----------------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-kernel/linux/linux-arm64-ack-tc0.inc |
+--------+-----------------------------------------------------------------------------------------------+
| Files  | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/Image                             |
+--------+-----------------------------------------------------------------------------------------------+


Poky Linux distro
*****************

The layer is based on the `poky <https://www.yoctoproject.org/software-item/poky/>`__ Linux distribution.
The provided distribution is based on BusyBox and built using glibc.

+--------+---------------------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/openembedded-core/meta/recipes-core/images/core-image-minimal.bb       |
+--------+---------------------------------------------------------------------------------------------------+
| Files  | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/fitImage-core-image-minimal-tc0-tc0   |
+--------+---------------------------------------------------------------------------------------------------+


Android
*******

Android 10 is supported in this release with device profiles suitable for TC0 machine configuration.
Android is built as a separate project and then booted with the BSP built by Yocto.


Run scripts
###########

Within the ``<tc0_workspace>/bsp/run-scripts/`` are several convenience functions for testing the software
stack. Usage descriptions for the various scripts are provided in the following sections.


Running the software on FVP
---------------------------

A Fixed Virtual Platform (FVP) of the TC0 platform must be available to execute the included run scripts.

The run-scripts structure is as follows:

::

    run-scripts
    |--tc0
       |--run_model.sh
       |-- ...

Ensure that all dependencies are met by executing the FVP: ``./path/to/FVP_TC0``. You should see
the FVP launch, presenting a graphical interface showing information about the current state of the FVP.

The ``run_model.sh`` script in ``<tc0_workspace>/bsp/run-scripts/tc0`` will launch the FVP, providing
the previously built images as arguments. Execute the ``run_model.sh`` script:

::

       ./run_model.sh
       Incorrect script use, call script as:
       <path_to_run_model.sh> [OPTIONS]
       OPTIONS:
       -m, --model                      path to model
       -d, --distro                     distro version, values supported [poky, android-nano, android-swr]
       -a, --avb                        [OPTIONAL] avb boot, values supported [true, false], DEFAULT: false
       -t, --tap-interface              [OPTIONAL] enable TAP interface
       -e, --extra-model-params	        [OPTIONAL] extra model parameters
       If using an android distro, export ANDROID_PRODUCT_OUT variable to point to android out directory
       for eg. ANDROID_PRODUCT_OUT=<tc0_workspace>/android/out/target/product/tc0_swr

       For running Poky:
        ./run-scripts/tc0/run_model.sh -m <model binary path> -d poky

       For running android with AVB disabled:
        ./run-scripts/tc0/run_model.sh -m <model binary path> -d android-swr
        OR
        ./run-scripts/tc0/run_model.sh -m <model binary path> -d android-nano

       For running android with AVB enabled:
        ./run-scripts/tc0/run_model.sh -m <model binary path> -d android-swr -a true
        OR
        ./run-scripts/tc0/run_model.sh -m <model binary path> -d android-nano -a true

When the script is executed, two terminal instances will be launched. terminal_s0 used for the SCP,
TF-A, OP-TEE core logs and terminal_s1 used by TF-A early boot, Hafnium, U-boot and Linux.

Once the FVP is running, the SCP will be the first to boot, bringing the AP out of reset.
The AP will start booting from its ROM and then proceed to boot Trusted Firmware-A, Hafnium, OP-TEE
then U-Boot, and then Linux and Poky/Android.

When booting Poky the model will boot Linux and present a login prompt. Login using the username ``root``.
You may need to hit Enter for the prompt to appear. The OP-TEE OS works on both the Android and Poky distro, but
can be tested only on Poky using optee-test (xtest) simply by typing ``xtest`` on the linux shell.

--------------

*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*