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.