Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_target_runner: |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 2 | |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 3 | ---------------- |
| 4 | pw_target_runner |
| 5 | ---------------- |
| 6 | The target runner module implements a gRPC server designed to run executables |
| 7 | in parallel. These executables may be run directly on the host, or flashed to |
| 8 | one or more attached targets. |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 9 | |
| 10 | Overview |
| 11 | -------- |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 12 | The target runner server is responsible for processing requests to distribute |
| 13 | executables among a pool of workers that run in parallel. This allows things |
| 14 | like unit tests to be run across multiple devices simultaneously, greatly |
| 15 | reducing the overall time it takes to run a collection of tests. |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 16 | |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 17 | Additionally, the server allows many executables to be queued up at once and |
| 18 | scheduled across available devices, making it possible to automatically run unit |
| 19 | tests from a Ninja build after code is updated. This integrates nicely with the |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 20 | ``pw watch`` command to re-run all affected unit tests after modifying code. |
| 21 | |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 22 | The target runner is implemented as a library in various programming languages. |
| 23 | This library provides the core gRPC server and a mechanism through which worker |
| 24 | routines can be registered. Code using the library instantiates a server with |
| 25 | some custom workers for the desired target to run passed executables. |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 26 | |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 27 | The ``pw_target_runner`` module also provides a standalone |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 28 | ``pw_target_runner_server`` program which runs the server with configurable |
| 29 | workers that launch external processes to execute passed binaries. This |
| 30 | program should be sufficient to quickly get unit tests running in a simple |
| 31 | setup, such as multiple devices plugged into a development machine. |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 32 | |
| 33 | Standalone executable |
| 34 | --------------------- |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 35 | This section describes how to use the ``pw_target_runner_server`` program to |
| 36 | set up a simple unit test server with workers. |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 37 | |
| 38 | Configuration |
| 39 | ^^^^^^^^^^^^^ |
| 40 | The standalone server is configured from a file written in Protobuf text format |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 41 | containing a ``pw.target_runner.ServerConfig`` message as defined in |
Wyatt Hepler | 9174147 | 2021-02-03 08:45:10 -0800 | [diff] [blame] | 42 | ``//pw_target_runner/pw_target_runner_server_protos/exec_server_config.proto``. |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 43 | |
| 44 | At least one ``worker`` message must be specified. Each of the workers refers to |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 45 | a script or program which is invoked with the path to an executable file as a |
| 46 | positional argument. Other arguments provided to the program must be options/ |
| 47 | switches. |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 48 | |
| 49 | For example, the config file below defines two workers, each connecting to an |
| 50 | STM32F429I Discovery board with a specified serial number. |
| 51 | |
| 52 | **server_config.txt** |
| 53 | |
| 54 | .. code:: text |
| 55 | |
| 56 | runner { |
| 57 | command: "stm32f429i_disc1_unit_test_runner" |
| 58 | args: "--openocd-config" |
Rob Mohr | 3d61b32 | 2021-05-17 10:52:24 -0700 | [diff] [blame] | 59 | args: "targets/stm32f429i_disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg" |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 60 | args: "--serial" |
| 61 | args: "066DFF575051717867013127" |
| 62 | } |
| 63 | |
| 64 | runner { |
| 65 | command: "stm32f429i_disc1_unit_test_runner" |
| 66 | args: "--openocd-config" |
Rob Mohr | 3d61b32 | 2021-05-17 10:52:24 -0700 | [diff] [blame] | 67 | args: "targets/stm32f429i_disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg" |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 68 | args: "--serial" |
| 69 | args: "0667FF494849887767196023" |
| 70 | } |
| 71 | |
| 72 | |
| 73 | Running the server |
| 74 | ^^^^^^^^^^^^^^^^^^ |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 75 | To start the standalone server, run the ``pw_target_runner_server`` program and |
| 76 | point it to your config file. |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 77 | |
| 78 | .. code:: text |
| 79 | |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 80 | $ pw_target_runner_server -config server_config.txt -port 8080 |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 81 | |
| 82 | |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 83 | Sending requests |
| 84 | ^^^^^^^^^^^^^^^^ |
| 85 | To request the server to run an executable, run the ``pw_target_runner_client``, |
| 86 | specifying the path to the executable through a ``-binary`` option. |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 87 | |
| 88 | .. code:: text |
| 89 | |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 90 | $ pw_target_runner_client -host localhost -port 8080 -binary /path/to/my/test.elf |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 91 | |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 92 | This command blocks until the executable has finished running. Multiple |
| 93 | requests can be scheduled in parallel; the server will distribute them among its |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 94 | available workers. |
| 95 | |
| 96 | Library APIs |
| 97 | ------------ |
Armando Montanez | c0ad978 | 2019-12-30 14:58:00 -0800 | [diff] [blame] | 98 | To use the target runner library in your own code, refer to one of its |
| 99 | programming language APIs below. |
Alexei Frolov | d0b2d48 | 2019-12-04 11:06:23 -0800 | [diff] [blame] | 100 | |
| 101 | .. toctree:: |
| 102 | :maxdepth: 1 |
| 103 | |
| 104 | go/docs |