task APIs

task API More...

Data Structures
struct	task_config
	Constant task configuration. More...
struct	task_data
	Task runtime state. More...

Macros
#define	TASK_RUNNER_TASKS_DEFINE(config_name, data_name, ...)
	Instantiate tasks information for task runner.
#define	TASK_SCHEDULE_TDF_LOG_ARRAY(schedule, tdf_mask, tdf_id, tdf_num, tdf_time, period, data)
	Type safe wrapper around task_schedule_tdf_log_array.
#define	TASK_SCHEDULE_TDF_LOG(schedule, tdf_mask, tdf_id, tdf_time, data)
	Type safe wrapper around task_schedule_tdf_log.

Typedefs
typedef void(*	task_runner_task_fn) (const struct task_schedule *schedule, struct k_poll_signal *terminate, void *arg)

Enumerations
enum	{ TASK_EXECUTOR_THREAD , TASK_EXECUTOR_WORKQUEUE }
enum	{ TASK_FLAG_ARG_IS_DEVICE = BIT(0) }

Functions
static struct task_data *	task_data_from_work (struct k_work *work)
	Get the parent task_data struct from the work pointer.
const struct task_schedule *	task_schedule_from_data (struct task_data *data)
	Retrieve the schedule associated with a task.
uint8_t *	task_schedule_persistent_storage (struct task_data *data)
	Retrieve per-schedule persistent memory.
void	task_workqueue_reschedule (struct task_data *task, k_timeout_t delay)
	Reschedule the task to run again after a delay.
static int	task_runner_task_block (struct k_poll_signal *terminate_signal, k_timeout_t timeout)
	Block on the termination signal for a duration.
static bool	task_schedule_tdf_requested (const struct task_schedule *schedule, uint8_t tdf_mask)
	Determine if a given TDF was requested by the schedule.
static void	task_schedule_tdf_log_core (const struct task_schedule *schedule, uint8_t tdf_mask, uint16_t tdf_id, uint8_t tdf_len, uint8_t tdf_num, enum tdf_data_format format, uint64_t time, uint32_t idx_period, const void *data)
	Log an array of TDFs as requested by a schedule as a diff array.
static void	task_schedule_tdf_log_array (const struct task_schedule *schedule, uint8_t tdf_mask, uint16_t tdf_id, uint8_t tdf_len, uint8_t tdf_num, uint64_t time, uint32_t period, const void *data)
	Log an array of TDFs as requested by a schedule.
static void	task_schedule_tdf_log (const struct task_schedule *schedule, uint8_t tdf_mask, uint16_t tdf_id, uint8_t tdf_len, uint64_t time, const void *data)
	Log a single TDF as requested by a schedule.

Detailed Description

task API

Macro Definition Documentation

TASK_RUNNER_TASKS_DEFINE

#define TASK_RUNNER_TASKS_DEFINE	(		config_name,
			data_name,
			... )

#include <infuse/task_runner/task.h>

Value:

        /* Define task specific variables */                                                       \
        FOR_EACH_NONEMPTY_TERM(_TASK_VAR_DEFINE, (;), __VA_ARGS__);                                \
        /* Define the configurations for each task */                                              \
        static const struct task_config config_name[] = {                                          \
                FOR_EACH_NONEMPTY_TERM(_TASK_CONFIG_DEFINE, (,), __VA_ARGS__)                      \
        };                                                                                         \
        /* Define the runtime task data array */                                                   \
        static struct task_data data_name[ARRAY_SIZE(config_name)]

Instantiate tasks information for task runner.

Helper macro that automatically creates the 3 items needed for correct operation of the task runner:

1. Variably sized memory for the task (e.g. thread stack)
2. Array of task configuration structs for the runner
3. Array of task data structs for the runner

Example Usage:

