1Corstone SSE-310 with Ethos-U55/U65 Example Subsystem for Arm Ecosystem FVP and for MPS3 (AN555)
2================================================================================================
3
4Introduction
5------------
6
7Corstone-310 (formerly Corstone-Polaris) is an Arm reference subsystem for
8secure System on Chips containing an Armv8.1-M Cortex-M85 processor and an
9Ethos-U55/U65 neural network processor. It is an MPS3 based platform with the
10usual MPS3 peripherals.
11
12This platform port supports all TF-M regression tests (Secure and Non-secure)
13with Isolation Level 1 and 2.
14
15.. note::
16
17   For Ethos-U55/U65 IP this platform support only provides base address,
18   interrupt number and an example NPU setup as non-secure, unprivileged.
19
20.. note::
21
22   For Armclang compiler v6.18 or later version is required.
23
24Building TF-M
25-------------
26
27Follow the instructions in :doc:`Building instructions </building/tfm_build_instruction>`.
28^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
29
30Build instructions with platform name: arm/mps3/corstone310/an555
31^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
32``-DTFM_PLATFORM=arm/mps3/corstone310/an555``
33
34.. note::
35
36   For Ethos-U55/U65 IP this platform support only provides base address,
37   interrupt number and an example NPU setup as non-secure, unprivileged.
38
39
40Build instructions with platform name: arm/mps3/corstone310/fvp
41^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42``-DTFM_PLATFORM=arm/mps3/corstone310/fvp``
43
44.. note::
45
46   For Ethos-U55/U65 IP this platform support only provides base address,
47   interrupt number and an example NPU setup as non-secure, unprivileged.
48
49.. note::
50
51   The built binaries can be run on the Corstone-310 Ethos-U55/U65 Ecosystem FVP
52   (FVP_SSE310_MPS3). At least Ecosystem FVP version 11.22 is required.
53
54.. note::
55
56   Provisioning bundles can be generated with the ``-DPLATFORM_DEFAULT_PROVISIONING=OFF``
57   flag. The provisioning bundle binary will be generated and it's going to contain the
58   provisioning code and provisioning values.
59
60.. note::
61
62   If ``-DPLATFORM_DEFAULT_PROVISIONING=OFF`` and ``-DTFM_DUMMY_PROVISIONING=ON`` then the keys in
63   the ``tf-m/platform/ext/target/arm/mps3/common/provisioning/provisioning_config.cmake`` and the
64   default MCUBoot signing keys will be used for provisioning.
65
66   If ``-DPLATFORM_DEFAULT_PROVISIONING=OFF`` and ``-DTFM_DUMMY_PROVISIONING=OFF`` are set
67   then unique values can be used for provisioning. The keys and seeds can be changed by
68   passing the new values to the build command, or by setting the ``-DPROVISIONING_KEYS_CONFIG`` flag
69   to a .cmake file that contains the keys. An example config cmake file can be seen at
70   ``tf-m/platform/ext/target/arm/mps3/common/provisioning/provisioning_config.cmake``.
71   Otherwise new random values are going to be generated and used. For the image signing
72   the ${MCUBOOT_KEY_S} and ${MCUBOOT_KEY_NS} will be used. These variables should point to
73   .pem files that contain the code signing private keys. The public keys are going to be generated
74   from these private keys and will be used for provisioning. The hash of the public key is going to
75   be written into the ``provisioning_data.c`` automatically.
76
77   If ``-DMCUBOOT_GENERATE_SIGNING_KEYPAIR=ON`` is set then a new mcuboot signing public and private
78   keypair is going to be generated and it's going to be used to sign the S and NS binaries.
79
80
81   The new generated keypair can be found in the ``<build dir>/bin`` folder or in the
82   ``<install directory>/image_signing/keys`` after installation.
83   The generated provisioning_data.c file can be found at
84   ``<build directory>/platform/target/provisioning/provisioning_data.c``
85
86.. note::
87
88   The provisioning bundle generation depends on pyelftools that's have to be installed::
89
90    pip3 install pyelftools
91
92To run the example code on Corstone SSE-310 with Ethos-U55/U65 Example Subsystem for MPS3 (AN555)
93-------------------------------------------------------------------------------------------------
94FPGA image is available to download `here <https://developer.arm.com/downloads/view/AN555?sortBy=availableBy&revision=r3p0-00rel0-1>`__
95
96If the link above is not working just go to `Arm PDH <https://developer.arm.com/downloads>`__ and search for AN555.
97
98To run BL2 bootloader, TF-M example application and tests in the MPS3 board,
99it is required to have AN555 image in the MPS3 board SD card. The image should
100be located in ``<MPS3 device name>/MB/HBI<BoardNumberBoardrevision>/AN555``
101
102The MPS3 board tested is HBI0309C.
103
104#. Execute the following command to create the tfm.bin binary
105   which fills the entire available space on the MPS3 onboard QSPI.
106   This way the whole flash content (PS, ITS, OTP, NV counters) is in a known state.
107   (If anything left in the QSPI, this binary will overwrite it.)
108   Also, MPS3 can only handle SFN 8.3 format, so the binary name must be shortened.::
109
110   $ cd <build dir>/bin
111   $ cp tfm_s_ns_signed.bin tfm.bin
112   $ truncate -s 8M tfm.bin
113
114#. Copy ``bl2.bin`` and ``tfm.bin`` files from
115   build dir to ``<MPS3 device name>/SOFTWARE/``
116#. Open ``<MPS3 device name>/MB/HBI0309C/AN555/images.txt``
117#. Update the ``images.txt`` file as follows::
118
119    [IMAGES]
120    TOTALIMAGES: 2
121
122    IMAGE0ADDRESS: 0x01_00_1100_0000
123    IMAGE0UPDATE: RAM
124    IMAGE0FILE: \SOFTWARE\bl2.bin
125
126    IMAGE1ADDRESS: 0x01_00_0000_0000
127    IMAGE1UPDATE: FORCEQSPI
128    IMAGE1FILE: \SOFTWARE\tfm.bin
129
130#. Close ``<MPS3 device name>/MB/HBI0309C/AN555/images.txt``
131#. Unmount/eject the ``<MPS3 device name>`` unit
132#. Reset the board to execute the TF-M example application
133#. After completing the procedure you should be able to visualize on the serial
134   port (baud 115200 8n1) the following messages::
135
136    [INF] Starting bootloader
137    [INF] Beginning BL2 provisioning
138    [WRN] TFM_DUMMY_PROVISIONING is not suitable for production! This device is NOT SECURE
139    [INF] Image index: 1, Swap type: none
140    [INF] Image index: 0, Swap type: none
141    [INF] Bootloader chainload address offset: 0x0
142    [INF] Jumping to the first image slot
143    [INF] Beginning TF-M provisioning
144    [WRN] TFM_DUMMY_PROVISIONING is not suitable for production! This device is NOT SECURE
145    [WRN] This device was provisioned with dummy keys. This device is NOT SECURE
146    [Sec Thread] Secure image initializing!
147    TF-M isolation level is: 0x00000001
148    Booting TF-M v1.8.1
149
150.. note::
151
152   Some of the messages above are only visible when ``CMAKE_BUILD_TYPE`` is set
153   to ``Debug``.
154
155.. note::
156
157   If ``-DPLATFORM_DEFAULT_PROVISIONING=OFF`` is set then the provisioning bundle has to
158   be placed on the ``0x11022400`` address by copying ``provisioning_bundle.bin`` and
159   renaming it to ``prv.bin``, then extending the images.txt with::
160
161    IMAGE2UPDATE: RAM
162    IMAGE2ADDRESS: 0x01_00_1102_2400
163    IMAGE2FILE: \SOFTWARE\prv.bin
164
165To run the example code on Corstone-310 Ethos-U55/U65 Ecosystem FVP
166-------------------------------------------------------------------
167FVP is available to download `here <https://developer.arm.com/Tools%20and%20Software/Fixed%20Virtual%20Platforms/IoT%20FVPs>`__
168
169#. Install the FVP
170#. Copy ``bl2.axf`` and ``tfm_s_ns_signed.bin`` files from
171   build dir to ``<FVP installation path>/models/Linux64_GCC-9.3/``
172#. Navigate to the same directory and execute the following command to start FVP::
173
174    $ ./FVP_Corstone_SSE-310 -a cpu0*="bl2.axf" --data "tfm_s_ns_signed.bin"@0x38000000
175
176#. After completing the procedure you should be able to see similar messages
177   to this on the serial port (baud 115200 8n1)::
178
179    Trying 127.0.0.1...
180    Connected to localhost.
181    Escape character is '^]'.
182    [INF] Starting bootloader
183    [INF] Beginning BL2 provisioning
184    [WRN] TFM_DUMMY_PROVISIONING is not suitable for production! This device is NOT SECURE
185    [INF] Image index: 1, Swap type: none
186    [INF] Image index: 0, Swap type: none
187    [INF] Bootloader chainload address offset: 0x0
188    [INF] Jumping to the first image slot
189    [INF] Beginning TF-M provisioning
190    [WRN] TFM_DUMMY_PROVISIONING is not suitable for production! This device is NOT SECURE
191    [WRN] This device was provisioned with dummy keys. This device is NOT SECURE
192    [Sec Thread] Secure image initializing!
193    TF-M isolation level is: 0x00000001
194    Booting TF-M v1.8.1
195
196.. note::
197
198   Some of the messages above are only visible when ``CMAKE_BUILD_TYPE`` is set
199   to ``Debug``.
200
201.. note::
202
203   If ``-DPLATFORM_DEFAULT_PROVISIONING=OFF`` is set then the provisioning bundle has to
204   be placed on the ``0x11022000`` address with::
205
206   $ ./FVP_Corstone_SSE-310 -a cpu0*="<path-to-build-directory>/bl2.axf" --data "<path-to-build-directory>/tfm_s_ns_signed.bin"@0x38000000 --data "<path-to-build-directory>/provisioning_bundle.bin"@0x11022000
207
208
209-------------
210
211*Copyright (c) 2021-2024, Arm Limited. All rights reserved.*
212