docs/tfm_erpc_test_framework.rst

############################
The TF-M eRPC Test Framework
############################

The TF-M eRPC Test Framework is an Remote Procedure Call (RPC) framework for testing purpose.
It's based on the `eRPC <https://github.com/EmbeddedRPC/erpc>`__ system.
It is an additional framework to the existing one for running NS test suites.
It enables you to run test codes on host machines as if they were running on the device.
It has the following advantages.

- Off-load test codes from device to host

  Arm M-profile devices usually have limited flash storage which can only fit limited test suites.
  With test codes running on hosts you can run far more tests than on the devices.

- Less frequent image downloading for test code development.

  As the test codes run on the host, you don't need to update the image on device when you update
  test codes.

- Host can get test pass or failure directly from the return codes.

  This would be helpful for test automation because you don't need to parse the test logs.

****************
How Does It Work
****************
Originally, the NS tests are executed in the NSPE of the device.
The NS image on the device contains the test codes, which calls into TF-M through the PSA client
APIs.

With the eRPC test framework, the NS tests code are executed on the host machine.
The NSPE of device side does not run the test codes anymore.
When the tests call the PSA client APIs, they call into the eRPC framework.
The eRPC framework communicates with the NSPE on the device, which calls into TF-M through the PSA
client APIs.

The prototypes of the PSA client APIs are the same while the implementations are different.
Refer to the following sections for more details.

The Stucture
============

The following diagram shows the software structure.

.. figure:: media/erpc_test_framework.svg

- eRPC Framework

  The eRPC framework system

- eRPC Client Shim

  The eRPC generated shim layer of remote APIs for clients.
  It serializes the identifier of the API and its parameters into a stream of bytes and transports
  to the server through a communication channel such as UART and TCP/IP.
  The codes are generated by the `erpcgen tool <https://github.com/EmbeddedRPC/erpc/wiki/erpcgen>`_.

- eRPC Server Shim

  The generated shim layer of the server.
  It registers a callback function to the eRPC framework.
  When the framework receives any requests from the client, it calls the callback function.
  The callback unserializes the bytes streams to determine what API to call and then invoke it with
  the corresponding parameters from the bytes streams.
  And then it returns the results to the client in the reverse routine.

- API Wrapper

  Part of the parameters of ``psa_call`` API is not supported by eRPC directly, thus an API wrapper
  is required to transform the ``in_vec/out_vec`` structures to the eRPC supported data types.
  The wrapper API is named as ``erpc_psa_call``.

  On the client side, the wrapper implements the ``psa_call`` which calls the ``erpc_psa_call`` in
  the client shim layer.
  On the server side, the wrapper implements the ``erpc_psa_call`` which is called by the shim layer.
  The ``erpc_psa_call`` then calls the ``psa_call``.

- Test Suites

  Can be the existing TF-M regression tests or any other tests that interact with TF-M using the
  PSA Client APIs.

- Host App

  Initializes the eRPC client and starts test suites.

- Target App

  Initializes the eRPC server and listens for requests from the client.

Supported APIs
==============

The APIs supported for doing RPC are the PSA Client APIs because they are the lowest level APIs that
interact with TF-M. You can build lots of test suites upon them.
You can also add your own APIs in the ``tfm.erpc`` file.
Please refer to `IDL Reference <https://github.com/EmbeddedRPC/erpc/wiki/IDL-Reference>`_ for the
syntax of the file.

API Grouping
************

PSA client APIs are categorised into common APIs and connection-based service APIs.
Connection-based APIs are available when there are connection-based services in the TF-M.
So in the eRPC integration, the APIs are also split into two groups so that the shim layer of the
APIs can be separated into different files as well.
Then build systems can decide which source files to build based on the existence of connection-based
services.

Common APIs:

- psa_framework_version()
- psa_version()
- psa_call()

Connection-based specific:

- psa_connect()
- psa_close()

Transportation
==============

On device side, only UART transportation is supported in NSPE.
For the host side, both UART and TCP are supported.
The TCP transportation support is basically for fast models where UART data are transferred between
a TCP/IP socket on the host and a serial port on the target.
See the
`fast model reference guide <https://developer.arm.com/documentation/100966/1116/Getting-Started-with-Fixed-Virtual-Platforms/Using-a-terminal-with-a-system-model>`_
for more details.

********************
Platform Integration
********************

First, the UART drivers of platforms shall support TX/RX control feature.
The TF-M build system provides a ``CONFIG_ENABLE_NS_UART_TX_RX_CONTROL`` option to enable or disable
the TX/RX control feature and it is disabled by default.
When the eRPC test framework is enabled, the ``CONFIG_ENABLE_NS_UART_TX_RX_CONTROL`` will be enabled
automatically.

Secondly, platforms need to specify the UART port and driver for eRPC transportation config via
``target_cfg.h``.

.. code-block::

  #define ERPC_UART           Driver_USART0

It's recommended to use a different UART to the stdio UART.
If the same UART is used for both, then the TF-M logs (both SPM and Secure Partitions) must be
disabled.
Otherwise, the eRPC transportation might fail.

***********************
Application Integration
***********************

The TF-M eRPC test framework provides two CMake libraries for integration.
One is the ``erpc_client``, the other is the ``erpc_server``.
Both include the eRPC framework, the shim layers, API wrappers and expose an initialization API
for client and server respectively.

The initialization does not include the initialization of the transportation layer because it is use
case specific which kind of transportation is used.
So it is the client and server's responsibilities to initialize the transportation layers and pass
them to the ``erpc_client`` and ``erpc_server``.

TF-M provides a ``app/erpc_app.c`` as the default server application which initializes the UART
transportation and starts the eRPC server.

A config option ``CONFIG_TFM_ERPC_TEST_FRAMEWORK`` is provided to enable the eRPC framework on
device (server) side.
The default server will be built and developers only need to focus on the client application
developments.

In summary, on the server side, you only need to build with the ``CONFIG_TFM_ERPC_TEST_FRAMEWORK``
enabled.
On the client side, you must

- Initializes the transportation layer using eRPC provided APIs.
- Call the initialization function provided by TF-M eRPC test framework with the transportation
  instance initialized above.
- Develop the application code
- Building with CMake

  - ``add_subdirectory`` with the ``erpc/client``
  - link the ``erpc_client`` library

There is an example at ``erpc/host_example`` for reference.

--------------

*Copyright (c) 2023, Arm Limited. All rights reserved.*