[processor-sdk/pdk.git] / packages / ti / drv / sciclient / docs / system-firmware-public-documentation / _sources / 1_intro / TISCI.rst.txt
1 Brief Introduction to SoC System Control Entity
2 -----------------------------------------------
4 Traditional Texas Instruments SoCs implement system control functions such as
5 power management within operating systems on each of the processing units
6 (ARM/DSP etc). However, the traditional approach has had tremendous challenges
7 to ensure system stability. A few of the challenges include:
9 - Complex interactions between Operating Systems on heterogeneous SoCs for
10 generic features.
11 - Lack of centralized knowledge of system state.
12 - Complex implementation challenges with regards to implementation of
13 workarounds for system quirks.
14 - Equivalent system capability entitlement on all variations of operation
15 conditions.
17 Texas Instruments' System Control Interface (TISCI) defines the communication
18 protocol between various processing entities to the System Control Entity on
19 TI SoCs. This is a set of message formats and sequence of operations required
20 to communicate and get system services processed from the System Control Entity
21 in the SoC.
23 .. note::
24 The majority of users will not need to use TISCI since they will
25 use Processor SDK Linux/RTOS services. For users that do not use
26 Processor SDK, TISCI is provided to access system services.
28 An example of when you may need to make use of TISCI is for the
29 implementation of another operating system. Users can look at the
30 integration in Processor SDK for an example.
32 Introduction to the TISCI protocol
33 ----------------------------------
35 The Primary goal of the TISCI protocol is to be SoC independent. To achieve
36 this, the following rules are followed by TISCI protocol:
38 - Limited in scope to SoC boundary
40 - Entities outside the SoC boundary are not directly controlled by the
41 TISCI protocol.
42 - Centralized control of SoC system
43 functions including power management, resource management, and security.
44 This implies that operating systems do not directly access any of the
45 hardware modules that control system functions such as power management,
46 instead TISCI will be used.
47 - SoC comprises of multiple hardware blocks, hence all
48 abstractions are at the hardware block level. This implies that if the I2C2
49 instance is to be requested, then the I2C2 device is requested and the clock
50 frequency, for example, is referenced from I2C2's perspective. Hence, if the
51 OS driver controlling I2C2 needs to know the functional clock frequency it
52 makes a TISCI request for I2C2 functional clock frequency.
54 Functionality Available Through the TISCI Protocol
55 --------------------------------------------------
57 Power and Clock Management Features
58 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
60 Public APIs are provided to:
62 - Enable and release a module, such as a UART or a core
64 - This configures both power and clock details for the module and keeps
65 track of its usage.
66 - Configure the lowest/deepest low-power (sleep) mode allowed as well as EMIF
67 details to enable self-refresh
68 - Query thermal sensors
70 Resource Management Features
71 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
73 Public APIs are provided to:
75 - Manage DMA/Navigator Resources
77 - UDMAP
78 - Ring Accelerator
79 - PSI-L
80 - Proxy
81 - Program interrupts (interrupt aggregators and routers) both
82 at SoC and subsystem (DMA/Navigator) level
84 Security Features
85 ^^^^^^^^^^^^^^^^^
87 Public APIs are provided to directly configure these features following
88 polices and root of trust:
90 - ISC
92 - Present at originator/master interfaces to control credentials from master
93 - Firewall
95 - Additional layer of access control beyond MMU/MPU located at each
96 destination/slave interface to control memory and register access
97 - SA2-UL Security Contexts
99 - Contains actual keys for crypto accelerator
101 APIs are also provided to authenticate and/or decrypt blobs in memory.
103 Generic Messaging Header
104 ------------------------
106 All messages are prefixed by a header. This header is always present for
107 transmit or receive messages. The format is as follows:
109 .. sysfwapistruct:: tisci_header
110 :exclude-members: payload
112 The ``host`` field must contain a value from the
113 :doc:`Valid SoC Host ID List <../5_soc_doc/am6x/hosts>`
114 that corresponds to the host actually sending the message as identified
116 The ``seq`` field is a sequence number that will be returned back to the user
117 for the response corresponding to the message. It is up to the user to define
118 ``seq`` in whatever way they choose. The primary intent of this field is to
119 allow for the queueing of multiple messages on different priority queues while
120 still being able to identify the response to the specific message that was
121 transmitted.
123 The following generic flags are available for the ``flags`` field:
125 Request flags
126 ^^^^^^^^^^^^^
128 .. sysfwapimacro:: TISCI_MSG_FLAG_RESERVED0
129 .. sysfwapimacro:: TISCI_MSG_FLAG_AOP
131 .. warning::
133 It is critical that the TISCI_MSG_FLAG_AOP is set (often
134 TISCI_MSG_FLAG_AOP is the desired option) if a proper response is
135 required, as without any ACK requested no response will be sent at all,
136 even in the case of failure. If no response is acceptable this warning
137 can be disregarded.
139 Response flags
140 ^^^^^^^^^^^^^^
142 .. sysfwapimacro:: TISCI_MSG_FLAG_ACK
145 Secure Messaging Header
146 -----------------------
148 All messages received by System Firmware through a secure transport must include
149 a "Secure Messaging Header" in addition to the "Generic Messaging Header". The
150 "Secure Messaging Header" allows System Firmware to verify that the message has
151 been received intact. The format is as follows.
153 .. note::
154 The Secure Messaging Header is only required when sending messages over
155 secure transport. Messages sent over non-secure transport must not
156 contain the secure messaging header.
158 .. sysfwapistruct:: tisci_sec_header
160 .. figure:: ../img/tisci-sec-ext-images/secure-header.png
162 Secure Messaging Header format
165 1. The Secure header is mandatory for all messages that are received via secure
166 transports. In AM6x devices, secure transport is a secure proxy thread that
167 has been marked as secure.
169 2. The secure header is placed before a TI SCI message. We chose this header
170 placement as it is akin to wrapping a TISCI message in a secure header.
171 Processing of the secure header can happen in a separate layer on both the
172 transmitter and the receiver. Rest of the code can be unaware of the secure
173 header.
175 3. The first two bytes of the secure header are used for storing the
176 integrity check field.
178 4. The next two bytes of the secure header are reserved for future use and are
179 initialized to zero.
181 Secure header in the request path
182 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
184 The maximum length of the data that needs to be integrity checked is 56 bytes.
185 Of these 8 bytes are taken up by the standard TISCI header, 4 bytes by the
186 secure header leaving 44 bytes for the payload.
188 .. figure:: ../img/tisci-sec-ext-images/user-integrity-check-calculation.png
190 Integrity Check calculation in the request path
192 The user is expected to
194 1. Prepare the TISCI message as usual.
196 2. Prepend the secure header initialized to zero. In the memory layout, the
197 secure header should be followed by the TISCI header. TISCI header should be
198 followed by the payload.
200 3. The value of the integrity check is calculated as described in
201 :ref:`tisci-sec-hdr-integ-check-calc`.
203 4. The calculated value of the integrity check is inserted MSB first into the
204 secure header extension.
206 .. code-block:: c
208 integ_check[0] = MSB(calc_val)
209 integ_check[1] = LSB(calc_val)
211 5. Send the message to System Firmware via the chosen transport.
213 Secure header in the response path
214 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
216 In the response path, System Firmware populates the integrity check in the same
217 manner for all responses via a secure transport. The sender of the message can
218 verify the integrity check before processing the response.
220 Secure header on a GP device vs a HS device
221 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
223 GP Device
224 ~~~~~~~~~
226 The Secure Messaging header **is not processed by System Firmware on a GP
227 device**. So the host sending the TISCI request can populate the Secure
228 Messaging Header with zeros.
230 To maintain API compatiblity between GP and HS devices, all messages sent or
231 received from System Firmware via a secure transport must include the Secure
232 Messaging Header.
234 HS Device
235 ~~~~~~~~~
237 On a HS device, System Firmware processes the integrity check field. The
238 integrity check field needs to be correctly populated as per the defined
239 integrity check function for HS devices.
242 .. _tisci-sec-hdr-integ-check-calc:
244 Secure header integrity check calculation
245 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
247 .. note::
249 The integrity check function for HS devices will be defined with the release
250 of the HS devices.
252 TISCI Message Eligibility for Secure vs Non-secure transport
253 ------------------------------------------------------------
255 Certain messages are only eligible to be sent over secure transport due
256 to the nature of the services they offer. However, all messages are able be
257 sent on secure queues, even when supported on non-secure queues as well.
258 However, it must be considered that messages that can be sent on either
259 secure or non-secure transport must have the tisci_sec_header **only**
260 when being sent over secure transport.
262 Each message has a table under a *Usage* section that describes whether a
263 message is limited to being sent over secure queues only.