Triggers in GeMRTOS

Table of Contents

The trigger resource can be seen as the generalization of interrupts. Tasks can be registered to a trigger resource in order to be resumed or restarted when the trigger resource is triggered. The gu_trigger_create functions creates a trigger resource and it allows associating an external interrupt with the trigger resource created. The gu_trigger_register_task function registers a task to a trigger resource. When the trigger resource is triggered, it is disabled until all the tasks that have been resumed or restarted turn into waiting for a new trigger of the trigger resource. The gu_trigger_wait function puts the task into the waiting for the trigger state. A task associated with a trigger resource also waits for the trigger when finishes its execution. Trigger resources can be associated with external events (meaning hardware interrupts); in this case, all the tasks registered to the trigger resource will behave as Interrupt Service Routines (ISRs). Because several tasks may be registered to a trigger resource, each one of these tasks will behave as an ISR independently of the others. On the other hand, trigger resources may be triggered from tasks' code. The gu_trigger_release function triggers a trigger resource. If enabled, all the registered tasks will be resumed or restarted. The function gu_trigger_enable enables a trigger resource, while the function gu_trigger_disable is used to disable it.

Enable and disable hook functions #

Hook functions can be configured to be executed when a trigger resource is either enabled or disabled. The gu_trigger_enable_hook may be used to configure a function to be executed prior to the trigger resource being enabled. The gu_trigger_disable_hook may be used to configure a function to be executed after the trigger resource is disabled. These hook functions are intended to be used to execute the special code associated with the devices associated with the trigger resource.

Trigger flexibility #

Trigger resources are very flexible for handling system events. They overcome the limitations of interrupts in a generalized way. For instance, UART devices (as many other peripherals) group internal events, input buffer full, and output buffer empty into a single hardware interrupt signal. Therefore, the UART driver should check if an interrupt was produced either by the input or the output buffer and execute the corresponding code. Using trigger resources, a trigger resource may be associated with the UART interrupt signal, and the task code registered to it checks whether the interrupt was produced either by the input buffer, the output buffer, or both. If the input buffer is full, it triggers a trigger resource where all the reading tasks are registered.

If the output buffer is empty, then it triggers a trigger resource where all the writing tasks are registered. In this way, there may be as many reading tasks and as many writing tasks as required without interfering with one another. The trigger resource associated with the input buffer should have defined hook functions to enable and disable the input buffer full event, while the trigger resource associated with the output buffer should have defined hook functions to enable and disable the output buffer empty event. Consequently, trigger resources allow the virtualization and generalization of either internal or external events.

Trigger related functions #

Creating and initializing a Trigger #

The first step is to create a trigger resource using:

G_RCB * gu_trigger_create (int IRQ_ID)

The function creates a trigger trigger resource. It accepts an IRQ_ID argument to allow associating the trigger resource to a hardware interrupt.

The trigger is created and initilized with the following paramenters:



IRQ_IDThe number of the hardware interrupt wanted to be associated with. Set this argument equal to -1 if no association with hardware interrupt is wanted. 


Returns
The gu_trigger_create returns the poitner to the trigger resource created. This pointer should be used to reference the trigger resource in all the trigger related functions.

Registering a task with a trigger resource #

A task is register to a trigger resource with the following function:

G_INT32 gu_trigger_register_task (struct gs_tcb * ptcb, G_INT32 irq_nbr )

The gu_trigger_register_task function associates a task with a trigger resource.

The task registration with the trigger resource is performed with the following parameters:



ptcbIt is a pointer to the GS_TCB structure of the task wanting to be associated with the trigger resource. 


irq_nbrThe IRQ number of the hardware interrupt associated with the trigger, or the pointer to trigger resource returned by the gu_trigger_create function. The pointer to the trigger resource should be cast to int. 


Returns
G_TRUE when successful, G_FALSE otherwise

Enabling and disabling a trigger resource #

Enabling a trigger resource #

A trigger resource can be enabled with the following function:

G_INT32 gu_trigger_enable (int IRQ_ID)

The gu_trigger_enable functions enables the trigger resource to be triggered with the gu_trigger_release or the hardware interrupt associated with.

