mbed-os/tools/psa/README.md

# PSA tools

## Code generation script

Mbed-OS contains two implementations of PSA Firmware Framework:

* Mbed-SPM - Implementation for dual-core v7 targets.
* TF-M - Implementation for v8 targets.

Both PSA Firmware Framework implementation impose the following requirements:

* 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.

To satisfy the requirement listed above, Mbed-OS build system invokes `generate_partition_code.py` script
during the build process for PSA 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).

## Secure image generation

`release.py` is the script assigned with compiling the default secure images.

For an application with custom secure portions, the secure image should be generated by invoking `mbed-cli` directly.

> **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] [-t TC] [-d] [-q] [-l] [--commit]
                  [--skip-tests] [-x ...]

optional arguments:
  -h, --help           show this help message and exit
  -m MCU, --mcu MCU    build for the given MCU
  -t TC, --tc TC       build for the given tool chain (default is
                       default_toolchain)
  -d, --debug          set build profile to debug
  -q, --quiet          No Build log will be printed
  -l, --list           Print supported PSA secure targets
  --commit             create a git commit for each platform
  --skip-tests         skip the test build phase
  -x ..., --extra ...  additional build parameters
```

* When `MCU ` is not specified, the script compiles all the images for all the targets.
* When `-t/--tc` is not specified, the script compiles with the default_toolchain speciified in targets.json.
* When `-d/--debug` is not specified, the script compiles the images using the release profile.
* When `--commit` is not specified, the script will not commit the images to git.
* A user can specify additional commands that will be passed on to the build commands (Ex. -D for compilation defines).

This script should be run in following scenarios:

* Release.
* Update to files originating in the secure side.
* Drivers update.
* PSA updates.