4.13.1. Introduction

Traditional Texas Instruments SoCs implement system control functions such as power management on each of the processing units (ARM/DSP etc). However, the traditional approach 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.

K3 devices introduces the concept of a centralized Power, Resource and Security Management to allow mitigating the challenges of the traditional approach to system control.

System Firmware is a collective term used to describe the TI Foundational Security (TIFS) and Resource Management (RM)/ Power Management (PM) services.

System Firmware executes on the Security Manager and Device Manager Core. On K3 devices, the DMSC subsystem is the Security Manager Core in the SoC. The Device Manager core can be on the DMSC itself or the MCU R5F. The choice of whether this runs on the DMSC or the MCU R5F is based on the kind of applications the device is targeting. If the device is targetting applications, where there is a need for a dedicated HSM, the Device manager core is independent of the DMSC (which is exclusively kept for Security functions). For devices which do not have need for a dedicated security island or HSM, the device manager runs on the DMSC.

The following table highlights the variations of where the RM and PM execute versus the TIFS on the different K3 family of devices.

Table 4.1 TI Foundational Security Software and RM/PM SCI Server Mapping
Device TI Foundation Security 3rd Party HSM/SHE stack RM/PM SCI Server
AM65x/ DRA80x, AM64x DMSC (M3 based) NA DMSC (M3 based)
J721E, J7200 DMSC (M3 based) DMSC (M3 based) Library on MCU R5*

More information regarding the TI-SCI is given here .

The Sciclient is an interface to the TI-SCI protocol for RTOS and non-OS based applications. It exposes the core message details, valid module/clock IDs to the higher level software and abstracts the communication with SYSFW based on the TI-SCI protocol. These APIs can be called by power, resource and security RTOS drivers or any other non-OS or RTOS based higher level software to be able to communicate with DMSC for its services. The higher level software is expected to populate the necessary message core parameters.

The Sciclient components running on different cores are given in the figure below:


Fig. 4.1 Sciclient on different cores

Every core in the device can be secure or non secure. Based on the secure and non-secure nature of the core or context of the core, it can use the secure threads or non-secure threads of communication. All non-secure requests are sent to the MCU R5F when the RM/PM services are running on the MCU R5F. All secure requests are sent to the DMSC.

The flow of control for a secure host making a secure message processing request is as shown in the figure below. The flow is the same for non-secure cores for devices like AM65xx and AM64x where the RM/PM services run on the DMSC M3.


Fig. 4.2 Sequence Diagram (Secure) – All Cores

The flow of control for a non secure message running from the MCU R5F is as below:


Fig. 4.3 Sequence Diagram (Non Secure) – MCU R5F

For the MCU R5F can link the following libraries when it is the only core running software in the entire device. This scenario is only applicable for certain PDK examples.

In the following table, SCI_PATH=”pdk_<soc>_<version>/packages/ti/drv/sciclient”

Library Name Library Path Include Header Description
sciclient_direct $(SCI_PATH)/lib/<soc>/mcu1_0/<profile>/sciclient_direct.aer5f $(SCI_PATH)/sciclient.h Direct function calls to RM/PM HAL services. Applicable to baremetal, TI-RTOS or other OS based applications.
rm_pm_hal $(SCI_PATH)/lib/<soc>/mcu1_0/<profile>/rm_pm_hal.aer5f NA - Always call via sciclient APIs. Actual implementation of the RM/PM HAL operations. Applicable to baremetal, TI-RTOS or other OS based applications.

For typical applications where there is software running on other non-MCU1_0 cores the MCU1_0 needs to link the following libraries.

In the following table, SCI_PATH=”pdk_<soc>_<version>/packages/ti/drv/sciclient”

Library Name Library Path Include Header Description
sciserver_tirtos $(SCI_PATH)/lib/<soc>/mcu1_0/<profile>/sciserver_tirtos.aer5f $(SCI_PATH)/sciserver_tirtos.h Applicable when RTOS is executing on the MCU1_0
sciclient_direct $(SCI_PATH)/lib/<soc>/mcu1_0/<profile>/sciclient_direct.aer5f $(SCI_PATH)/sciclient.h Direct function calls to RM/PM HAL services. Applicable to baremetal, RTOS or other OS based applications.
rm_pm_hal $(SCI_PATH)/lib/<soc>/mcu1_0/<profile>/rm_pm_hal.aer5f NA - Always call via sciclient APIs. Actual implementation of the RM/PM HAL operations. Applicable to baremetal, RTOS or other OS based applications.

The above table assumes that the application developer is running RTOS on the MCU1_0. In cases where the MCU1_0 is not running RTOS but an OS like AUTOSAR for eaxmple, the application developer should use the below library and also create, build and link an equivalent file as sciserver_tirtos.c.

