vsf_task.h File Reference

#include "./kernel/vsf_kernel_cfg.h"
#include "service/vsf_service.h"
#include "../vsf_eda.h"
#include "./vsf_pt.h"
#include "./vsf_fsm.h"

Go to the source code of this file.

Macros
#define	__vsf_task_func(__name)
#define	vsf_task_func(__name)
	Expand to the name of the task entry function.
#define	__vsf_task(__name)
#define	vsf_task(__name)
	Expand to the type name of the task control block.
#define	__implement_vsf_task(__name)
#define	vsf_task_begin()
	Begin the task entry function body.
#define	vsf_task_end()
	End the task entry function body started by implement_vsf_task().
#define	vsf_task_state   (vsf_this.fsm_state)
	Expand to the current state of the task control block.
#define	implement_vsf_task(__name)
	Start the implementation of the task entry function.
#define	imp_vsf_task(__name)
	Alias of implement_vsf_task().
#define	vsf_task_start   vsf_teda_start
	Start a task with the given configuration. In this variant (VSF_KERNEL_CFG_EDA_SUPPORT_TIMER is ENABLED) it is mapped to vsf_teda_start(), so timer services are available to the task.
#define	__def_vsf_task(__name, ...)
#define	def_vsf_task(__name, ...)
	Define a task control block and declare its entry function.
#define	define_vsf_task(__name, ...)
	Alias of def_vsf_task().
#define	end_def_vsf_task(...)
	End a task definition started by def_vsf_task(). It is empty and only used for coding style symmetry.
#define	end_define_vsf_task(...)
	Alias of end_def_vsf_task().
#define	__declare_vsf_task(__name)
#define	declare_vsf_task(__name)
	Declare a task (the task class and its control block type) before it is defined by def_vsf_task().
#define	dcl_vsf_task(__name)
	Alias of declare_vsf_task().
#define	prepare_vsf_task(__name, __task)
	Prepare a task control block before the task is started, i.e. reset the task state.
#define	prp_vsf_task(__name, __task)
	Alias of prepare_vsf_task().
#define	__init_vsf_task(__name, __task, __pri, ...)
#define	init_vsf_task(__name, __task, __pri, ...)
	Prepare and start a task defined by def_vsf_task().
#define	vsf_task_call_task(__name, __target, ...)
	Call another task as a sub-task from the current task, and wait until it finishes.
#define	vsf_task_call_sub(__name, __target, ...)
	Call an event-driven subroutine (sub-eda) from the current task.
#define	vsf_eda_call_task   vsf_task_call_task
	Alias of vsf_task_call_task().
#define	vsf_task_call_pt(__name, __target)
	Call a protothread (pt) as a subroutine from the current task.
#define	on_vsf_task_init()
	Condition helper checking whether the current event is VSF_EVT_INIT, i.e. the task is started.
#define	on_vsf_task_fini()
	Condition helper checking whether the current event is VSF_EVT_FINI, i.e. the task is about to terminate.
#define	on_vsf_task_evt(__evt)
	Condition helper checking whether the current event is the given event.
#define	vsf_task_wait_until(...)
	Wait cooperatively until the given condition is satisfied.

Typedefs
typedef vsf_teda_t	vsf_task_t
	Cooperative task type, alias of vsf_teda_t when VSF_KERNEL_CFG_EDA_SUPPORT_TIMER is ENABLED; the base type produced by def_vsf_task()
typedef fsm_rt_t(*	vsf_task_entry_t) (uintptr_t target, vsf_evt_t evt)
	Task entry function (the event handler of the task), returning fsm_rt_t when VSF_KERNEL_CFG_EDA_SUBCALL_HAS_RETURN_VALUE is ENABLED.

Functions
fsm_rt_t	__vsf_eda_call_task (vsf_task_entry_t entry, uintptr_t param, size_t local_size)
	Call a task as a sub-task and wait for its return value.

Macro Definition Documentation

__vsf_task_func

#define __vsf_task_func

(

__name

)

Value:

vsf_task_func_##__name

vsf_task_func

#define vsf_task_func

(

__name

)

Value:

__vsf_task_func(__name)

Expand to the name of the task entry function.

