arm_ffa: introduce armffa command

Provide armffa command showcasing the use of the U-Boot FF-A support

armffa is a command showcasing how to invoke FF-A operations.
This provides a guidance to the client developers on how to
call the FF-A bus interfaces. The command also allows to gather secure
partitions information and ping these  partitions. The command is also
helpful in testing the communication with secure partitions.

For more details please refer to the command documentation [1].

A Sandbox test is provided for the armffa command.

[1]: doc/usage/cmd/armffa.rst

Signed-off-by: Abdellatif El Khlifi <abdellatif.elkhlifi@arm.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
Cc: Tom Rini <trini@konsulko.com>
Cc: Ilias Apalodimas <ilias.apalodimas@linaro.org>
Cc: Jens Wiklander <jens.wiklander@linaro.org>
Cc: Heinrich Schuchardt <xypron.glpk@gmx.de>

2 files changed, 95 insertions, 0 deletions

diff --git a/doc/usage/cmd/armffa.rst b/doc/usage/cmd/armffa.rst
new file mode 100644
index 00000000000..13fa90c1290
--- /dev/null
+++ b/doc/usage/cmd/armffa.rst
@@ -0,0 +1,94 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+
+armffa command
+==============
+
+Synopsis
+--------
+
+::
+
+   armffa [sub-command] [arguments]
+
+   sub-commands:
+
+        getpart [partition UUID]
+
+            lists the partition(s) info
+
+        ping [partition ID]
+
+            sends a data pattern to the specified partition
+
+        devlist
+
+            displays information about the FF-A device/driver
+
+Description
+-----------
+
+armffa is a command showcasing how to use the FF-A bus and how to invoke its operations.
+
+This provides a guidance to the client developers on how to call the FF-A bus interfaces.
+
+The command also allows to gather secure partitions information and ping these  partitions.
+
+The command is also helpful in testing the communication with secure partitions.
+
+Example
+-------
+
+The following examples are run on Corstone-1000 platform.
+
+* ping
+
+::
+
+   corstone1000# armffa ping 0x8003
+   SP response:
+   [LSB]
+   fffffffe
+   0
+   0
+   0
+   0
+
+* ping (failure case)
+
+::
+
+   corstone1000# armffa ping 0
+   Sending direct request error (-22)
+
+* getpart
+
+::
+
+   corstone1000# armffa getpart 33d532ed-e699-0942-c09c-a798d9cd722d
+   Partition: id = 8003 , exec_ctxt 1 , properties 3
+
+* getpart (failure case)
+
+::
+
+   corstone1000# armffa getpart 33d532ed-e699-0942-c09c-a798d9cd7221
+   INVALID_PARAMETERS: Unrecognized UUID
+   Failure in querying partitions count (error code: -22)
+
+* devlist
+
+::
+
+   corstone1000# armffa devlist
+   device name arm_ffa, dev 00000000fdf41c30, driver name arm_ffa, ops 00000000fffc0e98
+
+Configuration
+-------------
+
+The command is available if CONFIG_CMD_ARMFFA=y and CONFIG_ARM_FFA_TRANSPORT=y.
+
+Return value
+------------
+
+The return value $? is 0 (true) on success, 1 (false) on failure.
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 072db53614c..3326ec82fff 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -22,6 +22,7 @@ Shell commands
 
    cmd/acpi
    cmd/addrmap
+   cmd/armffa
    cmd/askenv
    cmd/base
    cmd/bdinfo