Library Name Library Path Include Header Description
sciserver_baremetal $(SCI_PATH)/lib/<soc>/mcu1_0/<profile>/sciserver_baremetal.aer5f $(SCI_PATH)/sciserver.h This is the bare-metal barebones functions of Sciserver. Note you cannot run sciserver without an OS. The application developer must develop their own version of $(SCI_PATH)/src/ sciserver/sciserver_tirtos.c for the OS you are using before working with Sciserver on the MCU1_0.


sciserver_tirtos library supports FreeRTOS as well. Some Sciserver APIs are also named as Sciserver_tirtos**, but it actually supportes FreeRTOS too. The naming is misleading, but the name is not changed due to compatibility issues.

The flow of control for a non secure message running from a non MCU1_0 core is as below:


Fig. 4.4 Sequence Diagram (Non Secure) – Other Cores

For a non-secure entity requesting a secure service like setting up firewalls the message is routed from the non-secure MCU1_0 to the DMSC and after the DMSC processes the message it is sent back to the MCU1_0 which forwards the response to the host requesting the message.

Similarly for a secure entity requesting a non-secure service like Power management, the message is routed from the DMSC to the MCU1_0 and after the MCU1_0 processes the message it is sent back to the DMSC which forwards the response to the host requesting the message. Terms and Abbreviation

term definition or explanation
DMSC Device Management and Security Controller
BOARDCFG Board configuration for DMSC initialization data
SCI System Control Interface
SYSFW System Firmware
PM Power Management
RM Resource Management
RM/PM HAL Implementation of RM and PM
HSM Hardware Security Module Directory Structure

The directory structure of Sciclient is as follows:

├── ./docs
│   ├── ./docs/design                                   /* Contains Sciclient design documentation */
│   │   └── ./docs/design/images
│   └── ./docs/doxygen                                  /* Doxygen for Sciclient */
├── ./examples
│   ├── ./examples/common                               /* Common functions used for examples */
│   ├── ./examples/sciclient_ccs_init                   /* Example used to init board config for SYSFW with CCS based debug */
│   ├── ./examples/sciclient_firmware_boot_TestApp      /* Example showcasing how to load DMSC M3 software */
│   ├── ./examples/sciclient_fw_testapp                 /* Example showcasing firewall setting and memory access control */
│   ├── ./examples/sciclient_rtos_app                   /* Example on RTOS for showing Sciclient usage */
│   ├── ./examples/sciclient_unit_testapp               /* Example on RTOS for different sciclient APIs */
│   └── ./examples/sciserver_testapp                    /* Example on RTOS showing Sciserver initialization.
|                                                        *  This is used with other PDK apps for servicing RM and PM */
├── ./include                                           /* Include folders for Sciclient */
├── ./soc
│   ├── ./soc/sysfw
│   │   ├── ./soc/sysfw/binaries                        /* TIFS and SYSFW binaries for GP and HS kept here */
│   │   └── ./soc/sysfw/include                         /* TISCI interface Headers are kept here */
│   └── ./soc/V0                                        /* AM65x SoC specific headers/files */
│   └── ./soc/V1                                        /* J721E SoC specific headers/files */
│   └── ./soc/V2                                        /* J7200 SoC specific headers/files */
│   └── ./soc/V3                                        /* AM64x SoC specific headers/files */
├── ./src
│   ├── ./src/priv                                      /* Sciclient specific private files */
│   │   ├── ./src/priv/drivers
│   │   └── ./src/priv/osal
│   ├── ./src/rm_pm_hal                                 /* RM/PM HAL source folder */
│   │   ├── ./src/rm_pm_hal/build
│   │   ├── ./src/rm_pm_hal/common
│   │   ├── ./src/rm_pm_hal/include
│   │   ├── ./src/rm_pm_hal/pm
│   │   ├── ./src/rm_pm_hal/rm
│   │   ├── ./src/rm_pm_hal/scripts
│   │   └── ./src/rm_pm_hal/utils
│   ├── ./src/sciclient                                 /* Sciclient direct and Indirect source folder */
│   └── ./src/sciserver                                 /* Sciserver source folder */
│       ├── ./src/sciserver/j7200
│       └── ./src/sciserver/j721e
└── ./tools
    ├── ./tools/bin2c
    └── ./tools/ccsLoadDmsc                             /* CCS loadable executables and launch scripts */
        ├── ./tools/ccsLoadDmsc/am64x
        ├── ./tools/ccsLoadDmsc/am65xx
        ├── ./tools/ccsLoadDmsc/j7200
        └── ./tools/ccsLoadDmsc/j721e

4.13.2. Build and Run

This section assumes that you have PDK at PDK_INSTALL_DIR .

PDK_BUILD_PATH = PDK_INSTALL_DIR/packages/ti/build
SCICLIENT_PATH = PDK_INSTALL_DIR/drv/sciclient Build targets

