Brief Introduction to SoC System Control Entity

Traditional Texas Instruments SoCs implement system control functions such as power management within operating systems on each of the processing units (ARM/DSP etc). However, the traditional approach has had tremendous challenges to ensure system stability. A few of the challenges include:

  • Complex interactions between Operating Systems on heterogeneous SoCs for generic features.
  • Lack of centralized knowledge of system state.
  • Complex implementation challenges with regards to implementation of workarounds for system quirks.
  • Equivalent system capability entitlement on all variations of operation conditions.

Texas Instruments’ System Control Interface (TISCI) defines the communication protocol between various processing entities to the System Control Entity on TI SoCs. This is a set of message formats and sequence of operations required to communicate and get system services processed from the System Control Entity in the SoC.

Note

The majority of users will not need to use TISCI since they will use Processor SDK Linux/RTOS services. For users that do not use Processor SDK, TISCI is provided to access system services.

An example of when you may need to make use of TISCI is for the implementation of another operating system. Users can look at the integration in Processor SDK for an example.

Introduction to the TISCI protocol

The Primary goal of the TISCI protocol is to be SoC independent. To achieve this, the following rules are followed by TISCI protocol:

  • Limited in scope to SoC boundary
    • Entities outside the SoC boundary are not directly controlled by the TISCI protocol.
  • Centralized control of SoC system functions including power management, resource management, and security. This implies that operating systems do not directly access any of the hardware modules that control system functions such as power management, instead TISCI will be used.
  • SoC comprises of multiple hardware blocks, hence all abstractions are at the hardware block level. This implies that if the I2C2 instance is to be requested, then the I2C2 device is requested and the clock frequency, for example, is referenced from I2C2’s perspective. Hence, if the OS driver controlling I2C2 needs to know the functional clock frequency it makes a TISCI request for I2C2 functional clock frequency.

Functionality Available Through the TISCI Protocol

Power and Clock Management Features

Public APIs are provided to:

  • Enable and release a module, such as a UART or a core
    • This configures both power and clock details for the module and keeps track of its usage.
  • Configure the lowest/deepest low-power (sleep) mode allowed as well as EMIF details to enable self-refresh
  • Query thermal sensors

Resource Management Features

Public APIs are provided to:

  • Manage DMA/Navigator Resources
    • UDMAP
    • Ring Accelerator
    • PSI-L
    • Proxy
  • Program interrupts (interrupt aggregators and routers) both at SoC and subsystem (DMA/Navigator) level

Security Features

Public APIs are provided to directly configure these features following polices and root of trust:

  • ISC
    • Present at originator/master interfaces to control credentials from master
  • Firewall
    • Additional layer of access control beyond MMU/MPU located at each destination/slave interface to control memory and register access
  • SA2-UL Security Contexts
    • Contains actual keys for crypto accelerator

APIs are also provided to authenticate and/or decrypt blobs in memory.

Generic Messaging Header

All messages are prefixed by a header. This header is always present for transmit or receive messages. The format is as follows:

struct tisci_header

Header that prefixes all TISCI messages.

Parameter Type Description
type u16 Type of message identified by a TISCI_MSG_* ID
host u8 Host of the message.
seq u8 Message identifier indicating a transfer sequence.
flags u32 TISCI_MSG_FLAG_* for the message.

The host field must contain a value from the Valid SoC Host ID List that corresponds to the host actually sending the message as identified

The seq field is a sequence number that will be returned back to the user for the response corresponding to the message. It is up to the user to define seq in whatever way they choose. The primary intent of this field is to allow for the queueing of multiple messages on different priority queues while still being able to identify the response to the specific message that was transmitted.

The following generic flags are available for the flags field:

Request flags

TISCI_MSG_FLAG_AOR          BIT(0)

Send an ack to the message when it is received

TISCI_MSG_FLAG_AOP          BIT(1)

Send an ack to the message when it has been processed

Warning

It is critical that one of the two above flags are set (often TISCI_MSG_FLAG_AOP is the desired option) so that a proper response is received, as without any ACK requested no response will be sent at all, even in the case of failure. If no response is acceptable this warning can be disregarded.

Response flags

TISCI_MSG_FLAG_ACK          BIT(1)

Response flag for a message that indicates success. If this flag is NOT set then that is to be interpreted as a NAK.

Secure Messaging Header

All messages received by System Firmware through a secure transport must include a “Secure Messaging Header” in addition to the “Generic Messaging Header”. The “Secure Messaging Header” allows System Firmware to verify that the message has been received intact. The format is as follows.

Note

The Secure Messaging Header is only required when sending messages over secure transport. Messages sent over non-secure transport must not contain the secure messaging header.

struct tisci_sec_header

Header that prefixes all TISCI messages sent via secure transport.

Parameter Type Description
integ_check u16 This field should always be initialized to zero on GP devices. The mechanism to calculate the integrity check for HS devices is under definition.
rsvd u16 Reserved field for future use. Initialize to zero.

../_images/secure-header.png

Fig. 1 Secure Messaging Header format

  1. The Secure header is mandatory for all messages that are received via secure transports. In AM6x devices, secure transport is a secure proxy thread that has been marked as secure.
  2. The secure header is placed before a TI SCI message. We chose this header placement as it is akin to wrapping a TISCI message in a secure header. Processing of the secure header can happen in a separate layer on both the transmitter and the receiver. Rest of the code can be unaware of the secure header.
  3. The first two bytes of the secure header are used for storing the integrity check field.
  4. The next two bytes of the secure header are reserved for future use and are initialized to zero.

Secure header in the request path

The maximum length of the data that needs to be integrity checked is 56 bytes. Of these 8 bytes are taken up by the standard TISCI header, 4 bytes by the secure header leaving 44 bytes for the payload.

../_images/user-integrity-check-calculation.png

Fig. 2 Integrity Check calculation in the request path

The user is expected to

  1. Prepare the TISCI message as usual.
  2. Prepend the secure header initialized to zero. In the memory layout, the secure header should be followed by the TISCI header. TISCI header should be followed by the payload.

3. The value of the integrity check is calculated as described in Secure header integrity check calculation.

  1. The calculated value of the integrity check is inserted MSB first into the secure header extension.

    integ_check[0] = MSB(calc_val)
integ_check[1] = LSB(calc_val)

  2. Send the message to System Firmware via the chosen transport.

Secure header in the response path

In the response path, System Firmware populates the integrity check in the same manner for all responses via a secure transport. The sender of the message can verify the integrity check before processing the response.

Secure header on a GP device vs a HS device

GP Device

The Secure Messaging header is not processed by System Firmware on a GP device. So the host sending the TISCI request can populate the Secure Messaging Header with zeros.

To maintain API compatiblity between GP and HS devices, all messages sent or received from System Firmware via a secure transport must include the Secure Messaging Header.

HS Device

On a HS device, System Firmware processes the integrity check field. The integrity check field needs to be correctly populated as per the defined integrity check function for HS devices.

Secure header integrity check calculation

Note

The integrity check function for HS devices will be defined with the release of the HS devices.

TISCI Message Eligibility for Secure vs Non-secure transport

Certain messages are only eligible to be sent over secure transport due to the nature of the services they offer. However, all messages are able be sent on secure queues, even when supported on non-secure queues as well. However, it must be considered that messages that can be sent on either secure or non-secure transport must have the tisci_sec_header only when being sent over secure transport.

Each message has a table under a Usage section that describes whether a message is limited to being sent over secure queues only.