SCIF Operating System Abstraction Layer

Introduction

The Sensor Controller Studio Interface (SCIF) driver uses a thin operating system abstraction layer (OSAL) to allow support for multiple operating systems, such as “TI-RTOS”. This document provides background information about the OSAL, and instructions for creating your own OSAL for the SCIF driver.

The OSAL provides a set of functions for internal use by the SCIF driver, which allows it to interface seamlessly with the real-time operating system or other run-time framework running on the System CPU. The OSAL also implements other operating system dependent functions that must be called by the application.

The following operating system abstractions are included in the Sensor Controller Studio installation:

  • TI-RTOS : Uses the TI-RTOS API directly.
  • TI Driver Porting Layer : Uses the TI SimpleLink SDK Driver Porting Layer (DPL) to interface with the underlying operating system, for example TI-RTOS.
  • None : Uses direct register access and DriverLib API.

Operating system is selected per Sensor Controller project in the Project Panel .

OSAL Files

There are three to seven files for each supported operating system:

  • One OSAL definition XML file, called scif_osal_<os_name>.osd
  • One, two or three C header file(s), typically called scif_osal_<os_name><chip_family>.h
    • Due to hardware differences, two or three instances may be needed in order to support the CC13x0/CC26x0, CC13x2/CC26x2 and CC13x4/CC26x4 chip families.
    • In the SCIF driver output, the C header file is typically called scif_osal<os_name>.h .
  • One, two or three C source file(s), typically called scif_osal_<os_name><chip_family>.c
    • Due to hardware differences, two or three instances are needed in order to support the CC13x0/CC26x0, CC13x2/CC26x2 and CC13x4/CC26x4 chip families.
    • In the SCIF driver output, the C header file is typically called scif_osal<os_name>.h .

The <os_name> is the operating system name, using lower-case letters, numbers and underscores, for example ti_rtos for TI-RTOS, or ti_dpl for TI Driver Porting Layer.

The <chip_family> indicates which chip family (or families) are supported. The following naming convention is used:

  • __0 if the file supports CC13x0/CC26x0 devices only, for example scif_osal_tirtos__0.c
  • __1 if the file supports CC13x2/CC26x2 devices only, for example scif_osal_none__1.c
  • __2 if the file supports CC13x4/CC26x4 devices only, for example scif_osal_none__2.c
  • __1_2 if the file supports both CC13x2/CC26x2 and CC13x4/CC26x4 devices, for example scif_osal_tirtos__1_2.c
  • The field is not included if it supports all chip families, for example scif_osal_tirtos.h

File Locations

Installer-provided OSAL definitions (and associated C header/source files) are located in the osal_defs installation subdirectory (typically C:\Program Files (x86)\Texas Instruments\Sensor Controller Studio\osal_defs ). This directory also contains the OSAL definition XML document type definition (DTD) file, osal_def.dtd .

Custom (user-specified) OSAL definitions (and associated C header/source files) are by default located under the <My Documents>/Texas Instruments/Sensor Controller Studio/osal_defs directory. The directory location can be changed in the Preferences Panel .

The OSAL definiton files in these directories are loaded when Sensor Controller Studio is started. Note that Sensor Controller Studio will not start if there are incorrectly formatted OSAL definition files.

Chip Family Support

Installer-provided OSAL definitions support all chip families.

Custom (user-specified) OSAL definitions do not need to support all chip families. If an unsupported target chip is selected, an error message will occur during code generation.

Implementation Guide

This section describes how to implement your own OSAL for the SCIF driver. Please note that the SCIF driver supports the TI Driver Porting Layer (DPL) . If the DPL has already been ported to your operating system, there is no need to create an additional OSAL for the SCIF driver.

It is recommended to use an existing OSAL implementation as a starting point . Make sure that you select source (and header) file(s) that match your target chip family ( *__0.c/h for CC13x0/CC26x0, *__1.c/h for CC13x2/CC26x2 or CC13x4/CC26x4).

All installer-provided SCIF driver source code is documented using Doxygen syntax.

OSAL Definition File

There is one OSAL definition file for each supported operating system. The file specifies:

  • The operating system name
  • The C header and source files for each chip family. Each file tag specifies:
    • The file source, that is, the name of the file in the osal_defs directory
    • The file destination, that is, the name of the file in the generated SCIF driver

Example: TI-RTOS, with support for all chip families

