4.17. SCICLIENT¶

4.17.1.1. Terms and Abbreviation¶

4.17.1.2. 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.17.2.1. 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 .

Note

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.

4.17.2.2. 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.

4.17.2.3. 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.

4.17.2.4. Load using CCS¶

Follow these steps to load the sciclient_ccs_init application through CCS

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

Modify for AM65xx:

//Path to GEL files
gelFilePath = "<Your CCS Path>/ccs_base/emulation/gel/AM65xEVM/"; ? GEL path location
// Path to the directory in which this file would be residing. CCS expects
// absolute paths to load the binaries.
thisJsFileDirectory = "PDK_INSTALL_DIR/packages/ti/drv/sciclient/tools/ccsLoadDmsc";

• 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:

load("SCICLIENT_PATH/tools/ccsLoadDmsc/<soc>/launch.js")

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

For AM65xx:

js:> load("SCICLIENT_PATH/tools/ccsLoadDmsc/am65xx/launch.js")
Connecting to DMSC_Cortex_M3_0!
Loading DMSC Firmware...
DMSC Firmware Load Done...
DMSC Firmware run starting now...
Connecting to MCU Cortex_R5_0!
Running the board configuration initialization from R5!
Initializing DDR!
Running DDR Memory Checks....
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.

4.17.2.5. 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.17.5.1. 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_loadFirmware(gSciclient_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
  Polling based	Invoked using SCICLIENT_SERVICE_OPERATION_MODE_POLLED
  Interrupt based	Invoked using SCICLIENT_SERVICE_OPERATION_MODE_INTERRUPT

Definition

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

Note

- This API provides a software initialization for the driver. Any application using Sciclient must call this API.
- SCICLIENT_SERVICE_OPERATION_MODE_INTERRUPT is not supported as of now.

Typical usage

Sciclient_ConfigPrms_t        config =
{
    SCICLIENT_SERVICE_OPERATION_MODE_POLLED,
    NULL
};
Sciclient_init(&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 =
{
    TISCI_MSG_VERSION,
    TISCI_MSG_FLAG_AOP,
    NULL,
    0,
    SCICLIENT_SERVICE_WAIT_FOREVER
};

struct tisci_msg_version_resp response;
Sciclient_RespPrm_t           respPrm =
{
    0,
    (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

Sciclient_deinit();

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) ;
}

4.17.5.2. 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.

4.17.5.3. 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_initPrms_Init(&prms);
Sciserver_init(&prms);

SCIServer de-initialization

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

Typical usage

Sciserver_deinit();

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.

Note

- 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;
    while(loopForever)
    {
        Semaphore_pend(semHandle[utd->semaphore_id]);
        Sciserver_processtask (utd);
        <Enable interrupt that calls Semaphore_post(semHandle[utd->semaphore_id])>
    }
}

4.17.5.4. SCIServer RTOS¶

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.

Note

- 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_tirtosInitPrms_Init(&appPrms);
Sciserver_tirtosInit(&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();

4.17.5.5. 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.

4.17.5.6. 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;

2. 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;

3. 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);

4. 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(
    (uint8_t *) SCISERVER_COMMON_X509_HEADER_ADDR,
    &clientPrms.inPmPrms, &clientPrms.inRmPrms);

5. 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);

6. After OS_start is called the Sciserver task would start.

OS_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.