DOC: update documentation.
Add documentation covering:
- developer information about architecture
- project structure and building
- project overview and service descriptions
- the portability model for supporting hardware
Signed-off-by: Julian Hall <julian.hall@arm.com>
Co-Authored-By: Gyorgy Szing <gyorgy.szing@gmail.com>
Change-Id: I8bf9c01a66350719d82a7ca2bc1c78a8ab17978d
diff --git a/docs/environments/ffa/libsp.rst b/docs/environments/ffa/libsp.rst
new file mode 100644
index 0000000..ff1b552
--- /dev/null
+++ b/docs/environments/ffa/libsp.rst
@@ -0,0 +1,132 @@
+libsp
+=====
+
+libsp is intended to be used from S-EL0 secure partitions. It contains all
+the necessary features for communicating with other components using the FF-A
+interfaces.
+
+The implementation is split into multiple layers for easy maintainability and
+usage. The structure and the short description of the components of the library
+is described below.
+
+For detailed information about the FF-A interfaces please check the
+`FF-A specification <https://developer.arm.com/documentation/den0077/a/>`_
+
+The API reference documentation is included in the code.
+
+The components of the following diagram are illustrated as classes but as the
+library is written in C they are not real classes. Their purpose is to describe
+the interfaces and dependencies of the library's components.
+
+.. uml:: /uml/libsp_functions.puml
+
+SP layer
+--------
+
+The SP layer provides convenient high level interface for accessing FF-A
+features. The layer has multiple components around the groups of the FF-A
+interfaces.
+
+SP RXTX
+'''''''
+
+The FF-A calls may utilize a pair or buffers called RXTX buffers for passing
+data to the SPM that won't fit into registers. These buffers should be set up
+during the initialization phase of the SP, then the FF-A calls can use these in
+discovery or memory management calls.
+
+The SP RXTX component provides a high level interface for registering these
+buffers. It also enables other components of the SP layer to use these buffers
+during FF-A calls without the need of manually passing the buffers to the
+functions.
+
+SP memory management
+''''''''''''''''''''
+
+The FF-A memory management interfaces involve multiple steps for setting up a
+memory transaction. This component gives a set of functions to the user for
+doing these transactions in a simple way. The supported memory transactions
+follows below:
+
+* Donate
+
+* Lend
+
+* Share
+
+* Retrieve
+
+* Relinquish
+
+* Reclaim
+
+FF-A layer
+----------
+
+The FF-A layer provides functions and types for accessing FF-A features through
+a C API. This low level API gives full control of the FF-A call parameters.
+
+FF-A API
+''''''''
+
+The FF-A API provides wrappers for the FF-A interfaces. These interfaces are
+fitted into the following groups:
+
+* Setup and discovery interfaces
+
+* CPU cycle management interfaces
+
+* Messaging interfaces
+
+* Memory management interfaces
+
+The functions of this unit give raw control of all the parameters of the FF-A
+calls beside providing basic validity checks for the parameters.
+
+Couple FF-A interfaces have the ability to receive a response which indicates
+an interrupt that is meant to be handled by the SP. All these functions call a
+common interrupt handler function which is defined in the FF-A API component.
+This interrupt handler function should be implemented by the upper layers (in
+fact it is implemented by the SP layer or libsp).
+
+FF-A memory descriptors
+'''''''''''''''''''''''
+
+The FF-A defines memory descriptors to provide information to the SPM about the
+referenced memory areas. These are used by memory transactions like sharing,
+lending, etc. This information covers various details like instruction and data
+access rights, the endpoints of the transaction, address and size of the area,
+and so on. Building and parsing memory transaction structures can be quite
+complex and this is what this component addresses.
+
+First of all it provides a type for describing buffers where the transaction
+descriptors should be built. Using this type provides safety against buffer
+overflows during the transaction build and parse processes.
+
+The transaction data consists of three main sections.
+
+1. A transaction descriptor should be added where the memory region attributes
+ are described.
+
+2. Multiple memory access descriptors should be added which specify access for
+ each receiver of the memory area.
+
+3. Addresses and sizes of the memory regions can be added.
+
+At this point the transaction data should be ready to passed to the SPM by
+invoking the suitable FF-A call.
+
+
+FF-A internal API
+-----------------
+
+The lowest layer implemented in libsp is responsible for wrapping FF-A layer
+calls into the SVC conduit. Practically this means an escalation of the
+exception level and invoking the SVC handler of the SPM with the suitable
+parameters passed in registers.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause