vsf_pt.h File Reference

#include "./kernel/vsf_kernel_cfg.h"
#include "../vsf_eda.h"
#include "./__vsf_task_common.h"

Go to the source code of this file.

Macros
#define	__implement_vsf_pt(__name)
#define	__implement_vsf_pt_ex(__name, __func_name)
#define	__vsf_pt_state()
#define	__vsf_pt_end()
#define	__vsf_pt_entry(__state, ...)
#define	vsf_pt_entry(...)
	Mark a re-entry point inside the protothread body.
#define	__vsf_pt_begin(__state)
#define	vsf_pt_begin()
	Begin the protothread body, opened right after implement_vsf_pt().
#define	vsf_pt_end()
	End the protothread body started by vsf_pt_begin(), and terminate the protothread.
#define	vsf_pt_wait_for_evt(__evt)
	Wait cooperatively until the given event arrives.
#define	vsf_pt_wfe(__evt)
	Alias of vsf_pt_wait_for_evt().
#define	vsf_pt_yield()
	Yield the cpu cooperatively: mark a re-entry point and post a VSF_EVT_YIELD event to the current protothread, so that it will be rescheduled.
#define	vsf_pt_raw_next()
	Set the protothread state to the next re-entry point, without emitting the re-entry label.
#define	vsf_pt_raw_entry(...)
	Emit a re-entry label, optionally executing the given code first.
#define	vsf_pt_wait_until(...)
	Wait cooperatively until the given condition is satisfied.
#define	__vsf_pt_call_sub(__name, __target, ...)
#define	vsf_pt_call_sub(__name, __target)
	Call an event-driven subroutine (sub-eda) from the current protothread, and wait until it finishes.
#define	vsf_pt_call_pt(__name, __target)
	Call another protothread as a subroutine from the current protothread, and wait until it finishes.
#define	vsf_eda_call_pt(__name, __target)
	Call a protothread as a subroutine from an event-driven task (eda), without blocking.
#define	__vsf_pt_call_task(__name, __target, ...)
#define	vsf_pt_call_task(__name, __target, __ret_addr, ...)
	Call a task as a sub-task from the current protothread, and wait until it finishes.
#define	vsf_pt_start   vsf_teda_start
	Start a protothread 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.
#define	implement_vsf_pt(__name)
	Start the implementation of the protothread entry function.
#define	implement_vsf_pt_ex(__name, __FUNC_NAME)
	Start the implementation of the protothread entry function with a dedicated function name.
#define	imp_vsf_pt(__name)
	Alias of implement_vsf_pt().
#define	imp_vsf_pt_ex(__name, __FUNC_NAME)
	Alias of implement_vsf_pt_ex().
#define	__vsf_pt_func(__name)
	Expand to the name of the protothread entry function.
#define	vsf_pt_func(__name)
#define	__vsf_pt(__name)
	Expand to the type name of the protothread control block.
#define	vsf_pt(__name)
#define	__def_vsf_pt(__name, ...)
#define	def_vsf_pt(__name, ...)
	Define a protothread control block.
#define	end_def_vsf_pt(...)
	End a protothread definition started by def_vsf_pt(). It is empty and only used for coding style symmetry.
#define	define_vsf_pt(__name, ...)
	Alias of def_vsf_pt().
#define	end_define_vsf_pt(...)
	Alias of end_def_vsf_pt().
#define	__declare_vsf_pt(__name)
#define	declare_vsf_pt(__name)
	Declare a protothread (the protothread class, its control block type and its entry function prototype) before it is defined by def_vsf_pt().
#define	dcl_vsf_pt(__name)
	Alias of declare_vsf_pt().
#define	__init_vsf_pt(__name, __pt, __pri, ...)
#define	vsf_pt_call_thread(__name, __target)
	Call a thread from the current protothread, and wait until the thread terminates.
#define	init_vsf_pt(__name, __pt, __pri, ...)
	Prepare and start a protothread defined by def_vsf_pt().

Typedefs
typedef vsf_teda_t	vsf_pt_t
	Protothread type, alias of vsf_teda_t when VSF_KERNEL_CFG_EDA_SUPPORT_TIMER is ENABLED.
typedef vsf_eda_evthandler_t	vsf_pt_entry_t
	Protothread entry function, with the eda event handler signature (alias of vsf_eda_evthandler_t)

Macro Definition Documentation

__implement_vsf_pt

#define __implement_vsf_pt

(

__name

)

Value:

            __implement_vsf_pt_common(__name, uintptr_t local)                  \
            {                                                                   \
                __vsf_pt_common(__name) *vsf_pthis =                            \
                    *(__vsf_pt_common(__name) **)                               \
                        ((uintptr_t)local - sizeof(uintptr_t));

__implement_vsf_pt_ex

#define __implement_vsf_pt_ex	(		__name,
			__func_name )

