TISCI General Message API Documentation

This document describes the TISCI API set for general messages such as those to fetch the firmware version in use, send usecase specific configuration, and get notified of the boot state of system-firmware.

TISCI_MSG_VERSION

Objective

Retrieve the version of the currently running system-firmware.

Usage

Message Type Normal
Secure Queue Only? No

This retrieves several pieces of information about the version of system-firmware that is loaded and running.

TISCI Message ID

TISCI_MSG_VERSION          (0x0002U)

Message Data Structures

struct tisci_msg_version_req

Notification message to indicate the DMSC is available.

Parameter Type Description
hdr struct tisci_header TISCI header

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation.

struct tisci_msg_version_resp

TISCI_MSG_VERSION request to provide version info about currently running firmware.

Parameter Type Description
hdr struct tisci_header TISCI header.
str char Human readable version string.
version u16 Version number of the firmware.
abi_major u8 Major version number of ABI in use by firmware.
abi_minor u8 Minor version number of ABI in use by firmware.
sub_version u8 Sub-version number of the firmware.
patch_version u8 Patch-version number of the firmware.

TISCI_MSG_BOOT_NOTIFICATION

Objective

Notify the system boot host that the system-firmware is ready to begin receiving and processing TISCI messages.

Usage

Message Type Notification
Secure Queue Only? Yes

This is a system-firmware initiated notification message that is sent to the boot core of the system to notify system-firmware is ready to receive TISCI messages. Up until this point, no interaction is possible with system firmware.

TISCI Message ID

TISCI_MSG_BOOT_NOTIFICATION          (0x000AU)

Message Data Structures

struct tisci_msg_boot_notification_req

Notification message to indicate the DMSC is available.

Parameter Type Description
hdr struct tisci_header TISCI header
extboot_status u32 Status of extended boot. Applicable only for combined image

struct tisci_msg_boot_notification_resp

Response to notification message about firmware availability.

Parameter Type Description
hdr struct tisci_header TISCI header

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation.

TISCI_MSG_BOARD_CONFIG

See TISCI API for Board Config.

TISCI_MSG_BOARD_CONFIG_RM

See TISCI API for Resource Management Board Config.

TISCI_MSG_BOARD_CONFIG_SECURITY

See TISCI API for Security Board Config.

TISCI_MSG_BOARD_CONFIG_PM

See TISCI API for Power Management Board Config.

TISCI_MSG_QUERY_MSMC

Objective

Retrieve the MSMC memory available.

Usage

Message Type Normal
Secure Queue Only? No

This API is enabled ONLY on SoCs that actually have MSMC memory. This retrieves valid start and end address of MSMC memory considering size of allocation for cache backing RAM and MSMC shared usage by System Firmware.

This API is linked with the parameter provided in Design for boardcfg_msmc. The parameter msmc_cache_size is a value ranging from 0x00 to 0x20 independent of SoC and configured at system startup. This API is used by software components that start functionality later in the boot sequence and intends to manage or use the remaining SRAM contents.

To understand the relationship, let’s consider a SoC with actual physical MSMC SRAM available to allocate as 2MB:

case A) Allocation of 1/2 SRAM(1MB) for L3 backing RAM

../../_images/msmc_alloc_strategy.png

In the above example, when the msmc_cache_size parameter is 0x10, 1MB is reserved for backing ram by the SoC. Memory needed for communication infrastructure is automatically relocated to the center of MSMC SRAM.

The available MSMC SRAM for use by software queried via TISCI_MSG_QUERY_MSMC will respond with: start = 0x0000000070000000 and end = 0x00000000700EFFFF (1MB-64K)

case B) Allocation of 0bytes SRAM for L3 backing RAM

../../_images/msmc_alloc_strategy_0cache.png

In the above example, when the msmc_cache_size parameter is 0x00, no memory is reserved for backing ram by the SoC. Memory needed for communication infrastructure is automatically relocated to the far end of MSMC SRAM.

The available MSMC SRAM for use by software queried via TISCI_MSG_QUERY_MSMC will respond with: start = 0x0000000070000000 and end = 0x00000000701EFFFF (2MB-64K)

Warning

It is important to keep the following in mind. Software applications must always use this API to know the actual SRAM memory available for use. This is extremely critical if the software component providing (example: bootloader) does not have means to communicate information to the component that actually uses the SRAM.

As a hardware behavior, a read from MSMC SRAM reserved for backing L3 Cache will return 0x0 on a read, vs a write will cause a data abort to that address. Meanwhile a read/write to the memory reserved for communication memory will generate a firewall exception.

TISCI query MSMC

TISCI_MSG_QUERY_MSMC          (0x0020U)

Message Data Structures

struct tisci_query_msmc_req

TISCI_MSG_QUERY_MSMC request to provide currently available MSMC memory if present in the SoC

Parameter Type Description
hdr struct tisci_header TISCI header

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation.

struct tisci_query_msmc_resp

TISCI_MSG_QUERY_MSMC request response providing currently available MSMC memory if present in the SoC

Parameter Type Description
hdr struct tisci_header TISCI header.
msmc_start_low u32 Low 32-bits of physical address start of MSMC memory
msmc_start_high u32 High 32-bits of physical address start of MSMC memory
msmc_end_low u32 Low 32-bits of physical addressable address (byte aligned) of valid range of MSMC memory.
msmc_end_high u32 High 32-bits of physical addressable address (byte aligned) of valid range of MSMC memory.

TISCI_MSG_GET_TRACE_CONFIG

Objective

Retrieve debug trace configuration from TIFS.

Usage

Note

DM firmware doesn’t have the information about debug trace configuration. DM uses this message to query TIFS for debug trace configuration.

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_GET_TRACE_CONFIG          (0x0021U)

Message Data Structures

struct tisci_get_trace_config_req

TISCI_MSG_GET_TRACE_CONFIG request to get the debug trace config from base board config

Parameter Type Description
hdr struct tisci_header TISCI header

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation.

struct tisci_get_trace_config_resp

TISCI_MSG_GET_TRACE_CONFIG request response providing the debug config from base board config

Parameter Type Description
hdr struct tisci_header TISCI header.
trace_dst_enables u16 enabled destination traces
trace_src_enables u16 enabled source traces

TISCI_MSG_QUERY_FW_CAPS

Objective

Retrieve the firmware capabilities of the currently running system-firmware.

Usage

Message Type Normal
Secure Queue Only? No

Each bit in the response indicating a certain functionality is present or not.

Feature Present Representing Bit
Generic capability 0
Deep sleep low power mode 1
MCU only low power mode 2
Standby low power mode 3
Partial IO on low power mode 4
DM Managed low power mode 5
Reserved 6-63

TISCI Message ID

TISCI_MSG_QUERY_FW_CAPS          (0x0022U)

Message Data Structures

struct tisci_query_fw_caps_req

TISCI_MSG_QUERY_FW_CAPS request to provide the firmware/SOC capabilities

Parameter Type Description
hdr struct tisci_header TISCI header

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation.

struct tisci_query_fw_caps_resp

TISCI_MSG_QUERY_FW_CAPS request response providing currently available SOC/firmware capabilities

Parameter Type Description
hdr struct tisci_header TISCI header.
fw_caps u64 Each bit in fw_caps indicating one FW/SOC capability