AM62Px MCU+ SDK  10.01.00
SCICLIENT

Sciclient as a software block has multiple functional sub-blocks inside it, as shown in the below image:

Sciclient Sub-blocks

More details on the APIs provided on these layers can be found in the API section, linked towards the end of this page.

Generally speaking, the Sciclient driver provides API to communicate with the SYSFW using the TISCI protocol. As mentioned above, this would be for system level tasks like resource allocation, peripheral power on/off, peripheral clock setting, secure services and so on. The sciclient will be part of the application code running on each core.

Typical Sciclient Operation

The above image shows the operation for only one core, but the same thing happens for all the cores. SYSFW deals with all the requests coming from each of the cores.

Sciclient is mostly used by other drivers, like DMA, GPIO etc. Sciclient acts as an interface to the SYSFW for these drivers when they need say a resource like DMA channel, or configure an interrupt route. Below are the high level features supported by the driver:

Features Supported

  • Abstracted APIs for Power and Resource Management
  • APIs for Processor Boot including secure boot
  • APIs for configuring firewalls
  • Ability to change and re-build the board configuration data
  • Ability to sign the board configuration blobs for HS devices

SysConfig Features

Note
It is strongly recommend to use SysConfig where it is available instead of using direct SW API calls. This will help simplify the SW application and also catch common mistakes early in the development cycle.
  • There are no user programmable features for Sciclient SysConfig. However, adding any module makes the PowerClock_init() initialize the module power and clock. This is indirectly done using Sciclient APIs.

Features NOT Supported

NA

Important Usage Guidelines

  • Sciclient is mostly used by other peripheral drivers, and mostly not directly by an application. From an application point of view, major usage of Sciclient APIs would be to power on/off a module, set/get the clock of a module, etc.

Board Configuration Overview

SYSFW Board Config files in the sciclient driver is a SOC specific configuration data regarding the various system attributes controlled by the SYSFW. These include resources, power and clock, security etc. This configuration is sent to SYSFW during boot time. The default configuration is stored in source/drivers/sciclient/sciclient_defaultBoardCfg/am62px/

  • Default Boardcfg - sciclient_defaultBoardcfg.c
  • Resource Management BoardCfg - sciclient_defaultBoardCfg_rm.c
  • Power Management BoardCfg - sciclient_defaultBoardCfg_pm.c
  • Security BoardCfg - sciclient_defaultBoardCfg_security.c

The user can change the board configuration data based on their requirement and rebuild the board configuration by following the steps in SYSFW Board Config Generation.

Refer SYSFW board config documentation

Enforcing Processor Access Control List

  • The Access Control List(ACL) for a processor can be set using the Security Boardcfg data. There can be one primary host and three secondary hosts that can control a processor.
  • For example, set the WKUP-R5 core as primary host and A53 core as secondary host for ACL of MCU-R5 processor in the source/drivers/sciclient/sciclient_defaultBoardCfg/am62px/sciclient_defaultBoardCfg_security.c file.
.proc_acl_entries = {
{
.processor_id = SCICLIENT_PROC_ID_MCU_R5FSS0_CORE0,
.proc_access_master = TISCI_HOST_ID_WKUP_0_R5_0,
.proc_access_secondary = {TISCI_HOST_ID_A53_0, TISCI_HOST_ID_TIFS, TISCI_HOST_ID_TIFS},
},
/* set the remaining entries to zero */
{
0,
},
.
.
.
{
0,
},
},

Example Usage

Include the below file to access the APIs

#include <stdio.h>

Module Power ON Example

