twister: add a hardware map support for using serial pty

The hardware map feature can be used with serial pty mode in
this change. And also add an runner_params option for passing
more parameters from hardware map file to west runner. Note
that you need to create this map file manually because it
cannot be scanned out correctly due to pty is not a physical
HW device existing in system.

And also update doc/develop/test/twister.rst for the usage.

Signed-off-by: Enjia Mai <enjia.mai@intel.com>

doc/develop/test/twister.rst

@@ -525,6 +525,16 @@ only one board at a time, specified using the ``--platform`` option.
 The ``--device-serial-baud`` option is only needed if your device does not run at
 115200 baud.
 
+To support devices without a physical serial port, use the ``--device-serial-pty``
+option. In this cases, log messages are captured for example using a script.
+In this case you can run twister with the following options::
+
+    scripts/twister --device-testing --device-serial-pty "script.py" \
+    -p intel_adsp_cavs25 -T tests/kernel
+
+The script is user-defined and handles delivering the messages which can be
+used by twister to determine the test execution status.
+
 
 Executing tests on multiple devices
 ===================================
@@ -594,6 +604,46 @@ on those platforms.
   with the hardware map features. Boards that require other runners to flash the
   Zephyr binary are still work in progress.
 
+Serial PTY support using ``--device-serial-pty``  can also be used in the
+hardware map::
+
+ - connected: true
+   id: None
+   platform: intel_adsp_cavs18
+   product: None
+   runner: intel_adsp
+   serial_pty: path/to/script.py
+   runner_params:
+     - --remote-host=remote_host_ip_addr
+     - --key=/path/to/key.pem
+ - connected: true
+   id: None
+   platform: intel_adsp_cavs25
+   product: None
+   runner: intel_adsp
+   serial_pty: path/to/script.py
+   runner_params:
+     - --remote-host=remote_host_ip_addr
+     - --key=/path/to/key.pem
+
+
+The runner_params field indicates the parameters you want to pass to the
+west runner. For some boards the west runner needs some extra parameters to
+work. It is equivalent to following west and twister commands::
+
+   west flash --remote-host remote_host_ip_addr --key /path/to/key.pem
+
+   twister -p intel_adsp_cavs18 --device-testing --device-serial-pty script.py
+   --west-flash="--remote-host=remote_host_ip_addr,--key=/path/to/key.pem"
+
+
+.. note::
+
+  For serial PTY, the "--generate-hardware-map" option cannot scan it out
+  and generate a correct hardware map automatically. You have to edit it
+  manually according to above example. This is because the serial port
+  of the PTY is not fixed and being allocated in the system at runtime.
+
 Fixtures
 +++++++++
 

scripts/pylib/twister/twisterlib.py

@@ -790,7 +790,7 @@ class DeviceHandler(Handler):
 
     def make_device_available(self, serial):
         for d in self.suite.duts:
-            if d.serial == serial or d.serial_pty:
+            if serial in [d.serial_pty, d.serial]:
                 d.available = 1
 
     @staticmethod
@@ -876,6 +876,13 @@ class DeviceHandler(Handler):
                     elif runner == "stm32cubeprogrammer":
                         command.append("--tool-opt=sn=%s" % (board_id))
 
+                    # Receive parameters from an runner_params field
+                    # of the specified hardware map file.
+                    for d in self.suite.duts:
+                        if (d.platform == self.instance.platform.name) and d.runner_params:
+                            for param in d.runner_params:
+                                command.append(param)
+
             if command_extra_args != []:
                 command.append('--')
                 command.extend(command_extra_args)
@@ -908,7 +915,10 @@ class DeviceHandler(Handler):
                 outs, errs = ser_pty_process.communicate()
                 logger.debug("Process {} terminated outs: {} errs {}".format(serial_pty, outs, errs))
 
-            self.make_device_available(serial_device)
+            if serial_pty:
+                self.make_device_available(serial_pty)
+            else:
+                self.make_device_available(serial_device)
             return
 
         ser.flush()
@@ -1003,8 +1013,10 @@ class DeviceHandler(Handler):
         if post_script:
             self.run_custom_script(post_script, 30)
 
-        self.make_device_available(serial_device)
-
+        if serial_pty:
+            self.make_device_available(serial_pty)
+        else:
+            self.make_device_available(serial_device)
 
 class QEMUHandler(Handler):
     """Spawns a thread to monitor QEMU output from pipes
@@ -4360,6 +4372,7 @@ class DUT(object):
                  product=None,
                  serial_pty=None,
                  connected=False,
+                 runner_params=None,
                  pre_script=None,
                  post_script=None,
                  post_flash_script=None,
@@ -4376,6 +4389,7 @@ class DUT(object):
         self.id = id
         self.product = product
         self.runner = runner
+        self.runner_params = runner_params
         self.fixtures = []
         self.post_flash_script = post_flash_script
         self.post_script = post_script
@@ -4478,17 +4492,22 @@ class HardwareMap:
             platform  = dut.get('platform')
             id = dut.get('id')
             runner = dut.get('runner')
+            runner_params = dut.get('runner_params')
+            serial_pty = dut.get('serial_pty')
             serial = dut.get('serial')
             baud = dut.get('baud', None)
             product = dut.get('product')
             fixtures = dut.get('fixtures', [])
+            connected= dut.get('connected') and ((serial or serial_pty) is not None)
             new_dut = DUT(platform=platform,
                           product=product,
                           runner=runner,
+                          runner_params=runner_params,
                           id=id,
+                          serial_pty=serial_pty,
                           serial=serial,
                           serial_baud=baud,
-                          connected=serial is not None,
+                          connected=connected,
                           pre_script=pre_script,
                           post_script=post_script,
                           post_flash_script=post_flash_script)

scripts/schemas/twister/hwmap-schema.yaml

@@ -27,6 +27,14 @@ sequence:
       "runner":
         type: str
         required: true
+      "runner_params":
+        type: seq
+        required: false
+        sequence:
+          - type: str
+      "serial_pty":
+        type: str
+        required: false
       "serial":
         type: str
         required: false