Add libpsa to documentation
Adding libpsa related changes to the documentation.
Signed-off-by: Gabor Toth <gabor.toth2@arm.com>
Change-Id: I551acdf2da43cfd00030f33a1abab8e5754301a2
diff --git a/docs/deployments/libraries.rst b/docs/deployments/libraries.rst
index 25902ef..81d18cb 100644
--- a/docs/deployments/libraries.rst
+++ b/docs/deployments/libraries.rst
@@ -31,6 +31,80 @@
* - Used by
- * Userspace applications
+.. _libs-libpsa:
+
+libpsa
+------
+Trusted Services implements the `PSA Certified APIs`_. Libpsa encapsulates the service client implementations
+which implement this API. Linux uuser-space applications can use libpsa to easily access the PSA services
+implemented by the project. Libpsa depends on libts for RPC and service discovery services.
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 0
+
+ * - Supported Environments
+ - * | *linux-pc*
+ * | *arm-linux*
+ * - Used by
+ - * Userspace applications
+ * - Depends on
+ - * `libts`_ library
+
+Build and integration examples
+..............................
+
+Build as shared library::
+
+ cmake -S ./trusted-services/deployments/libpsa/linux-pc/ -B ./build
+ make -C build && make -C build install
+
+.. warning::
+ Building as static library is not yet supported.
+
+To integrate the library libts shall also be integrated. To achieve this add the listed
+lines to the application's cmake files::
+
+ find_package(libpsa "1.0.0" REQUIRED PATHS "<install path>")
+ find_package(libts "2.0.0" REQUIRED PATHS "<install path>")
+ target_link_libraries(ts-demo PRIVATE libpsa::psa)
+
+Initialization
+..............
+
+Before calling any function from libpsa the proper part of the library has to be initialized.
+Before exiting the application (or when PSA services are no longer needed) the initialized
+parts must be deinitialized. To access the library **libpsa.h** must be included::
+
+ psa_status_t libpsa_init_crypto_context(const char *service_name);
+ void libpsa_deinit_crypto_context(void);
+
+ psa_status_t libpsa_init_attestation_context(const char *service_name);
+ void libpsa_deinit_attestation_context(void);
+
+ psa_status_t libpsa_init_its_context(const char *service_name);
+ void libpsa_deinit_its_context(void);
+
+ psa_status_t libpsa_init_ps_context(const char *service_name);
+ void libpsa_deinit_ps_context(void);
+
+The example below initializes and then deinitializes crypto::
+
+ psa_status_t psa_status = libpsa_init_crypto_context("sn:trustedfirmware.org:crypto:0");
+ if (psa_status) {
+ printf("libpsa_init_crypto_context failed: %d\n", psa_status);
+ return PSA_ERROR_GENERIC_ERROR;
+ }
+
+ libpsa_deinit_crypto_context();
+
+Known issues and Limitations
+............................
+
+| The library is single client.
+| The library is not thread safe.
+| Only linux user-space is supported currently.
+
.. _libs-libsp:
libsp
@@ -48,8 +122,17 @@
* - Used by
- * Secure partitions
+Known issues and Limitations
+............................
+
+| The library is single client.
+| The library is not thread safe.
+| Only linux user-space is supported currently.
+
--------------
-*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+.. _`PSA Certified APIs`: https://arm-software.github.io/psa-api/
+
+*Copyright (c) 2022-2023, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/versioning_policy.rst b/docs/project/versioning_policy.rst
index c176db3..0d1352e 100644
--- a/docs/project/versioning_policy.rst
+++ b/docs/project/versioning_policy.rst
@@ -29,7 +29,8 @@
The project hosts multiple components which can be used separately and thus need
compatibility information expressed independently. Such components get a
-dedicated version ID. Examples are :ref:`libs-libsp` and :ref:`libs-libts`.
+dedicated version ID. Examples are :ref:`libs-libsp` :ref:`libs-libts` and
+:ref:`libs-libpsa`.
Components are never released standalone but only part of a TS release. In that
sense a set of independent component version IDs are assigned to a TS release ID.
diff --git a/docs/quickstart/pc-testing.rst b/docs/quickstart/pc-testing.rst
index 295273d..7cace20 100644
--- a/docs/quickstart/pc-testing.rst
+++ b/docs/quickstart/pc-testing.rst
@@ -36,7 +36,7 @@
cmake -B build-ts -S deployments/ts-service-test/linux-pc
make -C build-ts install
- LD_PRELOAD=build-ts/install/linux-pc/lib/libts.so build-ts/install/linux-pc/bin/ts-service-test -v
+ LD_LIBRARY_PATH=build-ts/install/linux-pc/lib build-ts/install/linux-pc/bin/ts-service-test -v
Build and run *psa-api-test*
----------------------------
@@ -51,7 +51,7 @@
cmake -B build-pa deployments/psa-api-test/crypto/linux-pc
make -C build-pa install
- LD_PRELOAD=build-pa/install/linux-pc/lib/libts.so build-pa/install/linux-pc/bin/psa-crypto-api-test
+ LD_LIBRARY_PATH=build-ts/install/linux-pc/lib build-pa/install/linux-pc/bin/psa-crypto-api-test
psa-api test binaries accept the listed command-line arguments: