1##################################
2Platform Service Integration Guide
3##################################
4
5************
6Introduction
7************
8TF-M Platform service is a trusted service which allows secure partitions and
9non-secure applications to interact with some platform-specific components.
10There are a number of features which requires some interaction with
11platform-specific components which are at the same time essential for the
12security of the system.
13Therefore, those components need to be handled by a secure partition which is
14part of the trusted compute base.
15
16These platform-specific components include system reset, power management,
17Debug, GPIO, etc.
18
19************************
20TF-M Platform interfaces
21************************
22The TF-M interfaces for the Platform service are located in
23``interface/include/``.
24The TF-M Platform service source files are located in
25``secure_fw/partitions/platform``.
26
27*********************
28TF-M Platform service
29*********************
30The Platform service interfaces and types are defined and documented in
31``interface/include/tfm_platform_api.h``
32
33- ``platform_sp.h/c`` : These files define and implement functionalities related
34  to the platform service
35- ``tfm_platform_api.c`` : This file implements ``tfm_platform_api.h``
36  functions to be called from the secure partitions. This is the entry point
37  when the secure partitions request an action to the Platform service
38  (e.g system reset).
39
40************
41Platform HAL
42************
43
44The Platform Service relies on a platform-specific implementation to
45perform some functionalities. Mandatory functionality (e.g. system reset)
46that are required to be implemented for a platform to be supported by TF-M have
47their dedicated HAL API functions. Additional platform-specific services can be
48provided using the IOCTL function call.
49
50For API specification, please check: ``platform/include/tfm_platform_system.h``
51
52An implementation is provided in all the supported platforms. Please, check
53``platform/ext/target/<SPECIFIC_TARGET_FOLDER>/services/src/tfm_platform_system.c``
54for examples.
55
56The API **must** be implemented by the system integrators for their targets.
57
58IOCTL
59=====
60
61A single entry point to platform-specific code across the HAL is provided by the
62IOCTL service and HAL function:
63
64.. code-block:: c
65
66  enum tfm_platform_err_t tfm_platform_hal_ioctl(tfm_platform_ioctl_req_t request,
67                                                 psa_invec *in_vec,
68                                                 psa_outvec *out_vec);
69
70A request type is provided by the client, with additional parameters contained
71in the optional ``in_vec`` parameter. An optional output buffer can be passed to
72the service in ``out_vec``.
73An IOCTL request type not supported on a particular platform should return
74``TFM_PLATFORM_ERR_NOT_SUPPORTED``
75
76Non-Volatile counters
77=====================
78
79The Platform Service provides an abstracted service for exposing the NV counters
80to secure partitions or non-secure callers. The following operations are
81supported:
82
83- Increment a counter.
84- Read a counter value to a preallocated buffer.
85
86.. code-block:: c
87
88    enum tfm_platform_err_t
89    tfm_platform_nv_counter_increment(uint32_t counter_id);
90
91    enum tfm_platform_err_t
92    tfm_platform_nv_counter_read(uint32_t counter_id,
93                                 uint32_t size, uint8_t *val);
94
95The range of counters id is defined in :
96``platform/include/tfm_plat_nv_counters.h``
97
98For Level 2,3 isolation implementations, secure partitions in the
99Application Root of Trust, should have ``TFM_PLATFORM_SERVICE`` set as a
100dependency for access to the NV counter API.
101
102***************************
103Current Service Limitations
104***************************
105- **system reset** - The system reset functionality is only supported in
106  isolation level 1. Currently the mechanism by which PSA-RoT services should
107  run in privileged mode in level 3 is not in place due to an ongoing work in
108  TF-M Core. So, the ``NVIC_SystemReset`` call performed by the service is
109  expected to generate a memory fault when it tries to access the ``SCB->AIRCR``
110  register in level 3 isolation.
111
112--------------
113
114*Copyright (c) 2018-2022, Arm Limited. All rights reserved.*
115