1################################
2Uniform Secure Service Signature
3################################
4
5:Author: Miklos Balint
6:Organization: Arm Limited
7:Contact: Miklos Balint <miklos.balint@arm.com>
8
9**********************************
10Declaring secure service interface
11**********************************
12
13The following alternative secure service signature is proposed as an
14amendment to existing implementation.
15
16Individual signatures - current method
17======================================
18
19A ``<service_name>_veneers.c`` file is created in the ``secure_fw/ns_callable``
20directory, that specifies the signature for each veneer function, and calls the
21secure function from the veneers. The respective
22``interface/include/<service_name>_veneers.h`` file with the veneer declarations
23have to be created and maintained manually.
24Note that at present TF-M framework limits the range of valid return values a
25secure service can provide, reserving a range for framework error codes.
26
27Uniform signatures - proposal
28=============================
29
30The proposal is to use a uniform signature for all the secure functions of the
31secure service. There are multiple advantages of this method:
32
33- TF-M Core can do a sanity check on the access rights of the veneer
34  parameters, and there is no need for the secure services to make these checks
35  individually. Please note that in the present implementation sanity check is
36  only fully supported for level 1 isolation.
37
38- The veneer declarations and implementations for the secure functions can be
39  generated automatically from a template (using the secure function list in the
40  secure service's manifest)
41
42The signature for such secure services would look like this:
43
44.. code-block:: c
45
46    psa_status_t secure_function_name(struct psa_invec *in_vec, size_t in_len,
47                                      struct psa_outvec *out_vec, size_t out_len);
48
49where
50
51Return value:
52-------------
53
54``psa_status_t`` is a status code whose values are described in PSA Firmware
55Framework (as in version 1.0-beta-0 chapter 4.3.3).
56
57Note:
58-----
59The return value limitations imposed by TF-M framework for proprietary
60secure service veneers would not apply to secure services using the uniform
61signature. This is analogous to how PSA Firmware Framework handles values
62returned by ``psa_reply()`` function.
63
64Arguments:
65----------
66
67.. code-block:: c
68
69    /**
70     * A read-only input memory region provided to a RoT Service.
71     */
72    typedef struct psa_invec {
73        const void *base;   /*!< the start address of the memory buffer */
74        size_t len;         /*!< the size in bytes */
75    } psa_invec;
76
77    /**
78     * A writable output memory region provided to a RoT Service.
79     */
80    typedef struct psa_outvec {
81        void *base;         /*!< the start address of the memory buffer */
82        size_t len;         /*!< the size in bytes */
83    } psa_outvec;
84
85    /**
86     * in_len: the number of input parameters, i.e. psa_invecs
87     * out_len: the number of output parameters, i.e. psa_outvecs
88     */
89
90The number of vectors that can be passed to a secure service is constrained:
91
92.. code-block:: c
93
94    in_len + out_len <= PSA_MAX_IOVEC
95
96The veneer function declarations and implementations are generated in the
97``interface/include/tfm_veneers.h`` and ``secure_fw\ns_callable\tfm_veneers.c``
98files respectively. The veneer functions are created with the name
99``tfm_<secure_function_name>_veneer``
100
101Services that implement the uniform signature do not need to manually fill
102the template veneer function to call ``TFM_CORE_SFN_REQUEST`` macro.
103
104*************
105Compatibility
106*************
107
108Note that the proposal is for the two types of services (those with proprietary
109signatures and those with uniform signatures) to co-exist, with the intention of
110eventually phasing out proprietary signatures in favour of the more robust,
111uniform signature.
112
113*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*