targets/apollo4/target_docs.rst

.. _target-apollo4:

===========================
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.

.. _AmbiqSuite SDK: https://ambiq.com/apollo4-blue-plus

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:

.. code-block:: sh

  $ gn args out

Then add the following lines to that text file:

.. code-block::

   # 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:

.. code-block:: sh

  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:

.. code-block:: sh

  #!/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:

.. code-block:: sh

  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.

.. code-block:: sh

  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`_.

.. _Thread Aware Debugging: https://www.segger.com/products/debug-probes/j-link/tools/j-link-gdb-server/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.

.. code-block:: sh

  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:

.. code-block:: sh

  #!/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:

.. code-block:: sh

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