Ambiq Apollo4

Setup

To use this target, Pigweed must be set up to use the AmbiqSuite SDK HAL for the Apollo4 series which can be downloaded from the Ambiq website.

Once the AmbiqSuite SDK package has been downloaded and extracted, the user needs to set dir_pw_third_party_ambiq_SDK build arg to the location of extracted directory:

$ gn args out

Then add the following lines to that text file:

# Path to the extracted AmbiqSuite SDK package.
dir_pw_third_party_ambiq_SDK = "/path/to/AmbiqSuite_R4.3.0"

Usage

The Apollo4 is configured to output logs and test results over the UART to an on-board J-Link Debug Probe (Virtual COM Port) at a baud rate of 115200.

Once the AmbiqSuite SDK is configured, the unit tests for the Apollo4 board can be build with a command:

ninja -C out apollo4

If using out as a build directory, tests will be located in out/apollo4/obj/[module name]/[test_name].elf.

Flashing using SEGGER’s J-Link

Flashing the Apollo4 board can be done using the J-Flash Lite GUI program or from a command line using JLinkExe program. The latter requires a script which describes the steps of programming. Here is an example bash script to flash an Apollo4 board using JLinkExe program:

#!/bin/bash
function flash_jlink()
{
   local TMP_FLASH_SCRIPT=/tmp/gdb-flash.txt

   cat > $TMP_FLASH_SCRIPT <<- EOF
      r
      h
      loadfile $1
      r
      q
   EOF

   JLinkExe -NoGui 1 -device AMAP42KK-KBR -if SWD -speed 4000 -autoconnect 1 -CommanderScript $TMP_FLASH_SCRIPT

   rm "$TMP_FLASH_SCRIPT"
}

flash_jlink $@

Then call this script:

bash ./flash_amap4.sh ./out/apollo4_debug/obj/pw_log/test/basic_log_test.elf

In this case the basic log test is debugged, but substitute your own ELF file.

Debugging

Debugging can be done using the on-board J-Link Debug Probe. First you need to start JLinkGDBServer and connect to the on-board J-Link Debug Probe.

JLinkGDBServer -select USB      \
          -device AMAP42KK-KBR  \
          -endian little        \
          -if SWD               \
          -speed 4000           \
          -noir -LocalhostOnly  \
          -singlerun            \
          -nogui                \
          -excdbg               \
          -rtos GDBServer/RTOSPlugin_FreeRTOS.dylib

The -rtos option is for Thread Aware Debugging.

Then on the second terminal window use arm-none-eabi-gdb to load an executable into the target, debug, and run it.

arm-none-eabi-gdb -q out/apollo4_debug/obj/pw_log/test/basic_log_test.elf

This can be combined with a simple bash script. Here is an example of one:

#!/bin/bash

function debug_jlink()
{
   local TMP_GDB_SCRIPT=/tmp/gdb-debug.txt

   # Create GDB script.

   cat > $TMP_GDB_SCRIPT <<- EOF

   # Backtrace all threads.

   define btall
     thread apply all backtrace
   end

   target remote localhost:2331
   load
   monitor reset
   monitor halt
   b pw_boot_Entry

   EOF

   # Start GDB server.

   set -m
   JLinkGDBServer -select USB       \
              -device AMAP42KK-KBR  \
              -endian little        \
              -if SWD               \
              -speed 4000           \
              -noir -LocalhostOnly  \
              -singlerun            \
              -nogui                \
              -excdbg               \
              -rtos GDBServer/RTOSPlugin_FreeRTOS.dylib &
   set +m

   # Debug program.

   arm-none-eabi-gdb -q $1 -x $TMP_GDB_SCRIPT

   rm "$TMP_GDB_SCRIPT"
}

debug_jlink $@

Then call this script:

bash ./debug_amap4.sh ./out/apollo4_debug/obj/pw_log/test/basic_log_test.elf