GeMRTOS Trigger Resources: Event Handling Beyond Interrupts

In GeMRTOS multiprocessor RTOS applications on Altera FPGA platforms with Nios V processors, a trigger resource generalizes the concept of a hardware interrupt — allowing one or more tasks to be resumed or restarted when a specific event occurs. Unlike traditional interrupt service routines limited to a single handler, trigger resources let multiple independent tasks register against the same event and respond concurrently, each acting as its own ISR. Trigger resources can be associated with hardware interrupts or activated programmatically from task code.

What Are GeMRTOS Trigger Resources? #

A trigger resource is created with gu_TriggerCreate and optionally linked to a hardware interrupt. Tasks are registered with the trigger using gu_TriggerRegisterTask. When the trigger fires, all registered tasks that are in a waiting state are resumed or restarted simultaneously. The trigger resource is automatically disabled until every registered task transitions back to a waiting state — either by completing execution or by calling gu_TriggerWait explicitly. This mechanism prevents re-triggering while tasks are still processing the previous event.

Trigger resources can also be activated from task code using gu_TriggerRelease, enabling software-driven event signalling independent of hardware interrupts. The gu_TriggerEnable and gu_TriggerDisable functions control whether a trigger resource responds to activation requests.

Trigger Flexibility: Handling Complex Hardware Events #

Trigger resources overcome a key limitation of traditional interrupts. Consider a UART device: like many peripherals, a UART typically maps multiple internal events (input buffer full, output buffer empty) to a single hardware interrupt line. Normally, an ISR must inspect the device to determine which event fired and dispatch accordingly — adding complexity to the interrupt handler.

With trigger resources, a single trigger resource is associated with the UART interrupt. The registered task checks which event occurred. If the input buffer is full, the corresponding trigger resource is activated, resuming all tasks registered for reading. This approach allows an arbitrary number of independent reader and writer tasks to operate concurrently without interfering with each other.

If the output buffer is empty, a separate trigger resource associated with writing tasks is activated. Each trigger resource defines hook functions to enable and disable its specific sub-event (input buffer full, output buffer empty). This virtualizes and generalizes both internal and external events, eliminating complex dispatch logic from the interrupt handler and improving modularity.

Enable and Disable Hook Functions #

GeMRTOS allows hook functions to be executed when trigger resources are enabled or disabled. gu_TriggerEnableHook registers a callback to run before the trigger resource is enabled; gu_TriggerDisableHook registers a callback to run after the trigger resource is disabled. These hooks are typically used to configure or de-configure the hardware device associated with the trigger — for example, enabling or masking a specific interrupt source on a peripheral.

Trigger Resource API Reference #

Creating a Trigger Resource #

Create and initialize a new trigger resource with:

GS_RCB *gu_TriggerCreate(int irq_id, G_UINT64 ticks_to_wait);

The gu_TriggerCreate function allocates a new trigger resource and optionally associates it with a hardware interrupt.

Returns: pointer to the newly created trigger resource (GS_RCB). This pointer must be used in all subsequent trigger-related function calls.

Registering a Task with a Trigger Resource #

Associate a task with a trigger resource using:

G_UINT32 gu_TriggerRegisterTask(struct gs_tcb *ptcb, GS_RCB *ptrigger);

The gu_TriggerRegisterTask function registers a task so that it is resumed or restarted whenever the trigger resource fires.

Returns: G_TRUE if registration succeeded, G_FALSE otherwise.

Enabling a Trigger Resource #

Allow a trigger resource to respond to activation with:

G_UINT32 gu_TriggerEnable(GS_RCB *ptrigger);

The gu_TriggerEnable function enables the trigger resource, allowing it to be activated by either gu_TriggerRelease or its associated hardware interrupt.

Returns: G_TRUE if the operation succeeded.

Disabling a Trigger Resource #

Prevent a trigger resource from responding to activation with:

G_UINT32 gu_TriggerDisable(GS_RCB *ptrigger);

The gu_TriggerDisable function disables the trigger resource, preventing activation by gu_TriggerRelease or its associated hardware interrupt.

Returns: G_TRUE if the operation succeeded.

Waiting for a Trigger #

Place the current task into a waiting state for its trigger resource with:

GS_TRGStatus gu_TriggerWait(void);

The gu_TriggerWait function suspends the calling task until its registered trigger resource fires again. It can be called anywhere in task code. The same effect occurs automatically when a non-infinite-loop task completes execution. No parameters are required — the task waits for the trigger resource it was registered to.

Returns: G_TRUE when called from task code, G_FALSE when called from main code.

Releasing a Trigger Resource #

Activate a trigger resource from task code with:

GS_TRGStatus gu_TriggerRelease(GS_RCB *ptrigger);

The gu_TriggerRelease function activates the trigger resource. If the resource is enabled and all registered tasks are in a waiting state, those tasks are immediately resumed or restarted.

Returns: G_TRUE if the trigger was successfully activated, G_FALSE otherwise.

Enable Hook Function #

Register a callback to execute before a trigger resource is enabled:

G_UINT32 gu_TriggerEnableHook(GS_RCB *ptrigger, void (*code_callback)(void *), void *p_arg);

The gu_TriggerEnableHook function sets the hook called immediately before the trigger resource is enabled.

Returns: G_TRUE if the hook was successfully configured, G_FALSE otherwise.

Disable Hook Function #

Register a callback to execute after a trigger resource is disabled:

G_UINT32 gu_TriggerDisableHook(GS_RCB *ptrigger, void (*code_callback)(void *), void *p_arg);

The gu_TriggerDisableHook function sets the hook called immediately after the trigger resource is disabled.

Returns: G_TRUE if the hook was successfully configured, G_FALSE otherwise.

T_TRIGGER_RESOURCE Structure #

The T_TRIGGER_RESOURCE structure is embedded as the trigger field within a GS_RCB resource. Access its fields using: (GS_RCB *)->trigger.<field>

Setting the Timeout Behaviour #

Control what happens when a trigger does not fire within its timeout:

G_UINT32 gu_TriggerSetTimeoutType(GS_RCB *ptrigger, GS_TRGTimeOutType type);

Returns: G_TRUE if the operation succeeded.

gu_TriggerWait returns a GS_TRGStatus value, which is how a task
distinguishes a real trigger from a timeout.

Destroying a Trigger Resource #

Release a trigger resource and its timeout event back to the free pool:

G_UINT32 gu_TriggerDestroy(GS_RCB *ptrigger);

Returns: G_TRUE if the operation succeeded.

Key Takeaways #

• GeMRTOS trigger resources generalize hardware interrupts for Nios V FPGA RTOS — multiple independent tasks can register against a single event and each act as a dedicated ISR.
• A trigger is automatically disabled after firing and re-enabled only once all registered tasks return to their waiting state, preventing event re-entry before processing is complete.
• The UART example illustrates how a single hardware interrupt can drive multiple independent trigger resources — one per sub-event — eliminating complex dispatch logic from the ISR.
• Enable/disable hook functions (gu_TriggerEnableHook / gu_TriggerDisableHook) allow peripheral-specific setup and teardown to run automatically around each trigger activation cycle.
• Triggers can be fired from task code via gu_TriggerRelease, making them equally useful for pure software event signalling without any hardware interrupt involvement.