The driver provides targets for building library, unit tests and docs . The library and unit tests can be built from PDK_BUILD_PATH or SCICLIENT_PATH . The docs can only be built from SCICLIENT_PATH .

Target Command Description
Library make PDK_INSTALL_PATH=<your PDK_ROOT_PATH> BOARD= j721e_evm CORE=<mcu1_0 or mpu1_0> sciclient Sciclient library
Library make PDK_INSTALL_PATH=<your PDK_ROOT_PATH> BOARD= j721e_evm CORE=mcu1_0 sciserver Sciserver library
Boardcfgs make PDK_INSTALL_PATH=<your PDK_ROOT_PATH> BOARD= j721e_evm sciclient_boardcfg Board configuration data binaries (base, RM, PM, and security) for GP devices
HS boardcfgs make PDK_INSTALL_PATH=<your PDK_ROOT_PATH> BOARD= j721e_evm sciclient_boardcfg_hs Signed Board configuration data binaries for HS devices
sciclient_ccs_init make PDK_INSTALL_PATH=<your PDK_ROOT_PATH> BOARD= j721e_evm CORE=<mcu1_0 or mpu1_0> sciclient_ccs_init Sciclient application that loads the firmware during ccs load.(No need to build this normally.)
sciclient_firmware_boot make PDK_INSTALL_PATH=<your PDK_ROOT_PATH> BOARD= j721e_evm CORE=<mcu1_0 or mpu1_0> sciclient_firmware_boot Sciclient example application
Design Doc make PDK_INSTALL_PATH=<your PDK_ROOT_PATH> designdoc Sciclient design documentation


For building the example "sciclient_firmware_boot" or "your application" using Sciclient lib, make sure you have a section "boardcfg_data" defined in your linker cmd file which resides in OC-MSRAM .

The next sections will explain how to load the system firmware using sciclient. Changing your board configuration

The PDK provides a standard board configuration which is validated with the SDK tests and applications. If any changes are to be made to the board configuration elements, for example reassignment of resource entires for RM or update to security policy, the board configurations must be rebuilt for consumption by the boot binary.

To rebuild, follow the steps listed above for building the boardcfg targets based on the device type you are using and ensure that the boot application consumes the new binary data by rebuilding/relinking the relevant sections.


For security-enforced devices, the board configurations must be authenticated by TIFS/SYSFW and hence must be signed with the active customer key in order to fully boot the device. For compatibility across all devices, always ensure the software revision (SWREV) extension is set to at least 1 with a fresh device. This will need to be incremented across the device life-cycle to match at least the current value set into the dmsc_fw_cfgrev efuse to enforce anti-rollback checks on the board configurations. Load using a boot-media

Follow these steps to load the sciclient_firmware_boot application through a boot media:

  • Build the example: sciclient_firmware_boot_TestApp
  • Ensure to create a tiboot3.bin file from the sciclient application.
  • Refer the section Boot-Modes for details on how to use a bootmedia.
  • You can also use the SBL to load the system firmware and initialize the SoC. Refer to the SBL user guide for more details. Load using CCS

Follow these steps to load the sciclient_ccs_init application through CCS


This boot method is not valid security-enforced devices due to the JTAG port being locked at device boot.

  • Update the File SCICLIENT_PATH/sciclient/tools/ccsLoadDmsc/<soc>/launch.js for the following variables to your PC location .

Modify for J721E :

//PDK path. Edit this
pdkPath = "PDK_INSTALL_DIR";
  • Connect the Javascript to the CCXML file with the steps shown below: (Note: this step needs to be repeated if you switch workspaces or clean your workspace).The Javascript is run on re-launch of the ccxml. If you would like to run the Javascript without relaunch then you can look ahead to the section: “Re-running the script once ccxml is already launched.” Click on Debug Configurations from the button as follows:

  • Select the CCXML file from the left-hand side and populate the path to the launch_am65xx.js file in the “Initialization Script” free form field and click on “Apply”.

  • Once you Launch the ccxml the java script would automatically run and connect to R5F.

Re-running the script once ccxml is already launched

In CCS, go to View > Scripting Console. Type in the CCS Scripting Console:


Available SOC_NAMEs: am65xx, am64x, j721e, j7200 This would give the following output on the scripting console

For J721E :

js:> load("SCICLIENT_PATH/tools/ccsLoadDmsc/<soc>/launch.js")
Connecting to DMSC_Cortex_M3_0!
Fill R5F ATCM memory...
Writing While(1) for R5F
Loading DMSC Firmware ... SCICLIENT_PATH/sciclient/soc/sysfw/binaries/ti-fs-firmware-<soc>-gp.bin
DMSC Firmware Load Done...
DMSC Firmware run starting now...
Connecting to MCU Cortex_R5_0!
 WKUP Boot Mode is 56
 Main Boot Mode is 17
