From 9b066a27564322bfaff27978d01a829e572b4485 Mon Sep 17 00:00:00 2001
From: Pieter De Gendt <pieter.degendt@basalte.be>
Date: Fri, 20 Dec 2024 10:26:08 +0100
Subject: [PATCH 1/2] boards: custom_plank: Add demo out-of-tree runner

Demonstrate how to use an out-of-tree runner with the custom_plank
board.

Signed-off-by: Pieter De Gendt <pieter.degendt@basalte.be>
---
 boards/common/example_runner.board.cmake |  4 +++
 boards/vendor/custom_plank/board.cmake   |  2 ++
 scripts/example_runner.py                | 32 ++++++++++++++++++++++++
 zephyr/module.yml                        |  4 +++
 4 files changed, 42 insertions(+)
 create mode 100644 boards/common/example_runner.board.cmake
 create mode 100644 scripts/example_runner.py

diff --git a/boards/common/example_runner.board.cmake b/boards/common/example_runner.board.cmake
new file mode 100644
index 000000000..4fd795dc5
--- /dev/null
+++ b/boards/common/example_runner.board.cmake
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+
+board_set_sim_runner_ifnset(example)
+board_finalize_runner_args(example) # No default arguments to provide.
diff --git a/boards/vendor/custom_plank/board.cmake b/boards/vendor/custom_plank/board.cmake
index 5c6b5319f..7a661e72e 100644
--- a/boards/vendor/custom_plank/board.cmake
+++ b/boards/vendor/custom_plank/board.cmake
@@ -3,6 +3,7 @@
 
 board_runner_args(jlink "--device=nrf52" "--speed=4000")
 board_runner_args(pyocd "--target=nrf52840" "--frequency=4000000")
+board_runner_args(example "--param=foo")
 
 set(OPENOCD_NRF5_SUBFAMILY "nrf52")
 
@@ -10,3 +11,4 @@ include(${ZEPHYR_BASE}/boards/common/nrfjprog.board.cmake)
 include(${ZEPHYR_BASE}/boards/common/jlink.board.cmake)
 include(${ZEPHYR_BASE}/boards/common/pyocd.board.cmake)
 include(${ZEPHYR_BASE}/boards/common/openocd-nrf5.board.cmake)
+include(${CMAKE_CURRENT_LIST_DIR}/../../common/example_runner.board.cmake)
diff --git a/scripts/example_runner.py b/scripts/example_runner.py
new file mode 100644
index 000000000..8168e1034
--- /dev/null
+++ b/scripts/example_runner.py
@@ -0,0 +1,32 @@
+# Copyright (c) 2024 Basalte bv
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from runners.core import RunnerCaps, ZephyrBinaryRunner
+
+
+class ExampleRunner(ZephyrBinaryRunner):
+    """Dummy example runner."""
+
+    def __init__(self, cfg, param):
+        super().__init__(cfg)
+        self.param = param
+
+    @classmethod
+    def name(cls):
+        return "example"
+
+    @classmethod
+    def capabilities(cls):
+        return RunnerCaps(commands=({"simulate"}))
+
+    @classmethod
+    def do_add_parser(cls, parser):
+        parser.add_argument("--param", action="store", help="An example parameter")
+
+    @classmethod
+    def do_create(cls, cfg, args):
+        return cls(cfg, param=args.param)
+
+    def do_run(self, command, **kwargs):
+        self.logger.info(f"Running {command} on {self.param}")
diff --git a/zephyr/module.yml b/zephyr/module.yml
index 047032a91..7d53dfde2 100644
--- a/zephyr/module.yml
+++ b/zephyr/module.yml
@@ -18,3 +18,7 @@ build:
     # `<dts_root>/dts/bindings` for additional dts binding files. The `.` is
     # the root of this repository.
     dts_root: .
+runners:
+  # Additional runners, Zephyr will import these when discovering
+  # subclasses of the `ZephyrBinaryRunner` class.
+  - file: scripts/example_runner.py

From 130947dfad8492b9a5bd9ce2f01af5946ec0bc94 Mon Sep 17 00:00:00 2001
From: Pieter De Gendt <pieter.degendt@basalte.be>
Date: Mon, 23 Dec 2024 09:27:02 +0100
Subject: [PATCH 2/2] readme: add external runner entry

Add external runner entry to overview of the features demonstrated.

Signed-off-by: Pieter De Gendt <pieter.degendt@basalte.be>
---
 README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.md b/README.md
index 66165c937..ceb2c51eb 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@ applications. Some of the features demonstrated in this example are:
 - Out-of-tree libraries
 - Example CI configuration (using GitHub Actions)
 - Custom [west extension][west_ext]
+- Custom [Zephyr runner][runner_ext]
 - Doxygen and Sphinx documentation boilerplate
 
 This repository is versioned together with the [Zephyr main tree][zephyr]. This
@@ -45,6 +46,7 @@ points to the development branch of Zephyr, also `main`.
 [drivers]: https://docs.zephyrproject.org/latest/reference/drivers/index.html
 [zephyr]: https://github.com/zephyrproject-rtos/zephyr
 [west_ext]: https://docs.zephyrproject.org/latest/develop/west/extensions.html
+[runner_ext]: https://docs.zephyrproject.org/latest/develop/modules.html#external-runners
 
 ## Getting Started