Add SPMC test documentations
Add build and run instructions for the SPMC test. Document the structure
of the SPMC test environment and the implemented test cases.
Signed-off-by: Imre Kis <imre.kis@arm.com>
Change-Id: I5139f36dc78a2c37c3000f15f74722f945ab738f
diff --git a/docs/developer/index.rst b/docs/developer/index.rst
index 4ea55f5..3204633 100644
--- a/docs/developer/index.rst
+++ b/docs/developer/index.rst
@@ -16,9 +16,10 @@
docs-build
writing-documentation
b-test
+ spmc-tests
--------------
-*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2024, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/spmc-tests.rst b/docs/developer/spmc-tests.rst
new file mode 100644
index 0000000..a61077f
--- /dev/null
+++ b/docs/developer/spmc-tests.rst
@@ -0,0 +1,180 @@
+OP-TEE SPMC tests
+=================
+
+Build and run
+-------------
+
+Please follow the instructions of :ref:`build-spmc-tests`.
+
+Structure
+---------
+
+* `xtest`_ is the |NWd| test application which is used to send multiple |FF-A| messages to the SPMC and to the test SPs in
+ the |SWd|. It is part of the `optee_test`_ repository.
+* The ``arm-ffa-user`` driver provides access to the FF-A layer from the |NWd| user space. ``xtest`` uses it to send |FF-A|
+ messages.
+* The test SPs implement various testing functions which can be invoked from ``xtest``.
+
+.. uml:: uml/SpmcTestStructure.puml
+
+Implementation
+--------------
+
+* |TS|
+ * ``components/service/spm_test`` implements the common code of the test SPs.
+ * ``deployments/spm-test*`` are the test SP deployments. There are currently four test SPs to cover various test
+ scenarios. SPM test SPs use |FF-A| v1.1 except SPM test SP 2 which uses v1.0 to cover the backwards compatibility test
+ of the SPMC.
+* `optee_test`_
+ * `ffa_spmc_1000.c`_ contains the SPMC test cases of ``xtest``.
+
+SPMC test RPC protocol
+----------------------
+
+Tests can invoke the functions of the test SPs via an SPMC test specific RPC interface which is built on top of FF-A direct
+messages.
+
+.. list-table:: Test RPC protocol
+ :header-rows: 1
+
+ * - Message ID
+ - Description
+ - ``args[0]``
+ - ``args[1]``
+ - ``args[2]``
+ - ``args[3]``
+ - ``args[4]``
+ * - EP_TEST_SP
+ - Run internal SP tests
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ * - EP_TEST_SP_COMMUNICATION
+ - Test FF-A direct message request
+ - ``0x00000001``
+ - The destination SP's FF-A endpoint ID
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ * - EP_TEST_SP_INCREASE
+ - Increase each ``param`` value by one and return response
+ - ``0x00000002``
+ - ``param[0]``
+ - ``param[1]``
+ - ``param[2]``
+ - ``param[3]``
+ * - EP_TRY_R_ACCESS
+ - Test shared buffer read access
+ - ``0x00000003``
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ * - EP_TRY_W_ACCESS
+ - Test shared buffer write access
+ - ``0x00000004``
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ * - EP_RETRIEVE
+ - Do FF-A memory retrieve
+ - ``0x00000005``
+ - Memory handle LSW
+ - Memory handle MSW
+ - Sender endpoint ID
+ - ``0x00000000``
+ * - EP_RELINQUISH
+ - Do FF-A memory relinquish
+ - ``0x00000006``
+ - Memory handle LSW
+ - Memory handle MSW
+ - Flags
+ - ``0x00000000``
+ * - EP_SP_MEM_SHARING
+ - Test FF-A memory sharing
+ - ``0x00000007``
+ - Target endpoint's FF-A ID
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ * - EP_SP_MEM_SHARING_MULTI
+ - Test FF-A memory sharing with multiple endpoints
+ - ``0x00000008``
+ - Target endpoint 1 FF-A ID
+ - Target endpoint 2 FF-A ID
+ - ``0x00000000``
+ - ``0x00000000``
+ * - EP_SP_MEM_SHARING_EXC
+ - Test exclusive FF-A memory sharing
+ - ``0x00000009``
+ - Target endpoint's FF-A ID
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ * - EP_SP_MEM_INCORRECT_ACCESS
+ - Negative FF-A memory sharing test
+ - ``0x0000000a``
+ - Target endpoint's FF-A ID
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ * - EP_SP_NOP
+ - No operation
+ - ``0x0000000b``
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ * - EP_TEST_SP_COMMUNICATION_RESPONSE
+ - Test FF-A direct message response
+ - ``0x0000000c``
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+ * - SP_TEST_OK
+ - Successful test response
+ - ``0x000000aa``
+ - Request specific parameter
+ - Request specific parameter
+ - Request specific parameter
+ - Request specific parameter
+ * - SP_TEST_ERROR
+ - Error test response
+ - ``0x000000ff``
+ - Error code
+ - ``0x00000000``
+ - ``0x00000000``
+ - ``0x00000000``
+
+Test cases
+----------
+
+The following test cases are defined in ``ffa_spmc_1000.c``:
+
+* 1001: Test basic FF-A communication
+ * Try to connect to multiple SPs
+ * Have different SPs sending messages to each other
+ * Test standard SP messages (partition_info_get, get_own_id, ...)
+* 1002: Test FF-A memory
+ * Test memory sharing between the |NWd| and the |SWd|
+* 1003: Test FF-A memory: SP to SP
+ * Test memory sharing between to SPs
+* 1004: Test FF-A memory: Access and flags
+ * Test the different access modifiers and flags when sharing memory
+* 1005: Test FF-A memory: multiple receiver
+ * Share a memory region with multiple SPs
+
+--------------
+
+.. _`xtest`: https://optee.readthedocs.io/en/latest/building/gits/optee_test.html
+.. _`optee_test`: https://github.com/OP-TEE/optee_test
+.. _`ffa_spmc_1000.c`: https://github.com/OP-TEE/optee_test/blob/master/host/xtest/ffa_spmc_1000.c
+
+
+*Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
\ No newline at end of file
diff --git a/docs/developer/uml/SpmcTestStructure.puml b/docs/developer/uml/SpmcTestStructure.puml
new file mode 100644
index 0000000..4b015b1
--- /dev/null
+++ b/docs/developer/uml/SpmcTestStructure.puml
@@ -0,0 +1,34 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+package "Normal World" {
+ package "EL-1" {
+ [arm-ffa-user] as driver
+ [Linux kernel] as kernel
+ }
+ package "EL-0" {
+ [shell]
+ [xtest]
+ }
+}
+package "Secure World" {
+ package "SEL-0" {
+ [Test SP] as sp
+ }
+ package "SEL-1" {
+ [OP-TEE kernel] as optee
+ }
+}
+
+[shell] -> driver: Load driver
+[shell] -> [xtest] : Call xtest -t ffa_spmc
+[xtest] -> driver: Open
+driver -> kernel: Send FF-A message
+kernel -> optee: Forward FF-A message
+optee -> sp: Forward FF-A message
+@enduml