The class to interface the OS. More...

#include <kernel.hpp>

Inheritance diagram for qOS::core:

Collaboration diagram for qOS::core:

Public Member Functions
bool	init (const getTickFcn_t tFcn=nullptr, taskFcn_t callbackIdle=nullptr) noexcept
	Task Scheduler initialization. This core method is required and must be called once in the application main thread before any task is being added to the OS.

bool	add (task &Task, taskFcn_t callback, const priority_t p, const duration_t t, const iteration_t n, const taskState s=taskState::ENABLED_STATE, void *arg=nullptr) noexcept
	Add a task to the scheduling scheme. The task is scheduled to run every t time units, n times and executing callback method on every pass.

bool	add (task &Task, taskFcn_t callback, const priority_t p, void *arg=nullptr) noexcept
	Add a task to the scheduling scheme. This API creates a task with a taskState::DISABLED_STATE state by default, so this task will be executed only, when asynchronous events occurs. However, this behavior can be changed in execution time using task::setTime() or task::setIterations().

bool	add (task &Task, stateMachine &m, const priority_t p, const duration_t t, const taskState s=taskState::ENABLED_STATE, void *arg=nullptr) noexcept
	Add a task to the scheduling scheme running a dedicated state-machine. The task is scheduled to run every t time units in task::PERIODIC mode. The event info will be available as a generic pointer inside the sm::handler_t::Data field.

bool	add (task &Task, commandLineInterface &cli, const priority_t p, void *arg=nullptr) noexcept
	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 event_t::TaskData storage-Pointer.

bool	setIdleTask (taskFcn_t callback) noexcept
	Set/Change the callback for the Idle-task.

bool	setNameIdleTask (const char *tName) noexcept
	Set the name for the idle task.

bool	schedulerRelease (void) noexcept
	Disables the kernel scheduling. The main thread will continue after the core::run() call.

bool	setSchedulerReleaseCallback (taskFcn_t callback) noexcept
	Set/Change the scheduler release callback function.

bool	remove (task &Task) noexcept
	Remove the task from the scheduling scheme.

bool	run (void) noexcept
	Executes the scheduling scheme. It must be called once after the task pool has been defined.

bool	notify (notifyMode mode, task &Task, void *eventData=nullptr) noexcept
	Sends a notification generating an asynchronous event. If mode = notifyMode::SIMPLE, the method marks the task as ready for execution and the scheduler planner will launch the task immediately according to the scheduling rules (even if task is disabled) and setting the `trigger` flag to trigger::byNotificationSimple. If mode = notifyMode::QUEUED, the notification will insert the notification in the FIFO priority queue. The scheduler get this notification as an asynchronous event and the task will be ready for execution according to the queue order (determined by priority), even if task is in a disabled or sleep operational state. When extracted, the scheduler will set `trigger` flag to trigger::byNotificationQueued. Specific user-data can be passed through, and will be available inside the event_t::EventData field, only in corresponding launch. If the task is in a `SLEEP` operation state, the scheduler will change the operational state to `AWAKEN` setting the `SHUTDOWN` bit. Specific user-data can be passed through, and will be available in the respective callback inside the qOS::event_t::EventData field.

bool	notify (notifyMode mode, void *eventData=nullptr) noexcept
	Try to spread a notification among all the tasks in the scheduling scheme.

bool	hasPendingNotifications (const task &Task) const noexcept
	Check if the supplied task has pending notifications.

bool	eventFlagsModify (task &Task, const taskFlag_t tFlags, const bool action) noexcept
	Modify the EventFlags for the provided task.

taskFlag_t	eventFlagsRead (task &Task) const noexcept
	Returns the current value of the task's EventFlags.

bool	eventFlagsCheck (task &Task, taskFlag_t flagsToCheck, const bool clearOnExit=true, const bool checkForAll=false) noexcept
	Check for flags set to `true` inside the task Event-Flags.

task *	getTaskByName (const char *name) noexcept
	Tries to find the task that matches the name provided.

