Detailed Description

Hardware Interrupt module for the RTOS Porting Interface.

============================================================================

The HwiP_disable()/HwiP_restore() APIs can be called recursively. The order of the HwiP_restore() calls, must be in reversed order. For example:

uintptr_t key1, key2;
key1 = HwiP_disable();
key2 = HwiP_disable();
HwiP_restore(key2);
HwiP_restore(key1);

Cross-platform Considerations

The following sections highlight some important items to consider when using the HwiP DPL. Due to the nature and intention of different operating systems, the HwiP DPL implementation may differ depending on the underlying platform and operating system.

Arm Cortex-M Interrupt Priorities

On Arm Cortex-M platforms, the highest logical interrupt priority has the lowest numerical value. That is, 0 is the highest interrupt priority (interrupt level 0 has the highest urgency). The number of interrupt priorities is given by the number of interrupt priority bits implemented, which is vendor-specific.

For example:

Device Family	Architecture	Priority Bits	Priority Levels
CC23X0	Armv6-m	2	4 (0-3)
CC13X2_CC26X2	Armv7-m	3	8 (0-7)
CC13X4_CC26X4	Armv8-m	3	8 (0-7)
CC27XX	Armv8-m	4	16 (0-15)

On Arm Cortex-M platforms, interrupt priority values are stored in the most significant bits of the 8-bit interrupt priority registers. For example, with 3 interrupt priority bits implemented, interrupt priority level 2 (0b010) is represented in the interrupt priority registers as 0b010 << (8-3) = 0x40. This is automatically handled by SysConfig, but may cause some confusion, for example, when inspecting the raw value of the HwiP_Params.priority field or the Cortex-M interrupt priority registers.

See http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html for more details.

Arm Cortex-M devices may support 2 methods for masking interrupts

PRIMASK disables all interrupt levels indiscriminately (with the exception of non-maskable interrupts).
BASEPRI disables interrupts with priority equal to or lower than a certain level. Software can set BASEPRI to a priority level between 1 (second highest priority) and the maximum supported priority level (lowest priority). This means that interrupt priority level 0 cannot be masked using BASEPRI.

The table gives an overview of what interrupt masking controls the different Arm platforms support:

Architecture	PRIMASK	BASEPRI
Armv6-m	Yes	No
Armv7-m	Yes	Yes
Armv8-m	Yes	Yes

FreeRTOS

On Cortex-M platforms that support BASEPRI, the FreeRTOS kernel does not completely disable interrupts even inside critical sections. This is achieved by these FreeRTOS configurations:

configMAX_SYSCALL_INTERRUPT_PRIORITY defines the highest logical priority at which FreeRTOS kernel API calls can be made.
configKERNEL_INTERRUPT_PRIORITY sets the priority of the FreeRTOS kernel itself, usually the lowest logical priority possible.

This permits a fully nested model where higher-priority interrupts can preempt lower-priority ones. However, interrupts that require FreeRTOS API calls must adhere to the configMAX_SYSCALL_INTERRUPT_PRIORITY limit to avoid corrupting kernel data.

See https://www.freertos.org/a00110.html#kernel_priority for more details.

HwiP_disable(): sets BASEPRI to configMAX_SYSCALL_INTERRUPT_PRIORITY. Returns original BASEPRI.
HwiP_restore() sets BASEPRI to 0 (no interrupts are masked).

TI-RTOS

TI-RTOS behaves similar to FreeRTOS, meaning that on Cortex-M platforms that support BASEPRI, the TI-RTOS kernel does not completely disable interrupts even inside critical sections.

HwiP_disable() sets BASEPRI to Hwi_disablePriority. Returns original BASEPRI.
HwiP_restore() sets BASEPRI to the provided argument value.

See TI-RTOS Hwi documentation for more details.

NoRTOS

HwiP_disable() disables all interrupt levels indiscriminately.
HwiP_restore() globally enables all interrupts.

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for HwiP.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
union	HwiP_Struct
	HwiP structure. More...

struct	HwiP_Params
	Basic HwiP Parameters. More...

Macros
#define	HwiP_STRUCT_SIZE (28)
	Number of bytes greater than or equal to the size of any RTOS HwiP object. More...

Typedefs
typedef union HwiP_Struct	HwiP_Struct
	HwiP structure. More...

typedef void *	HwiP_Handle
	Opaque client reference to an instance of a HwiP. More...

typedef void(*	HwiP_Fxn) (uintptr_t arg)
	Prototype for the entry function for a hardware interrupt. More...

Enumerations
enum	HwiP_Status { HwiP_OK = 0, HwiP_FAILURE = -1 }
	Status codes for HwiP APIs. More...

Functions
HwiP_Handle	HwiP_construct (HwiP_Struct handle, int interruptNum, HwiP_Fxn hwiFxn, HwiP_Params params)
	Function to construct a hardware interrupt object. More...

