The TF-M eRPC Test Framework

The TF-M eRPC Test Framework is a Remote Procedure Call (RPC) based test framework written in order to have complex test cases running on a host system which trigger the PSA client APIs on a connected target. It is based on the eRPC project. It is an additional framework to the existing one which runs NS test suites entirely on the target. 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 Cortex-M based platform devices usually have limited flash storage which can only fit small test suites. With test codes running on hosts you can run far more tests than on the devices, within a richer test environment.
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 the system which triggers the tests can read the results programmatically and not relying on parsing the UART logs like it happens for the current device-based tests.

How Does It Work

Usually, the NS tests are executed in the NSPE of the device. The NS image on the device contains the test code, which calls into TF-M through the PSA client APIs.

Using the eRPC test framework, the tests use a client-server architecture: the NS test code is executed on the host machine as a client, while the NSPE on the device implements the server side. The NSPE of device side does not run the test code anymore. When the tests call the PSA client APIs, they call into the eRPC framework. The eRPC framework handles the communication 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 Structure

The following diagram shows the software structure.

eRPC Framework

The eRPC (Embedded Remote Procedure Call) 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. To re-generate the shim code for server and client side:
```
cd <tf-m-tests/erpc>
erpcgen -o generated_files/ -v tfm.erpc
```
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 deserializes the byte stream to determine what API to call and then invokes it with the corresponding parameters from the byte stream. 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 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

It 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 the test suites.
Target App

Initializes the eRPC server and listens for requests from the eRPC 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 for the syntax of the file.

API Grouping

PSA Client APIs are categorized into common APIs and connection-based service APIs. Connection-based APIs can only be used if there are connection-based services enabled in TF-M, otherwise they return with an error code.

Common APIs:

psa_framework_version()
psa_version()
psa_call()

Connection-based specific APIs:

psa_connect()
psa_close()

Transportation layer

On the device side, only UART transportation is supported in NSPE being the most common peripheral that is generally available on all supported platforms. For the host side, both UART and TCP are available. The main use case of the TCP transport from the host side is to interface with Fast Models (FVPs) where the UART data is getting transferred between a TCP/IP socket of the host and a serial port of the target. This happens with the help of a virtual component of the model called the TelnetTerminal which acts as a gateway between the host and the target. See the Fast Models reference guide for more details.

Platform Integration

As a basic requirement the platform must provide a UART driver that is compliant with the CMSIS-Driver specification and support the enablement of the receiver and transmitter side of the peripheral via the ARM_USART_Control() CMSIS API. These requirements are coming from the fact that the UART transport implementation in eRPC is based on CMSIS-Driver APIs.

Secondly, platforms need to create their folders under the erpc/platform and then create the config_erpc_target.h to specify the UART port to be used for eRPC transportation.

#define ERPC_UART           Driver_USART0

Note

The folder structure in erpc/platform must be the same as the platform/ext/target of the TF-M repository.

It is recommended to use a different UART than the one used for stdio. If the same UART device is used for both, then the TF-M logs (both SPM and Secure Partitions) and any log messages from the NSPE must be disabled. Otherwise, the eRPC transportation might fail. This happens when the eRPC messages are intermixed with other data (e.g. log messages) on the same UART device ultimately corrupting eRPC communication.

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 the client and server respectively.

The initialization does not include the initialization of the transportation layer as it is use case specific which kind of transportation is used. It is the responsibility of the client and server applications to initialize the transportation layers and pass them to the erpc_client and erpc_server components.

TF-M provides the app/erpc_app.c as the default server application which first initializes a CMSIS UART transport and then starts the eRPC server.

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

In summary, on the server side the only requirement is to enable CONFIG_TFM_ERPC_TEST_FRAMEWORK option at build time. On the client side, one must:

Initialize the transportation layer using eRPC provided APIs,
Call the eRPC client initialization function provided by TF-M’s eRPC test framework with the transportation instance initialized above as its parameter,
Develop the application code,
Building with CMake:
- add_subdirectory with the erpc/client,
- link the erpc_client library to the application.

For more information on how to build and run the TF-M regression test suites on various platforms please refer to this document. There is also an example of a simple host application at erpc/host_example for reference.