1.. _target-apollo4: 2 3=========================== 4Ambiq Apollo4 5=========================== 6----- 7Setup 8----- 9To use this target, Pigweed must be set up to use the `AmbiqSuite SDK`_ HAL 10for the Apollo4 series which can be downloaded from the Ambiq website. 11 12.. _AmbiqSuite SDK: https://ambiq.com/apollo4-blue-plus 13 14Once the AmbiqSuite SDK package has been downloaded and extracted, the user 15needs to set ``dir_pw_third_party_ambiq_SDK`` build arg to the location of 16extracted directory: 17 18.. code-block:: sh 19 20 $ gn args out 21 22Then add the following lines to that text file: 23 24.. code-block:: 25 26 # Path to the extracted AmbiqSuite SDK package. 27 dir_pw_third_party_ambiq_SDK = "/path/to/AmbiqSuite_R4.3.0" 28 29Usage 30===== 31The Apollo4 is configured to output logs and test results over the UART to an 32on-board J-Link Debug Probe (Virtual COM Port) at a baud rate of 115200. 33 34Once the AmbiqSuite SDK is configured, the unit tests for the Apollo4 board 35can be build with a command: 36 37.. code-block:: sh 38 39 ninja -C out apollo4 40 41If using out as a build directory, tests will be located in out/apollo4/obj/[module name]/[test_name].elf. 42 43Flashing using SEGGER's J-Link 44============================== 45Flashing the Apollo4 board can be done using the J-Flash Lite GUI program or from 46a command line using ``JLinkExe`` program. The latter requires a script which 47describes the steps of programming. Here is an example bash script to flash 48an Apollo4 board using ``JLinkExe`` program: 49 50.. code-block:: sh 51 52 #!/bin/bash 53 function flash_jlink() 54 { 55 local TMP_FLASH_SCRIPT=/tmp/gdb-flash.txt 56 57 cat > $TMP_FLASH_SCRIPT <<- EOF 58 r 59 h 60 loadfile $1 61 r 62 q 63 EOF 64 65 JLinkExe -NoGui 1 -device AMAP42KK-KBR -if SWD -speed 4000 -autoconnect 1 -CommanderScript $TMP_FLASH_SCRIPT 66 67 rm "$TMP_FLASH_SCRIPT" 68 } 69 70 flash_jlink $@ 71 72Then call this script: 73 74.. code-block:: sh 75 76 bash ./flash_amap4.sh ./out/apollo4_debug/obj/pw_log/test/basic_log_test.elf 77 78In this case the basic log test is debugged, but substitute your own ELF file. 79 80Debugging 81========= 82Debugging can be done using the on-board J-Link Debug Probe. First you need to 83start ``JLinkGDBServer`` and connect to the on-board J-Link Debug Probe. 84 85.. code-block:: sh 86 87 JLinkGDBServer -select USB \ 88 -device AMAP42KK-KBR \ 89 -endian little \ 90 -if SWD \ 91 -speed 4000 \ 92 -noir -LocalhostOnly \ 93 -singlerun \ 94 -nogui \ 95 -excdbg \ 96 -rtos GDBServer/RTOSPlugin_FreeRTOS.dylib 97 98The ``-rtos`` option is for `Thread Aware Debugging`_. 99 100.. _Thread Aware Debugging: https://www.segger.com/products/debug-probes/j-link/tools/j-link-gdb-server/thread-aware-debugging/ 101 102Then on the second terminal window use ``arm-none-eabi-gdb`` to load an executable 103into the target, debug, and run it. 104 105.. code-block:: sh 106 107 arm-none-eabi-gdb -q out/apollo4_debug/obj/pw_log/test/basic_log_test.elf 108 109This can be combined with a simple bash script. Here is an example of one: 110 111.. code-block:: sh 112 113 #!/bin/bash 114 115 function debug_jlink() 116 { 117 local TMP_GDB_SCRIPT=/tmp/gdb-debug.txt 118 119 # Create GDB script. 120 121 cat > $TMP_GDB_SCRIPT <<- EOF 122 123 # Backtrace all threads. 124 125 define btall 126 thread apply all backtrace 127 end 128 129 target remote localhost:2331 130 load 131 monitor reset 132 monitor halt 133 b pw_boot_Entry 134 135 EOF 136 137 # Start GDB server. 138 139 set -m 140 JLinkGDBServer -select USB \ 141 -device AMAP42KK-KBR \ 142 -endian little \ 143 -if SWD \ 144 -speed 4000 \ 145 -noir -LocalhostOnly \ 146 -singlerun \ 147 -nogui \ 148 -excdbg \ 149 -rtos GDBServer/RTOSPlugin_FreeRTOS.dylib & 150 set +m 151 152 # Debug program. 153 154 arm-none-eabi-gdb -q $1 -x $TMP_GDB_SCRIPT 155 156 rm "$TMP_GDB_SCRIPT" 157 } 158 159 debug_jlink $@ 160 161Then call this script: 162 163.. code-block:: sh 164 165 bash ./debug_amap4.sh ./out/apollo4_debug/obj/pw_log/test/basic_log_test.elf 166