Docs: Generic update to the eRPC framework document
- Update obsolete information,
- Basic RST style fixes found by doc8,
- Add command example to generate shim code.
Signed-off-by: David Vincze <david.vincze@arm.com>
Change-Id: If59a7bc259b511f69a4ecd029cdd8b4f272c1d98
diff --git a/docs/tfm_erpc_test_framework.rst b/docs/tfm_erpc_test_framework.rst
index 146e12e..bb82595 100644
--- a/docs/tfm_erpc_test_framework.rst
+++ b/docs/tfm_erpc_test_framework.rst
@@ -2,44 +2,50 @@
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.
+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 <https://github.com/EmbeddedRPC/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 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.
+ 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.
+- 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.
+ 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.
+- 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.
+ 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
****************
-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
+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.
-The prototypes of the PSA client APIs are the same while the implementations are different.
-Refer to the following sections for more details.
+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 Stucture
-============
+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.
@@ -47,101 +53,108 @@
- eRPC Framework
- The eRPC framework system
+ 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 <https://github.com/EmbeddedRPC/erpc/wiki/erpcgen>`_.
+ 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>`_.
+ To re-generate the shim code for server and client side:
+
+ .. code-block:: bash
+
+ 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 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.
+ 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 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``.
+ 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
- Can be the existing TF-M regression tests or any other tests that interact with TF-M using the
- PSA Client APIs.
+ 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 test suites.
+ Initializes the eRPC client and starts the test suites.
- Target App
- Initializes the eRPC server and listens for requests from the client.
+ 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 <https://github.com/EmbeddedRPC/erpc/wiki/IDL-Reference>`_ for the
-syntax of the file.
+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.
+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()
-- psa_framework_version()
-- psa_version()
-- psa_call()
+Connection-based specific APIs:
+ - psa_connect()
+ - psa_close()
-Connection-based specific:
+Transportation layer
+====================
-- 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>`_
+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
+<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.
+As a basic requirement the platform must provide a UART driver that is
+compliant with the `CMSIS-Driver specification
+<https://www.keil.com/pack/doc/CMSIS_Dev/Driver/html/index.html>`_ 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
+<https://github.com/EmbeddedRPC/erpc/blob/1.9.1/erpc_c/transports/erpc_uart_cmsis_transport.h>`_
+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 drivers for eRPC transportation.
+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.
.. code-block::
@@ -149,51 +162,55 @@
.. note::
- The folder structure in ``erpc/platform`` must be the same as the ``platform/ext/target`` of TF-M
- repo.
+ The folder structure in ``erpc/platform`` must be the same as the
+ ``platform/ext/target`` of the TF-M repository.
-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.
+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 client and server respectively.
+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 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``.
+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 a ``app/erpc_app.c`` as the default server application which initializes the UART
-transportation and starts the eRPC server.
+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.
-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.
+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, you only need to build with the ``CONFIG_TFM_ERPC_TEST_FRAMEWORK``
-enabled.
-On the client side, you must
+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:
-- 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
+- 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
+ - ``add_subdirectory`` with the ``erpc/client``,
+ - link the ``erpc_client`` library to the application.
-There is an example at ``erpc/host_example`` for reference.
+There is also an example at ``erpc/host_example`` for reference.
--------------
-*Copyright (c) 2023, Arm Limited. All rights reserved.*
+*Copyright (c) 2023-2024, Arm Limited. All rights reserved.*