<?xml version="1.0" encoding="ISO-8859-15"?>
<!DOCTYPE osal_def SYSTEM "osal_def.dtd"[]>
<osal_def name="TI-RTOS">

    <!-- CC13x0 / CC26x0 -->
    <file chip_family="0" src="scif_osal_tirtos.h"      dest="scif_osal_tirtos.h"/>
    <file chip_family="0" src="scif_osal_tirtos__0.c"   dest="scif_osal_tirtos.c"/>

    <!-- CC13x2 / CC26x2 -->
    <file chip_family="1" src="scif_osal_tirtos.h"      dest="scif_osal_tirtos.h"/>
    <file chip_family="1" src="scif_osal_tirtos__1_2.c" dest="scif_osal_tirtos.c"/>

    <!-- CC13x4 / CC26x4 -->
    <file chip_family="2" src="scif_osal_tirtos.h"      dest="scif_osal_tirtos.h"/>
    <file chip_family="2" src="scif_osal_tirtos__1_2.c" dest="scif_osal_tirtos.c"/>

</osal_def>

OSAL C Header File

The C header file contains:

  • Documentation
  • Function prototypes
  • Anything else that the OSAL must expose to the application

The application interface depends both on the operating system and on the chip family:

  • For some operating systems (for example TI-RTOS), the OSAL must be initialized. For operating systems “TI-RTOS” and “TI Driver Porting Layer” this is done by:

    void scifOsalInit(void);
    
  • Task ALERT and control READY interrupts must be communicated to the application. The installer-provided OSALs use callbacks, which must be configured through:

    void scifOsalRegisterCtrlReadyCallback(SCIF_VFPTR callback);
    void scifOsalRegisterTaskAlertCallback(SCIF_VFPTR callback);
    
  • For CC13x0/CC26x0 devices, software must enable access to the AUX domain before accessing the Sensor Controller. This is handled automatically by the TI Power driver. For operating system “None”, it is done by:

    void scifOsalEnableAuxDomainAccess(void);
    void scifOsalDisableAuxDomainAccess(void);
    

The following function prototypes must always be included:

void scifOsalEnableTaskAlertInt(void);
void scifOsalDisableTaskAlertInt(void);

OSAL C Source File

The C source file contains:

  • Mapping of control READY and task ALERT interrupts to System CPU interrupt numbers
  • Mapping of wake-up signals to the System CPU application
  • OSAL global variables, such as semaphore and hardware interrupt parameters, objects, handles, and so on
  • Internal functions, used by the SCIF driver framework
  • External functions, exposed to the application

The C source file is included directly in scif_framework.c . This means that internal OSAL functionality does not need to be exposed to the application. It also means that the file does not need to be compiled separately.

To prevent the C source file contents from being compiled twice, the contents of the file must be enclosed in the following “ifdef” ( SCIF_INCLUDE_OSAL_C_FILE is defined only in scif_framework.c ):

#ifdef SCIF_INCLUDE_OSAL_C_FILE

...

#endif

Interrupt Mapping

Interrupts are used to signalize whether the Sensor Controller task control interface is ready, and let the Sensor Controller alert the System CPU application.

The interrupt mapping is fixed, and is the same for CC13x0/CC26x0 and CC13x2/CC26x2 devices:

/// The READY interrupt is implemented using INT_AON_AUX_SWEV0
#define INT_SCIF_CTRL_READY     INT_AON_AUX_SWEV0
/// The ALERT interrupt is implemented using INT_AON_AUX_SWEV1
#define INT_SCIF_TASK_ALERT     INT_AON_AUX_SWEV1

Wake-Up Signal Mapping

The READY and ALERT interrupts do not wake up the System CPU from standby mode by themselves.

For CC13x0/CC26x0 there are 4 MCU domain wake-up events in total. One of these is reserved for the Sensor Controller, and is used for the ALERT interrupt:

/// MCU wakeup source to be used with the Sensor Controller task ALERT event, must not conflict with OS
#define OSAL_MCUWUSEL_WU_EV_S   AON_EVENT_MCUWUSEL_WU3_EV_S

For CC13x2/CC26x2 and CC13x4/CC26x4 there are 8 MCU domain wake-up events in total. This allows for wake-up both on ALERT and READY interrupt:

/// MCU wakeup source to be used with the Sensor Controller control READY event, must not conflict with OS
#define OSAL_CTRL_READY_MCUWUSEL_WU_EV_INDEX    6
/// MCU wakeup source to be used with the Sensor Controller task ALERT event, must not conflict with OS
#define OSAL_TASK_ALERT_MCUWUSEL_WU_EV_INDEX    7

Functions

The table below lists all functions with brief descriptions. For details, descriptions of parameters and return values, and examples, see the source code for the installer-provided OSALs:

