docs: add porting considerations for Ztest

Add a new section to the Ztest documentation providing details of
what sorts of EC unit tests are not good candidates for porting
to Ztest.

BUG=b:172240633, b:172240757
BRANCH=None
TEST=N/A

Signed-off-by: Paul Fagerburg <pfagerburg@google.com>
Change-Id: I3010dfb338e8e9c835c55b10a79a2e4dce703f96
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2648397
Tested-by: Paul Fagerburg <pfagerburg@chromium.org>
Reviewed-by: Jack Rosenthal <jrosenth@chromium.org>
Commit-Queue: Paul Fagerburg <pfagerburg@chromium.org>

1 files changed, 29 insertions, 0 deletions

diff --git a/docs/ztest.md b/docs/ztest.md
index 9c020c5d58..1dd4c91a0c 100644
--- a/docs/ztest.md
+++ b/docs/ztest.md
@@ -12,6 +12,35 @@ For examples of porting an EC unit test to the Ztest API, see:
 * [base32](https://crrev.com/c/2492527) and [improvements](https://crrev.com/c/2634401)
 * [accel_cal](https://crrev.com/c/2645198)
 
+## Porting Considerations
+
+Not every EC unit test can be ported to Ztest. This section describes cases
+that are not supported and cases where caveats apply.
+
+### EC Mocks Are Not Supported
+
+If a test has a `$TEST.mocklist` file associated with the unit test, it is
+using the EC mocking framework, which is unsupported in the Ztest framework.
+Ztest has its own mocking framework which the EC does not support.
+
+### Multiple Task Caveats
+
+The EC unit test framework starts a single task to call `run_test`, and this
+task will then call the functions for the various test cases.  Some unit tests
+have multiple threads of execution, which is enabled by a `$TEST.tasklist`
+file associated with the unit test. The test runner task has a task ID of
+`TASK_ID_TEST_RUNNER`, which can be used as an argument to any of the task
+functions. See for example the [`charge_ramp` unit test](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/test/charge_ramp.c#81)
+and the [`host_command` unit test](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/test/host_command.c#32)
+
+When a unit test is ported to Ztest, `test_main` doesn't have a thread ID, so
+`TASK_ID_TEST_RUNNER` is undefined. `charge_ramp` and `host_command` cannot
+be ported at this time. `test_main` also cannot call any of the task functions
+that must be called from a task, such as `task_wake`; these functions can pend
+the calling task, but since `test_main` doesn't have a thread ID, the pend
+will fail. See the [`mutex` unit test](https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/test/mutex.c#116)
+for an example.
+
 ## Determine source files being tested
 
 Determine which C files the unit test requires by finding the test in