task *	getTaskByID (size_t id) noexcept
	Tries to find the task that matches the ID provided.

bool	yieldToTask (task &Task) noexcept
	Yield the control of the current running task to another task.

globalState	getGlobalState (task &Task) const noexcept
	Retrieve the task global-state.

bool	add (input::watcher &w) noexcept
	Add an input-watcher so that its function is executed by the kernel.

bool	remove (input::watcher &w) noexcept
	Remove an input-watcher so that the kernel stops executing its function.

Static Public Member Functions
static core &	getInstance (void) noexcept
	Returns a reference to the OS control instance.

Static Public Attributes
static const priority_t	LOWEST_PRIORITY
	A constant that holds the value of the lowest priority.

static const priority_t	MEDIUM_PRIORITY
	A constant that holds the value of the medium priority.

static const priority_t	HIGHEST_PRIORITY
	A constant that holds the value of the highest priority.

Detailed Description

The class to interface the OS.

Note: Use the predefined os instance

Member Function Documentation

◆ add() [1/3]

bool qOS::core::add ( input::watcher & w )

noexcept

Add an input-watcher so that its function is executed by the kernel.

Note: The input-watcher is considered as an always-active task

Parameters

[in] w The input watcher.

Returns: Returns true if success, otherwise returns false.

◆ add() [2/3]

bool qOS::core::add	(	task &	Task,
		taskFcn_t	callback,
		const priority_t	p,
		const duration_t	t,
		const iteration_t	n,
		const taskState	s = taskState::ENABLED_STATE,
		void *	arg = nullptr )

noexcept

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

Parameters

[in]	Task	The task node.
[in]	callback	A pointer to a void callback method with a qOS::event_t parameter as input argument. If user uses the OOP approach for defining a task, you can pass `nullptr` as argument.
[in]	p	Task priority Value. [0(min) - `Q_PRIORITY_LEVELS(max)`]
[in]	t	Execution interval (time) given in milliseconds. For immediate execution use t = clock::IMMEDIATE.
[in]	n	Number of task executions (Integer value). For indefinite execution ( n = task::PERIODIC or task::INDEFINITE ). 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 taskState::DISABLED_STATE.; Asynchronous triggers do not affect the iteration counter.

Parameters