Function Prototype Internal External Description
Task Control READY Interrupt
static void osalRegisterCtrlReadyInt(void) Yes  

Registers the READY interrupt.

This attaches osalCtrlReadyIsr() to INT_SCIF_CTRL_READY .

static void osalUnregisterCtrlReadyInt(void) Yes  

Unregisters the READY interrupt.

This detaches osalCtrlReadyIsr() from INT_SCIF_CTRL_READY .

static void osalEnableCtrlReadyInt(void) Yes   Enables the READY interrupt.
static void osalDisableCtrlReadyInt(void) Yes   Disables the READY interrupt.
static void osalClearCtrlReadyInt(void) Yes   Clears the READY interrupt.
Task ALERT Interrupt
static void osalRegisterTaskAlertInt(void) Yes  

Registers the ALERT interrupt.

This attaches osalTaskAlertIsr() to INT_SCIF_TASK_ALERT .

static void osalUnregisterTaskAlertInt(void) Yes  

Unregisters the ALERT interrupt.

This detaches osalTaskAlertIsr() from INT_SCIF_TASK_ALERT .

void scifOsalEnableTaskAlertInt(void) Yes Yes Enables the ALERT interrupt.
void scifOsalDisableTaskAlertInt(void) Yes Yes Disables the ALERT interrupt.
static void osalClearTaskAlertInt(void) Yes   Clears the ALERT interrupt.
Thread-Safe Operation
uint32_t scifOsalEnterCriticalSection(void) Yes*  

Enters a critical section.

* This function is also used by the SCIF driver setup.

void scifOsalLeaveCriticalSection(uint32_t key) Yes*  

Leaves a critical section.

The key is the value returned by scifOsalEnterCriticalSection() .

* This function is also used by the SCIF driver setup.

static bool osalLockCtrlTaskNbl(void) Yes  

Locks use of task control non-blocking functions.

The function returns whether the operation completed successfully.

static void osalUnlockCtrlTaskNbl(void) Yes  

Unlocks use of task control non-blocking functions.

The function will be called one time after a successful osalLockCtrlTaskNbl() .

Task Control Support
static SCIF_RESULT_T osalWaitOnCtrlReady(uint32_t timeoutUs) Yes  

Waits until the task control interface is ready/idle, or timeout occurs.

The timeoutUs is the value passed to scifWaitOnNbl() .

The function returns one of the following:

  • SCIF_SUCCESS if the operation succeeded
  • SCIF_NOT_READY if the timeout occurred
  • SCIF_ILLEGAL_OPERATION if the timeout value is invalid/out of range
Application Notifications
static void osalIndicateCtrlReady(void) Yes  

Called by osalCtrlReadyIsr() to notify the application.

This shall trigger a callback, generate a message/event etc.

static void osalIndicateTaskAlert(void) Yes  

Called by osalTaskAlertIsr() to notify the application.

This shall trigger a callback, generate a message/event etc.

Interrupt Service Routines
static void osalCtrlReadyIsr(*) Yes  

Sensor Controller READY interrupt service routine (ISR).

The ISR shall simply disable the interrupt, and then call osalIndicateCtrlReady() .

The interrupt is cleared and reenabled at the next task control request.

* Parameter(s) are operating system dependent.

static void osalTaskAlertIsr(*) Yes  

Sensor Controller ALERT interrupt service routine (ISR).

The ISR shall simply disable the interrupt, and then call osalIndicateTaskAlert() .

The interrupt source is cleared by scifClearAlertIntSource() .

The interrupt is reenabled by scifAckAlertEvents() .

* Parameter(s) are operating system dependent.

Examples of OSAL Specific Functions
void scifOsalInit(void)   Yes

Implemented for OSALs “TI-RTOS” and “TI Driver Porting Layer”.

Initializes the OSAL (called one time at application startup).

The function creates a binary semaphore used to wait on the task control interface.

void scifOsalEnableAuxDomainAccess(void)   Yes

Implemented for OSAL “None” for CC13x0/CC26x0.

Enables the AUX domain and Sensor Controller for access from the MCU domain.

void scifOsalDisableAuxDomainAccess(void)   Yes

Implemented for OSAL “None” for CC13x0/CC26x0.

Disables the AUX domain and Sensor Controller for access from the MCU domain.

void scifOsalRegisterCtrlReadyCallback(SCIF_VFPTR callback)   Yes

Implemented for all installer-provided OSALs.

Registers the task control READY interrupt callback.

void scifOsalRegisterTaskAlertCallback(SCIF_VFPTR callback)   Yes

Implemented for all installer-provided OSALs.

Registers the task ALERT interrupt callback.