psasim: update README file
The README file content dates back to the early stages of PSASIM
development. Since then a lot of things have changed, so the README
file required a complete rewrite.
Signed-off-by: Valerio Setti <valerio.setti@nordicsemi.no>
diff --git a/tests/psa-client-server/psasim/README.md b/tests/psa-client-server/psasim/README.md
index 1b950d6..db49ae9 100644
--- a/tests/psa-client-server/psasim/README.md
+++ b/tests/psa-client-server/psasim/README.md
@@ -1,61 +1,42 @@
# psasim
-This tool simulates a PSA Firmware Framework implementation.
-It allows you to develop secure partitions and their clients on a desktop computer.
-It should be able to run on all systems that support POSIX and System V IPC:
-e.g. macOS, Linux, FreeBSD, and perhaps Windows 10 WSL2.
+PSASIM holds necessary C source and header files which allows to test Mbed TLS in a "pure crypto client" scenario, i.e `MBEDTLS_PSA_CRYPTO_CLIENT && !MBEDTLS_PSA_CRYPTO_C`.
+In practical terms it means that this allow to build PSASIM with Mbed TLS sources and get 2 Linux applications, a client and a server, which are connected through Linux's shared memeory, and in which the client relies on the server to perform all PSA Crypto operations.
-Please note that the code in this directory is maintained by the Mbed TLS / PSA Crypto project solely for the purpose of testing the use of Mbed TLS with client/service separation. We do not recommend using this code for any other purpose. In particular:
+The goal of PSASIM is _not_ to provide a ready-to-use solution for anyone looking to implement the pure crypto client structure (see [Limitations](#limitations) for details), but to provide an example of TF-PSA-Crypto RPC (Remote Procedure Call) implementation using Mbed TLS.
+## Limitations
-* This simulator is not intended to pass or demonstrate compliance.
-* This code is only intended for simulation and does not have any security goals. It does not isolate services from clients.
+In the current implementation:
-## Building
+- Only Linux PC is supported.
+- There can be only 1 client connected to 1 server.
+- Shared memory is the only communication medium allowed. Others can be implemented (ex: net sockets), but in terms of simulation speed shared memory proved to be the fastest.
+- Server is not secure at all: keys and operation structs are stored on the RAM, so they can easily be dumped.
-To build and run the test program make sure you have `make`, `python` and a
-C compiler installed and then enter the following commands:
+## Testing
-```sh
-make run
-```
+Please refer to `tests/scripts/components-psasim.sh` for guidance on how to build & test PSASIM:
-Optionally the `DEBUG=1` command line option can be enabled to increase verbosity:
+- `component_test_psasim()`: builds the server and a couple of test clients which are used to evaluate some basic PSA Crypto API commands.
+- `component_test_suite_with_psasim()`: builds the server and _all_ the usual test suites (those found under the `<mbedtls-root>/tests/suites/*` folder) which are used by the CI and runs them. A small subset of test suites (`test_suite_constant_time_hmac`,`test_suite_lmots`,`test_suite_lms`) are being skipped, for CI turnover time optimization. They can be run locally if required.
-```sh
-make DEBUG=1 run
-```
+## How to update automatically generated files
-Once done with the test, it is possible to clean all the generated files with:
+A significant portion of the intermediate code of PSASIM is auto-generated using Perl. In particular:
-```sh
-make clean
-```
+- `psa_sim_serialise.[c|h]`:
+ - Generated by `psa_sim_serialise.pl`.
+ - These files provide the serialisation/deserialisation support that is required to pass functions' parameters between client and server.
+- `psa_sim_crypto_[client|server].c` and `psa_functions_codes.h`:
+ - Generated by `psa_sim_generate.pl`.
+ - `psa_sim_crypto_[client|server].c` provide interfaces for PSA Crypto APIs on client and server sides, while `psa_functions_codes.h` simply enumerates all PSA Crypto APIs.
-## Features
+These files need to be regenerated whenever some PSA Crypto API is added/deleted/modified. The procedure is as follows:
-The implemented API is intended to be compliant with PSA-FF 1.0.0 with the exception of a couple of things that are a work in progress:
-
-* `psa_notify` support
-* "strict" policy in manifest
-
-The only supported "interrupts" are POSIX signals, which act
-as a "virtual interrupt".
-
-The standard PSA RoT APIs are not included (e.g. cryptography, attestation, lifecycle etc).
-
-## Design
-
-The code is designed to be readable rather than fast or secure.
-In this implementation only one message is delivered to a
-RoT service at a time.
-The code is not thread-safe.
-
-## Unsupported features
-
-Because this is a simulator there are a few things that
-can't be reasonably emulated:
-
-* Manifest MMIO regions are unsupported
-* Manifest priority field is ignored
-* Partition IDs are in fact POSIX `pid_t`, which are only assigned at runtime,
- making it infeasible to populate pid.h with correct values.
+- `psa_sim_serialise.[c|h]`:
+ - go to `<mbedtls-root>/tests/psa-client-server/psasim/src/`
+ - run `./psa_sim_serialise.pl h > psa_sim_serialise.h`
+ - run `./psa_sim_serialise.pl c > psa_sim_serialise.c`
+- `psa_sim_crypto_[client|server].c` and `psa_functions_codes.h`:
+ - go to Mbed TLS' root folder
+ - run `./tests/psa-client-server/psasim/src/psa_sim_generate.pl`