1libsp
2=====
3
4libsp is intended to be used from S-EL0 secure partitions. It contains all
5the necessary features for communicating with other components using the FF-A
6interfaces.
7
8The implementation is split into multiple layers for easy maintainability and
9usage. The structure and the short description of the components of the library
10is described below.
11
12For detailed information about the FF-A interfaces please check the
13`FF-A specification <https://developer.arm.com/documentation/den0077/a/>`_
14
15The API reference documentation is included in the code.
16
17The components of the following diagram are illustrated as classes but as the
18library is written in C they are not real classes. Their purpose is to describe
19the interfaces and dependencies of the library's components.
20
21.. uml:: /uml/libsp_functions.puml
22
23SP layer
24--------
25
26The SP layer provides convenient high level interface for accessing FF-A
27features. The layer has multiple components around the groups of the FF-A
28interfaces.
29
30SP RXTX
31'''''''
32
33The FF-A calls may utilize a pair or buffers called RXTX buffers for passing
34data to the SPM that won't fit into registers. These buffers should be set up
35during the initialization phase of the SP, then the FF-A calls can use these in
36discovery or memory management calls.
37
38The SP RXTX component provides a high level interface for registering these
39buffers. It also enables other components of the SP layer to use these buffers
40during FF-A calls without the need of manually passing the buffers to the
41functions.
42
43SP memory management
44''''''''''''''''''''
45
46The FF-A memory management interfaces involve multiple steps for setting up a
47memory transaction. This component gives a set of functions to the user for
48doing these transactions in a simple way. The supported memory transactions
49follows below:
50
51* Donate
52
53* Lend
54
55* Share
56
57* Retrieve
58
59* Relinquish
60
61* Reclaim
62
63FF-A layer
64----------
65
66The FF-A layer provides functions and types for accessing FF-A features through
67a C API. This low level API gives full control of the FF-A call parameters.
68
69FF-A API
70''''''''
71
72The FF-A API provides wrappers for the FF-A interfaces. These interfaces are
73fitted into the following groups:
74
75* Setup and discovery interfaces
76
77* CPU cycle management interfaces
78
79* Messaging interfaces
80
81* Memory management interfaces
82
83The functions of this unit give raw control of all the parameters of the FF-A
84calls beside providing basic validity checks for the parameters.
85
86Couple FF-A interfaces have the ability to receive a response which indicates
87an interrupt that is meant to be handled by the SP. All these functions call a
88common interrupt handler function which is defined in the FF-A API component.
89This interrupt handler function should be implemented by the upper layers (in
90fact it is implemented by the SP layer or libsp).
91
92FF-A memory descriptors
93'''''''''''''''''''''''
94
95The FF-A defines memory descriptors to provide information to the SPM about the
96referenced memory areas. These are used by memory transactions like sharing,
97lending, etc. This information covers various details like instruction and data
98access rights, the endpoints of the transaction, address and size of the area,
99and so on. Building and parsing memory transaction structures can be quite
100complex and this is what this component addresses.
101
102First of all it provides a type for describing buffers where the transaction
103descriptors should be built. Using this type provides safety against buffer
104overflows during the transaction build and parse processes.
105
106The transaction data consists of three main sections.
107
1081. A transaction descriptor should be added where the memory region attributes
109   are described.
110
1112. Multiple memory access descriptors should be added which specify access for
112   each receiver of the memory area.
113
1143. Addresses and sizes of the memory regions can be added.
115
116At this point the transaction data should be ready to passed to the SPM by
117invoking the suitable FF-A call.
118
119
120FF-A internal API
121-----------------
122
123The lowest layer implemented in libsp is responsible for wrapping FF-A layer
124calls into the SVC conduit. Practically this means an escalation of the
125exception level and invoking the SVC handler of the SPM with the suitable
126parameters passed in registers.
127
128--------------
129
130*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
131
132SPDX-License-Identifier: BSD-3-Clause
133