Docs: Add document for eRPC framework
Change-Id: I66a8d2a441042c40fb35a1a670aa57273133cf7b
Signed-off-by: Kevin Peng <kevin.peng@arm.com>
diff --git a/docs/tfm_erpc_test_framework.rst b/docs/tfm_erpc_test_framework.rst
new file mode 100644
index 0000000..5fa33ee
--- /dev/null
+++ b/docs/tfm_erpc_test_framework.rst
@@ -0,0 +1,194 @@
+############################
+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.*