#define SLEEPY_TASK(define_mem, define_config, dev_pointer)                  \
   IF_ENABLED(define_mem,                                                    \
              (K_THREAD_STACK_DEFINE(sleep_stack_area, 1024);                \
               struct k_thread sleep_thread_obj))                            \
   IF_ENABLED(define_config,                                                 \
       ({                                                                    \
           .name = "sleepy",                                                 \
           .task_id = TASK_ID_SLEEPY,                                        \
           .task_args.const_arg = dev_pointer,                               \
           .exec_type = TASK_EXECUTOR_THREAD,                                \
           .executor.thread = {                                              \
               .thread = &sleep_thread_obj,                                  \
               .task_fn = example_task_fn,                                   \
               .thread_stack = sleep_stack_area,                             \
               .thread_stack_size = K_THREAD_STACK_SIZEOF(sleep_stack_area), \
           },
       }))
 
#define WORKQ_TASK(define_mem, define_config, ptr)  \
    IF_ENABLED(define_config,                       \
        ({                                          \
            .name = "workq",                        \
            .task_id = TASK_ID_WORKQ,               \
            .task_args.arg = ptr,                   \
            .exec_type = TASK_EXECUTOR_WORKQUEUE,   \
            .executor.workqueue = {                 \
                .worker_fn = example_workqueue_fn,  \
            },                                      \
        }))
 
TASK_RUNNER_TASKS_DEFINE(config, data,
  (SLEEPY_TASK, DEVICE_DT_GET(DT_NODELABEL(dev))),
  (WORKQ_TASK, &some_pointer));

Parameters

config_name	Name of the created task_config array
data_name	Name of the created task_data array
...	Grouped list of task definition macros and their arguments

TASK_SCHEDULE_TDF_LOG

#define TASK_SCHEDULE_TDF_LOG	(		schedule,
			tdf_mask,
			tdf_id,
			tdf_time,
			data )

#include <infuse/task_runner/task.h>

Value:

        task_schedule_tdf_log(schedule, tdf_mask, tdf_id, sizeof(TDF_TYPE(tdf_id)), tdf_time,      \
                              data);                                                               \
        do {                                                                                       \
                __maybe_unused const TDF_TYPE(tdf_id) *_data = data;                               \
        } while (0)

Type safe wrapper around task_schedule_tdf_log.

Adds compile-time validation that the passed pointer matches the type associated with tdf_id.

Note

Only works for TDF types without trailing variable length arrays

Parameters

schedule	Task schedule
tdf_mask	Single TDF mask that corresponds to tdf_id
tdf_id	TDF sensor ID
tdf_time	Epoch time associated with the first TDF. 0 for no timestamp.
data	TDF data array

TASK_SCHEDULE_TDF_LOG_ARRAY

#define TASK_SCHEDULE_TDF_LOG_ARRAY	(		schedule,
			tdf_mask,
			tdf_id,
			tdf_num,
			tdf_time,
			period,
			data )

#include <infuse/task_runner/task.h>

Value:

        task_schedule_tdf_log_array(schedule, tdf_mask, tdf_id, sizeof(TDF_TYPE(tdf_id)), tdf_num, \
                                    tdf_time, period, data);                                       \
        do {                                                                                       \
                __maybe_unused const TDF_TYPE(tdf_id) *_data = data;                               \
        } while (0)

Type safe wrapper around task_schedule_tdf_log_array.

Adds compile-time validation that the passed pointer matches the type associated with tdf_id.

Note

Only works for TDF types without trailing variable length arrays

Parameters

schedule	Task schedule
tdf_mask	Single TDF mask that corresponds to tdf_id
tdf_id	TDF sensor ID
tdf_num	Number of TDFs to log
tdf_time	Epoch time associated with the first TDF. 0 for no timestamp.
period	Time period between the TDF samples
data	TDF data array

Typedef Documentation

task_runner_task_fn

typedef void(* task_runner_task_fn) (const struct task_schedule *schedule, struct k_poll_signal *terminate, void *arg)

#include <infuse/task_runner/task.h>

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <infuse/task_runner/task.h>

Enumerator
TASK_EXECUTOR_THREAD	Task runs on its own thread.
TASK_EXECUTOR_WORKQUEUE	Task runs on the system workqueue.

anonymous enum

anonymous enum

#include <infuse/task_runner/task.h>

Enumerator
TASK_FLAG_ARG_IS_DEVICE	task_arg union is a device pointer

Function Documentation

task_data_from_work()

static struct task_data * task_data_from_work ( struct k_work * work )

