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¶
TISCI_MSG_BOARD_CONFIG_RM¶
TISCI_MSG_BOARD_CONFIG_SECURITY¶
TISCI_MSG_BOARD_CONFIG_PM¶
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
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
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 |
| Reserved | 5-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 |