1MAX32657
2========
3
4
5Introduction
6------------
7
8The MAX32657 microcontroller (MCU) is an advanced system-on-chip (SoC)
9featuring an Arm® Cortex®-M33 core with single-precision floating point unit (FPU)
10with digital signal processing (DSP) instructions, large flash and SRAM memories,
11and the latest generation Bluetooth® 5.4 Low Energy (LE) radio.
12The nano-power modes increase battery life substantially.
13
14MAX32657 1MB flash and 256KB RAM split to define section for MCUBoot,
15TF-M (S), Zephyr (NS) and storage that used for secure services and configurations.
16Default layout of MAX32657 is listed in below table.
17
18+----------+------------------+---------------------------------+
19| Name     | Address[Size]    | Comment                         |
20+==========+==================+=================================+
21| boot     | 0x1000000[64K]   | MCU Bootloader                  |
22+----------+------------------+---------------------------------+
23| slot0    | 0x1010000[320k]  | Secure image slot0 (TF-M)       |
24+----------+------------------+---------------------------------+
25| slot0_ns | 0x1060000[576k]  | Non-secure image slot0          |
26+----------+------------------+---------------------------------+
27| slot1    | 0x10F0000[0k]    | Updates slot0 image             |
28+----------+------------------+---------------------------------+
29| slot1_ns | 0x10F0000[0k]    | Updates slot0_ns image          |
30+----------+------------------+---------------------------------+
31| storage  | 0x10f0000[64k]   | File system, persistent storage |
32+----------+------------------+---------------------------------+
33
34
35+----------------+------------------+-------------------+
36| RAM            | Address[Size]    | Comment           |
37+================+==================+===================+
38| secure_ram     | 0x30000000[64k]  | Secure memory     |
39+----------------+------------------+-------------------+
40| non_secure_ram | 0x20010000[192k] | Non-Secure memory |
41+----------------+------------------+-------------------+
42
43
44Secure Boot ROM
45---------------
46
47MAX32657 has Secure Boot ROM that used to authenticate user code via ECDSA 256 public key.
48The Secure Boot ROM is disabled on default, to enable it user need to provision device first.
49
50ADI provides enable_secure_boot.py (under <CMAKE_BINARY_DIR>/lib/ext/tesa-toolkit-src/devices/max32657/scripts/bl1_provision)
51script to simply provision the device. This script reads user certificate via command line parameter
52then writes user key on the device and disables debug interface.
53
54To create pub & private key pair for MAX32657 run:
55
56.. code-block:: bash
57
58    openssl ecparam -out <MY_CERT_FILE.pem> -genkey -name prime256v1
59
60
61.. note::
62
63   Debug interface will be disabled after secure boot is enabled.
64   User must write final firmware before provisioning the device. It can
65   be written during device provision, Just add your final firmware hex file in
66   JLinkScript under <CMAKE_BINARY_DIR>/lib/ext/tesa-toolkit-src/devices/max32657/scripts/bl1_provision folder.
67
68
69After secure boot has been enabled BL2 image must be signed with user certificate
70otherwise Secure Boot ROM will not validate BL2 image and will not execute it.
71The sign process will be done automatically if BL1 be ON ``-DBL1=ON``
72The sign key can be specified over command line option -DTFM_BL2_SIGNING_KEY_PATH=<MY_KEY_FILE>
73or by setting the flag in <TF-M base folder>/platform/ext/target/adi/max32657/config.cmake
74Development purpose test certificate is here:
75<CMAKE_BINARY_DIR>/lib/ext/tesa-toolkit-src/devices/max32657/keys/bl1_dummy.pem
76It shall not been used for production purpose just for development purpose.
77
78.. note::
79
80   The signature generation depends on ecdsa that's have to be installed::
81
82    pip3 install ecdsa
83
84
85Building TF-M
86-------------
87
88This platform port supports TF-M regression tests (Secure and Non-secure)
89with Isolation Level 1.
90
91To build S and NS application, run the following commands:
92
93.. note::
94
95   Only GNU toolchain is supported.
96
97.. note::
98
99   Only "profile_small" predefined profile is supported.
100
101Prepare the tf-m-tests repository inside the TF-M base folder.
102
103.. code-block:: bash
104
105    cd <TF-M base folder>
106    git clone https://git.trustedfirmware.org/TF-M/tf-m-tests.git
107
108.. code:: bash
109
110    cd <TF-M base folder>/tf-m-test/tests_reg
111
112    cmake -S spe -B build_spe \
113            -G"Unix Makefiles"               \
114            -DTFM_PLATFORM=adi/max32657      \
115            -DCONFIG_TFM_SOURCE_PATH=<TF-M base folder>/trusted-firmware-m \
116            -DTFM_TOOLCHAIN_FILE=<TF-M base folder>/trusted-firmware-m/toolchain_GNUARM.cmake \
117            -DTEST_S=OFF                \
118            -DTEST_NS=ON               \
119            -DTFM_NS_REG_TEST=ON        \
120            -DTFM_BL2_LOG_LEVEL=LOG_LEVEL_INFO  \
121            -DTFM_ISOLATION_LEVEL=1
122    cmake --build build_spe -- install
123
124    cmake -S . -B build_test    \
125            -G"Unix Makefiles"  \
126            -DCONFIG_SPE_PATH=<TF-M base folder>/tf-m-tests/tests_reg/build_spe/api_ns \
127            -DTFM_TOOLCHAIN_FILE=cmake/toolchain_ns_GNUARM.cmake \
128            -DTFM_NS_REG_TEST=ON
129    cmake --build build_test
130
131
132Merge and Flash Images
133----------------------
134
135Follow the steps below to program the flash with a compiled TF-M image (i.e. S, NS or both).
136
137
138Generate Intel hex files from the output binary (bin) files as follows:
139
140.. code-block:: console
141
142    srec_cat build_spe/bin/tfm_s_signed.bin -binary --offset 0x01010000 -o build_spe/bin/tfm_s_signed.hex -intel
143    srec_cat build_test/bin/tfm_ns_signed.bin -binary --offset 0x01060000 -o build_test/bin/tfm_ns_signed.hex -intel
144
145
146Merge hex files as follows:
147
148.. code-block:: console
149
150    srec_cat build_spe/bin/bl2.hex -Intel build_spe/bin/tfm_s_signed.hex -Intel build_test/bin/tfm_ns_signed.hex -Intel -o tfm_merged.hex -Intel
151
152Alternatively, you can merge hex files with `mergehex.py <https://github.com/zephyrproject-rtos/zephyr/blob/main/scripts/build/mergehex.py>`_
153
154.. code-block:: console
155
156    python /PATH/TO/mergehex.py -o tfm_merged.hex build_spe/bin/bl2.hex build_spe/bin/tfm_s_signed.hex build_test/bin/tfm_ns_signed.hex
157
158.. note::
159
160   Use bl2_signed.hex instead bl2.hex if Secure Boot ROM is enabled.
161
162
163Flash them with JLink as follows:
164
165.. code-block:: console
166
167    JLinkExe -device MAX32657 -if swd -speed 2000 -autoconnect 1
168    J-Link>h
169    J-Link>r
170    J-Link>erase
171    J-Link>loadfile build_spe/bin/tfm_merged.hex
172
173
174BL2 and TF-M Provisioning
175-------------------------
176
177On default ``-DPLATFORM_DEFAULT_PROVISIONING=ON`` and ``-DTFM_DUMMY_PROVISIONING=ON``
178which will use default provisioning and dummpy keys, these configuration is fine
179for development purpose but for production customer specific keys shall be used
180Provisioning bundles can be generated with the ``-DPLATFORM_DEFAULT_PROVISIONING=OFF`` flag.
181The provisioning bundle binary will be generated and it's going to contain
182the provisioning code and provisioning values.
183
184If ``-DPLATFORM_DEFAULT_PROVISIONING=OFF`` and ``-DTFM_DUMMY_PROVISIONING=ON`` then the keys in
185the ``tf-m/platform/ext/target/common/provisioning/provisioning_config.cmake`` and the
186default MCUBoot signing keys will be used for provisioning.
187
188If ``-DPLATFORM_DEFAULT_PROVISIONING=OFF`` and ``-DTFM_DUMMY_PROVISIONING=OFF`` are set
189then unique values can be used for provisioning. The keys and seeds can be changed by
190passing the new values to the build command, or by setting the ``-DPROVISIONING_KEYS_CONFIG`` flag
191to a .cmake file that contains the keys. An example config cmake file can be seen at
192``tf-m/platform/ext/target/common/provisioning/provisioning_config.cmake``.
193Otherwise new random values are going to be generated and used. For the image signing
194the ${MCUBOOT_KEY_S} and ${MCUBOOT_KEY_NS} will be used. These variables should point to
195.pem files that contain the code signing private keys. The public keys are going to be generated
196from these private keys and will be used for provisioning. The hash of the public key is going to
197be written into the ``provisioning_data.c`` automatically.
198
199If ``-DMCUBOOT_GENERATE_SIGNING_KEYPAIR=ON`` is set then a new mcuboot signing public and private
200keypair is going to be generated and it's going to be used to sign the S and NS binaries.
201
202The new generated keypair can be found in the ``<build dir>/bin`` folder or in the
203``<install directory>/image_signing/keys`` after installation.
204The generated provisioning_data.c file can be found at
205``<build directory>/platform/target/provisioning/provisioning_data.c``
206
207.. note::
208
209   The provisioning bundle generation depends on pyelftools that's have to be installed::
210
211    pip3 install pyelftools
212
213UART Console
214************
215
216MAX32657 has one UART (UART0) peripheral which is routed for Non-Secure console output by default.
217S and NS firmware can not use UART at the same time.
218If TFM_S_REG_TEST been defined the UART console will be routed to the Secure side otherwise it will
219be on NS side.
220
221--------------
222
223*Copyright 2025 Analog Devices, Inc. All rights reserved.
224*SPDX-License-Identifier: BSD-3-Clause*
225