Value:

            __implement_vsf_pt_common(  __func_name,  uintptr_t local)          \
            {                                                                   \
                __vsf_pt_common(__name) *vsf_pthis =                            \
                    *(__vsf_pt_common(__name) **)                               \
                        ((uintptr_t)local - sizeof(uintptr_t));

__vsf_pt_state

#define __vsf_pt_state

(

)

Value:

(vsf_this.fsm_state)

__vsf_pt_end

#define __vsf_pt_end

(

)

Value:

__vsf_pt_end_common()

__vsf_pt_entry

#define __vsf_pt_entry	(		__state,
			... )

Value:

            __vsf_pt_entry_common(__state, __VA_ARGS__)

vsf_pt_entry

#define vsf_pt_entry

(

...

)

Value:

            __vsf_pt_entry(__vsf_pt_state(), __VA_ARGS__)

Mark a re-entry point inside the protothread body.

Parameters

[in]

...

optional code executed right after the re-entry point is set

Note

When the protothread is entered again later, execution resumes at the re-entry point. It does not return from the entry function by itself; it is usually used by other blocking macros such as vsf_pt_wait_until().

__vsf_pt_begin

#define __vsf_pt_begin

(

__state

)

Value:

__vsf_pt_begin_common(__state)

vsf_pt_begin

#define vsf_pt_begin

(

)

Value:

                                    VSF_UNUSED_PARAM(evt);                      \
                                    __vsf_pt_begin(__vsf_pt_state())

Begin the protothread body, opened right after implement_vsf_pt().

Note

Used together with vsf_pt_end(); the blocking macros can only be used between them.

vsf_pt_end

#define vsf_pt_end

(

)

Value:

__vsf_pt_end() }

End the protothread body started by vsf_pt_begin(), and terminate the protothread.

vsf_pt_wait_for_evt

#define vsf_pt_wait_for_evt

(

__evt

)

Value:

__vsf_pt_wfe_common(__vsf_pt_state(), __evt)

Wait cooperatively until the given event arrives.

Parameters

[in]

__evt

the event to wait for, of type vsf_evt_t

Note

If the current event is not the expected one, the protothread returns and resumes here when a new event arrives.

vsf_pt_wfe

#define vsf_pt_wfe

(

__evt

)

Value:

vsf_pt_wait_for_evt(__evt)

Alias of vsf_pt_wait_for_evt().

Parameters

[in]

__evt

the event to wait for, of type vsf_evt_t

vsf_pt_yield

#define vsf_pt_yield

(

)

Value:

vsf_pt_entry(__vsf_eda_yield();)

Yield the cpu cooperatively: mark a re-entry point and post a VSF_EVT_YIELD event to the current protothread, so that it will be rescheduled.

vsf_pt_raw_next

#define vsf_pt_raw_next

(

)

Value:

__vsf_pt_raw_next_common(__vsf_pt_state())

Set the protothread state to the next re-entry point, without emitting the re-entry label.

Note

Used in pairs with vsf_pt_raw_entry() to implement fast sub-calls (VSF_KERNEL_CFG_EDA_FAST_SUB_CALL is ENABLED).

vsf_pt_raw_entry

#define vsf_pt_raw_entry

(

...

)

Value:

__vsf_pt_raw_entry_common(__vsf_pt_state(), __VA_ARGS__)

Emit a re-entry label, optionally executing the given code first.

Parameters

[in]

...

optional code executed before the re-entry label

Note

Used in pairs with vsf_pt_raw_next() to implement fast sub-calls (VSF_KERNEL_CFG_EDA_FAST_SUB_CALL is ENABLED).

vsf_pt_wait_until

#define vsf_pt_wait_until

(

...

)

Value:

            vsf_pt_entry();                                                     \
            __VA_ARGS__ {} else {                                               \
                return ;                                                        \
            }

Wait cooperatively until the given condition is satisfied.

Note

please use if-then clause in the vsf_pt_wait_until() ! E.g. ! vsf_pt_wait_until( if (...) ); ! ! ! NOTE: wait_for_one(), wait_for_any() and wait_for_all() can be seen as ! an if-then clause. So you can use them directly here. E.g. ! ! vsf_pt_wait_until( wait_for_one(&__user_grouped_evts, sem_evt_msk) ); !

Parameters

[in]

...

the condition to wait for, must be an if-then clause, e.g. vsf_pt_wait_until( if (...) );

Note

If the condition is not satisfied, the protothread returns and resumes here when it is entered again.

__vsf_pt_call_sub

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

