1################################################
2Fixing implicit casting for C enumeration values
3################################################
4
5:Author: Hugues de Valon
6:Organization: Arm Limited
7:Contact: hugues.devalon@arm.com
8
9********
10Abstract
11********
12
13C enumerations provide a nice way to increase readability by creating new
14enumerated types but the developer should take extra care when mixing
15enumeration and integer values.
16This document investigates C enumerations safety and proposes strategies on how
17to fix the implicit casting of the enumeration values of TF-M with other types.
18
19**************************
20C99 Standard point of view
21**************************
22
23In TF-M many implicit casts are done between integer types (``uint32_t``,
24``int32_t``, ``size_t``, etc), enumerated types (``enum foobar``) and
25enumeration constants (``FOOBAR_ENUM_1``).
26
27According to the C99 standard [1]_:
28
29    **§6.2.5, 16**:
30    An enumeration comprises a set of named integer constant values. Each
31    distinct enumeration constitutes a different numerated type.
32
33    **§6.7.2.2, 2**:
34    The expression that defines the value of an enumeration constant shall be an
35    integer constant expression that has a value representable as an int.
36
37    **§6.7.2.2, 3**:
38    The identifiers in an enumerator list are declared as constants that have
39    type int and may appear wherever such are permitted.
40
41    **§6.7.2.2, 4**:
42    Each enumerated type shall be compatible with char, a signed integer type,
43    or an unsigned integer type. The choice of type is implementation-defined,
44    but shall be capable of representing the values of all the members of the
45    enumeration.
46
47From these four quotes from the C99 standard [1]_, the following conclusions can
48be made:
49
50* an enumeration defines a new type and should be treated as such
51* the enumeration constants must only contains value representable as an ``int``
52* the enumeration constants have type ``int``
53* the actual type of the enumeration can be between ``char``, signed and
54  unsigned ``int``. The compiler chooses the type it wants among those that can
55  represent all declared constants of the enumeration.
56
57Example::
58
59    enum french_cities {
60        MARSEILLE,
61        PARIS,
62        LILLE,
63        LYON
64    };
65
66In that example, ``MARSEILLE``, ``PARIS``, ``LILLE`` and ``LYON`` are
67enumeration constants of type ``int`` and ``enum french_cities`` is a enumerated
68type which can be of actual type ``char``, ``unsigned int`` or ``int``
69(the compiler chooses!).
70
71For these reasons, doing an implicit cast between an enumeration and another
72type is the same as doing an implicit cast between two different types. From a
73defensive programming point of view, it should be checked that the destination
74type can represent the values from the origin type. In this specific case it
75means four things for enumerations:
76
77* it is always safe to assign an enumeration constant to an int, but might be
78  better to cast to show intent.
79* when casting an enumeration constant to another type, it should be checked
80  that the constant can fit into the destination type.
81* when casting from an integer type (``uint32_t``, ``int32_t``, etc) to an
82  enumeration type, it should be checked that the integer's value is one of the
83  enumeration constants. The comparison needs to be done on the biggest type of
84  the two so that no information is lost. C integer promotion should
85  automatically do that for the programmer (check §6.3.1.8, 1 for the rules).
86* when casting from an enumeration type to an integer type, it should be checked
87  that the enumeration type value fits into the integer type. The value of a
88  variable which has the type of an enumeration type is not limited to the
89  enumeration constants of the type. An enumeration constant will always fit
90  into an ``int``.
91
92*****************
93Strategies to fix
94*****************
95
960. Replace the enumerated type with an integer type and replace the enumeration
97   constant with preprocessor constants.
981. Whenever possible, try to use matching types to avoid implicit casting.
99   It happens, for example, for arithmetic operations, function calls and
100   function returns. This strategy always have the lowest performance impact.
1012. When using an enumeration constant in an arithmetic operation with another
102   type, verify that the constant can fit in the other type and cast it.
1033. When converting an integer to an enumeration type, use a conversion function
104   to check if the integer matches an enumeration constant. To not impact
105   performance too much, this function should be an inline function. If it does
106   not match, use (or add) the error constant or return an error value.
1074. When converting an enumeration type to an integer, use a conversion function
108   to check that the integer type can contain the enumeration value.
109
110************************
111Design proposal for TF-M
112************************
113
114In TF-M, an action will be taken for all enumerated types and enumeration
115constants that are used for implicit casting. The goal of this proposal is to
116remove all implicit casting of enumeration values in TF-M.
117
118The following enumerated types will be removed and replaced with preprocessor
119constants (strategy 0). These enumerated types are not used in TF-M
120but only the constants they declare.
121
122* ``enum spm_part_state_t``
123* ``enum spm_part_flag_mask_t``
124* ``enum tfm_partition_priority``
125
126The following enumerated types will be kept because they are used in the
127prototypes of functions and are useful for debugging. Whenever possible,
128strategy 1 will be applied to remove implicit casting related with those
129enumerations but dynamic conversions will be used if the first option would
130create too much change in the code base.
131
132* ``enum tfm_status_e``: the return type of the following functions will be
133  changed to return the ``enum tfm_status_e`` type. These functions are already
134  returning the enumeration constants, but implicitly casted to an integer type
135  like ``int32_t``.
136
137  * ``int32_t check_address_range``
138  * ``int32_t has_access_to_region``
139  * ``int32_t tfm_core_check_sfn_parameters``
140  * ``int32_t tfm_start_partition``
141  * ``int32_t tfm_return_from_partition``
142  * ``int32_t tfm_check_sfn_req_integrity``
143  * ``int32_t tfm_core_check_sfn_req_rules``
144  * ``int32_t tfm_spm_sfn_request_handler``
145  * ``int32_t tfm_spm_sfn_request_thread_mode``
146* ``enum tfm_buffer_share_region_e``: the following function prototypes will be
147  changed:
148
149  * ``tfm_spm_partition_set_share(uint32_t partition_idx, uint32_t share)`` -> ``tfm_spm_partition_set_share(uint32_t partition_idx, enum tfm_buffer_share_region_e share)``
150* ``enum tfm_memory_access_e``
151* ``enum attest_memory_access_t``
152* ``enum engine_cipher_mode_t``
153* ``mbedtls_cipher_type_t``
154
155The following enumerated types are used for error code values of Secure service
156calls. They should be kept as they are part of the interface and might be used
157by external parties in Non-Secure code. For the Initial Attestation service,
158the enumeration is defined in the PSA Attestation API specifications.
159
160* ``enum psa_attest_err_t``
161* ``enum psa_audit_err``
162* ``enum tfm_platform_err_t``
163
164Implicit casting related with these enumerations is happening in two locations
165of TF-M and need conversion functions in those locations, because the types can
166not be changed:
167
168* In the Non-Secure Client library, all of the Secure Service functions
169  implicitly cast the ``uint32_t`` returned by ``tfm_ns_lock_dispatch`` to
170  these enumerated types. Strategy 3 is needed here.
171* In all of the veneer functions, there is an implicit cast from the ``int32_t``
172  value returned by the SVC request function (``tfm_core_*_request``) to these
173  enumerated types. Strategy 3 is needed here as well. The implicit cast will
174  eventually be removed if all of the services are using the Uniform Signatures
175  Prototypes so that the veneer functions all return ``psa_status_t`` which is
176  an ``int32_t``.
177
178If the interface of those services can be changed, these enumerations could be
179removed and replaced with the ``psa_status_t`` type to remove the implicit
180casting.
181
182.. [1] C99 standard: http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf
183
184
185--------------
186
187
188*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
189
190