Introduction #
The concept of a "trigger resource" serves as a generalization of interrupts, enabling tasks to be resumed or restarted when a specific event occurs. Tasks can be registered with a trigger resource, and when the trigger resource is activated, the associated tasks are resumed or restarted. The gu_trigger_create function creates a trigger resource and allows associating an external interrupt with it. The gu_trigger_register_task function registers a task with a trigger resource. When the trigger resource is activated, it is disabled until all registered tasks that have been resumed or restarted transition to a waiting state for a new trigger. Tasks associated with a trigger resource enter a waiting state for the trigger when they finish execution. Additionally, the gu_trigger_wait function explicitly places a task into the waiting for the trigger state. Trigger resources can be associated with external events, such as hardware interrupts. In this case, all tasks registered with the trigger resource behave as Interrupt Service Routines (ISRs). Importantly, these tasks operate independently of each other, ensuring that multiple tasks can be associated with a single trigger resource. Trigger resources can also be triggered from tasks' code using the gu_trigger_release function. When triggered, all registered tasks will be resumed or restarted if the trigger resource is enabled. The gu_trigger_enable function enables a trigger resource, while the gu_trigger_disable function disables it.
Enable and disable hook functions #
The system provides flexibility in handling events by allowing hook functions to be executed when trigger resources are enabled or disabled. The gu_trigger_enable_hook function allows configuring a function to be executed before a trigger resource is enabled, while gu_trigger_disable_hook configures a function to be executed after the trigger resource is disabled. These hook functions are intended to execute specific code associated with the devices associated with the trigger resource.
Trigger flexibility #
The system provides flexibility in handling events by allowing hook functions to be executed when trigger resources are enabled or disabled. The gu_trigger_enable_hook function allows configuring a function to be executed before a trigger resource is enabled, while gu_trigger_disable_hook configures a function to be executed after the trigger resource is disabled. These hook functions are intended to execute specific code associated with the devices associated with the trigger resource. Trigger resources offer a flexible approach to handling system events, overcoming the limitations of traditional interrupts. For example, Universal Asynchronous Receiver/Transmitter (UART) devices, like many peripherals, typically group various internal events, such as input buffer full and output buffer empty, into a single hardware interrupt signal. This requires the UART driver to determine which event triggered the interrupt and execute the corresponding code. With trigger resources, a trigger resource can be associated with the UART interrupt signal. The task code registered to this trigger resource then checks which event triggered the interrupt: input buffer full, output buffer empty, or both. If the input buffer is full, the trigger resource is activated, resuming all tasks associated with reading from the buffer. This example demonstrates the flexibility of trigger resources by allowing for the specific handling of individual events within a single interrupt signal. This approach eliminates the need for complex logic within the interrupt service routine to determine the cause of the interrupt and execute the appropriate actions. By leveraging trigger resources and hook functions, the GeMRTOS system provides a powerful and flexible mechanism for managing system events, enhancing the efficiency and modularity of the overall system design.
If the output buffer is empty, the system activates a trigger resource associated with writing tasks. This allows for an arbitrary number of reading and writing tasks to operate concurrently without interfering with each other. The trigger resource associated with the input buffer should have defined hook functions to enable and disable the input buffer full event. Similarly, the trigger resource associated with the output buffer should have defined hook functions to enable and disable the output buffer empty event. This approach allows for the virtualization and generalization of both internal and external events through the use of trigger resources.
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 resource. It accepts an IRQ_ID argument to allow associating the trigger resource with a hardware interrupt.
The trigger is created and initilized with the following paramenters:Name Description IRQ_ID The IRQ_ID argument specifies the number of the hardware interrupt to associate with the trigger resource. Setting this argument to -1 indicates that no association with a hardware interrupt is desired.
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.
gu_trigger_register_task
The task registration with the trigger resource is performed using the following parameters:Name Description ptcb This is a pointer to the GS_TCB structure of the task to be associated with the trigger resource. irq_nbr This is either the IRQ number of the hardware interrupt associated with the trigger or the pointer to the trigger resource returned by the gu_trigger_create function, cast to an integer (int).
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 function enables the trigger resource, allowing it to be activated using either the gu_trigger_release function or the associated hardware interrupt.
gu_trigger_enable
The enabling of the trigger resource is performed with the following parameters:Name Description IRQ_ID This parameter represents either the IRQ number of the hardware interrupt associated with the trigger resource or the pointer to the trigger resource returned by the gu_trigger_create function. If the IRQ_ID is a pointer, it should be cast to an integer (int) for use within the function.
Disabling a trigger resource #
A trigger resource can be disabled with the following function:
G_INT32 gu_trigger_disable(unsigned int IRQ_ID);
The gu_trigger_disable function disables the trigger resource, preventing it from being activated using either the gu_trigger_release function or the associated hardware interrupt.
gu_trigger_disable
The disabling of the trigger resource is performed with the following parameter:Name Description IRQ_ID This parameter represents either the IRQ number of the hardware interrupt associated with the trigger resource or the pointer to the trigger resource returned by the gu_trigger_create function. If the IRQ_ID is a pointer, it should be cast to an integer (int) for use within the function.
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 places the task into a waiting state for the trigger resource it is registered to. It can be executed anywhere in the task's code, and the same effect occurs when the task completes its execution (assuming it's not an infinite loop).
gu_trigger_wait
The gu_trigger_wait function does not require any parameters, as the task automatically waits for the trigger resource it is associated with.Releasing a trigger resource #
A trigger resource may be triggered with the following function:
G_INT32 gu_trigger_release(int irq_nbr);
The function activates a trigger resource. If the trigger resource is enabled and all associated tasks are in a waiting state for the trigger, then the tasks are resumed or restarted.
The trigger resource is activated using the following parameter:Name Description irq_nbr This parameter represents either the IRQ number of the hardware interrupt associated with the trigger resource or the pointer to the trigger resource returned by the gu_trigger_create function. If the irq_nbr is a pointer, it should be cast to an integer (int) for use within the function..
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 gu_trigger_enable_hook sets the hook function to be called before the trigger resource is enabled.
The function returns G_TRUE if the enable hook function was successfully configured; otherwise, it returns G_FALSE.Name Description IRQ_ID This parameter represents either the IRQ number of the hardware interrupt associated with the trigger resource or the pointer to the trigger resource returned by the gu_trigger_create function. If the IRQ_ID is a pointer, it should be cast to an integer (int) for use within the function. code_callback This parameter defines the name of the function to be executed as a hook function when the trigger resource is enabled. p_arg This parameter represents the value to be passed to the hook function when it is called. This allows the same hook function to be used for multiple trigger resources with different parameter values.
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 gu_trigger_disable_hook function sets the hook function to be called after the trigger resource is disabled.
The disable hook function is specified using the following parameters:Name Description IRQ_ID This parameter represents either the IRQ number of the hardware interrupt associated with the trigger resource or the pointer to the trigger resource returned by the gu_trigger_create function. If the IRQ_ID is a pointer, it should be cast to an integer (int) for use within the function. code_callback This parameter defines the name of the function to be executed as a hook function when the trigger resource is disabled. p_arg This parameter represents the value to be passed to the hook function when it is called. This allows the same hook function to be used for multiple trigger resources with different parameter values.
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_INT32 | associated_IRQ |
G_TRUE if associated with IRQ, G_FALSE otherwise. | |
G_INT32 | IRQ_ID |
Number of IRQ associated with. | |
G_INT32 | TRG_Enabled |
G_TRUE if trigger is enabled | |
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. |