void	HwiP_destruct (HwiP_Struct *handle)
	Function to destruct a hardware interrupt object. More...

void	HwiP_clearInterrupt (int interruptNum)
	Function to clear a single interrupt. More...

HwiP_Handle	HwiP_create (int interruptNum, HwiP_Fxn hwiFxn, HwiP_Params *params)
	Function to create an interrupt on CortexM devices. More...

void	HwiP_delete (HwiP_Handle handle)
	Function to delete an interrupt on CortexM devices. More...

uintptr_t	HwiP_disable (void)
	Function to disable interrupts to enter a critical region. More...

void	HwiP_enable (void)
	Function to enable interrupts. More...

void	HwiP_disableInterrupt (int interruptNum)
	Function to disable a single interrupt. More...

void	HwiP_enableInterrupt (int interruptNum)
	Function to enable a single interrupt. More...

bool	HwiP_inISR (void)
	Function to return a status based on whether it is in an interrupt context. More...

bool	HwiP_interruptsEnabled (void)
	Function to determine whether interrupts are currently enabled. More...

void	HwiP_Params_init (HwiP_Params *params)
	Initialize params structure to default values. More...

void	HwiP_plug (int interruptNum, void *fxn)
	Function to plug an interrupt vector. More...

void	HwiP_post (int interruptNum)
	Function to generate an interrupt. More...

void	HwiP_restore (uintptr_t key)
	Function to restore interrupts to exit a critical region. More...

void	HwiP_setFunc (HwiP_Handle handle, HwiP_Fxn fxn, uintptr_t arg)
	Function to overwrite HwiP function and arg. More...

void	HwiP_setPriority (int interruptNum, uint32_t priority)
	Function to set the priority of a hardware interrupt. More...

void	HwiP_dispatchInterrupt (int interruptNum)
	Function to call the HW ISR function registered by HwiP_construct() More...

Variables
int	HwiP_swiPIntNum
	Interrupt number posted by SwiP. More...

Macro Definition Documentation

§ HwiP_STRUCT_SIZE

#define HwiP_STRUCT_SIZE (28)

Number of bytes greater than or equal to the size of any RTOS HwiP object.

NoRTOS: 12 FreeRTOS: 12 BIOS 6.x: 28 BIOS 7.x: 20

Typedef Documentation

§ HwiP_Struct

typedef union HwiP_Struct HwiP_Struct

HwiP structure.

Opaque structure that should be large enough to hold any of the RTOS specific HwiP objects.

§ HwiP_Handle

typedef void* HwiP_Handle

Opaque client reference to an instance of a HwiP.

A HwiP_Handle returned from the HwiP_create() represents that instance.

§ HwiP_Fxn

typedef void(* HwiP_Fxn) (uintptr_t arg)

Prototype for the entry function for a hardware interrupt.

Enumeration Type Documentation

§ HwiP_Status

enum HwiP_Status

Status codes for HwiP APIs.

Enumerator
HwiP_OK
HwiP_FAILURE

Function Documentation

§ HwiP_construct()

HwiP_Handle HwiP_construct	(	HwiP_Struct *	handle,
		int	interruptNum,
		HwiP_Fxn	hwiFxn,
		HwiP_Params *	params
	)

Function to construct a hardware interrupt object.

Parameters

handle	Pointer to HwiP_Struct object.
interruptNum	Interrupt Vector Id
hwiFxn	entry function of the hardware interrupt
params	Pointer to the instance configuration parameters. NULL denotes to use the default parameters. The HwiP default parameters are noted in HwiP_Params_init().

Returns: A HwiP_Handle on success or a NULL on an error

§ HwiP_destruct()

void HwiP_destruct ( HwiP_Struct * handle )

Function to destruct a hardware interrupt object.

Parameters

handle Pointer to a HwiP_Struct object that was passed to HwiP_construct().

Returns

§ HwiP_clearInterrupt()

void HwiP_clearInterrupt ( int interruptNum )

Function to clear a single interrupt.

Parameters

interruptNum interrupt number to clear

§ HwiP_create()

HwiP_Handle HwiP_create	(	int	interruptNum,
		HwiP_Fxn	hwiFxn,
		HwiP_Params *	params
	)

Function to create an interrupt on CortexM devices.

Note: This function may not be available on all implementations

Parameters

interruptNum	Interrupt Vector Id
hwiFxn	entry function of the hardware interrupt
params	Pointer to the instance configuration parameters. NULL denotes to use the default parameters. The HwiP default parameters are noted in HwiP_Params_init().

Returns: A HwiP_Handle on success or a NULL on an error

§ HwiP_delete()

void HwiP_delete ( HwiP_Handle handle )