Parameters

[in]

__name

name of the task

__vsf_task

#define __vsf_task

(

__name

)

Value:

task_cb_##__name

vsf_task

#define vsf_task

(

__name

)

Value:

__vsf_task(__name)

Expand to the type name of the task control block.

Parameters

[in]

__name

name of the task

__implement_vsf_task

#define __implement_vsf_task

(

__name

)

Value:

        fsm_rt_t vsf_task_func(__name)( uintptr_t local,                        \
                                        vsf_evt_t evt)                          \
        {                                                                       \
            vsf_task(__name) *vsf_pthis =                                       \
                *(vsf_task(__name) **)                                          \
                    ((uintptr_t)local - sizeof(uintptr_t));

vsf_task_begin

#define vsf_task_begin

(

)

Begin the task entry function body.

Note

Used together with implement_vsf_task() and vsf_task_end().

vsf_task_end

#define vsf_task_end

(

)

Value:

            } return fsm_rt_on_going;

End the task entry function body started by implement_vsf_task().

Note

In this variant (VSF_KERNEL_CFG_EDA_SUBCALL_HAS_RETURN_VALUE is ENABLED), it returns fsm_rt_on_going to keep the task alive.

vsf_task_state

#define vsf_task_state   (vsf_this.fsm_state)

Expand to the current state of the task control block.

implement_vsf_task

#define implement_vsf_task

(

__name

)

Value:

__implement_vsf_task(__name)

Start the implementation of the task entry function.

Parameters

[in]

__name

name of the task

Note

Inside the body, vsf_pthis points to the task control block, and vsf_this gives direct access to its members. When VSF_KERNEL_CFG_EDA_SUBCALL_HAS_RETURN_VALUE is ENABLED, the entry function returns fsm_rt_t, otherwise it returns void.

Used together with def_vsf_task() and init_vsf_task().

imp_vsf_task

#define imp_vsf_task

(

__name

)

Value:

implement_vsf_task(__name)

Alias of implement_vsf_task().

Parameters

[in]

__name

name of the task

vsf_task_start

#define vsf_task_start   vsf_teda_start

Start a task with the given configuration. In this variant (VSF_KERNEL_CFG_EDA_SUPPORT_TIMER is ENABLED) it is mapped to vsf_teda_start(), so timer services are available to the task.

Parameters

[in]	__task	pointer to the task, of type vsf_task_t
[in]	__cfg	pointer to the task configuration, of type vsf_eda_cfg_t

Returns

vsf_err_t: VSF_ERR_NONE if the task is started successfully; VSF_ERR_NOT_ENOUGH_RESOURCES if no frame is available

Note

A VSF_EVT_INIT event is sent to the task once it is started.

__def_vsf_task

#define __def_vsf_task	(		__name,
			... )

Value:

        struct task_cb_##__name {                                               \
            uint8_t fsm_state;                                                  \
            __VA_ARGS__                                                         \
        };                                                                      \
        struct __name {                                                         \
            implement(vsf_task_t);                                              \
            implement_ex(task_cb_##__name, param);                              \
        };                                                                      \
        extern fsm_rt_t vsf_task_func_##__name( uintptr_t local,                \
                                                vsf_evt_t evt);

def_vsf_task

#define def_vsf_task	(		__name,
			... )

Value:

__def_vsf_task(__name,__VA_ARGS__)

Define a task control block and declare its entry function.

Parameters

[in]	__name	name of the task
[in]	...	member variables of the task control block

Note

The first member of the task control block is fsm_state, which is used internally to hold the task state.

Used together with implement_vsf_task() and init_vsf_task().

define_vsf_task

#define define_vsf_task	(		__name,
			... )

Value:

def_vsf_task(__name,__VA_ARGS__)

Alias of def_vsf_task().

Parameters

[in]	__name	name of the task
[in]	...	member variables of the task control block

end_def_vsf_task

#define end_def_vsf_task

(

...

)

End a task definition started by def_vsf_task(). It is empty and only used for coding style symmetry.

end_define_vsf_task

#define end_define_vsf_task

(

...

)

Alias of end_def_vsf_task().

__declare_vsf_task

