1.. _target-stm32f429i-disc1: 2 3---------------- 4stm32f429i-disc1 5---------------- 6The STMicroelectronics STM32F429I-DISC1 development board is currently Pigweed's 7primary target for on-device testing and development. 8 9Building 10======== 11To build for this Pigweed target, simply build the top-level "stm32f429i" Ninja 12target. 13 14.. code-block:: sh 15 16 $ ninja -C out stm32f429i 17 18Testing 19======= 20When working in upstream Pigweed, building this target will build all Pigweed modules' unit tests. 21These tests can be run on-device in a few different ways. 22 23Run a unit test 24--------------- 25If using ``out`` as a build directory, tests will be located in 26``out/stm32f429i_disc1_debug/obj/[module name]/[test_name].elf``. To run these 27on device, the stm32f429i-disc1 target provides a helper script that flashes the 28test to a device and then runs it. 29 30.. code-block:: sh 31 32 # Setup pigweed environment. 33 $ source activate.sh 34 # Run test. 35 $ stm32f429i_disc1_unit_test_runner /path/to/binary 36 37Run multiple tests 38------------------ 39Running all tests one-by-one is rather tedious. To make running multiple 40tests easier, use Pigweed's ``pw test`` command and pass it a path to the build 41directory and the name of the test runner. By default, ``pw test`` will run all 42tests, but it can be restricted it to specific ``pw_test_group`` targets using 43the ``--group`` argument. Alternatively, individual test binaries can be 44specified with the ``--test`` option. 45 46.. code-block:: sh 47 48 # Setup Pigweed environment. 49 $ source activate.sh 50 # Run test. 51 $ pw test --root out/stm32f429i_disc_debug/ \ 52 --runner stm32f429i_disc1_unit_test_runner 53 54Run tests affected by code changes 55---------------------------------- 56When writing code that will impact multiple modules, it's helpful to only run 57all tests that are affected by a given code change. Thanks to the GN/Ninja 58build, this is possible! This is done by using a ``pw_target_runner_server`` 59that Ninja can send the tests to as it rebuilds affected targets. 60 61Additionally, this method enables distributed testing. If multiple devices are 62connected, the tests will be run across all attached devices to further speed up 63testing. 64 65Step 1: Start test server 66^^^^^^^^^^^^^^^^^^^^^^^^^ 67To allow Ninja to properly serialize tests to run on an arbitrary number of 68devices, Ninja will send test requests to a server running in the background. 69The first step is to launch this server. By default, the script will attempt 70to automatically detect all attached STM32f429I-DISC1 boards and use them for 71testing. To override this behavior, provide a custom server configuration file 72with ``--server-config``. 73 74.. tip:: 75 76 If you unplug or plug in any boards, you'll need to restart the test server 77 for hardware changes to properly be detected. 78 79.. code-block:: sh 80 81 $ stm32f429i_disc1_test_server 82 83Step 2: Configure GN 84^^^^^^^^^^^^^^^^^^^^ 85By default, this hardware target has incremental testing via 86``pw_target_runner`` disabled. Enabling the ``pw_use_test_server`` build arg 87tells GN to send requests to a running ``stm32f429i_disc1_test_server``. 88 89.. code-block:: sh 90 91 $ gn args out 92 # Modify and save the args file to use pw_target_runner. 93 pw_use_test_server = true 94 95Step 3: Build changes 96^^^^^^^^^^^^^^^^^^^^^ 97Whenever you run ``ninja -C out stm32f429i``, affected tests will be built and 98run on the attached device(s). Alternatively, you may use ``pw watch`` to set up 99Pigweed to build/test whenever it sees changes to source files. 100 101RPC server 102========== 103The stm32f429i target implements a system RPC server that over a simple UART 104driver. To communicate with a device running the RPC server, run 105``pw rpc -d <device> -b 115200 <protos>``. 106 107Debugging 108========= 109There are multiple ways to debug the device, including using commercial tools 110like SEGGER's J-Link. However, the Discovery board has an on-board STLink 111debugger, which is supported by the open source OpenOCD debugger. To debug with 112OpenOCD requires a few steps. Summary version of the steps: 113 114#. Connect OpenOCD to the device in terminal A. Leave this running 115 116 .. code-block:: sh 117 118 $ openocd -f targets/stm32f429i_disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg 119 120#. Connect GDB to the running OpenOCD instance in terminal B 121 122 .. code-block:: sh 123 124 $ arm-none-eabi-gdb -ex "target remote :3333" \ 125 out/stm32f429i_disc1_debug/obj/pw_assert/test/assert_facade_test.elf 126 127#. Flash (``load``), run (``mon reset run; continue``), and debug 128 129 .. code-block:: none 130 131 (gdb) set print pretty on 132 (gdb) load 133 (gdb) mon reset run 134 (gdb) continue 135 136#. You can re-flash the device after compiling by running ``load``. 137 138 139Step 1: Start an OpenOCD server and connect to the device 140--------------------------------------------------------- 141OpenOCD is a persistent server that you run and leave running to bridge between 142GDB and the device. To run it for the Discovery board: 143 144.. code-block:: sh 145 146 $ openocd -f targets/stm32f429i_disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg 147 148Typical output: 149 150.. code-block:: none 151 152 Open On-Chip Debugger 0.10.0+dev-01243-ge41c0f49-dirty (2020-05-21-10:27) 153 Licensed under GNU GPL v2 154 For bug reports, read 155 http://openocd.org/doc/doxygen/bugs.html 156 DEPRECATED! use 'adapter driver' not 'interface' 157 Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD 158 srst_only separate srst_nogate srst_open_drain connect_deassert_srst 159 160 Info : Listening on port 6666 for tcl connections 161 Info : Listening on port 4444 for telnet connections 162 Info : clock speed 2000 kHz 163 Info : STLINK V2J25M14 (API v2) VID:PID 0483:374B 164 Info : Target voltage: 2.871879 165 Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints 166 Info : starting gdb server for stm32f4x.cpu on 3333 167 Info : Listening on port 3333 for gdb connections 168 169Step 2: Start GDB and connect to the OpenOCD server 170--------------------------------------------------- 171Start GDB pointing to the correct .elf file, and tell it to connect to the 172OpenOCD server (running on port 333 by default). 173 174.. code-block:: sh 175 176 $ arm-none-eabi-gdb -ex "target remote :3333" \ 177 out/stm32f429i_disc1_debug/obj/pw_assert/test/assert_facade_test.elf 178 179In this case the assert facade test is debugged, but substitute your own ELF 180file. This should produce output similar to the following: 181 182.. code-block:: none 183 184 GNU gdb (GNU Arm Embedded Toolchain 9-2020-q2-update) 8.3.1.20191211-git 185 Copyright (C) 2019 Free Software Foundation, Inc. 186 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> 187 This is free software: you are free to change and redistribute it. 188 There is NO WARRANTY, to the extent permitted by law. 189 Type "show copying" and "show warranty" for details. 190 This GDB was configured as "--host=x86_64-apple-darwin10 --target=arm-none-eabi". 191 Type "show configuration" for configuration details. 192 For bug reporting instructions, please see: 193 <http://www.gnu.org/software/gdb/bugs/>. 194 Find the GDB manual and other documentation resources online at: 195 <http://www.gnu.org/software/gdb/documentation/>. 196 197 For help, type "help". 198 Type "apropos word" to search for commands related to "word"... 199 Reading symbols from out/stm32f429i_disc1_debug/obj/pw_assert//test/assert_facade_test.elf... 200 Remote debugging using :3333 201 pw_BootEntry () at ../pw_boot_cortex_m/core_init.c:117 202 117 } 203 204Step 3: Flash, run, and debug 205----------------------------- 206Now that the GDB instance is connected to the device, you can flash, run, and debug. 207 208To flash 209 210.. code-block:: none 211 212 (gdb) load 213 214This will produce output similar to: 215 216.. code-block:: none 217 218 (gdb) load 219 Loading section .vector_table, size 0x10 lma 0x8000000 220 Loading section .code, size 0xdb8c lma 0x8000200 221 Loading section .ARM, size 0x8 lma 0x800dd90 222 Loading section .static_init_ram, size 0x1d0 lma 0x800dd98 223 Start address 0x8007c48, load size 56692 224 Transfer rate: 25 KB/sec, 8098 bytes/write. 225 226To reset the device and halt on the first instruction (before main): 227 228.. code-block:: none 229 230 (gdb) mon reset run 231 232 233This will produce output similar to: 234 235.. code-block:: none 236 237 (gdb) mon reset run 238 Unable to match requested speed 2000 kHz, using 1800 kHz 239 Unable to match requested speed 2000 kHz, using 1800 kHz 240 target halted due to debug-request, current mode: Thread 241 xPSR: 0x01000000 pc: 0x08007930 msp: 0x20030000 242 Unable to match requested speed 8000 kHz, using 4000 kHz 243 Unable to match requested speed 8000 kHz, using 4000 kHz 244 245The device is now ready for debugging. You can place breakpoints and start the 246device with ``continue``. 247