twister: add support for custom emulator in simulator

Enable the possibility for boards to implement a custom `run` target in
its board.cmake to run any arbitrary commands. This is helpful for devs
who would like to add support for proprietary simulator to their boards
that can't be upstreamed.

Signed-off-by: Yong Cong Sin <ycsin@meta.com>

cmake/emu/custom.cmake

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# ${ZEPHYR_BASE}/CMakeLists.txt looks for ${ZEPHYR_BASE}/cmake/emu/${EMU_PLATFORM}.cmake
+# when building the `run` target. Create this placeholder file so it doesn't complain.
+# The real 'run' custom_target should be defined in `board.cmake` instead.
+#
+# See https://docs.zephyrproject.org/latest/develop/test/twister.html#running-tests-on-custom-emulator
+#

doc/develop/test/twister.rst

@@ -643,6 +643,42 @@ integration keyword in the testcase definition file (testcase.yaml and
 sample.yaml).
 
 
+Running tests on custom emulator
+********************************
+
+Apart from the already supported QEMU and other simulated environments, Twister
+supports running any out-of-tree custom emulator defined in the board's :file:`board.cmake`.
+To use this type of simulation, add the following properties to
+:file:`custom_board/custom_board.yaml`:
+
+::
+
+   simulation: custom
+   simulation_exec: <name_of_emu_binary>
+
+This tells Twister that the board is using a custom emulator called ``<name_of_emu_binary>``,
+make sure this binary exists in the PATH.
+
+Then, in :file:`custom_board/board.cmake`, set the supported emulation platforms to ``custom``:
+
+::
+
+   set(SUPPORTED_EMU_PLATFORMS custom)
+
+Finally, implement the ``run_custom`` target in :file:`custom_board/board.cmake`.
+It should look something like this:
+
+::
+
+   add_custom_target(run_custom
+     COMMAND
+     <name_of_emu_binary to invoke during 'run'>
+     <any args to be passed to the command, i.e. ${BOARD}, ${APPLICATION_BINARY_DIR}/zephyr/zephyr.elf>
+     WORKING_DIRECTORY ${APPLICATION_BINARY_DIR}
+     DEPENDS ${logical_target_for_zephyr_elf}
+     USES_TERMINAL
+     )
+
 Running Tests on Hardware
 *************************
 

scripts/pylib/twister/twisterlib/handlers.py

@@ -39,7 +39,7 @@ except ImportError as capture_error:
 logger = logging.getLogger('twister')
 logger.setLevel(logging.DEBUG)
 
-SUPPORTED_SIMS = ["mdb-nsim", "nsim", "renode", "qemu", "tsim", "armfvp", "xt-sim", "native"]
+SUPPORTED_SIMS = ["mdb-nsim", "nsim", "renode", "qemu", "tsim", "armfvp", "xt-sim", "native", "custom"]
 SUPPORTED_SIMS_IN_PYTEST = ['native', 'qemu']
 
 

scripts/schemas/twister/platform-schema.yaml

@@ -24,7 +24,19 @@ mapping:
     enum: ["mcu", "qemu", "sim", "unit", "native"]
   "simulation":
     type: str
-    enum: ["qemu", "simics", "xt-sim", "renode", "nsim", "mdb-nsim", "tsim", "armfvp", "native"]
+    enum:
+      [
+        "qemu",
+        "simics",
+        "xt-sim",
+        "renode",
+        "nsim",
+        "mdb-nsim",
+        "tsim",
+        "armfvp",
+        "native",
+        "custom",
+      ]
   "simulation_exec":
     type: str
   "arch":