#define __declare_vsf_task

(

__name

)

Value:

            typedef struct __name __name;                                       \
            typedef struct task_cb_##__name  task_cb_##__name;

declare_vsf_task

#define declare_vsf_task

(

__name

)

Value:

__declare_vsf_task(__name)

Declare a task (the task class and its control block type) before it is defined by def_vsf_task().

Parameters

[in]

__name

name of the task

dcl_vsf_task

#define dcl_vsf_task

(

__name

)

Value:

declare_vsf_task(__name)

Alias of declare_vsf_task().

Parameters

[in]

__name

name of the task

prepare_vsf_task

#define prepare_vsf_task	(		__name,
			__task )

Value:

            do {(__task)->fsm_state = 0; } while(0)

Prepare a task control block before the task is started, i.e. reset the task state.

Parameters

[in]	__name	name of the task
[in]	__task	pointer to the task control block

prp_vsf_task

#define prp_vsf_task	(		__name,
			__task )

Value:

prepare_vsf_task(__name, __task)

Alias of prepare_vsf_task().

Parameters

[in]	__name	name of the task
[in]	__task	pointer to the task control block

__init_vsf_task

#define __init_vsf_task	(		__name,
			__task,
			__pri,
			... )

Value:

        do {                                                                    \
            vsf_eda_cfg_t VSF_MACRO_SAFE_NAME(cfg) = {                          \
                .fn.func = (uintptr_t)vsf_task_func(__name),                    \
                .priority = (__pri),                                            \
                .target = (uintptr_t)&((__task)->param),                        \
                .feature.is_subcall_has_return_value = true,                    \
                __VA_ARGS__                                                     \
            };                                                                  \
            prepare_vsf_task(__name, &((__task)->param));                       \
            vsf_task_start(&((__task)->use_as__vsf_task_t),                     \
                &VSF_MACRO_SAFE_NAME(cfg));                                     \
        } while(0)

init_vsf_task

#define init_vsf_task	(		__name,
			__task,
			__pri,
			... )

Value:

            __init_vsf_task(__name, (__task), (__pri), __VA_ARGS__)

Prepare and start a task defined by def_vsf_task().

Parameters

[in]	__name	name of the task
[in]	__task	pointer to the task instance
[in]	__pri	priority of the task, of type vsf_prio_t
[in]	...	optional extra initializers for vsf_eda_cfg_t

Note

The task control block is reset first, then the task is started via vsf_task_start(); the task entry function will receive a VSF_EVT_INIT event.

vsf_task_call_task

#define vsf_task_call_task	(		__name,
			__target,
			... )

