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

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.
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 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 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 create their folders under the erpc/platform and then create the config_erpc_target.h to specify the UART port drivers 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 TF-M repo.

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.