Value:

            __vsf_eda_call_eda( (uintptr_t)(__name),                            \
                                (uintptr_t)(__target),                          \
                                (0, ##__VA_ARGS__))

vsf_pt_call_sub

#define vsf_pt_call_sub	(		__name,
			__target )

Value:

            vsf_pt_raw_next();                                                  \
            vsf_err_t VSF_MACRO_SAFE_NAME(ret) =                                \
                __vsf_pt_call_sub(__name, (__target));                          \
            VSF_KERNEL_ASSERT(VSF_ERR_NONE == VSF_MACRO_SAFE_NAME(ret));        \
            return ;                                                            \
            vsf_pt_raw_entry();

Call an event-driven subroutine (sub-eda) from the current protothread, and wait until it finishes.

Parameters

[in]	__name	entry function of the subroutine
[in]	__target	pointer to the target (parameter) of the subroutine

Note

In this variant (VSF_KERNEL_CFG_EDA_FAST_SUB_CALL is ENABLED), the subroutine is dispatched directly. The protothread returns while the subroutine is running, and resumes after it finishes.

vsf_pt_call_pt

#define vsf_pt_call_pt	(		__name,
			__target )

Value:

            (__target)->fsm_state = 0;                                          \
            vsf_pt_call_sub(vsf_pt_func(__name), (__target))

Call another protothread as a subroutine from the current protothread, and wait until it finishes.

Parameters

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

Note

The control block of the sub protothread is reset first.

vsf_eda_call_pt

#define vsf_eda_call_pt	(		__name,
			__target )

Value:

            __vsf_pt_call_sub(vsf_pt_func(__name), (__target))

Call a protothread as a subroutine from an event-driven task (eda), without blocking.

Parameters

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

Returns

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

Note

Used inside a plain eda event handler; inside a protothread please use vsf_pt_call_pt() instead.

__vsf_pt_call_task

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

Value:

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

vsf_pt_call_task

#define vsf_pt_call_task	(		__name,
			__target,
			__ret_addr,
			... )

Value:

        do {                                                                    \
            fsm_rt_t VSF_MCONNECT3(__vsf_pt_call_task,__LINE__,tReturn);        \
            vsf_pt_entry();                                                     \
            VSF_MCONNECT3(__vsf_pt_call_task,__LINE__,tReturn) =                \
                __vsf_pt_call_task(vsf_task_func(__name), (__target), (0, ##__VA_ARGS__));\
            if (fsm_rt_on_going ==                                              \
                VSF_MCONNECT3(__vsf_pt_call_task,__LINE__,tReturn)) {           \
                return ;                                                        \
            }                                                                   \
            if (NULL != (__ret_addr)) {                                         \
                *(__ret_addr) =                                                 \
                    VSF_MCONNECT3(__vsf_pt_call_task,__LINE__,tReturn);         \
            }                                                                   \
        } while(0)

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

Parameters

[in]	__name	name of the sub-task
[in]	__target	pointer to the control block of the sub-task
[out]	__ret_addr	pointer receiving the fsm_rt_t return value of the sub-task, can be NULL
[in]	...	optional size of the local variables of the sub-task frame

Note

The protothread returns while the sub-task is running, and resumes after it finishes. Only available when VSF_KERNEL_CFG_EDA_SUBCALL_HAS_RETURN_VALUE is ENABLED.

vsf_pt_start

#define vsf_pt_start   vsf_teda_start

Start a protothread 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.

Parameters

[in]	__pt	pointer to the protothread, of type vsf_pt_t
[in]	__cfg	pointer to the configuration, of type vsf_eda_cfg_t

Returns

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

Note

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

implement_vsf_pt

#define implement_vsf_pt

(

__name

)

Value:

__implement_vsf_pt(__name)

Start the implementation of the protothread entry function.

Parameters

[in]

__name

name of the protothread

Note

Inside the body, vsf_pthis points to the protothread control block, and vsf_this gives direct access to its members. The body must be bracketed by vsf_pt_begin() and vsf_pt_end().

Used together with def_vsf_pt() and init_vsf_pt().

implement_vsf_pt_ex

#define implement_vsf_pt_ex	(		__name,
			__FUNC_NAME )

Value:

            __implement_vsf_pt_ex(__name, __FUNC_NAME)

Start the implementation of the protothread entry function with a dedicated function name.

Parameters

[in]	__name	name of the protothread
[in]	__FUNC_NAME	function name of the entry function

imp_vsf_pt

#define imp_vsf_pt

(

__name

)

Value:

implement_vsf_pt(__name)

Alias of implement_vsf_pt().

Parameters

[in]

__name

name of the protothread

imp_vsf_pt_ex

#define imp_vsf_pt_ex	(		__name,
			__FUNC_NAME )

Value:

            implement_vsf_pt_ex(__name, __FUNC_NAME)

