boards: stm32n6: Document sb variant and testing using twister

erwango · kartben · commit 17c73039ce82 · 2025-02-03T19:56:49.000+01:00
Update stm32n6 based boards documentation to reflect addition
of new sb variant and how it could be used for twister tests automation.

Signed-off-by: Erwan Gouriou &lt;erwan.gouriou@st.com&gt;
diff --git a/boards/st/nucleo_n657x0_q/doc/index.rst b/boards/st/nucleo_n657x0_q/doc/index.rst
@@ -3,7 +3,7 @@
 Overview
 ********
 
-The STM32 Nucleo-144 board provides an affordable and flexible way for users to try out
+The NUCLEO-N657X0-Q board provides an affordable and flexible way for users to try out
 new concepts and build prototypes by choosing from the various combinations of performance
 and power consumption features, provided by the STM32 microcontroller. For the compatible boards,
 the internal or external SMPS significantly reduces power consumption in Run mode.
@@ -12,7 +12,7 @@ The ST Zio connector, which extends the ARDUINO® Uno V3 connectivity, and the S
 provide an easy means of expanding the functionality of the Nucleo open development platform with
 a wide choice of specialized shields.
 
-The STM32 Nucleo-144 board does not require any separate probe as it integrates the ST-LINK
+The NUCLEO-N657X0-Q board does not require any separate probe as it integrates the ST-LINK
 debugger/programmer.
 
 The STM32 Nucleo-144 board comes with the STM32 comprehensive free software libraries and
@@ -51,6 +51,12 @@ Hardware
   - On-board ST-LINK (STLINK/V2-1, STLINK-V3E, or STLINK-V3EC) debugger/programmer with
     USB re-enumeration capability: mass storage, Virtual COM port, and debug port
 
+For more details, please refer to:
+
+* `NUCLEO-N657X0-Q website`_
+* `STM32N657X0 on www.st.com`_
+* `STM32N657 reference manual`_
+
 Supported Features
 ==================
 
@@ -79,10 +85,10 @@ The default configuration can be found in the defconfig file:
 Connections and IOs
 ===================
 
-NUCLEO_N657X0_Q Board has 12 GPIO controllers. These controllers are responsible
+NUCLEO-N657X0-Q Board has 12 GPIO controllers. These controllers are responsible
 for pin muxing, input/output, pull-up, etc.
 
-For more details please refer to `NUCLEO_N657X0_Q User Manual`_.
+For more details please refer to `NUCLEO-N657X0-Q User Manual`_.
 
 Default Zephyr Peripheral Mapping:
 ----------------------------------
@@ -95,83 +101,147 @@ Default Zephyr Peripheral Mapping:
 System Clock
 ------------
 
-NUCLEO_N657X0_Q System Clock could be driven by internal or external oscillator,
+NUCLEO-N657X0-Q System Clock could be driven by internal or external oscillator,
 as well as main PLL clock. By default System clock is driven by PLL clock at
 400MHz, driven by 64MHz high speed internal oscillator.
 
 Serial Port
 -----------
 
-NUCLEO_N657X0_Q board has 10 U(S)ARTs. The Zephyr console output is assigned to
+NUCLEO-N657X0-Q board has 10 U(S)ARTs. The Zephyr console output is assigned to
 USART1. Default settings are 115200 8N1.
 
 Programming and Debugging
 *************************
 
-NUCLEO_N657X0_Q board includes an ST-LINK/V3 embedded debug tool interface.
-This probe allows to flash the board using various tools.
+NUCLEO-N657X0-Q board includes an ST-LINK/V3 embedded debug tool interface.
+This probe allows to flash and debug the board using various tools.
+
 
-Flashing
-========
 
-The board is configured to be flashed using west `STM32CubeProgrammer`_ runner,
-so its :ref:`installation <stm32cubeprog-flash-host-tools>` is required.
+Flashing or loading
+===================
+
+The board is configured to be programmed using west `STM32CubeProgrammer`_ runner,
+so its :ref:`installation <stm32cubeprog-flash-host-tools>` is needed.
 Version 2.18.0 or later of `STM32CubeProgrammer`_ is required.
 
-Flashing an application to NUCLEO_N657X0_Q
-------------------------------------------
+To program the board, there are two options:
+
+- Program the firmware in external flash. At boot, it will then be loaded on RAM
+  and executed from there.
+- Optionally, it can also be taken advantage from the serial boot interface provided
+  by the boot ROM. In that case, firmware is directly loaded in RAM and executed from
+  there. It is not retained.
+
+Programming an application to NUCLEO-N657X0-Q
+---------------------------------------------
+
+Here is an example to build and run :zephyr:code-sample:`hello_world` application.
+
+First, connect the NUCLEO-N657X0-Q to your host computer using the ST-Link USB port.
 
-Connect the NUCLEO_N657X0_Q to your host computer using the USB port.
-Then build and flash an application.
+   .. tabs::
+
+      .. group-tab:: ST-Link
+
+         Build and flash an application using ``nucleo_n657x0_q`` target.
+
+         .. zephyr-app-commands::
+            :zephyr-app: samples/hello_world
+            :board: nucleo_n657x0_q
+            :goals: build flash
 
 .. note::
