|
1 | | -# test-refactor |
| 1 | +# wolfHSM unit tests |
2 | 2 |
|
3 | | -Prototype of the refactored wolfHSM test infrastructure. |
| 3 | +## TLDR |
| 4 | +To run the unit tests on a POSIX system (Linux/Mac): |
4 | 5 |
|
5 | | -## Key differences from test/ |
| 6 | +``` |
| 7 | +cd test-refactor/posix |
| 8 | +make check |
| 9 | +``` |
6 | 10 |
|
7 | | -- **Runner** (`wh_test_runner.h/c`): generic suite executor. |
8 | | - Each suite is a name + NULL-terminated test array, run |
9 | | - either via `whTestRunner_Run` (suite owns its setup/cleanup) |
10 | | - or `whTestRunner_RunWithCtx` (caller provides the live |
11 | | - context). Group functions use the latter. |
12 | | -- **App-owned init**: the port's main() brings up the server |
13 | | - and client once at startup (mirroring real firmware boot) |
14 | | - and hands the live contexts to the group functions. Suites |
15 | | - no longer stand up their own fixtures. |
16 | | -- **Port helpers** (`wh_test_helpers_server_<port>.h/c`, |
17 | | - `wh_test_helpers_client_<port>.h/c`): per-port files that |
18 | | - stand in for what a real target does at boot -- configure |
19 | | - flash, init NVM/crypto, wire up a transport, bring up the |
20 | | - server or client context. |
21 | | -- **Groups** (`wh_test_groups.h/c`): three portable entry |
22 | | - points (Misc/Server/Client) that main invokes. Each runs |
23 | | - its gated suites and calls the caller-implemented reset |
24 | | - hook between them. |
25 | | -- **Threaded driver**: the POSIX port's main runs the server |
26 | | - and client on separate threads. The server thread runs the |
27 | | - server-only group first, then enters a `HandleRequestMessage` |
28 | | - loop; the client thread runs the client-only group against |
29 | | - the live server. Ports that already split server and client |
30 | | - onto different cores/tasks do the same thing natively. |
31 | | -- **Platform split**: platform-specific code is isolated in |
32 | | - `wh_test_helpers_server_<port>.c`, |
33 | | - `wh_test_helpers_client_<port>.c`, and |
34 | | - `wh_test_main_<port>.c`. Test modules and groups are |
35 | | - identical on all platforms. |
| 11 | +Results are printed via `WOLFHSM_CFG_PRINTF` from the wolfHSM build. `test-suite.log` contains the detailed output. |
36 | 12 |
|
37 | | -## Suites implemented so far |
| 13 | +## Overview |
| 14 | +The wolfHSM unit tests are split into 3 groups: |
38 | 15 |
|
39 | | -| Suite | Group | Description | |
40 | | -|-------|-------|-------------| |
41 | | -| Flash RamSim | misc | Write-lock, erase, program, verify, blank-check | |
42 | | -| NVM Flash | misc | Flash unit ops, NVM add/overwrite/destroy/reclaim | |
43 | | -| Cert | server | Server-side cert add/verify/chain/erase | |
44 | | -| ClientServer | client-server | Echo round-trip, server info query | |
45 | | -| ThreadSafe Stress | client-server | Phased multi-thread contention (unchanged internals) | |
| 16 | +- Client, for tests that run on the client core/process |
| 17 | +- Server, for tests that run on the server core/process |
| 18 | +- Misc, for tests that can run on either core/process |
46 | 19 |
|
47 | | -## Remaining tests to port |
| 20 | +The groups are organized in `wh_test_list.c`. |
48 | 21 |
|
49 | | -| Suite | Group | Description | |
50 | | -|-------|-------|-------------| |
51 | | -| Comm | client-server | Transport layer (mem, TCP, SHM) | |
52 | | -| Crypto | client-server | AES, RSA, ECC, CMAC, curve25519, ed25519, etc. | |
53 | | -| Crypto Affinity | client-server | Device ID operation routing | |
54 | | -| SHE | client-server | Secure Hardware Extension key load, crypto, secure boot | |
55 | | -| Keywrap | client-server | Key wrap/unwrap operations | |
56 | | -| Log | misc | Logging frontend, ringbuf, POSIX file backends | |
57 | | -| Lock | misc | Lock primitives with POSIX backend | |
58 | | -| DMA | misc | DMA address translation and allow-list | |
59 | | -| Server Img Mgr | server | Image manager verify/install/erase | |
60 | | -| Timeout | client-server | POSIX timeout enforcement | |
61 | | -| wolfCrypt Test | client-server | wolfCrypt test suite via wolfHSM transport | |
62 | | -| MultiClient | client-server | 2 CS pairs, shared NVM, global/local key isolation | |
| 22 | +## Adding a port |
| 23 | +The unit tests run within the port's main application. As a prerequiste, setup a new port application as described in the [porting guide](docs/src/chapter08.md). |
63 | 24 |
|
64 | | -## Platforms requiring update |
| 25 | +For the unit test port, see `wh_test_posix_main.c` and the two `wh_test_posix_*.c` sources as a reference implementation. |
65 | 26 |
|
66 | | -Each platform with test infrastructure needs its own |
67 | | -`wh_test_helpers_server_<port>.c`, |
68 | | -`wh_test_helpers_client_<port>.c`, and |
69 | | -`wh_test_main_<port>.c` (see "Porting" below). |
| 27 | +### Client |
| 28 | +1. Implement `main()` which creates a client context |
| 29 | +1. Implement `whTestGroup_ResetClient` which resets the context between tests. Can be empty. |
| 30 | +2. Optionally call `whTestGroup_Misc()` |
| 31 | +3. Call `whTestGroup_Client(&clientCtx)` |
70 | 32 |
|
71 | | -| Platform | Vendor | Test files | |
72 | | -|----------|--------|------------| |
73 | | -| POSIX | wolfSSL | `test-refactor/posix/` (done) | |
74 | | -| Bernina | STMicro | `bernina-server/src/bh_test.c` | |
75 | | -| SR6 | STMicro | (no test files found) | |
76 | | -| TC3xx | Infineon | `port/client/wolfhsm_tests.c`, `port/server/ccb_tests.c` | |
77 | | -| RH850 F1KM | Renesas | `rh850_test2_1/`, `rh850_test2_2/` | |
78 | | -| PIC32CZ | Microchip | `czhsm-client/tests/`, `czhsm-server/` | |
79 | | -| TDA4VH | TI | (no test files found) | |
80 | | -| New Eagle | Customer | (no test files found) | |
| 33 | +### Server |
| 34 | +The client unit tests can be run against the normal server application -- no special modifications required. |
81 | 35 |
|
82 | | -## File layout |
| 36 | +To add the server side unit tests: |
| 37 | +1. Implement `whTestGroup_ResetServer` which resets the context between tests. Can be empty. |
| 38 | +2. Call `whTestGroup_Server(&serverCtx)` prior to entering the main request handling loop. |
83 | 39 |
|
84 | | -``` |
85 | | -Portable (ships in wolfHSM): |
86 | | - wh_test_runner.h/c - suite runner |
87 | | - wh_test_groups.h/c - Misc/Server/Client entry points |
88 | | - server/wh_test_*.c/h - server-only test modules |
89 | | - client-server/wh_test_*.c/h - client-server test modules |
90 | | - misc/wh_test_*.c/h - standalone test modules |
91 | | -
|
92 | | -Platform-specific (one directory per platform, e.g. posix/): |
93 | | - <port>/wh_test_helpers_misc_<port>.h/c - misc fixtures |
94 | | - <port>/wh_test_helpers_server_<port>.h/c - server bringup |
95 | | - <port>/wh_test_helpers_client_<port>.h/c - client bringup |
96 | | - <port>/wh_test_main_<port>.c - init, group |
97 | | - dispatch, reset |
98 | | - hooks |
99 | | - <port>/Makefile - build rules |
100 | | -``` |
| 40 | +## Adding a test |
| 41 | +1. Create a new function which returns `int` (0 for success) with a context argument (`whClientContext*` for client tests, `whServerContext*` for server tests, or none for misc tests). |
| 42 | +2. In wh_test_list.c, add a line with `WH_TEST_DECL(<function>)` |
| 43 | +3. In wh_test_list.c, add the function to the appropriate `whTestCase` array. |
101 | 44 |
|
102 | | -## Porting to other platforms |
| 45 | +**Note**: if the test is specific to a platform, do not add it to the common list as shown above. Port-specific tests live within the port (not this directory), and are called from the port-specific code. |
103 | 46 |
|
104 | | -1. Implement the init helpers for the side(s) the target |
105 | | - needs. These stand in for what your firmware's normal |
106 | | - boot flow already does -- if it's simpler to call your |
107 | | - existing init code directly from main, that works too: |
108 | | - - `whTestHelperPosix_Server_Init/Cleanup` (reference): |
109 | | - bring up flash/NVM/crypto/transport/server. |
110 | | - - `whTestHelperPosix_Client_Init/Cleanup` (reference): |
111 | | - bring up client comm + handshake. On single-process |
112 | | - targets, the server runs in its own thread and pumps |
113 | | - `HandleRequestMessage` itself. |
114 | | -2. Provide a `main()` that: |
115 | | - - Calls `whTestGroup_Misc()` for standalone tests. |
116 | | - - Brings up the server/client contexts once. |
117 | | - - Calls `whTestGroup_Server(&server)` and/or |
118 | | - `whTestGroup_Client(&client)` with the live handles. |
119 | | - - Tears the contexts down. |
120 | | - - Implements `whTestGroup_ResetServer` and/or |
121 | | - `whTestGroup_ResetClient` -- called between suites to |
122 | | - scrub persistent state. |
123 | | -3. Add the portable `.c` files and your port files to your |
124 | | - build system. |
| 47 | +## Next steps |
| 48 | +- Redesign the nvm_flash test to remove the dependency on the ramsim backend and become port-agnostic and runable on embedded targets, and move to the server group. |
| 49 | +- Redesign `whTest_LockConfig` and `whTest_LogBackend_RunAll` to fit into the misc group, likely with a context param. |
| 50 | +- Translate remaining tests from wolfHSM/test to this design, and confirm equivalent code coverage. |
125 | 51 |
|
126 | | -See `wh_test_main_posix.c` and the two `*_posix.c` helpers as |
127 | | -a reference implementation. |
128 | | - |
129 | | -## Build and run (POSIX) |
130 | | - |
131 | | -``` |
132 | | -cd posix |
133 | | -make run |
134 | | -make run DEBUG=1 |
135 | | -make run THREADSAFE=1 # enables stress test gate |
136 | | -``` |
0 commit comments