The enabling of the trigger resource is performed with the following parameters:



IRQ_IDThe IRQ number of the hardware interrupt associated with the trigger, or the pointer to trigger resource returned by the gu_trigger_create function. The pointer to the trigger resource should be cast to int. 


Returns
G_TRUE if successful

Disabling a trigger resource #

A trigger resource can be disabled with the following function:

G_INT32 gu_trigger_disable (int IRQ_ID)

The gu_trigger_disable functions disables the trigger resource to be triggered with the gu_trigger_release or the hardware interrupt associated with.

The disabling of the trigger resource is performed with the following parameters:



IRQ_IDThe IRQ number of the hardware interrupt associated with the trigger, or the pointer to trigger resource returned by the gu_trigger_create function. The pointer to the trigger resource should be cast to int. 


Returns
G_TRUE if successful

Waiting for a trigger resource #

A task registered to a trigger resource can wait for a triggering with the following function:

G_INT32 gu_trigger_wait (void )

The gu_trigger_wait function puts the task into a waiting for trigger state. It can be executed in any part of the task's code. The same effect happens when the task finishes its execution (it is not a endless loop) and it is associated with a trigger resource.

The wait for the trigger resource function does not require parameters. The task waits for the trigger resource it is registered to.

Returns
G_TRUE when executed from a task's code, G_FALSE when executed from main code.

Releasing a trigger resource #

A trigger resource may be triggered with the following function:

G_INT32 gu_trigger_release (int irq_nbr)

The function triggers a trigger resource. If the trigger resource is enabled, and all tasks associated with it are in waiting for trigger state, then the tasks are resumed or restarted.

The release of a trigger resource is performed with the following parameters:



irq_nbrThe IRQ number of the hardware interrupt, or the pointer to trigger resource returned by the gu_trigger_create function. The pointer to the trigger resource should be cast to int. 


Returns
G_TRUE when successful, G_FALSE otherwise*

Enable and disable trigger resource hook functions #

Enable hook function #

The enable hook function specification is performed with the following function:

G_INT32 gu_trigger_enable_hook (int IRQ_ID, void * code_callback, void * p_arg )

The function sets the hook function to be called prior enabling the trigger resource.

The specification of the enable hook function is performed with the following parameters:



IRQ_IDThe IRQ number of the hardware interrupt associated with the trigger, or the pointer to trigger resource returned by the gu_trigger_create function. The pointer to the trigger resource should be cast to int. 


code_callbackThe function name of the function to be called. This parameter defines the hook function to be executed when trigger resource is enabled. 


p_argThe value to be passed when the hook function is called. Therefore, the same hook function can be parametrized for several trigger resources. 


Returns
G_TRUE if successful.

Disable hook function #

The disable hook function specification is performed with the following function:

G_INT32 gu_trigger_disable_hook (int IRQ_ID, void * code_callback, void * p_arg )

The function sets the hook function to be called after disabling the trigger resource.

The specification of the disable hook function is performed with the following parameters:



IRQ_IDThe IRQ number of the hardware interrupt associated with the trigger, or the pointer to trigger resource returned by the gu_trigger_create function. The pointer to the trigger resource should be cast to int. 


code_callbackThe function name of the function to be called. This parameter defines the hook function to be executed when trigger resource is disabled. 


p_argThe value to be passed when the hook function is called. Therefore, the same hook function can be parametrized for several trigger resources. 


Returns
G_TRUE if successful.

Trigger resource related structure #

T_TRIGGER_RESOURCE #

The T_TRIGGER_RESOURCE is defined as the field "trigger" in a G_RCB resource. So, the fields of the T_TRIGGER_RESOURCE structure should be addressed as: (G_RCB *)->trigger.<field>

Structure fields #

G_INT32associated_IRQ
G_TRUE if associated with IRQ, G_FALSE otherwise.
G_INT32IRQ_ID
Number of IRQ associated with.
void *(*enable_code )(void *)
Pointer to the function to be executed to reenable trigger.
void *enable_arg
Pointer to the argument of the first call.
void *(*disable_code )(void *)
Pointer to the function to be executed to reenable trigger.
void *disable_arg
Pointer to the argument of the first call.

Leave a Reply