lazuli.h File Reference

The public API of the Lazuli kernel. More...

#include <stdint.h>
#include <Lazuli/common.h>
#include <Lazuli/config.h>

Go to the source code of this file.

Data Structures
struct	Lz_TaskConfiguration
	Represents the configuration of a task. More...

Macros
#define	CYCLIC_RT   ((lz_scheduling_policy_t)0U)
	Cyclic real-time scheduling.
#define	PRIORITY_RT   ((lz_scheduling_policy_t)1U)
	Priority time sliced real-time scheduling.
#define	LZ_SCHEDULING_POLICY_MAX   PRIORITY_RT
	Represents the maximum value currently defined for a lz_scheduling_policy_t.

Typedefs
typedef int8_t	lz_task_priority_t
	Represents the priority of a task, as a signed integer.
typedef uint16_t	lz_u_resolution_unit_t
	Represents the type used for the system clock resolution unit, as an unsigned integer.
typedef uint8_t	lz_scheduling_policy_t
	Represents the type used for scheduling policies of a Lazuli user task.

Functions
bool	Lz_RegisterTask (void(*const taskEntryPoint)(void), Lz_TaskConfiguration *taskConfiguration)
	Register a new task.
void	Lz_TaskConfiguration_Init (Lz_TaskConfiguration *const taskConfiguration)
	Initialize an Lz_TaskConfiguration with default values for all parameters.
void	Lz_Run (void)
	Run the scheduler.
void	Lz_Task_WaitInterrupt (uint8_t interruptCode)
	Wait for a specific interrupt to occur.
char const *	Lz_Task_GetName (void)
	Get the name of the calling task.
void	Lz_Task_Terminate (void)
	Terminate the calling task.
void	Lz_Task_WaitActivation (void)
	Set the calling task to wait for its next activation.
void	Lz_WaitTimer (lz_u_resolution_unit_t units)
	Set the calling task to wait for the specified number of time resolution units (time slices), using the software timer.

Detailed Description

The public API of the Lazuli kernel.

Copyright

2017-2020, Remi Andruccioli remi..nosp@m.andr.nosp@m.uccio.nosp@m.li@g.nosp@m.mail..nosp@m.com

This file describes the public (user) API of the Lazuli kernel. It defines public types and functions that can by used by user main code and tasks.

Definition in file lazuli.h.

Macro Definition Documentation

CYCLIC_RT

#define CYCLIC_RT   ((lz_scheduling_policy_t)0U)

Cyclic real-time scheduling.

Definition at line 51 of file lazuli.h.

PRIORITY_RT

#define PRIORITY_RT   ((lz_scheduling_policy_t)1U)

Priority time sliced real-time scheduling.

Equivalent to POSIX SCHED_RR.

Definition at line 58 of file lazuli.h.

LZ_SCHEDULING_POLICY_MAX

#define LZ_SCHEDULING_POLICY_MAX   PRIORITY_RT

Represents the maximum value currently defined for a lz_scheduling_policy_t.

Definition at line 63 of file lazuli.h.

Typedef Documentation

lz_task_priority_t

typedef int8_t lz_task_priority_t

Represents the priority of a task, as a signed integer.

The higher the value, the higher the priority.

Definition at line 30 of file lazuli.h.

lz_u_resolution_unit_t

typedef uint16_t lz_u_resolution_unit_t

Represents the type used for the system clock resolution unit, as an unsigned integer.

Definition at line 36 of file lazuli.h.

lz_scheduling_policy_t

typedef uint8_t lz_scheduling_policy_t

Represents the type used for scheduling policies of a Lazuli user task.

Definition at line 41 of file lazuli.h.

Function Documentation

Lz_RegisterTask()

bool Lz_RegisterTask	(	void(*)(void)	taskEntryPoint,
		Lz_TaskConfiguration *	taskConfiguration
	)

Register a new task.

If an error occurred during registration of the task false is returned and the task is not included in the set of tasks that will be run.

Parameters

taskEntryPoint	The entry point of the task to register. i.e. A pointer to the function representing the task.
taskConfiguration	A pointer to an Lz_TaskConfiguration containing the configuration of the task being registered. If NULL is passed, then default values are applied for all parameters.

Returns

• true if the task has been registered without error.
• false if an error occurred during registration.

Definition at line 764 of file scheduler.c.

Lz_TaskConfiguration_Init()

void Lz_TaskConfiguration_Init

(

Lz_TaskConfiguration *const

taskConfiguration

)

Initialize an Lz_TaskConfiguration with default values for all parameters.

No function is provided for allocating a new Lz_TaskConfiguration. So it is strongly advised to allocate the Lz_TaskConfiguration parameter on the stack before calling this function.

Parameters

taskConfiguration

A pointer to the Lz_TaskConfiguration to initialize.

Definition at line 752 of file scheduler.c.

Lz_Run()

void Lz_Run

(

void

)

Run the scheduler.

Start scheduling tasks.

Definition at line 771 of file scheduler.c.

Lz_Task_WaitInterrupt()

void Lz_Task_WaitInterrupt

(

uint8_t

interruptCode

)

Wait for a specific interrupt to occur.

Puts the calling task to sleep until the specified interrupt occurs.

Parameters

interruptCode

The code of the interrupt to wait for.

Attention

Only tasks with scheduling policy PRIORITY_RT can wait for interrupts.

Definition at line 799 of file scheduler.c.

Lz_Task_GetName()

char const * Lz_Task_GetName

(

void

)

Get the name of the calling task.

Returns

A pointer to a string containing the name of the current running task, or NULL if the task has no name.

Definition at line 785 of file scheduler.c.

Lz_Task_Terminate()

void Lz_Task_Terminate

(

void

)

Terminate the calling task.

The context of the task will be saved on its stack.

Calling this function has the same effect than returning from the task's main function.

The terminated task will never be scheduled again.

Definition at line 821 of file scheduler.c.

Lz_Task_WaitActivation()

void Lz_Task_WaitActivation

(

void

)

Set the calling task to wait for its next activation.

May be used if the task finished its work without consuming all of its completion time.

Attention

Only tasks with scheduling policy CYCLIC_RT can wait for next activation.

Definition at line 791 of file scheduler.c.

Lz_WaitTimer()

void Lz_WaitTimer

(

lz_u_resolution_unit_t

units

)

Set the calling task to wait for the specified number of time resolution units (time slices), using the software timer.

As Lazuli is a time sliced operating system, the effective waiting will start at the end of the current time slice. This means that the real waiting time starting from the calling of this function will be:

units / clock resolution frequency <= waiting time AND waiting time < (units + 1) / clock resolution frequency

See the configuration option LZ_CONFIG_SYSTEM_CLOCK_RESOLUTION_FREQUENCY.

Parameters

units

The number of time slices to wait.

Warning

Only works for tasks with PRIORITY_RT policy.

Definition at line 810 of file scheduler.c.