uint32_t moduleId = TISCI_DEV_TIMER0;
uint32_t moduleState, resetState, contextLossState;
/* Check the module status. Need not do power on if it's already ON */
&moduleState,
&resetState,
&contextLossState,
{
0x0U,
}
struct tisci_msg_rm_irq_set_req rmIrqReq;
struct tisci_msg_rm_irq_set_resp rmIrqResp;
/* Here we specify the core specific interrupt router number which we want to tie to the GPIO peripheral interrupt.
* In this example we are considering the MAIN GPIO instance, which 54 interrupt router outputs, out of which first 16
* are routed to all the R5 cores. Since these are shared resources, we will need to decide before hand which outputs will
* be used by which core, and specify this in the sciclient_defaultBoardCfg_rm.c file. In the current configuration,
* outputs 8 and 9 are allocated to R50-0 core, we can choose either of these to configure the interrupt configuration
*/
uint32_t gpioIntrNumber = CSLR_R5FSS0_CORE0_INTR_MAIN_GPIOMUX_INTROUTER0_OUTP_8;
/* Among the GPIOMUX_INTRRTR0 input pins, 0:86 comes from GPIO0 and 90:177 from GPIO1. We are configuring GPIO1 pin in this example, so
* we define a base interrupt number to be used later.
*/
uint32_t gpioIntrRtrInputGpio1_Base = 90;
/* The user interrupt button SW5 is tied to interrupt num 54 among the 88 GPIO interrupt lines of GPIO1 instance */
uint32_t gpioPushButtonPinNum = 54;
/* For setting the IRQ for GPIO using sciclient APIs, we need to populate
* a structure, tisci_msg_rm_irq_set_req instantiated above. The definition
* of this struct and details regarding the struct members can be found in
* the tisci_rm_irq.h.
*/
/* Initialize all flags to zero since we'll be setting only a few */
rmIrqReq.valid_params = 0U;
/* Our request has a destination id, so enable the flag for DST ID */
rmIrqReq.valid_params |= TISCI_MSG_VALUE_RM_DST_ID_VALID;
/* DST HOST IRQ is the output index of the interrupt router. We need to make sure this is also enabled as a valid param */
rmIrqReq.valid_params |= TISCI_MSG_VALUE_RM_DST_HOST_IRQ_VALID;
/* This is not a global event */
rmIrqReq.global_event = 0U;
/* Our interrupt source would be the GPIO peripheral. The source id has to be a device id recognizable by the SYSFW.
* The list of device IDs can be found in tisci_devices.h file under source/drivers/sciclient/include/tisci/am64x_am243x/.
* In GPIO case there are 3 possible options - TISCI_DEV_GPIO0, TISCI_DEV_GPIO1, TISCI_DEV_MCU_GPIO0. For input interrupt,
* we need to choose the TISCI_DEV_GPIO1
*/
rmIrqReq.src_id = TISCI_DEV_GPIO1;
/* This is the interrupt source index within the GPIO peripheral */
rmIrqReq.src_index = gpioIntrRtrInputGpio1_Base + GPIO_GET_BANK_INDEX(gpioPushButtonPinNum);
/* This is the destination of the interrupt, usually a CPU core. Here we choose the TISCI device ID for R5F0-0 core.
* For a different core, the corresponding TISCI device id has to be provided */
rmIrqReq.dst_id = TISCI_DEV_R5FSS0_CORE0;
/* This is the output index of the interrupt router. This depends on the core and board configuration */
rmIrqReq.dst_host_irq = gpioIntrNumber;
/* Rest of the struct members are unused for GPIO interrupt */
rmIrqReq.ia_id = 0U;
rmIrqReq.vint = 0U;
rmIrqReq.vint_status_bit_index = 0U;
rmIrqReq.secondary_host = TISCI_MSG_VALUE_RM_UNUSED_SECONDARY_HOST;
/* To set the interrupt we now invoke the Sciclient_rmIrqSet function which
* will find out the route to configure the interrupt and request SYSFW to
* grant the resource
*/
if(0 != Sciclient_rmIrqSet(&rmIrqReq, &rmIrqResp, SystemP_WAIT_FOREVER))
{
DebugP_log("[Error] Sciclient event config failed!!!\r\n");
}

API

APIs for SCI Client or SYSFW