Value:

            __vsf_eda_call_task((vsf_task_entry_t)vsf_task_func(__name),        \
                                (uintptr_t)(__target), (0, ##__VA_ARGS__))

Call another task as a sub-task from the current task, and wait until it finishes.

Parameters

[in]	__name	name of the sub-task
[in]	__target	pointer to the control block of the sub-task
[in]	...	optional size of the local variables of the sub-task frame

Returns

fsm_rt_t: the return value of the sub-task when it finishes, or fsm_rt_yield while the sub-task is scheduled to run

Note

Only available when VSF_KERNEL_CFG_EDA_SUBCALL_HAS_RETURN_VALUE is ENABLED.

vsf_task_call_sub

#define vsf_task_call_sub	(		__name,
			__target,
			... )

Value:

            if (VSF_ERR_NONE != __vsf_eda_call_eda(                             \
                    (vsf_task_entry_t)(__name),                                 \
                    (__target),                                                 \
                    (0, ##__VA_ARGS))) {                                        \
                return fsm_rt_on_going;                                         \
            }

Call an event-driven subroutine (sub-eda) from the current task.

Parameters

[in]	__name	entry function of the subroutine
[in]	__target	pointer to the target (parameter) of the subroutine
[in]	...	optional size of the local variables of the sub-frame

Note

If the subroutine cannot be started, the current task returns fsm_rt_on_going and retries later.

vsf_eda_call_task

#define vsf_eda_call_task   vsf_task_call_task

Alias of vsf_task_call_task().

Parameters

[in]	__name	name of the sub-task
[in]	__target	pointer to the control block of the sub-task
[in]	...	optional size of the local variables of the sub-task frame

vsf_task_call_pt

#define vsf_task_call_pt	(		__name,
			__target )

Value:

            vsf_task_call_sub(vsf_pt_func(__name), __target)

Call a protothread (pt) as a subroutine from the current task.

Parameters

[in]	__name	name of the protothread
[in]	__target	pointer to the control block of the protothread

on_vsf_task_init

#define on_vsf_task_init

(

)

Value:

        if (VSF_EVT_INIT == evt)

Condition helper checking whether the current event is VSF_EVT_INIT, i.e. the task is started.

Note

Used inside the task entry function, usually together with vsf_task_wait_until().

on_vsf_task_fini

#define on_vsf_task_fini

(

)

Value:

        if (VSF_EVT_FINI == evt)

Condition helper checking whether the current event is VSF_EVT_FINI, i.e. the task is about to terminate.

Note

Used inside the task entry function.

on_vsf_task_evt

#define on_vsf_task_evt

(

__evt

)

Value:

        if ((__evt) == evt)

Condition helper checking whether the current event is the given event.

Parameters

[in]

__evt

the event to check, of type vsf_evt_t

Note

Used inside the task entry function, usually together with vsf_task_wait_until().

vsf_task_wait_until

#define vsf_task_wait_until

(

...

)

Value:

            __VA_ARGS__ {} else {                                               \
                return fsm_rt_wait_for_evt;                                     \
            }

Wait cooperatively until the given condition is satisfied.

Note

IMPORTANT For anything you want to wait, which is coming from vsf system, you can use vsf_task_wait_until() optionally. Those includues: VSF_EVT_XXXXX, semaphore, mutex and etc.

For VSF_EVT_XXXX, please use: vsf_task_wait_until( on_vsf_task_evt(VSF_EVT_XXXXX) ) ;

 For semaphore, please use:
 vsf_task_wait_until( vsf_sem_pend(...) ) ;


 For time, please use:
 vsf_task_wait_until( vsf_delay(...) ) ;

Parameters

[in]

...

the condition to wait for, e.g. on_vsf_task_evt(XXX), vsf_sem_pend(...) or vsf_delay(...)

Note

If the condition is not satisfied, the task entry function returns fsm_rt_wait_for_evt, so the task sleeps until a new event arrives; the condition is checked again on the next run.

Used inside the task entry function.

Typedef Documentation

vsf_task_t

typedef vsf_teda_t vsf_task_t

Cooperative task type, alias of vsf_teda_t when VSF_KERNEL_CFG_EDA_SUPPORT_TIMER is ENABLED; the base type produced by def_vsf_task()

vsf_task_entry_t

typedef fsm_rt_t(* vsf_task_entry_t) (uintptr_t target, vsf_evt_t evt)

Task entry function (the event handler of the task), returning fsm_rt_t when VSF_KERNEL_CFG_EDA_SUBCALL_HAS_RETURN_VALUE is ENABLED.

Parameters

[in]	target	target (parameter) passed to the task
[in]	evt	the event to be handled

Returns

fsm_rt_t: the return value of the task

Function Documentation

__vsf_eda_call_task()

fsm_rt_t __vsf_eda_call_task ( vsf_task_entry_t entry, uintptr_t param, size_t local_size )

extern

Call a task as a sub-task and wait for its return value.

Parameters

[in]	entry	entry function of the sub-task, of type vsf_task_entry_t
[in]	param	pointer to the target (parameter) of the sub-task
[in]	local_size	size of the local variables of the sub-task frame

Returns

fsm_rt_t: the return value of the sub-task when it finishes, or fsm_rt_yield while the sub-task is scheduled to run

Note

This is an internal function, please use vsf_task_call_task() instead.

Note

• if VSF_ERR_NOT_ENOUGH_RESOURCES is detected, yield and try it again (automatically). For tasks sharing the same frame pool, if the pool is too small, only task performance will be affected, and all sub-task call will work when frame is allocated.
• if the frame is allocated and pushed to the stack, we should yield to let the sub-task run.

Since in either way, we will yield, no need to handle the return value of vsf_eda_call().