Kernel API interface to create/remove tasks and perform special OS operations. More...

Collaboration diagram for Scheduler Interface:

Macros
#define	qLowest_Priority
	A macro directive to indicate the lowest priority level.

#define	qMedium_Priority
	A macro directive to indicate the medium priority level.

#define	qHigh_Priority
	A macro directive to indicate the highest priority level.

#define	qPeriodic
	A directive indicating that the task will run every time its timeout has expired.

#define	qIndefinite
	Same as qPeriodic. A directive indicating that the task will run every time its timeout has expired.

#define	qSingleShot
	A directive that indicates that the task will be executed only once after its time has expired.

Functions
qBool_t	qOS_Setup (const qGetTickFcn_t tFcn, const qTimingBase_t t, qTaskFcn_t idleCallback)
	Task Scheduler Setup. This function is required and must be called once in the application main thread before any task is being added to the OS.

qBool_t	qOS_Set_IdleTask (qTaskFcn_t callbackFcn)
	Set/Change the callback for the Idle-task.

qBool_t	qOS_Add_Task (qTask_t const Task, qTaskFcn_t callbackFcn, const qPriority_t p, const qTime_t t, const qIteration_t n, const qState_t init, void arg)
	Add a task to the scheduling scheme. The task is scheduled to run every t seconds, n times and executing callbackFcn method on every pass.

qBool_t	qOS_Add_EventTask (qTask_t const Task, qTaskFcn_t callbackFcn, const qPriority_t p, void arg)
	Add a task to the scheduling scheme. This API creates a task with a qDisabled state by default, so this task will be executed only, when asynchronous events occurs. However, this behavior can be changed in execution time using qTask_Set_Time() or qTask_Set_Iterations().

qBool_t	qOS_Add_StateMachineTask (qTask_t const Task, qSM_t m, const qPriority_t p, const qTime_t t, const qState_t init, void *arg)
	Add a task to the scheduling scheme running a dedicated state-machine. The task is scheduled to run every t seconds in qPeriodic mode. The event info will be available as a generic pointer inside the qSM_Handler_t::Data field.

qBool_t	qOS_Add_ATCLITask (qTask_t const Task, qATCLI_t cli, const qPriority_t p, void *arg)
	Add a task to the scheduling scheme running an AT Command Line Interface. Task will be scheduled as event-triggered task. The parser address will be stored in the qEvent_t::TaskData storage-Pointer.

qBool_t	qOS_Remove_Task (qTask_t *const Task)
	Remove the task from the scheduling scheme.

qBool_t	qOS_Run (void)
	Executes the scheduling scheme. It must be called once after the task pool has been defined.

qBool_t	qOS_YieldToTask (qTask_t *const Task)
	Yield the control of the current running task to another task.

Detailed Description

Kernel API interface to create/remove tasks and perform special OS operations.

Precondition: Before using any scheduler interface, you must first configure and initialize the operating system using qOS_Setup()

Function Documentation

◆ qOS_Add_ATCLITask()

qBool_t qOS_Add_ATCLITask	(	qTask_t *const	Task,
		qATCLI_t *	cli,
		const qPriority_t	p,
		void *	arg )

Add a task to the scheduling scheme running an AT Command Line Interface. Task will be scheduled as event-triggered task. The parser address will be stored in the qEvent_t::TaskData storage-Pointer.

Precondition: The AT-CLI object should be previously configured with qATCLI_Setup().

See also: qATCLI_Setup()

Parameters

[in]	Task	A pointer to the task node.
[in]	cli	A pointer to the AT Command Line Inteface instance.
[in]	p	Task priority Value. [0(min) - `Q_PRIORITY_LEVELS` (max)]
[in]	arg	Represents the task arguments. All arguments must be passed by reference and cast to `void*`. Only one argument is allowed, so, for multiple arguments, create a structure that contains all of the arguments and pass a pointer to that structure.

Returns: Returns qTrue on success, otherwise returns qFalse.

◆ qOS_Add_EventTask()

qBool_t qOS_Add_EventTask	(	qTask_t *const	Task,
		qTaskFcn_t	callbackFcn,
		const qPriority_t	p,
		void *	arg )

Add a task to the scheduling scheme. This API creates a task with a qDisabled state by default, so this task will be executed only, when asynchronous events occurs. However, this behavior can be changed in execution time using qTask_Set_Time() or qTask_Set_Iterations().

Parameters

[in]	Task	A pointer to the task node.
[in]	callbackFcn	A pointer to a the task callback method with a qEvent_t parameter as input argument.
[in]	p	Task priority Value. [0(min) - `Q_PRIORITY_LEVELS` (max)]
[in]	arg	Represents the task arguments. All arguments must be passed by reference and cast to `void*`. Only one argument is allowed, so, for multiple arguments, create a structure that contains all of the arguments and pass a pointer to that structure.

Returns: Returns qTrue on success, otherwise returns qFalse.

◆ qOS_Add_StateMachineTask()

qBool_t qOS_Add_StateMachineTask	(	qTask_t *const	Task,
		qSM_t *	m,
		const qPriority_t	p,
		const qTime_t	t,
		const qState_t	init,
		void *	arg )

Add a task to the scheduling scheme running a dedicated state-machine. The task is scheduled to run every t seconds in qPeriodic mode. The event info will be available as a generic pointer inside the qSM_Handler_t::Data field.

Precondition: The State-machine object should be previously configured with qStateMachine_Setup()

See also: qStateMachine_Setup()

Parameters