[in]	s	Specifies the initial operational state of the task (taskState::ENABLED_STATE, taskState::DISABLED_STATE, taskState::AWAKE_STATE or taskState::AWAKE_STATE(implies taskState::ENABLED_STATE,)).
[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 true on success, otherwise returns false.

◆ add() [3/3]

bool qOS::core::add	(	task &	Task,
		taskFcn_t	callback,
		const priority_t	p,
		void *	arg = nullptr )

inlinenoexcept

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

Parameters

[in]	Task	The task node.
[in]	callback	A pointer to a the task callback method with a event_t parameter as input argument. If user uses the OOP approach for defining a task, you can pass `nullptr` as 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*`.

Returns: Returns true on success, otherwise returns false.

◆ getGlobalState()

globalState qOS::core::getGlobalState ( task & Task ) const

noexcept

Retrieve the task global-state.

Parameters

[in] Task The task node.

Returns: One of the available global states : globalState::WAITING, globalState::SUSPENDED, globalState::RUNNING, globalState::READY. Return globalState::UNDEFINED if the current task its passing through a current kernel transaction

◆ getInstance()

static core & qOS::core::getInstance ( void )

staticnoexcept

Returns a reference to the OS control instance.

Returns: The OS control instance.

◆ getTaskByID()

task * qOS::core::getTaskByID ( size_t id )

noexcept

Tries to find the task that matches the ID provided.

Note: Task idle with ID = 0 cannot be obtained

Parameters

[in] id The value of the task-ID to find.

Returns: A pointer to the task node if found, otherwise returns nullptr.

◆ getTaskByName()

task * qOS::core::getTaskByName ( const char * name )

noexcept

Tries to find the task that matches the name provided.

Note: Task idle with name = idle cannot be obtained

Parameters

[in] name The string with the name to find.

Returns: A pointer to the task node if found, otherwise returns nullptr.

◆ init()

bool qOS::core::init	(	const getTickFcn_t	tFcn = nullptr,
		taskFcn_t	callbackIdle = nullptr )

noexcept

Task Scheduler initialization. This core method 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 qOS::clock::sysTick() from the ISR, this parameter can be nullptr.

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

Parameters

[in] callbackIdle Callback function to the Idle Task. To disable the Idle-Task activities, ignore this parameter of pass nullptr as argument.

Returns: true on success. Otherwise return false.

Example : When tick is already provided

#include "QuarkTS.h"
#include "HAL.h"
 
using namespace qOS;
 
void main( void ) {
    HAL_Init();
    os.init( HAL_GetTick, IdleTask_Callback );
}

Example : When the tick is not provided

#include "QuarkTS.h"
#include "DeviceHeader.h"
 
using namespace qOS;
 
void Interrupt_Timer0( void ) {
    clock::sysTick();
}
 
void main( void ) {
    MCU_Init();
    BSP_Setup_Timer0();
    os.init( nullptr, IdleTask_Callback );
 
}

◆ remove() [1/2]

bool qOS::core::remove ( input::watcher & w )

noexcept

Remove an input-watcher so that the kernel stops executing its function.

Parameters

[in] w The input-watcher.

Returns: Returns true if success, otherwise returns false.

◆ remove() [2/2]

bool qOS::core::remove ( task & Task )

noexcept

Remove the task from the scheduling scheme.

Parameters

[in] Task The task node.

Returns: Returns true if success, otherwise returns false.

◆ run()

bool qOS::core::run ( void )

noexcept

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: true if a release action its performed. In a normal scenario, this function never returns.

◆ schedulerRelease()

bool qOS::core::schedulerRelease ( void )

noexcept

Disables the kernel scheduling. The main thread will continue after the core::run() call.

◆ setIdleTask()

bool qOS::core::setIdleTask ( taskFcn_t callback )

noexcept

Set/Change the callback for the Idle-task.

Parameters

[in] callback A pointer to a void callback method with a qOS::event_t parameter as input argument. To disable pass nullptr as argument.

Returns: true on success. Otherwise return false.

◆ setNameIdleTask()

bool qOS::core::setNameIdleTask ( const char * tName )

noexcept

Set the name for the idle task.

Remarks: The size of the string must be less than 11

Parameters

[in] tName A raw-string with the task name

Returns: true on success. Otherwise return false.

◆ setSchedulerReleaseCallback()

bool qOS::core::setSchedulerReleaseCallback ( taskFcn_t callback )

noexcept

Set/Change the scheduler release callback function.

Parameters

[in] callback A pointer to a void callback method with a event parameter as input argument.

Returns: true on success. Otherwise return false.

◆ yieldToTask()

bool qOS::core::yieldToTask ( task & Task )

noexcept

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 The the task to which current control will be yielded.

Returns: Returns true if success, otherwise returns false.

Member Data Documentation

◆ HIGHEST_PRIORITY

const priority_t qOS::core::HIGHEST_PRIORITY

static

A constant that holds the value of the highest priority.

◆ LOWEST_PRIORITY

const priority_t qOS::core::LOWEST_PRIORITY

static

A constant that holds the value of the lowest priority.

◆ MEDIUM_PRIORITY

const priority_t qOS::core::MEDIUM_PRIORITY

static

A constant that holds the value of the medium priority.

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ getGlobalState()

◆ getInstance()

◆ getTaskByID()

◆ getTaskByName()

◆ init()

◆ remove() [1/2]

◆ remove() [2/2]

◆ run()

◆ schedulerRelease()

◆ setIdleTask()

◆ setNameIdleTask()

◆ setSchedulerReleaseCallback()

◆ yieldToTask()

Member Data Documentation

◆ HIGHEST_PRIORITY

◆ LOWEST_PRIORITY

◆ MEDIUM_PRIORITY