Running the board configuration initialization from R5!
Running the DDR configuration... Wait till it completes!
Running DDR Memory Checks....
Loading Sciserver Application on MCU1_0. This will service RM/PM messages
If you do not want this to be loaded update the launch script to make loadSciserverFlag = 0
If you want to load and run other cores, please run the MCU1_0 core after Sciserver is loaded.
Happy Debugging!!

In order to load examples via CCS the following sub usecases should be kept in mind for devices where RM/PM run on the MCU1_0:.

Loading Applications on MCU1_0

When loading applications on the MCU1_0 the Sciclient_direct (in baremetal case and TI RTOS case) and Sciserver (in TI RTOS case) are assumed to be a part of the MCU1_0 application. Use the pdk/packages/ti/drv/sciclient/tools/ccsLoadDmsc/<soc>/launch.js file as descibed above to launch the TIFS on the DMSC M3 and run the board configuration for the secure proxy setup and the security board configuration via sciclient_ccs_init app.

A special configuration flag has been added to the `launch.js` file `loadSciserverFlag`. The default value of this flag is 1. When running your own application on the MCU1_0, please make sure to change this flag to 0.

For other cpus

When loading applications on other CPU cores apart from MCU1_0 which link the sciclient library which sends the TISCI messages over secure proxy use the launch.js file to load the TIFS on the DMSC M3, run the common and security board configuration via the sciclient_ccs_init app and then load the sciserver_testapp on the MCU1_0.

The MCU1_0 is left at the main() function of the sciserver_testapp before giving control back to the user. At this point one can load the non MCU1_0 core with the application of interest and then run both the MCU1_0 and the application core of choice.

A special configuration flag has been added to the `launch.js` file `loadSciserverFlag`. The default value of this flag is 1. When running your own application on the non-MCU1_0 core, please make sure to keep this flag as 1. Handling Two or more ccxml files

In case you need to connect two or more board to the same CCS session and use the launch script, please follow the steps below:

  • When you use 2 or more CCXML files with similar debugger (e.g. connect 2 boards XDS110 on-board debugger to the PC), CCS would enumerate the debuggers as below:
Texas Instruments XDS110 USB Debug Probe_0
Texas Instruments XDS110 USB Debug Probe_1

Notice the suffix “_0” and “_1”. - In order to use the same launch.js file with this, please create a second copy of the launch.js file. Update the first launch.js files as below:

function updateScriptVars()
    //Open a debug session
    dsMCU1_0 = debugServer.openSession( "*_0.*MCU_PULSAR_Cortex_R5_0" );
    dsDMSC_0 = debugServer.openSession( "*_0.*DMSC_Cortex_M3_0" );

Update the second launch.js as below:

function updateScriptVars()
    //Open a debug session
    dsMCU1_0 = debugServer.openSession( "*_1.*MCU_PULSAR_Cortex_R5_0" );
    dsDMSC_0 = debugServer.openSession( "*_1.*DMSC_Cortex_M3_0" );
Notice the addition of "*_0" and "*_1"

4.13.3. System Firmware Logs Parse

In many cases you may need to understand and debug if a System Firmware API fails due to incorrect parameters or some genuine issue in the firmware. In order to debug when the API is failing, you need to follow the steps below:

  • Enable logs in the system firmware by modifying the below structure:

File: sciclientsocVxsciclient_defaultBoardcfg.c Structure: const struct tisci_boardcfg gBoardConfigLow Update the structure to have trace enabled:

