Update PSA tools Readme

Author: Alexander Zilberkant

tools/psa/README.md

@@ -1,35 +1,40 @@
 # PSA tools
 
-This document describes the following scripts:
+## Code generation script
 
-* \_\_init\_\_.py
-* generate_partition_code.py
-* mbed_spm_tfm_common.py
-* release.py
+Mbed-OS contains two implementations of PSA Firmware Framework:
 
-## \_\_init\_\_.py
-
-This file holds common functions dedicated to help SiP with their post-build logic.
+* Mbed-SPM - Implementation for dual-core v7 targets.
+* TF-M - Implementation for v8 targets.
 
-* find_secure_image - Scans a Resource object to find the correct binary of the secure image to merge with the non-secure build.
+Both PSA Firmware Framework implementation impose the following requirements:
 
-## Code generation scripts
+* PSA manifests must be valid according to the JSON schema file provided by PSA FF spec.
+* There are no conflicts between various PSA manifests (duplicate SIDs and PIDs, dependencies, etc.)
+* Secure partition initialization code to be present at mbed-os core compile time.
 
-Mbed OS holds two implementations of PSA:
+To satisfy the requirement listed above, Mbed-OS build system invokes `generate_partition_code.py` script
+during the build process for PSA targets.
 
-* MBED_SPM - Implementation for dual-core v7 targets.
-* TF-M - Implementation for v8 targets.
+PSA code generation step has the following effects:
+* Scan the whole source tree for PSA manifest files, including application (in case invoked from application directory) and all the `TESTS` directories.
+* All found PSA manifest files get parsed and validated.
+* Source and header files for initializing SPM are generated. Test related partitions and SIDs are disabled by default by `#ifndef` guards. 
+  To enable them following defines must be passed to build command (typically done automatically via [release.py](#secure-image-generation)):
+  * `-DUSE_PSA_TEST_PARTITIONS`
+  * `-DUSE_<name>` where `<name>` corresponds to the name in PSA manifest file (`"name"` property).
 
-Each implementation requires a set of auto-generated files describing the secure partitions:
+## Secure image generation
 
-* `generate_partition_code.py` - Generate files for both implementations.
-* `mbed_spm_tfm_common.py` - Holds common functions for both.
+`release.py` is the script assigned with compiling the default secure images.
 
-## Secure image generation
+For an application with custom secure portions, the secure image should be generated by invoking `mbed-cli` directly.
 
-`release.py` is the script assigned with compiling the secure images:
+> **Note**: when building targets utilizing TF-M PSA implementations, add the following arguments to a build command for the secure image: 
+  `--app-config <mbed-os-root>/tools/psa/tfm/mbed_app.json`
 
-```
+### Usage
+```text
 usage: release.py [-h] [-m MCU] [-d] [-q] [-l] [--commit] [--skip-tests]
                   [-x ...]