From f74f1def29877e3b444ed59ea307c57455934ea0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kacper=20R=C4=85czy?= <gfw.kra@gmail.com>
Date: Thu, 20 Jul 2023 02:50:26 +0200
Subject: [PATCH] process_replay: API docs (#29041)

* Update process_replay README

* Expose get_custom_params_from_lr in top-level module
---
 selfdrive/test/process_replay/README.md   | 71 ++++++++++++++++++++++-
 selfdrive/test/process_replay/__init__.py |  2 +-
 2 files changed, 71 insertions(+), 2 deletions(-)

diff --git a/selfdrive/test/process_replay/README.md b/selfdrive/test/process_replay/README.md
index 531ddb3a02..571157dfc9 100644
--- a/selfdrive/test/process_replay/README.md
+++ b/selfdrive/test/process_replay/README.md
@@ -15,9 +15,10 @@ Currently the following processes are tested:
 * calibrationd
 * dmonitoringd
 * locationd
-* laikad
 * paramsd
 * ubloxd
+* laikad
+* torqued
 
 ### Usage
 ```
@@ -45,3 +46,71 @@ To generate new logs:
 `./test_processes.py`
 
 Then, check in the new logs using git-lfs. Make sure to also update the `ref_commit` file to the current commit.
+
+## API
+
+Process replay test suite exposes programmatic APIs for simultaneously running processes or groups of processes on provided logs. 
+
+```py
+def replay_process_with_name(name: Union[str, Iterable[str]], lr: Union[LogReader, List[capnp._DynamicStructReader]], *args, **kwargs) -> List[capnp._DynamicStructReader]:
+
+def replay_process(
+  cfg: Union[ProcessConfig, Iterable[ProcessConfig]], lr: Union[LogReader, List[capnp._DynamicStructReader]], frs: Optional[Dict[str, Any]] = None, 
+  fingerprint: Optional[str] = None, return_all_logs: bool = False, custom_params: Optional[Dict[str, Any]] = None, disable_progress: bool = False
+) -> List[capnp._DynamicStructReader]:
+```
+
+Example usage:
+```py
+from selfdrive.test.process_replay import replay_process_with_name
+from tools.lib.logreader import LogReader
+
+lr = LogReader(...)
+
+# provide a name of the process to replay
+output_logs = replay_process_with_name('locationd', lr)
+
+# or list of names
+output_logs = replay_process_with_name(['ubloxd', 'locationd', 'laikad'], lr)
+```
+
+Supported processes: 
+* controlsd
+* radard
+* plannerd
+* calibrationd
+* dmonitoringd
+* locationd
+* paramsd 
+* ubloxd
+* laikad
+* torqued
+* modeld
+* dmonitoringmodeld
+
+Certain processes may require an initial state, which is usually supplied within `Params` and persisting from segment to segment (e.g CalibrationParams, LiveParameters). The `custom_params` is dictionary  used to prepopulate `Params` with arbitrary values. The `get_custom_params_from_lr` helper is provided to fetch meaningful values from log files.
+
+```py
+from selfdrive.test.process_replay import get_custom_params_from_lr
+
+previous_segment_lr = LogReader(...)
+current_segment_lr = LogReader(...)
+
+custom_params = get_custom_params_from_lr(previous_segment_lr, 'last')
+
+output_logs = replay_process_with_name('calibrationd', lr, custom_params=custom_params)
+```
+
+Replaying processes that use VisionIPC (e.g. modeld, dmonitoringmodeld) require additional `frs` dictionary with camera states as keys and `FrameReader` objects as values.
+
+```py
+from tools.lib.framereader import FrameReader
+
+frs = {
+  'roadCameraState': FrameReader(...),
+  'wideRoadCameraState': FrameReader(...),
+  'driverCameraState': FrameReader(...),
+}
+
+output_logs = replay_process_with_name(['modeld', 'dmonitoringmodeld'], lr, frs=frs)
+```
\ No newline at end of file
diff --git a/selfdrive/test/process_replay/__init__.py b/selfdrive/test/process_replay/__init__.py
index 6667deaa2d..a9dbc71830 100644
--- a/selfdrive/test/process_replay/__init__.py
+++ b/selfdrive/test/process_replay/__init__.py
@@ -1 +1 @@
-from selfdrive.test.process_replay.process_replay import CONFIGS, get_process_config, replay_process, replay_process_with_name  # noqa: F401
+from selfdrive.test.process_replay.process_replay import CONFIGS, get_process_config, get_custom_params_from_lr, replay_process, replay_process_with_name  # noqa: F401