Alias of implement_vsf_pt_ex().

Parameters

[in]	__name	name of the protothread
[in]	__FUNC_NAME	function name of the entry function

__vsf_pt_func

#define __vsf_pt_func

(

__name

)

Value:

__vsf_pt_func_common(__name)

Expand to the name of the protothread entry function.

Parameters

[in]

__name

name of the protothread

vsf_pt_func

#define vsf_pt_func

(

__name

)

Value:

__vsf_pt_func(__name)

__vsf_pt

#define __vsf_pt

(

__name

)

Value:

__vsf_pt_common(__name)

Expand to the type name of the protothread control block.

Parameters

[in]

__name

name of the protothread

vsf_pt

#define vsf_pt

(

__name

)

Value:

__vsf_pt(__name)

__def_vsf_pt

#define __def_vsf_pt	(		__name,
			... )

Value:

            __def_vsf_pt_common(__name,                                         \
                                uint8_t fsm_state;                              \
                                __VA_ARGS__)

def_vsf_pt

#define def_vsf_pt	(		__name,
			... )

Value:

__def_vsf_pt(__name,__VA_ARGS__)

Define a protothread control block.

Parameters

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

Note

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

Used together with implement_vsf_pt() and init_vsf_pt().

end_def_vsf_pt

#define end_def_vsf_pt

(

...

)

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

define_vsf_pt

#define define_vsf_pt	(		__name,
			... )

Value:

def_vsf_pt(__name,__VA_ARGS__)

Alias of def_vsf_pt().

Parameters

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

end_define_vsf_pt

#define end_define_vsf_pt

(

...

)

Alias of end_def_vsf_pt().

__declare_vsf_pt

#define __declare_vsf_pt

(

__name

)

Value:

            __declare_vsf_pt_common(__name)                                     \
            __extern_vsf_pt_common(__name, uintptr_t local)

declare_vsf_pt

#define declare_vsf_pt

(

__name

)

Value:

__declare_vsf_pt(__name)

Declare a protothread (the protothread class, its control block type and its entry function prototype) before it is defined by def_vsf_pt().

Parameters

[in]

__name

name of the protothread

dcl_vsf_pt

#define dcl_vsf_pt

(

__name

)

Value:

declare_vsf_pt(__name)

Alias of declare_vsf_pt().

Parameters

[in]

__name

name of the protothread

__init_vsf_pt

#define __init_vsf_pt	(		__name,
			__pt,
			__pri,
			... )

Value:

        do {                                                                    \
            vsf_eda_cfg_t VSF_MACRO_SAFE_NAME(cfg) = {                          \
                .fn.evthandler = (vsf_pt_entry_t)__vsf_pt_func(__name),         \
                .priority = (__pri),                                            \
                .target = (uintptr_t)&((__pt)->param),                          \
                __VA_ARGS__                                                     \
            };                                                                  \
            (__pt)->param.fsm_state = 0;                                        \
            vsf_pt_start(&((__pt)->use_as__vsf_pt_t),                           \
                &VSF_MACRO_SAFE_NAME(cfg));                                     \
        } while(0)

vsf_pt_call_thread

#define vsf_pt_call_thread	(		__name,
			__target )

Value:

            vsf_eda_call_thread_prepare(__name, __target);                      \
            vsf_pt_raw_next();                                                  \
            vsf_err_t VSF_MACRO_SAFE_NAME(ret) =                                \
                                vsf_eda_call_thread(__target);                  \
            VSF_KERNEL_ASSERT(VSF_ERR_NONE == VSF_MACRO_SAFE_NAME(ret));        \
            return ;                                                            \
            vsf_pt_raw_entry();

Call a thread from the current protothread, and wait until the thread terminates.

Parameters

[in]	__name	name of the thread type defined by def_vsf_thread()
[in]	__target	pointer to the thread control block

Note

In this variant (VSF_KERNEL_CFG_EDA_FAST_SUB_CALL is ENABLED), the thread is started directly. The protothread returns while the thread is running, and resumes after the thread terminates.

init_vsf_pt

#define init_vsf_pt	(		__name,
			__pt,
			__pri,
			... )

Value:

            __init_vsf_pt(__name, __pt, __pri, __VA_ARGS__)

Prepare and start a protothread defined by def_vsf_pt().

Parameters

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

Note

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

Typedef Documentation

vsf_pt_t

typedef vsf_teda_t vsf_pt_t

Protothread type, alias of vsf_teda_t when VSF_KERNEL_CFG_EDA_SUPPORT_TIMER is ENABLED.

vsf_pt_entry_t

typedef vsf_eda_evthandler_t vsf_pt_entry_t

Protothread entry function, with the eda event handler signature (alias of vsf_eda_evthandler_t)