Function to delete an interrupt on CortexM devices.

Note: This function may not be available on all implementations

Parameters

handle returned from the HwiP_create call

Returns

§ HwiP_disable()

uintptr_t HwiP_disable ( void )

Function to disable interrupts to enter a critical region.

This function can be called multiple times, but must unwound in the reverse order. For example

uintptr_t key1, key2;
key1 = HwiP_disable();
key2 = HwiP_disable();
HwiP_restore(key2);
HwiP_restore(key1);

Returns: A key that must be passed to HwiP_restore() to re-enable interrupts.

§ HwiP_enable()

void HwiP_enable ( void )

Function to enable interrupts.

§ HwiP_disableInterrupt()

void HwiP_disableInterrupt ( int interruptNum )

Function to disable a single interrupt.

Parameters

interruptNum interrupt number to disable

§ HwiP_enableInterrupt()

void HwiP_enableInterrupt ( int interruptNum )

Function to enable a single interrupt.

Parameters

interruptNum interrupt number to enable

§ HwiP_inISR()

bool HwiP_inISR ( void )

Function to return a status based on whether it is in an interrupt context.

Returns: A status: indicating whether the function was called in an ISR (true) or at thread level (false).

§ HwiP_interruptsEnabled()

bool HwiP_interruptsEnabled ( void )

Function to determine whether interrupts are currently enabled.

Returns

Current state of interrupts.

true Interrupts are currently enabled.
false Interrupts are currently disabled.

§ HwiP_Params_init()

void HwiP_Params_init ( HwiP_Params * params )

Initialize params structure to default values.

The default parameters are:

arg: 0
priority: ~0
enableInt: true

Parameters

params Pointer to the instance configuration parameters.

§ HwiP_plug()

void HwiP_plug	(	int	interruptNum,
		void *	fxn
	)

Function to plug an interrupt vector.

Parameters

interruptNum	ID of interrupt to plug
fxn	ISR that services plugged interrupt

§ HwiP_post()

void HwiP_post ( int interruptNum )

Function to generate an interrupt.

Parameters

interruptNum ID of interrupt to generate

§ HwiP_restore()

void HwiP_restore ( uintptr_t key )

Function to restore interrupts to exit a critical region.

Parameters

key	return from HwiP_disable

§ HwiP_setFunc()

void HwiP_setFunc	(	HwiP_Handle	handle,
		HwiP_Fxn	fxn,
		uintptr_t	arg
	)

Function to overwrite HwiP function and arg.

Parameters

handle	Handle returned from the HwiP_create() or HwiP_construct() call
fxn	pointer to ISR function
arg	argument to ISR function

§ HwiP_setPriority()

void HwiP_setPriority	(	int	interruptNum,
		uint32_t	priority
	)

Function to set the priority of a hardware interrupt.

Parameters

interruptNum	id of the interrupt to change
priority	new priority

§ HwiP_dispatchInterrupt()

void HwiP_dispatchInterrupt ( int interruptNum )

Function to call the HW ISR function registered by HwiP_construct()

Note: This function may not be available on all implementations

Parameters

interruptNum Interrupt Vector Id

Variable Documentation

§ HwiP_swiPIntNum

int HwiP_swiPIntNum

Interrupt number posted by SwiP.

The SwiP module needs its scheduler to run at key points in SwiP processing. This is accomplished via an interrupt that is configured at the lowest possible interrupt priority level and is plugged with the SwiP scheduler. This interrupt must be the only interrupt at that lowest priority. SwiP will post this interrupt whenever its scheduler needs to run.

The default value for your device should suffice, but if a different interrupt is needed to be used for SwiP scheduling then HwiP_swiPIntNum can be assigned with this interrupt (early on, before HwiPs are created and before any SwiP gets posted).

Detailed Description

Cross-platform Considerations

Arm Cortex-M Interrupt Priorities

FreeRTOS

TI-RTOS

NoRTOS

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ HwiP_STRUCT_SIZE

Typedef Documentation

§ HwiP_Struct

§ HwiP_Handle

§ HwiP_Fxn

Enumeration Type Documentation

§ HwiP_Status

Function Documentation

§ HwiP_construct()

§ HwiP_destruct()

§ HwiP_clearInterrupt()

§ HwiP_create()

§ HwiP_delete()

§ HwiP_disable()

§ HwiP_enable()

§ HwiP_disableInterrupt()

§ HwiP_enableInterrupt()

§ HwiP_inISR()

§ HwiP_interruptsEnabled()

§ HwiP_Params_init()

§ HwiP_plug()

§ HwiP_post()

§ HwiP_restore()

§ HwiP_setFunc()

§ HwiP_setPriority()

§ HwiP_dispatchInterrupt()

Variable Documentation

§ HwiP_swiPIntNum