-   For flashing, BOOT0 pin should be set to 0 and BOOT1 to 1 before powering on
-   the board.
+            For flashing, before powering the board, set the boot pins in the following configuration:
+
+            * BOOT0: 0
+            * BOOT1: 1
 
-   To run the application after flashing, BOOT1 should be set to 0 and the board
-   should be powered off and on again.
+            After flashing, to run the application, set the boot pins in the following configuration:
 
-Here is an example for the :zephyr:code-sample:`hello_world` application.
+            * BOOT1: 0
 
-Run a serial host program to connect with your Nucleo board:
+	    Power off and on the board again.
+
+         Run a serial host program to connect to your board:
 
 .. code-block:: console
 
    $ minicom -D /dev/ttyACM0
 
-Then build and flash the application.
+      .. group-tab:: Serial Boot Loader (USB)
+
+         Additionally, connect the NUCLEO-N657X0-Q to your host computer using the USB port.
+         In this configuration, ST-Link is used to power the board and for serial communication
+         over the Virtual COM Port.
+
+         .. note::
+            Before powering the board, set the boot pins in the following configuration:
+
+            * BOOT0: 1
+            * BOOT1: 0
+
+         Build and load an application using ``nucleo_n657x0_q/stm32n657xx/sb`` target (you
+         can also use the shortened form: ``nucleo_n657x0_q//sb``)
 
 .. zephyr-app-commands::
    :zephyr-app: samples/hello_world
    :board: nucleo_n657x0_q
    :goals: build flash
 
+
+Run a serial host program to connect to your board:
+
+.. code-block:: console
+
+   $ minicom -D /dev/ttyACM0
+
 You should see the following message on the console:
 
 .. code-block:: console
 
    Hello World! nucleo_n657x0_q/stm32n657xx
 
+
 Debugging
 =========
 
 For now debugging is only available through STM32CubeIDE:
-* Go to File > Import and select C/C++ > STM32 Cortex-M Executable
-* In Executable field, browse to your <ZEPHYR_PATH>/build/zephyr/zephyr.elf
+
+* Go to File > Import and select C/C++ > STM32 Cortex-M Executable.
+* In Executable field, browse to your <ZEPHYR_PATH>/build/zephyr/zephyr.elf.
 * In MCU field, select STM32N657X0HxQ.
-* Click on Finish
-* Then click on Debug to start the debugging session
+* Click on Finish.
+* Finally, click on Debug to start the debugging session.
 
 .. note::
-   For debugging, BOOT0 pin should be set to 0 and BOOT1 to 1 before powering on the
-   board.
+   For debugging, before powering on the board, set the boot pins in the following configuration:
+
+   * BOOT0: 0
+   * BOOT1: 1
+
+
+Running tests with twister
+==========================
 
-.. _NUCLEO_N657X0_Q website:
+Due to the BOOT switches manipulation required when flashing the board using ``nucleo_n657x0_q``
+board target, it is only possible to run twister tests campaign on ``nucleo_n657x0_q/stm32n657xx/sb``
+board target which doesn't require BOOT pins changes to load and execute binaries.
+To do so, it is advised to use Twister's hardware map feature with the following settings:
+
+.. code-block:: yaml
+
+   - platform: nucleo_n657x0_q/stm32n657xx/sb
+     product: BOOT-SERIAL
+     pre_script: <path_to_zephyr>/boards/st/common/scripts/board_power_reset.sh
+     runner: stm32cubeprogrammer
+
+.. _NUCLEO-N657X0-Q website:
    https://www.st.com/en/evaluation-tools/nucleo-n657x0-q.html
 
-.. _NUCLEO_N657X0_Q User Manual:
+.. _NUCLEO-N657X0-Q User Manual:
    https://www.st.com/resource/en/user_manual/um3417-stm32n6-nucleo144-board-mb1940-stmicroelectronics.pdf
-
 .. _STM32N657X0 on www.st.com:
    https://www.st.com/en/microcontrollers-microprocessors/stm32n657x0.html
 
diff --git a/boards/st/stm32n6570_dk/doc/index.rst b/boards/st/stm32n6570_dk/doc/index.rst
@@ -55,6 +55,11 @@ Hardware
 - On-board STLINK-V3EC debugger/programmer with USB re-enumeration capability:
   Virtual COM port, and debug port
 
+For more details, please refer to:
+
+* `STM32N6570_DK website`_
+* `STM32N657X0 on www.st.com`_
+* `STM32N657 reference manual`_
 
 Supported Features
 ==================
@@ -114,43 +119,87 @@ Programming and Debugging
 *************************
 
 STM32N6570_DK board includes an ST-LINK/V3 embedded debug tool interface.
-This probe allows to flash the board using various tools.
+This probe allows to flash and debug the board using various tools.
+
 
-Flashing
-========
+Flashing or loading
+===================
 
-The board is configured to be flashed using west `STM32CubeProgrammer`_ runner,
-so its :ref:`installation <stm32cubeprog-flash-host-tools>` is required.
+The board is configured to be programmed using west `STM32CubeProgrammer`_ runner,
+so its :ref:`installation <stm32cubeprog-flash-host-tools>` is needed.
 Version 2.18.0 or later of `STM32CubeProgrammer`_ is required.
 
-Flashing an application to STM32N6570_DK
-------------------------------------------
+To program the board, there are two options:
 
-Connect the STM32N6570_DK to your host computer using the USB port.
-Then build and flash an application.
+- Program the firmware in external flash. At boot, it will then be loaded on RAM
+  and executed from there.
+- Optionally, it can also be taken advantage from the serial boot interface provided
+  by the boot ROM. In that case, firmware is directly loaded in RAM and executed from
+  there. It is not retained.
 
-.. note::
-   For flashing, BOOT0 pin should be set to 0 and BOOT1 to 1 before powering on
-   the board.
+Programming an application to STM32N6570_DK
+-------------------------------------------
+
+Here is an example to build and run :zephyr:code-sample:`hello_world` application.
+
+First, connect the STM32N6570_DK to your host computer using the ST-Link USB port.
+
+   .. tabs::
+
+      .. group-tab:: ST-Link
+
+         Build and flash an application using ``stm32n6570_dk`` target.
+
+         .. zephyr-app-commands::
+            :zephyr-app: samples/hello_world
+            :board: stm32n6570_dk
+            :goals: build flash
+
+         .. note::
+            For flashing, before powering the board, set the boot pins in the following configuration:
+
+            * BOOT0: 0
+            * BOOT1: 1
+
+            After flashing, to run the application, set the boot pins in the following configuration:
+
+            * BOOT1: 0
+
+	    Power off and on the board again.
+
+         Run a serial host program to connect to your board:
 
-   To run the application after flashing, BOOT1 should be set to 0 and the board
-   should be powered off and on again.
+         .. code-block:: console
+
+            $ minicom -D /dev/ttyACM0
+
+      .. group-tab:: Serial Boot Loader (USB)
+
+         Additionally, connect the STM32N6570_DK to your host computer using the USB port.
+         In this configuration, ST-Link is used to power the board and for serial communication
+         over the Virtual COM Port.
+
+         .. note::
+            Before powering the board, set the boot pins in the following configuration:
+
+            * BOOT0: 1
+            * BOOT1: 0
+
+         Build and load an application using ``stm32n6570_dk/stm32n657xx/sb`` target (you
+         can also use the shortened form: ``stm32n6570_dk//sb``)
+
+         .. zephyr-app-commands::
+            :zephyr-app: samples/hello_world
+            :board: stm32n6570_dk//sb
+            :goals: build flash
 
-Here is an example for the :zephyr:code-sample:`hello_world` application.
 
 Run a serial host program to connect with your Disco board:
 
 .. code-block:: console
 
    $ minicom -D /dev/ttyACM0
 
-Then build and flash the application.
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/hello_world
-   :board: stm32n6570_dk
-   :goals: build flash
-
 You should see the following message on the console:
 
 .. code-block:: console
@@ -162,15 +211,34 @@ Debugging
 =========
 
 For now debugging is only available through STM32CubeIDE:
-* Go to File > Import and select C/C++ > STM32 Cortex-M Executable
-* In Executable field, browse to your <ZEPHYR_PATH>/build/zephyr/zephyr.elf
+
+* Go to File > Import and select C/C++ > STM32 Cortex-M Executable.
+* In Executable field, browse to your <ZEPHYR_PATH>/build/zephyr/zephyr.elf.
 * In MCU field, select STM32N657X0HxQ.
-* Click on Finish
-* Then click on Debug to start the debugging session
+* Click on Finish.
+* Finally, click on Debug to start the debugging session.
 
 .. note::
-   For debugging, BOOT0 pin should be set to 0 and BOOT1 to 1 before powering on the
-   board.
+   For debugging, before powering on the board, set the boot pins in the following configuration:
+
+   * BOOT0: 0
+   * BOOT1: 1
+
+
+Running tests with twister
+==========================
+
+Due to the BOOT switches manipulation required when flashing the board using ``stm32n6570_dk``
+board target, it is only possible to run twister tests campaign on ``stm32n6570_dk/stm32n657xx/sb``
+board target which doesn't require BOOT pins changes to load and execute binaries.
+To do so, it is advised to use Twister's hardware map feature with the following settings:
+
+.. code-block:: yaml
+
+   - platform: stm32n6570_dk/stm32n657xx/sb
+     product: BOOT-SERIAL
+     pre_script: <path_to_zephyr>/boards/st/common/scripts/board_power_reset.sh
+     runner: stm32cubeprogrammer
 
 .. _STM32N6570_DK website:
    https://www.st.com/en/evaluation-tools/stm32n6570-dk.html