[in]	Task	A pointer to the task node.
[in]	m	A pointer to the Finite State-Machine (FSM) object.
[in]	p	Task priority Value. [0(min) - `Q_PRIORITY_LEVELS` (max)]
[in]	t	Execution interval defined in seconds (floating-point format). For immediate execution (tValue = qTimeImmediate).
[in]	init	Specifies the initial operational state of the task (qEnabled, qDisabled, qAsleep or qAwake(implies qEnabled)).
[in]	arg	Represents the task arguments. All arguments must be passed by reference and cast to `void*`. Only one argument is allowed, so, for multiple arguments, create a structure that contains all of the arguments and pass a pointer to that structure.

Returns: Returns qTrue on success, otherwise returns qFalse.

◆ qOS_Add_Task()

qBool_t qOS_Add_Task	(	qTask_t *const	Task,
		qTaskFcn_t	callbackFcn,
		const qPriority_t	p,
		const qTime_t	t,
		const qIteration_t	n,
		const qState_t	init,
		void *	arg )

Add a task to the scheduling scheme. The task is scheduled to run every t seconds, n times and executing callbackFcn method on every pass.

Parameters

[in]	Task	A pointer to the task node.
[in]	callbackFcn	A pointer to a void callback method with a qEvent_t parameter as input argument.
[in]	p	Task priority Value. [0(min) - `Q_PRIORITY_LEVELS(max)`]
[in]	t	Execution interval defined in seconds (floating-point format). For immediate execution (tValue = qTimeImmediate).
[in]	n	Number of task executions (Integer value). For indefinite execution ( n = qPeriodic or qIndefinite ). Tasks do not remember the number of iteration set initially. After the iterations are done, internal iteration counter is 0. To perform another set of iterations, set the number of iterations again.

Note: Tasks which performed all their iterations put their own state to qDisabled.; Asynchronous triggers do not affect the iteration counter.

Parameters

[in]	init	Specifies the initial operational state of the task (qEnabled, qDisabled, qAsleep or qAwake(implies qEnabled)).
[in]	arg	Represents the task arguments. All arguments must be passed by reference and cast to `void*` . Only one argument is allowed, so, for multiple arguments, create a structure that contains all of the arguments and pass a pointer to that structure.

Returns: Returns qTrue on success, otherwise returns qFalse.

◆ qOS_Remove_Task()

qBool_t qOS_Remove_Task ( qTask_t *const Task )

Remove the task from the scheduling scheme.

Parameters

[in] Task A pointer to the task node.

Returns: Returns qTrue if success, otherwise returns qFalse.

◆ qOS_Run()

qBool_t qOS_Run ( void )

Executes the scheduling scheme. It must be called once after the task pool has been defined.

Note: This call keeps the application in an endless loop.

Returns: qTrue if a release action its performed. In a normal scenario, this function never returns.

◆ qOS_Set_IdleTask()

qBool_t qOS_Set_IdleTask ( qTaskFcn_t callbackFcn )

Set/Change the callback for the Idle-task.

Parameters

[in] callbackFcn A pointer to a void callback method with a qEvent_t parameter as input argument. To disable pass NULL as argument.

Returns: qTrue on success. Otherwise return qFalse.

◆ qOS_Setup()

qBool_t qOS_Setup	(	const qGetTickFcn_t	tFcn,
		const qTimingBase_t	t,
		qTaskFcn_t	idleCallback )

Task Scheduler Setup. This function is required and must be called once in the application main thread before any task is being added to the OS.

Parameters

[in] tFcn The function that provides the tick value. If the user application uses the qClock_SysTick() from the ISR, this parameter can be NULL.

Note: Function should take void and return a 32bit value.

Parameters

[in]	t	(Optional) This parameter specifies the ISR background timer base time. This can be the period in seconds(Floating-point format) or frequency in Herzt(if `Q_SETUP_TICK_IN_HERTZ` is enabled).
[in]	idleCallback	Callback function to the Idle Task. To disable the Idle-Task activities, pass `NULL` as argument.

Returns: qTrue on success. Otherwise return qFalse.

Example : When tick is already provided

#include "QuarkTS.h"
#include "HAL.h"
 
#define TIMER_TICK   0.001f
 
void main( void ) {
    HAL_Init();
    qOS_Setup( HAL_GetTick, TIMER_TICK, IdleTask_Callback );
}

Example : When the tick is not provided

#include "QuarkTS.h"
#include "DeviceHeader.h"
 
#define TIMER_TICK   0.001
 
void Interrupt_Timer0( void ) {
    qClock_SysTick();
}
 
void main( void ) {
    MCU_Init();
    BSP_Setup_Timer0();
    qOS_Setup( NULL, TIMER_TICK, IdleTask_Callback );
 
}

◆ qOS_YieldToTask()

qBool_t qOS_YieldToTask ( qTask_t *const Task )

Yield the control of the current running task to another task.

Note: This API can only be invoked from the context of a task.; Target task will inherit the event data.

Warning: Yielding from the IDLE task is not allowed.

Parameters

[in] Task A pointer to the task to which current control will be yielded. Pass NULL to discard a previous request.

Returns: Returns qTrue if success, otherwise returns qFalse.

Macros

Functions

Detailed Description

Function Documentation

◆ qOS_Add_ATCLITask()

◆ qOS_Add_EventTask()

◆ qOS_Add_StateMachineTask()

◆ qOS_Add_Task()

◆ qOS_Remove_Task()

◆ qOS_Run()

◆ qOS_Set_IdleTask()

◆ qOS_Setup()

◆ qOS_YieldToTask()