1Arm China Alcor with Cortex-M52 Example Subsystem for MPS3 (AN557)
2=======================================================================================================
3Introduction
4------------
5
6Alcor is an ArmChina reference subsystem for secure System
7on Chips containing an Armv8.1-M Cortex-M52 processor.
8It is an MPS3 based platform with the usual MPS3 peripherals.
9
10This platform port supports all TF-M regression tests (Secure and Non-secure)
11with Isolation Level 1 and 2.
12
13.. note::
14
15   For Armclang compiler v6.18 or later version is required.
16
17Building TF-M
18-------------
19
20Follow the instructions in :doc:`Building instructions </building/tfm_build_instruction>`.
21^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
22
23Build instructions with platform name: armchina/mps3/alcor/an557
24^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
25``-DTFM_PLATFORM=armchina/mps3/alcor/an557``
26
27.. note::
28
29   Provisioning bundles can be generated with the ``-DPLATFORM_DEFAULT_PROVISIONING=OFF``
30   flag. The provisioning bundle binary will be generated and it's going to contain the
31   provisioning code and provisioning values.
32
33.. note::
34
35   If ``-DPLATFORM_DEFAULT_PROVISIONING=OFF`` and ``-DTFM_DUMMY_PROVISIONING=ON`` then the keys in
36   the ``tf-m/platform/ext/target/armchina/mps3/common/provisioning/provisioning_config.cmake`` and the
37   default MCUBoot signing keys will be used for provisioning.
38
39   If ``-DPLATFORM_DEFAULT_PROVISIONING=OFF`` and ``-DTFM_DUMMY_PROVISIONING=OFF`` are set
40   then unique values can be used for provisioning. The keys and seeds can be changed by
41   passing the new values to the build command, or by setting the ``-DPROVISIONING_KEYS_CONFIG`` flag
42   to a .cmake file that contains the keys. An example config cmake file can be seen at
43   ``tf-m/platform/ext/target/armchina/mps3/common/provisioning/provisioning_config.cmake``.
44   Otherwise new random values are going to be generated and used. For the image signing
45   the ${MCUBOOT_KEY_S} and ${MCUBOOT_KEY_NS} will be used. These variables should point to
46   .pem files that contain the code signing private keys. The public keys are going to be generated
47   from these private keys and will be used for provisioning. The hash of the public key is going to
48   be written into the ``provisioning_data.c`` automatically.
49
50   If ``-DMCUBOOT_GENERATE_SIGNING_KEYPAIR=ON`` is set then a new mcuboot signing public and private
51   keypair is going to be generated and it's going to be used to sign the S and NS binaries.
52
53   The new generated keypair can be found in the ``<build dir>/bin`` folder or in the
54   ``<install directory>/image_signing/keys`` after installation.
55   The generated provisioning_data.c file can be found at
56   ``<build directory>/platform/target/provisioning/provisioning_data.c``
57
58.. note::
59
60   The provisioning bundle generation depends on pyelftools that's have to be installed::
61
62    pip3 install pyelftools
63
64To run the example code on Arm China Alcor with Cortex-M52 Example Subsystem for MPS3 (AN557)
65-------------------------------------------------------------------------------------------------
66
67To run BL2 bootloader, TF-M example application and tests in the MPS3 board,
68it is required to have AN557 image in the MPS3 board SD card. The image should
69be located in ``<MPS3 device name>/MB/HBI<BoardNumberBoardrevision>/AN557``
70
71The MPS3 board tested is HBI0309C.
72
73#. Copy ``bl2.bin`` and ``tfm_s_ns_signed.bin`` files from
74   build dir to ``<MPS3 device name>/SOFTWARE/``
75#. Rename ``tfm_s_ns_signed.bin`` to ``tfm.bin`` (Filename should not be longer
76   than 8 characters.)
77#. Open ``<MPS3 device name>/MB/HBI0309C/AN557/images.txt``
78#. Update the ``images.txt`` file as follows::
79
80    TITLE: Arm MPS3 FPGA prototyping board Images Configuration File
81
82    [IMAGES]
83    TOTALIMAGES: 2                     ;Number of Images (Max: 32)
84
85    IMAGE0UPDATE: AUTO                 ;Image Update:NONE/AUTO/FORCE
86    IMAGE0ADDRESS: 0x00000000          ;Please select the required executable program
87    IMAGE0FILE: \SOFTWARE\bl2.bin
88    IMAGE1UPDATE: FORCEQSPI
89    IMAGE1ADDRESS: 0x00000000
90    IMAGE1FILE: \SOFTWARE\tfm.bin
91
92#. Close ``<MPS3 device name>/MB/HBI0309C/AN557/images.txt``
93#. Unmount/eject the ``<MPS3 device name>`` unit
94#. Reset the board to execute the TF-M example application
95#. After completing the procedure you should be able to visualize on the serial
96   port (baud 115200 8n1) the following messages::
97
98    [INF] Starting bootloader
99    [INF] Beginning BL2 provisioning
100    [WRN] TFM_DUMMY_PROVISIONING is not suitable for production! This device is NOT SECURE
101    [INF] Image index: 1, Swap type: none
102    [INF] Image index: 0, Swap type: none
103    [INF] Bootloader chainload address offset: 0x0
104    [INF] Jumping to the first image slot
105    [INF] Beginning TF-M provisioning
106    [WRN] TFM_DUMMY_PROVISIONING is not suitable for production! This device is NOT SECURE
107    [WRN] This device was provisioned with dummy keys. This device is NOT SECURE
108    [Sec Thread] Secure image initializing!
109    TF-M isolation level is: 0x00000001
110    Booting TF-M v2.0.0
111
112.. note::
113
114   Some of the messages above are only visible when ``CMAKE_BUILD_TYPE`` is set
115   to ``Debug``.
116
117.. note::
118
119   If ``-DPLATFORM_DEFAULT_PROVISIONING=OFF`` is set then the provisioning bundle has to
120   be placed on the ``0x10022400`` address by copying ``encrypted_provisioning_bundle.bin`` and
121   renaming it to ``prv.bin``, then extending the images.txt with::
122
123    IMAGE2UPDATE: AUTO
124    IMAGE2ADDRESS: 0x00022400
125    IMAGE2FILE: \SOFTWARE\prv.bin
126
127
128-------------
129
130*Copyright (c) 2020-2023, Arm Limited. All rights reserved.*
131*Copyright (c) 2024, ArmChina. All rights reserved.*
132