/* This enables the trace for DMSC logging. Should be used only for
 * debug.
.trace_dst_enables = (TISCI_BOARDCFG_TRACE_DST_UART0 |
                      TISCI_BOARDCFG_TRACE_DST_ITM |
.trace_src_enables = (TISCI_BOARDCFG_TRACE_SRC_PM |
                      TISCI_BOARDCFG_TRACE_SRC_RM |
                      TISCI_BOARDCFG_TRACE_SRC_SEC |
                      TISCI_BOARDCFG_TRACE_SRC_BASE |
                      TISCI_BOARDCFG_TRACE_SRC_USER |

In the case where rm_pm_hal runs on the MCU R5F, one needs to explicitly enable the trace and recompile the sciserver app. The steps are:

STEP 1: Uncomment the following lines in the file packages/ti/drv/sciclient/src/rm_pm_hal_build.mk


In order to enable trace on UART only do the following:


In order to enable trace on Memory only only do the following:


To enable both trace to memory and to UART do the following:


After this build the rm_pm_hal library and the sciserver_testapp using the command:

make -j -s sciserver_testapp_freertos

Once the build is complete, copy the sciserver_testapp_freertos_mcu1_0_release.rprc from pdk/packages/ti/binary/sciserver_testapp_freertos/bin/<soc>/ to pdk/packages/drv/sciclient/tools/ccsLoadDmsc/<soc>/.

Build the application of your interest to include the sciserver_testapp_freertos_mcu1_0_release.rprc. Note this happens automatically when building the app with PDK.

  • Capture the System firmware logs from the WKUP_USART0.
  • Get the parsed logs from sciclient/soc/sysfw/binaries/scripts/sysfw_trace_parser.py
usage: python3 ./sysfw_trace_parser.py [-h] (-l LOG_FILE | -d SERIAL_PORT)
                            (-o OUTPUT_FILE | -O) [-t] [-r RULES_FILE]

System Firmware Log Parse utility URL: http://software-

Required arguments - Choose one of the inputs:
-l LOG_FILE, --log_file LOG_FILE
                        Log File provided as input (default: None)
-d SERIAL_PORT, --serial_port SERIAL_PORT
                        Provide Device as input: Requires pyserial package
                        installed: See https://pyserial.readthedocs.io/
                        (default: None)

Required arguments - Choose one of the outputs:
-o OUTPUT_FILE, --output_file OUTPUT_FILE
                        Parse out the output to a file (default: None)
-O, --output_console  Log File to parse and report results to console
                        (default: False)

optional arguments:
-h, --help            show this help message and exit
-t, --time_stamp_relative
                        Add TimeStamp to output in relative milliseconds(this
                        is approximation ONLY) (default: False)
-r RULES_FILE, --rules_file RULES_FILE
                        Alternate Rules file (default: ./sysfw_trace_rules.json)
-Pm, --print_match_only
                        Print just decoded data, (default: False)

4.13.4. SBL loading of applications + Sciclient/Sciserver careabouts

When running PDK applications, the SBL will load the binaries corresponding to the application core which has the appropriate images in the AppImage file in SD Card, or flashed in OSPI, or sent via UART. In the case of MCU1_0 applications, the AppImage should contain the binary corresponding to the MCU application the developer has built along with the sciclient_direct, sciserver, rm_pm_hal libraries.

In the case of non MCU1_0 applications, in case the developer has no application running on MCU1_0, they must load the sciserver_testapp on the MCU1_0 core. If they have an application running on the MCU1_0, they must integrate the sciclient_direct, sciserver, rm_pm_hal libraries and also call the set of APIs from their MCU1_0 app. In summary, an MCU1_0 application is mandatory with an OS running when there are multiple cores.

In the PDK examples, the makefile is setup to always include the MCU1_0 sciserver_testapp_freertos_mcu1_0_release.rprc image in the Appimage if the MCU1_0 app is not present.

SBL by itself links the sciclient_direct and the rm_pm_hal libraries to be able to initialize the system.

The TI Foundational Security (TIFS) security code loading to the DMSC remains the same as it was before. API calls to the processor boot and security services remain the same as what it was before.

4.13.5. API descriptions

The driver is split into 4 parts :

  • Sciclient Core : This has APIs for loading SYSFW ,initialization, de-initialization and SYSFW communication .These are defined in sciclient.h .
    • sciclient: This is the default library used for Sciclient functionalities.
    • sciclient_direct: For systems that support the HSM software stack, this library is used for MCU R5F applications (e.g. sciserver_testapp).
  • Sciclient Shim Layer : This thin layer abstracts the message requests and responses sent to SYSW for Power_management , Resource_management and Processor_BOOT_API_Interface which the user can use without worrying about the request and response structures used .
  • SCIServer: Support HSM applications. Run on MCU R5 core for J721E and J7200.
    • SCIServer Core : The APIs are defined in sciserver.h. The sciserver must run on an OS. Reference SCIServer RTOS implementation for your own OS.
    • SCIServer RTOS : This is SCIServer Core running on RTOS. The initialization API contains registering interrupts, creating semaphore handles, and creating tasks.
  • RM/PM HAL : This library has APIs for processing the Power_management and Resource_management messages. Sciclient Core

The following core APIs for Sciclient are declared in sciclient.h.

#include <ti/drv/sciclient/sciclient.h>

Firmware Load

This API loads SYSFW.The image must be loaded through a boot media for this API to succeed (Refer Build and Run). Hence, this is typically called by SBL. Load firmware call does not require Sciclient_init to be done before.

Defined in sciclient.h as Sciclient_loadFirmware.

Typical usage

static const uint32_t gSciclient_firmware[BINARY_FILE_SIZE_IN_BYTES / 4U] =SCICLIENT_FIRMWARE;

Sciclient initialization

This API is called once for registering interrupts and creating semaphore handles to be able to talk to the firmware. The application should assume that the firmware is pre-loaded while calling this API. The firmware should have been loaded either via GEL or via the SBL (refer Sciclient_loadFirmware ) prior to the application calling this.

The API Sciclient_init takes a pointer to Sciclient_ConfigPrms_t as input.

  • The parameter opModeFlag allows 2 operation modes for Sciclient_service :

    opModeFlag Description


Defined in sciclient.h as **Sciclient_init**.


- This API provides a software initialization for the driver. Any application using Sciclient must call this API.

Typical usage

Sciclient_ConfigPrms_t        config =

SYSFW communication

This API allows communicating with the System firmware which can be called to perform various functions in the system. Core Sciclient function for transmitting payload and recieving the response. The caller is expected to allocate memory for the input request parameter Sciclient_ReqPrm_t . This involves setting the message type being communicated to the firmware, the response flags, populate the payload of the message based on the inputs in the files located at include/tisci/ . Since the payload in considered a stream of bytes in this API, the caller should also populate the size of this stream in reqPayloadSize. The timeout is used to determine for what amount of iterations the API would wait for their operation to complete.

To make sure the response is captured correctly the caller should also allocate the space for Sciclient_RespPrm_t parameters. The caller should populate the pointer to the pRespPayload and the size respPayloadSize. The API would populate the response flags to indicate any firmware specific errors and also populate the memory pointed by pRespPayload till the size given in respPayloadSize.

Defined in sciclient.h as **Sciclient_service** .

Typical usage

const Sciclient_ReqPrm_t      reqPrm =

struct tisci_msg_version_resp response;
Sciclient_RespPrm_t           respPrm =
    (uint8_t *) &response,
    sizeof (response)
status = Sciclient_init(&config);
status = Sciclient_service(&reqPrm, &respPrm);

Sciclient de-initialization

De-initialization of sciclient. This de-initialization is specific to the application. It only de-initializes the semaphores, interrupts etc. which are initialized using Sciclient_init . It does not de-initialize the system firmware.

Defined in sciclient.h as **Sciclient_deinit** .

Typical usage


Board configuration

One time board configuration needs to be done from R5 for rm,pm and security to communicate with SYSFW. It is normally done by SBL, so user doesn’t need to call these APIs.

User needs to define a section ”.boardcfg_data” in the linker file for the default configuration (NULL pointer to Sciclient_BoardCfgPrms_t is passed to the APIs), which needs to be present in OCMRAM . If user provides custom board_cfg, then the data must be present on OCMRAM.

Board configuration structure is defined in include/V0/sciclient_boardcfg.h as Sciclient_BoardCfgPrms_t.

Typical usage

status = Sciclient_boardCfg(NULL);
if (CSL_PASS == status)
    status = Sciclient_boardCfgPm(NULL) +
            Sciclient_boardCfgRm(NULL) +
            Sciclient_boardCfgSec(NULL) ;
} Sciclient Shim Layer

Power management

The APIs in include/sciclient_pm.h provide declarations of Sciclient APIs for power management of the SOC .

Resource management

The APIs in include/sciclient_rm.h provide declarations of Sciclient APIs for resource management of the SOC .

Processor BOOT API Interface

The APIs in include/sciclient_procboot.h provide declarations of Sciclient APIs for processor boot and control.

APIs are divided into the following two sets

  • Book keeping APIs - Meant to control access to allow a reasonable usage scenario of processors.
  • Processor Control APIs - Meant to be the actual Processor Corecontrols. SCIServer Core

The following core APIs for SCIServer are declared in sciserver.h.

#include <ti/drv/sciclient/sciserver.h>

SCIServer initialization

This API configures the state machine in the sciserver.

Typical usage

Sciserver_CfgPrms_t prms;

SCIServer de-initialization

This API de-initializes the state machine in the sciserver.

Typical usage


SCIServer process task

This API is the core function that processes messages sent to the SCIserver. It processes the power management and resource mangement messages, and it performs message forwarding for processor boot control or firewall configuration messages.

The API Sciserver_processtask takes a pointer to Sciserver_taskData as input.


- This API serves as a building block for the SCIServer running on non-TI-RTOS.
- Reference Sciserver_tirtosInit() on how this API is used.

Typical usage

void Sciserver_UserMsgTask(void *arg0)
    Sciserver_taskData *utd = (Sciserver_taskData *) arg0;
        Sciserver_processtask (utd);
        <Enable interrupt that calls Semaphore_post(semHandle[utd->semaphore_id])>
} SCIServer RTOS


Some APIs/Files are named as sciserver_tirtos**, but it actually supports FreeRTOS too. The naming is misleading, but the name is not changed due to compatibility issues.

The following core APIs for SCIServer are declared in sciserver_tirtos.h.

#include <ti/drv/sciclient/sciserver_tirtos.h>

SCIServer initialization in RTOS

This API is called once to initialize the sciserver, register interrupts, create semaphore handles, and create tasks in the RTOS. All OS related settings are configured and the SCIServer is ready for the following:

  • Process power management and resource management messages from secure and non-secure hosts. Handled by RM/PM HAL .
  • Forward non-secure host requests to DMSC to set the processor boot control or firewall configuration for safety applications.
  • Forward response recieved from DMSC to non-secure hosts for the above forwarded messages.

The API Sciserver_tirtosInit takes a pointer to Sciserver_TirtosCfgPrms_t as input.

  • The parameter taskPriority defines the priority of the high and low priority tasks.
  • The task priority defaults to 1 for low priority task and 3 for high priority task. The application developer may change the priority for those tasks, especially if additional applications are running with SCIServer on the same core(mcu1_0). Make sure that the SCIServer tasks are not starved by other applications threads.


- RTOS use case only. It can serve as a reference for SCIServer on non-RTOS.
- This API calls Sciserver_init and Sciserver_processtask underneath

Typical usage

Sciserver_TirtosCfgPrms_t appPrms;

SCIServer de-initialization in RTOS

De-initialization of SCIServer. It also de-initializes the semaphores, interrupts etc. which are initialized using Sciserver_tirtosInit . It does not de-initialize the system firmware.

Typical usage

Sciserver_tirtosDeinit(); RM/PM HAL

This library runs on the MCU R5F core. It contains the implementation of RM and PM message processing. When the SCIServer determines a message’s type belongs to RM or RM, this library’s functions are invoked to perform the message processing. Order of Functions to Call for Sciserver

The typical set of APIs to be called by the application are given in the example file: pdk_<soc>_<version>/packages/ti/drv/sciclient/examples/sciserver_testapp/sciserver_testapp_main.c.

The sequence is explained here for reference:

  1. Sciclient initialization parameters are required for the Sciclient direct interface for MCU1_0 applications.
Sciclient_ConfigPrms_t clientPrms;
  1. Sciserver initialization parameters are required for the Sciserver RTOS based applications. Note for other OSes the appPrms will be corresponding to your own implementation of the sciserver_tirtos.c file.
Sciserver_TirtosCfgPrms_t appPrms;
  1. The first API that needs to be called for initializing the default configuration of the Sciclient and Sciserver is as given below. If this step passes, then the code must proceed to read the board configuration left behind by the SBL.

    By default the Sciserver task is kept at a task priority of 3 - High priority task and 1 - Low priority task. Refer pdk_<soc>_<version>/packages/ti/drv/sciclient/sciserver_tirtos.h One can change this value after the default initialization.

ret = Sciclient_configPrmsInit(&clientPrms);
ret = Sciserver_tirtosInitPrms_Init(&appPrms);
  1. The Sciclient_boardCfgParseHeader should then be called to parse the content left behind by the SPL/SBL and populate the address for board configurations for the RM/PM services. To know more about the Board configurations which TISCI needs please refer TISCI documentation..
#define SCISERVER_COMMON_X509_HEADER_ADDR (0x41cffb00)

ret = Sciclient_boardCfgParseHeader(
    &clientPrms.inPmPrms, &clientPrms.inRmPrms);
  1. The Init APIs should then be called to initialize the Sciclient and also perform the board configuration for RM and PM. The Sciserver_tirtosInit will set up the Tasks and HWIs needed for the servicing of non-secure messsages for RM and PM.
ret = Sciclient_init(&clientPrms);
ret = Sciserver_tirtosInit(&appPrms);
  1. After OS_start is called the Sciserver task would start.

For other cores, post this point the Sciserver on MCU1_0 will be ready to recieve and service messages. This can be checked from other cores by requesting for a get version on a non-secure Secure Proxy queue. The Get version message can be sent via TISCI_MSG_VERSION message.

4.13.6. Board configuration passing between SPL/SBL and MCU1_0 applications

SBL/SPL reads the board configuration from the boot media. The SCISERVER also requires the board configuration data for setting up the RM and PM services. Hence the SPL/SBL needs to keep the board configuration data in an aligned memory location with a header which the SCISERVER can later read, check the header and if it finds the header, parse the board configuration and process it.

The main responsibilities for the SBL/SPL are:

  1. Read the board configuration from the boot media.
  2. Copy or store the configuration using the format shown Here
  3. Run the TIFS board configurations (Common board config and Security Board configuration)

The main responsibilities of the SCISERVER APP are:

  1. Look for the magic word in the aligned address.
  2. If the magic word matches, board configuration data is present and then read the board configuration address offsets
  3. Configure the config parameters for Sciclient init for the board configuration.

The flow is as below:


Fig. 4.5 Board configuration passing from SBL/SPL to SCISERVER

The format for the structure which is passed between SBL/SPL and the SCISERVER has 3 parts:

  1. Common Header
  2. Board Configuration Header
  3. Board Configuration

The Common Header format is as below:


Fig. 4.6 Common Header Format

The Board configuration Header format is as below:


Fig. 4.7 Board Configuration Header Format

The code version of the same formats are as below:

 * Length of magic word for extended boot info table.
 * Minimum number of components that should be present in combined image.
 * Max number of components in extended boot info table.
 * Base address where ROM loads the extended boot info.
 * Component type corresponding to SYSFW data blob.
#define EXTBOOT_X509_MAGIC_WORD_LEN             (8)
#define EXTBOOT_X509_MIN_COMPONENTS             (3)
#define EXTBOOT_X509_MAX_COMPONENTS             (8)
#define EXTBOOT_X509_COMPTYPE_SYSFW_DATA        (0x12)

 * Magic word that specifies whether combined image is being used.
const u8 EXTBOOT_X509_MAGIC_WORD[EXTBOOT_X509_MAGIC_WORD_LEN] = { 'E', 'X', 'T', 'B', 'O', 'O', 'T', 0 };

 * \brief Component information populated by ROM. The combined image has multiple components.
 *                  ROM populates this information for each component.
 * \param comp_type Type of component
 * \param boot_core Core that loads or runs image
 * \param comp_opts Component options. Not used for now.
 * \param dest_addr Image destination address
 * \param comp_size Size of the component in bytes
struct extboot_x509_comp {
    u32 comp_type;
    u32 boot_core;
    u32 comp_opts;
    u64 dest_addr;
    u32 comp_size;

 * \brief Component information table populated by ROM.
 * \param magic_word Magic word for extended boot
 * \param num_comps Number of components present in extended boot info table
 * \param comps Information for each component
struct extboot_x509_table {
    u8              magic_word[EXTBOOT_X509_MAGIC_WORD_LEN];
    u32             num_comps;
    struct extboot_x509_comp    comps[EXTBOOT_X509_MAX_COMPONENTS];

 * \brief Describes the board config data
 * \param type Type of board config data. This should map to corresponding TISCI
 *      message type. For example, a PM boardcfg should have a descriptor
 * \param offset Offset for board config data from beginning of SYSFW data binary blob
 * \param size Size of board config data
 * \param devgrp Device group to be used by SYSFW for automatic board config processing
 * \param reserved Reserved field. Not to be used.
struct extboot_boardcfg_desc {
    u16 type;
    u16 offset;
    u16 size;
    u8  devgrp;
    u8  reserved;
} __attribute__((__packed__));

 * Number of boardcfg data in SYSFW data blob.
#define EXTBOOT_BOARDCFG_NUM_DESCS              (4)

 * \brief Boardcfg descriptor table provided by system integrator
 * \param num_elems Number of elements in board config table.
 * \param sw_rev SW revision populated by system integrator.
 * \param descs Array of board config descriptors
struct boardcfg_desc_table {
    u8              num_elems;
    u8              sw_rev;
    struct extboot_boardcfg_desc    descs[EXTBOOT_BOARDCFG_NUM_DESCS];
} __attribute__((__packed__));

The memory map for where the board configuration is left behind is as below:

Address Size Purpose Persistence
0x41C0_0000 512 KB Hold SPL/SBL Image Only during SPL/SBL execution. Can be claimed once MCU1_0 app is jumped to.
0x41C8_0000 8 KB Hold the Board configuration passed between SPL/SBL and SCISERVER_APP Can be claimed once MCU1_0 app executes Sciclient_init on MCU1_0
0x41C8_2000 502 KB Loadable application on OCMS RAM (including SCISERVER) Through out MCU1_0 app execution
0x41cf_fb00 ~1.2 KB Common header used in ROM combined image format as well. Can be claimed once MCU1_0 app executes Sciclient_init on MCU1_0


For devices on which the ROM supports the combined image format support where a single X509 certificate can be used to load the TIFS and the MCU1_0 SPL, the ROM leaves a header with the details of which image went where. The 0x41cf_fb00 is the address where this table is left. The design of the table for the common header and ROM left behind table is the same to make sure any subsequent apps see the same format accross J721E, J7200 and future devices.

The choice of 0x41C8_0000 is to make sure multiple holes are not present in the loadable sections of the application.


Please make sure to use the board configuration in the MCU SRAM memory left behind by the SPL/SBL. Any other board configuration built into the MCU1_0 App should not be used. Also, if the board configuration is kept in any other memory apart from MCU SRAM the TIFS will crash. The TIFS is needed to authenticate the board configuration in HS devices. TIFS also uses the RM board configuration to set up channelized firewalls.

4.13.7. IRQ Sources and Destinations

The following tables give information regarding the IRQ sources and destinations used as part of the Sciclient_rmIrqSet function and Sciclient_rmIrqRelease function.