1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
############################
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 create their folders under the ``erpc/platform`` and then create the
``config_erpc_target.h`` to specify the UART port drivers for eRPC transportation.
.. code-block::
#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.
--------------
*Copyright (c) 2023, Arm Limited. All rights reserved.*
|