[processor-sdk/pdk.git] / packages / ti / drv / sciclient / soc / sysfw / binaries / system-firmware-public-documentation / _sources / 3_boardcfg / BOARDCFG_SEC.rst.txt
1 ============================
2 Security Board Configuration
3 ============================
5 .. _pub_boardcfg_sec_intro:
7 Security Configuration in System Firmware
8 =========================================
10 The security portion of system firmware has options that can be configured
11 independently of the main Board Configuration. These options are controlled
12 through the security board configuration. In addition, initialization of the
13 secure portion of the system firmware is deferred until the secure board
14 configuration is sent to allow tuning of the system boot time.
16 .. warning::
18 This message MUST be sent in order to initialize the security capabilities of
19 system firmware. Until it is received no security functionality is available.
21 A standalone board configuration message contains the security
22 data within a flat-typed array. The security data is provided
23 separately to reduce DMSC boot time. The security board cfg message
24 is sent any time after the boot notification message is sent and has no
25 dependence upon receipt of the standard board configuration message.
27 .. note::
29 Security Board configuration requires to be signed and encrypted on HS devices
30 to ensure authenticity and protect secrets. Please refer to
31 :doc:`../6_topic_user_guides/hs_boardcfg_signing` on how to sign and encrypt
32 board configuration on HS devices.
34 .. _pub_boardcfg_security_tisci:
36 TISCI API for Security Board Config
37 -----------------------------------
39 The following are the parameters required in the TI-SCI message to pass security
40 board configuration data to DMSC after DMSC sends boot notification complete.
41 The security board configuration message is not dependent on receipt of the
42 standard board configuration message.
44 Usage
45 ^^^^^
47 +------------------------+--------+
48 | **Message Type** | Normal |
49 +------------------------+--------+
50 | **Secure Queue Only?** | Yes |
51 +------------------------+--------+
53 TISCI Message ID
54 ^^^^^^^^^^^^^^^^
56 .. sysfwapimacro:: TISCI_MSG_BOARD_CONFIG_SECURITY
58 Message Data Structures
59 ^^^^^^^^^^^^^^^^^^^^^^^
61 .. sysfwapistruct:: tisci_msg_board_config_security_req
64 .. note::
66 Even though the security board configuration structure contains the
67 ``boardcfg_security_devgrp`` member, it is ignored. Initialization of
68 firewalls is performed for a devgrp when it is enabled via the core board
69 configuration message. This is necessary to ensure isolation. See
70 :doc:`./BOARDCFG`.
72 The reamining security services are initialized when the |sec_bcfg| is
73 received for the first time. Subsequent |sec_bcfg| messages do not have
74 any effect on operation of |sysfw|.
76 .. sysfwapistruct:: tisci_msg_board_config_security_resp
78 .. warning::
80 The boardcfg data structures described below **must** be placed in
81 MCU OCMC SRAM. The address used in the TISCI message will be
82 in MCU OCMC SRAM.
84 .. _pub_boardcfg_sec:
86 Configuration substructure enumeration
87 --------------------------------------
89 This is a fixed size c-structure which both defines the format of the
90 configuration as well as reserves DMSC memory to store the
91 configuration. The boardcfg_sec data structure makes use of the same
92 :ref:`pub_boardcfg_abi_rev` structure for the top level and
93 :ref:`pub_boardcfg_subhdr` for each member structure as the top level
94 boardcfg structure does..
96 +--------------------+----------------------------------------------+-----------------------------------------------------------+
97 | Element | Type | Description |
98 +====================+==============================================+===========================================================+
99 | boardcfg_abi_rev | :ref:`pub_boardcfg_abi_rev` | Board Config ABI version (separate from DMSC ABI version) |
100 +--------------------+----------------------------------------------+-----------------------------------------------------------+
101 | processor_acl_list | :ref:`pub_boardcfg_proc_acl` | Processor access control list configuration |
102 +--------------------+----------------------------------------------+-----------------------------------------------------------+
103 | host_hierarchy | :ref:`pub_boardcfg_host_hierarchy` | Host hierarchy configuration |
104 +--------------------+----------------------------------------------+-----------------------------------------------------------+
105 | otp_config | :ref:`pub_boardcfg_ext_otp_config` | Extended OTP access configuration |
106 +--------------------+----------------------------------------------+-----------------------------------------------------------+
107 | dkek_config | :ref:`pub_boardcfg_dkek_config` | DKEK access configuration |
108 +--------------------+----------------------------------------------+-----------------------------------------------------------+
109 | reserved_cfg_entry | :ref:`pub_boardcfg_reserved_entry` | Reserved configuration entry |
110 +--------------------+----------------------------------------------+-----------------------------------------------------------+
111 | reserved_cfg_entry | :ref:`pub_boardcfg_secure_debug_unlock` | Secure debug unlock configuration |
112 +--------------------+----------------------------------------------+-----------------------------------------------------------+
114 .. _pub_boardcfg_proc_acl:
116 Processor Access List
117 ---------------------
119 Access Control List for various Processors in the SoC.
121 .. _pub_boardcfg_proc:
123 boardcfg_proc
124 ^^^^^^^^^^^^^
126 +------------------+---------------------------------------------------------------+------------------------------------+
127 | Element | Type | Description |
128 +==================+===============================================================+====================================+
129 | subhdr | :ref:`pub_boardcfg_subhdr` | Magic and size for integrity check |
130 +------------------+---------------------------------------------------------------+------------------------------------+
131 | proc_access_list | :ref:`processor_access_list <pub_processor_access_list>` [32] | Processor access description |
132 +------------------+---------------------------------------------------------------+------------------------------------+
134 The magic number to be populated in the ``subhdr`` is ``0xF1EA``.
136 .. _pub_processor_access_list:
138 Processor access list entry
139 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
141 +----------------------------+------+-------------------------------------------------------------------------------+
142 | Element | Type | Description |
143 +============================+======+===============================================================================+
144 | processor_id | u8 | Processor ID (mandatory) - Use 0 to mark unused |
145 +----------------------------+------+-------------------------------------------------------------------------------+
146 | proc_access_master | u16 | Recovery Host ID or Primary control master host ID (mandatory) |
147 +----------------------------+------+-------------------------------------------------------------------------------+
148 | proc_access_secondary[0-2] | u16 | Other Host IDs that can control this processor(set to DMSC host ID if unused) |
149 +----------------------------+------+-------------------------------------------------------------------------------+
151 .. _pub_boardcfg_host_hierarchy:
153 Host Hierarchy
154 --------------
156 Host Hierarchy for various processing entities in the SoC. Host hierarchy
157 defines the supervisory tree for all processing entities in the SoC.
159 boardcfg_host_hierarchy
160 ^^^^^^^^^^^^^^^^^^^^^^^
162 +------------------------+----------------------------------------------------------+------------------------------------+
163 | Element | Type | Description |
164 +========================+==========================================================+====================================+
165 | subhdr | :ref:`pub_boardcfg_subhdr` | Magic and size for integrity check |
166 +------------------------+----------------------------------------------------------+------------------------------------+
167 | host_hierarchy_entries | :ref:`host_hierarchy_entries <pub_host_hierarchy>` [32] | Host hierarchy description |
168 +------------------------+----------------------------------------------------------+------------------------------------+
170 The magic number to be populated in the ``subhdr`` is ``0x8D27``.
172 .. _pub_host_hierarchy:
174 Host hierarchy entry
175 ^^^^^^^^^^^^^^^^^^^^
177 +--------------------+------+--------------------------------------------------------------+
178 | Element | Type | Description |
179 +====================+======+==============================================================+
180 | host_id | u8 | Processing entity Host ID (mandatory) - Use 0 to mark unused |
181 +--------------------+------+--------------------------------------------------------------+
182 | supervisor_host_id | u8 | Supervisor Host ID |
183 +--------------------+------+--------------------------------------------------------------+
185 .. _pub_boardcfg_ext_otp_config:
187 Extended OTP array configuration
188 --------------------------------
190 The below structure defines which hosts read the OTP area and which host has
191 permissions to write to the OTP area. Please also refer to the below documents
192 to understand the usage of the board configuration structure.
194 1. :doc:`../6_topic_user_guides/extended_otp` and
195 2. :doc:`../2_tisci_msgs/security/extended_otp` and
197 +------------------------+----------------------------------------------------------+------------------------------------+
198 | Element | Type | Description |
199 +========================+==========================================================+====================================+
200 | subhdr | :ref:`pub_boardcfg_subhdr` | Magic and size for integrity check |
201 +------------------------+----------------------------------------------------------+------------------------------------+
202 | otp_entry | :ref:`otp_entry <pub_boardcfg_otp_entry>` [32] | OTP MMR access control per row |
203 +------------------------+----------------------------------------------------------+------------------------------------+
204 | write_host | u8 | ID of the host who can perform |
205 | | | writes to OTP rows |
206 +------------------------+----------------------------------------------------------+------------------------------------+
208 The magic number to be populated in the ``subhdr`` is ``0x4081``.
210 .. note::
212 Wildcard host ID (128U/0x80) cannot be used in the ``write_host`` field. The host ID used here must map to
213 a secure proxy thread.
215 .. warning::
217 Even though OTP functionality is not available on GP devices, the boardcfg structure for OTP must be present.
218 The header must be populated with the size and magic number correctly.
220 .. _pub_boardcfg_otp_entry:
222 Extended OTP Row Entry
223 ^^^^^^^^^^^^^^^^^^^^^^
225 +--------------------+-----------+------------------------------------------------------------------------------------+
226 | Element | Type | Description |
227 +====================+===========+====================================================================================+
228 | host_id | u8 | Host ID |
229 | | | |
230 | | | - Set to 128 if the MMR must be accesible to all hosts |
231 | | | - Set to 0 if the MMR must not be accesible to any host |
232 +--------------------+-----------+------------------------------------------------------------------------------------+
233 | host_perms | u8 | 2 bit wide fields specifying permissions |
234 | | | |
235 | | | - bit 1:0 - 10b - non-secure, any other value secure |
236 | | | - bit 7:2 - Reserved for future use. |
237 +--------------------+-----------+------------------------------------------------------------------------------------+
239 .. _pub_boardcfg_dkek_config:
241 Derived KEK Management
242 ----------------------
244 The below structure controls access to DKEK on the SOC.
245 Please also refer to the below documents to understand the usage of the board configuration structure.
247 1. :doc:`../6_topic_user_guides/dkek_management` and
248 2. :doc:`../2_tisci_msgs/security/dkek_management` and
250 +------------------------------+----------------------------+---------------------------------------------------------------+
251 | Element | Type | Description |
252 +==============================+============================+===============================================================+
253 | subhdr | :ref:`pub_boardcfg_subhdr` | Magic and size for integrity check |
254 +------------------------------+----------------------------+---------------------------------------------------------------+
255 | dkek_allowed_hosts | u8[4] | Hosts allowed access to DKEK |
256 | | | |
257 | | | Set one of the entries to 128 if DKEK must accessible to all |
258 | | | hosts. |
259 +------------------------------+----------------------------+---------------------------------------------------------------+
260 | allow_dkek_export_tisci | u8 | Flag indicating whether DKEK can be exported via TISCI API |
261 | | | |
262 | | | Set to 0x5A if TISCI export is allowed. |
263 +------------------------------+----------------------------+---------------------------------------------------------------+
264 | rsvd | u8[3] | Reserved field. Currently unused. Set to 0. |
265 +------------------------------+----------------------------+---------------------------------------------------------------+
267 The magic number to be populated in the ``subhdr`` is ``0x5170``.
269 .. _pub_boardcfg_reserved_entry:
271 Reserved Entry
272 --------------
274 The below entry is reserved for future use.
276 +---------------------+-----------------------------------------+------------------------------------------------------------------------+
277 | Element | Type | Description |
278 +=====================+=========================================+========================================================================+
279 | subhdr | :ref:`pub_boardcfg_subhdr` | Magic and size for integrity check |
280 +---------------------+-----------------------------------------+------------------------------------------------------------------------+
281 | rsvd | u8[4] | Reserved for future use. Set to 0 |
282 +---------------------+-----------------------------------------+------------------------------------------------------------------------+
284 The magic number to be populated in the ``subhdr`` is ``0x23BE``.
286 .. _pub_boardcfg_secure_debug_unlock:
288 Secure Debug Unlock
289 -------------------
291 +------------------------------+----------------------------+---------------------------------------------------------------+
292 | Element | Type | Description |
293 +==============================+============================+===============================================================+
294 | subhdr | :ref:`pub_boardcfg_subhdr` | Magic and size for integrity check |
295 +------------------------------+----------------------------+---------------------------------------------------------------+
296 | allow_jtag_unlock | u8 | Set to 0x5A if runtime jtag unlock is allowed. |
297 | | | |
298 | | | Set to 0 otherwise. |
299 +------------------------------+----------------------------+---------------------------------------------------------------+
300 | allow_wildcard_unlock | u8 | If this field is set to 0x5A, the same debug unlock |
301 | | | certificate will work across all devices where it passes the |
302 | | | remaining checks. |
303 | | | |
304 | | | Set to 0 otherwise to enforce UID match before jtag unlock |
305 | | | The X509 certificate must contain the UID of the device |
306 | | | being unlocked in the designated field |
307 | | | |
308 | | | NOTE: This field is dependent on the ``allow_jtag_unlock`` |
309 | | | field above. If ``allow_jtag_unlock`` is set to 0, this field |
310 | | | is not used. |
311 +------------------------------+----------------------------+---------------------------------------------------------------+
312 | allow_debug_level_rsvd | u8 | Reserved field. Currently unused. Set to 0. |
313 | | | |
314 | | | This field can be used in the future to control the level of |
315 | | | debug allowed with a certificate. |
316 +------------------------------+----------------------------+---------------------------------------------------------------+
317 | rsvd | u8 | Reserved field. Currently unused. Set to 0. |
318 +------------------------------+----------------------------+---------------------------------------------------------------+
319 | min_cert_rev | u32 | Minimum revision value that must be contained in the debug |
320 | | | unlock certificate for it to be accepted. |
321 | | | Use this field to enforce rollback protection for debug |
322 | | | unlock certificates. |
323 | | | Set to 0 if you do not wish to use this field. |
324 +------------------------------+----------------------------+---------------------------------------------------------------+
325 | jtag_unlock_hosts | u8[4] | Hosts allowed send jtag unlock message via TISCI |
326 | | | |
327 | | | Set one of the entries to 128 if jtag unlock must be allowed |
328 | | | for all hosts. |
329 +------------------------------+----------------------------+---------------------------------------------------------------+
331 The magic number to be populated in the ``subhdr`` is ``0x42AF``.
334 .. _pub_boardcfg_security_handover:
336 Security Handover
337 -----------------
339 .. note::
341 This section is only processed on AM64 devices.
343 Please also refer to the below documents to understand the usage of the board configuration structure.
345 1. :doc:`../6_topic_user_guides/security_handover` and
346 2. :doc:`../2_tisci_msgs/security/security_handover` and
348 +------------------------------+----------------------------+---------------------------------------------------------------+
349 | Element | Type | Description |
350 +==============================+============================+===============================================================+
351 | subhdr | :ref:`pub_boardcfg_subhdr` | Magic and size for integrity check |
352 +------------------------------+----------------------------+---------------------------------------------------------------+
353 | handover_msg_sender | u8 | ID of the host who will send the security handover message |
354 | | | |
355 | | | Set to 0 if security handover is not desired |
356 | | | or is unsupported on the device. |
357 +------------------------------+----------------------------+---------------------------------------------------------------+
358 | handover_to_host_id | u8 | ID of the host who takes over the security functionality |
359 | | | |
360 | | | The credentials of this host are programmed in the firewalls |
361 | | | protecting the security configuration registers. |
362 | | | |
363 | | | Set to 0 if security handover is not desired |
364 | | | or is unsupported on the device. |
365 +------------------------------+----------------------------+---------------------------------------------------------------+
366 | rsvd | u8[4] | Reserved field. Currently unused. Set to 0. |
367 | | | |
368 | | | Security handover currently transfers ownership of the |
369 | | | SOC firewalls. These flags are intended for future use |
370 | | | to indicate whether ownership of additional resources must |
371 | | | be transferred |
372 +------------------------------+----------------------------+---------------------------------------------------------------+
374 The magic number to be populated in the ``subhdr`` is ``0x608F``.