sciclient.h
This file contains prototypes for APIs contained as a part of SCICLIENT as well as the structures of ...
Sciclient_pmSetModuleState
int32_t Sciclient_pmSetModuleState(uint32_t moduleId, uint32_t state, uint32_t reqFlag, uint32_t timeout)
Message to set the hardware block/module state This is used to request or release a device....
status
uint32_t status
Definition: tisci_lpm.h:1
tisci_msg_rm_irq_set_req
Configures peripherals within the interrupt subsystem according to the valid configuration provided....
Definition: tisci_rm_irq.h:202
TISCI_MSG_VALUE_RM_UNUSED_SECONDARY_HOST
#define TISCI_MSG_VALUE_RM_UNUSED_SECONDARY_HOST
Definition: tisci_rm_shared.h:75
SystemP_WAIT_FOREVER
#define SystemP_WAIT_FOREVER
Value to use when needing a timeout of infinity or wait forver until resource is available.
Definition: SystemP.h:83
Sciclient_rmIrqSet
int32_t Sciclient_rmIrqSet(const struct tisci_msg_rm_irq_set_req *req, const struct tisci_msg_rm_irq_set_resp *resp, uint32_t timeout)
Configures a peripheral to processor IRQ.
DebugP_log
#define DebugP_log(format,...)
Function to log a string to the enabled console.
Definition: DebugP.h:227
TISCI_MSG_VALUE_DEVICE_HW_STATE_OFF
#define TISCI_MSG_VALUE_DEVICE_HW_STATE_OFF
Definition: tisci_pm_device.h:99
TISCI_DEV_TIMER0
#define TISCI_DEV_TIMER0
Definition: tisci_devices.h:85
tisci_msg_rm_irq_set_resp
Response to setting a peripheral to processor interrupt.
Definition: tisci_rm_irq.h:222
TISCI_MSG_FLAG_AOP
#define TISCI_MSG_FLAG_AOP
Definition: tisci_protocol.h:75
Sciclient_pmGetModuleState
int32_t Sciclient_pmGetModuleState(uint32_t moduleId, uint32_t *moduleState, uint32_t *resetState, uint32_t *contextLossState, uint32_t timeout)
Message to get the hardware block/Module state. This request does not require the processing entity t...
SystemP_SUCCESS
#define SystemP_SUCCESS
Return status when the API execution was successful.
Definition: SystemP.h:56
TISCI_MSG_FLAG_DEVICE_EXCLUSIVE
#define TISCI_MSG_FLAG_DEVICE_EXCLUSIVE
Definition: tisci_pm_device.h:80
TISCI_MSG_VALUE_RM_DST_ID_VALID
#define TISCI_MSG_VALUE_RM_DST_ID_VALID
This file contains:
Definition: tisci_rm_irq.h:68
GPIO_GET_BANK_INDEX
#define GPIO_GET_BANK_INDEX(pinNum)
Returns the bank index based on pin number.
Definition: gpio/v0/gpio.h:126
TISCI_MSG_VALUE_DEVICE_SW_STATE_ON
#define TISCI_MSG_VALUE_DEVICE_SW_STATE_ON
Definition: tisci_pm_device.h:93
DebugP_assert
#define DebugP_assert(expression)
Function to call for assert check.
Definition: DebugP.h:175
TISCI_MSG_FLAG_DEVICE_RESET_ISO
#define TISCI_MSG_FLAG_DEVICE_RESET_ISO
Definition: tisci_pm_device.h:71
TISCI_MSG_VALUE_RM_DST_HOST_IRQ_VALID
#define TISCI_MSG_VALUE_RM_DST_HOST_IRQ_VALID
Definition: tisci_rm_irq.h:73
Sciclient_pmSetModuleRst
int32_t Sciclient_pmSetModuleRst(uint32_t moduleId, uint32_t resetBit, uint32_t timeout)
Set the device reset state. This is used to set or release various resets of the hardware block/modul...
FALSE
#define FALSE
Definition: csl_types.h:62
TISCI_DEV_GPIO1
#define TISCI_DEV_GPIO1
Definition: tisci_devices.h:114