inlinestatic

#include <infuse/task_runner/task.h>

Get the parent task_data struct from the work pointer.

Parameters

work	Work pointer provided to handler

Returns

struct task_data* Parent struct

task_runner_task_block()

static int task_runner_task_block ( struct k_poll_signal * terminate_signal, k_timeout_t timeout )

inlinestatic

#include <infuse/task_runner/task.h>

Block on the termination signal for a duration.

Parameters

terminate_signal	Termination signal received from the runner
timeout	Timeout for blocking

Return values

1	If task should terminate
0	If task should continue execution

task_schedule_from_data()

const struct task_schedule * task_schedule_from_data

(

struct task_data *

data

)

#include <infuse/task_runner/task.h>

Retrieve the schedule associated with a task.

Parameters

data	Task data struct

Returns

struct task_schedule* Task schedule

task_schedule_persistent_storage()

uint8_t * task_schedule_persistent_storage

(

struct task_data *

data

)

#include <infuse/task_runner/task.h>

Retrieve per-schedule persistent memory.

Parameters

data	Task data struct

Returns

uint8_t* Pointer to persistent memory of size CONFIG_TASK_RUNNER_PER_SCHEDULE_STORAGE

task_schedule_tdf_log()

static void task_schedule_tdf_log ( const struct task_schedule * schedule, uint8_t tdf_mask, uint16_t tdf_id, uint8_t tdf_len, uint64_t time, const void * data )

inlinestatic

#include <infuse/task_runner/task.h>

Log a single TDF as requested by a schedule.

Parameters

schedule	Task schedule
tdf_mask	Single TDF mask that corresponds to tdf_id
tdf_id	TDF sensor ID
tdf_len	Length of a single TDF
time	Epoch time associated with the first TDF. 0 for no timestamp.
data	TDF data array

task_schedule_tdf_log_array()

static void task_schedule_tdf_log_array ( const struct task_schedule * schedule, uint8_t tdf_mask, uint16_t tdf_id, uint8_t tdf_len, uint8_t tdf_num, uint64_t time, uint32_t period, const void * data )

inlinestatic

#include <infuse/task_runner/task.h>

Log an array of TDFs as requested by a schedule.

Parameters

schedule	Task schedule
tdf_mask	Single TDF mask that corresponds to tdf_id
tdf_id	TDF sensor ID
tdf_len	Length of a single TDF
tdf_num	Number of TDFs to log
time	Epoch time associated with the first TDF. 0 for no timestamp.
period	Time period between the TDF samples
data	TDF data array

task_schedule_tdf_log_core()

static void task_schedule_tdf_log_core ( const struct task_schedule * schedule, uint8_t tdf_mask, uint16_t tdf_id, uint8_t tdf_len, uint8_t tdf_num, enum tdf_data_format format, uint64_t time, uint32_t idx_period, const void * data )

inlinestatic

#include <infuse/task_runner/task.h>

Log an array of TDFs as requested by a schedule as a diff array.

Parameters

schedule	Task schedule
tdf_mask	Single TDF mask that corresponds to tdf_id
tdf_id	TDF sensor ID
tdf_len	Length of a single TDF
tdf_num	Number of TDFs to log
format	TDF encoding mode
time	Epoch time associated with the first TDF. 0 for no timestamp.
idx_period	Index of first sample if format == TDF_DATA_FORMAT_IDX_ARRAY Epoch time between tdfs when tdf_num > 0 otherwise.
data	TDF data array

task_schedule_tdf_requested()

static bool task_schedule_tdf_requested ( const struct task_schedule * schedule, uint8_t tdf_mask )

inlinestatic

#include <infuse/task_runner/task.h>

Determine if a given TDF was requested by the schedule.

Parameters

schedule	Task schedule to evaluate
tdf_mask	Single TDF mask from activity definition

Return values

true	TDF was requested
false	TDF was not requested

task_workqueue_reschedule()

void task_workqueue_reschedule	(	struct task_data *	task,
		k_timeout_t	delay )

#include <infuse/task_runner/task.h>

Reschedule the task to run again after a delay.

Parameters

task	Task data structure
delay	Delay until running again