vsf_fsm.h File Reference

#include "./kernel/vsf_kernel_cfg.h"
#include "utilities/vsf_utilities.h"

Go to the source code of this file.

Macros
#define	VSF_KERNEL_CFG_EDA_SUPPORT_SIMPLE_FSM   DISABLED
#define	vsf_this   (*vsf_pthis)
#define	def_states(...)
	Define the states of a simple fsm as an anonymous enum.
#define	def_params(...)
	Expand to the parameter declarations of the fsm initialiser.
#define	vsf_args(...)
	Expand to extra arguments with a leading comma, used to append arguments to the fsm initialiser call.
#define	vsf_fsm(__name)
	Expand to the type name of the fsm control block.
#define	__def_fsm(__fsm_type, ...)
#define	def_fsm(__name, ...)
	Define an fsm as a vsf task: define the fsm control block and declare its entry function.
#define	def_simple_fsm(__name, ...)
	Declare and define a simple fsm.
#define	end_def_simple_fsm(...)
	End a simple fsm definition started by def_simple_fsm(). It is empty and only used for coding style symmetry.
#define	__declare_fsm(__name)
#define	declare_vsf_fsm(__name)
	Declare an fsm (the fsm class and its control block type) before it is defined by def_simple_fsm().
#define	__extern_fsm_initialiser(__name, ...)
	extern fsm initialisation function and provide function prototype as <__name>_fn, E.g extern_vsf_fsm_initialiser( demo_fsm ); we extern a function called: extern fsm_demo_fsm_t *demo_fsm_init( fsm_demo_fsm_t *fsm_ptr ); and a prototype definition: typedef fsm_demo_fsm_t *demo_fsm_init_fn( fsm_demo_fsm_t *fsm_ptr ); We can then use demo_fsm_init_fn to define function pointer
#define	extern_vsf_fsm_initialiser(__name, ...)
	Declare the initialiser function of an fsm and provide the corresponding function prototype.
#define	call_vsf_fsm(__name, __fsm)
	Call a sub-fsm from the current fsm, and wait until it finishes.
#define	____state(__state, ...)
#define	vsf_state(__state, ...)
	Define a state of the fsm inside vsf_fsm_body() (or between vsf_fsm_begin() and vsf_fsm_end()).
#define	on_start(...)
	Define the code executed once when the fsm starts (state START).
#define	reset_vsf_fsm()
	Reset the fsm to its initial state.
#define	vsf_fsm_cpl()
	Reset the fsm and return fsm_rt_cpl to report completion.
#define	vsf_fsm_report(__ERROR)
	Reset the fsm and return the given value to report an error (or a user-defined result).
#define	vsf_fsm_wait_for_obj()
	Return fsm_rt_wait_for_obj, so the fsm waits for an object (e.g. a semaphore or a mutex).
#define	vsf_fsm_on_going()
	Return fsm_rt_on_going, so the fsm keeps running and resumes at the current state next time.
#define	update_state_to(__state)
	fsm_continue is deprecated, should not be used anymore
#define	transfer_to(__state)
	Set the fsm to the given state and return fsm_rt_on_going, so the target state is executed the next time the fsm runs.
#define	__fsm_initialiser(__name, ...)
#define	vsf_fsm_initialiser(__name, ...)
	Start the implementation of the fsm initialiser function <__name>_init().
#define	abort_vsf_fsm_init()
	Abort the fsm initialiser by returning NULL.
#define	vsf_fsm_init_body(...)
	The body of the fsm initialiser, closed with returning the fsm control block pointer.
#define	init_vsf_fsm(__name, __fsm, ...)
	Initialize an fsm by calling its initialiser <__name>_init().
#define	init_simple_fsm(__name, __fsm, ...)
	Initialize a simple fsm, mapped to init_vsf_fsm().
#define	start_vsf_fsm(__name, __fsm, __pri, ...)
	Prepare and start an fsm as a vsf task.
#define	start_simple_fsm(__name, __fsm, __pri, ...)
	Alias of start_vsf_fsm().
#define	__implement_fsm_ex(__name, __type)
#define	__body(...)
#define	vsf_fsm_body(...)
	The state-switch body of the fsm, containing all the states.
#define	vsf_fsm_begin()
	Begin the state-switch of the fsm, used together with vsf_fsm_end() instead of vsf_fsm_body().
#define	vsf_fsm_end()
	End the state-switch started by vsf_fsm_begin().
#define	implement_fsm_ex(__name, __type)
	Start the implementation of the fsm entry function, with a dedicated fsm type.
#define	__implement_fsm(__name)
#define	implement_vsf_fsm(__name, ...)
	Start the implementation of the fsm entry function.
#define	__privilege_state(__state, ...)
#define	privilege_state(__state, ...)
	Define a privilege state of the fsm: the state code is executed repeatedly within the current call until the state is changed (e.g. by update_state_to() or transfer_to()).
#define	privilege_group(...)
	Define a group of privilege states.
#define	privilege_body(...)
	The privilege state-switch body of the fsm: the states are executed in a loop within the current call, until a state returns (e.g. by transfer_to() or vsf_fsm_cpl()).
#define	__FSM_RT_TYPE__
#define	__extern_fsm_implementation_ex(__name, __type)
	extern fsm task function and provide function prototype as <__name>_fn, E.g extern_vsf_fsm_implementation( demo_fsm ); we extern a function called: fsm_rt_t demo_fsm( fsm_demo_fsm_t *fsm_ptr ) and a prototype definition: typedef fsm_rt_t demo_fsm_fn (fsm_demo_fsm_t *fsm_ptr); We can then use demo_fsm_fn to define function pointer
#define	declare_vsf_fsm_implementation_ex(__name, __type)
	Declare the entry function of an fsm implementation and provide the corresponding function prototype, with a dedicated fsm type.
#define	extern_vsf_fsm_implementation_ex(__name, __type)
	Alias of declare_vsf_fsm_implementation_ex().
#define	extern_vsf_fsm_implementation(__name)
	Declare the entry function of an fsm implementation and provide the corresponding function prototype.
#define	declare_vsf_fsm_implementation(__name)
	Alias of extern_vsf_fsm_implementation().

Enumerations
finit vsf_state machine vsf_state
enum	fsm_rt_t {   fsm_rt_err = -1 ,   fsm_rt_cpl = 0 ,   fsm_rt_on_going = 1 ,   fsm_rt_wait_for_obj = 2 ,   fsm_rt_asyn = 3 }

Macro Definition Documentation

VSF_KERNEL_CFG_EDA_SUPPORT_SIMPLE_FSM

#define VSF_KERNEL_CFG_EDA_SUPPORT_SIMPLE_FSM   DISABLED

vsf_this

#define vsf_this   (*vsf_pthis)

def_states

#define def_states

(

...

)

Value:

        enum {                                                                  \
            START = 0,                                                          \
            __VA_ARGS__                                                         \
        };

Define the states of a simple fsm as an anonymous enum.

Parameters

[in]

...

the state names

Note

The first enumerator START is 0, which is the initial state.

def_params

#define def_params

(

...

)

Value:

__VA_ARGS__

Expand to the parameter declarations of the fsm initialiser.

Parameters

[in]

...

the parameter declarations

vsf_args

#define vsf_args

(

...

)

Value:

,__VA_ARGS__

Expand to extra arguments with a leading comma, used to append arguments to the fsm initialiser call.

Parameters

[in]

...

the extra arguments

vsf_fsm

#define vsf_fsm

(

__name

)

Value:

vsf_task(__name)

Expand to the type name of the fsm control block.

Parameters

[in]

__name

name of the fsm

__def_fsm

#define __def_fsm	(		__fsm_type,
			... )

Value:

        def_vsf_task(__fsm_type,                                                \
            __VA_ARGS__);

def_fsm

#define def_fsm	(		__name,
			... )

Value:

        __def_fsm(__name, __VA_ARGS__)

Define an fsm as a vsf task: define the fsm control block and declare its entry function.

Parameters

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

Note

Based on def_vsf_task(); used together with implement_vsf_fsm() and start_vsf_fsm().

def_simple_fsm

#define def_simple_fsm	(		__name,
			... )

Value:

        __declare_fsm(__name);                                                  \
        __def_fsm(__name, __VA_ARGS__)

Declare and define a simple fsm.

Parameters

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

end_def_simple_fsm

#define end_def_simple_fsm

(

...

)

End a simple fsm definition started by def_simple_fsm(). It is empty and only used for coding style symmetry.

__declare_fsm

#define __declare_fsm

(

__name

)

Value:

        declare_vsf_task(__name)

declare_vsf_fsm

#define declare_vsf_fsm

(

__name

)

Value:

__declare_fsm(__name)

Declare an fsm (the fsm class and its control block type) before it is defined by def_simple_fsm().

Parameters

[in]

__name

name of the fsm

__extern_fsm_initialiser

#define __extern_fsm_initialiser	(		__name,
			... )

Value:

        vsf_fsm(__name) *__name##_init(vsf_fsm(__name) *fsm_ptr __VA_ARGS__);           \
        typedef vsf_fsm(__name) *__name##_init_fn(vsf_fsm(__name) *fsm_ptr __VA_ARGS__);

extern fsm initialisation function and provide function prototype as <__name>_fn, E.g extern_vsf_fsm_initialiser( demo_fsm ); we extern a function called: extern fsm_demo_fsm_t *demo_fsm_init( fsm_demo_fsm_t *fsm_ptr ); and a prototype definition: typedef fsm_demo_fsm_t *demo_fsm_init_fn( fsm_demo_fsm_t *fsm_ptr ); We can then use demo_fsm_init_fn to define function pointer

extern_vsf_fsm_initialiser

#define extern_vsf_fsm_initialiser	(		__name,
			... )

Value:

            __extern_fsm_initialiser(__name, __VA_ARGS__)

Declare the initialiser function of an fsm and provide the corresponding function prototype.

Parameters

[in]	__name	name of the fsm
[in]	...	optional extra parameters of the initialiser, declared with def_params()

Note

It declares a function <__name>_init() returning a pointer to the fsm control block, and a function prototype typedef <__name>_init_fn, which can be used to define function pointers.

__extern_fsm_implementation_ex

#define __extern_fsm_implementation_ex	(		__name,
			__type )

Value:

        fsm_rt_t __name(fsm(__type) *vsf_pthis, vsf_evt_t evt);                 \
        typedef fsm_rt_t __name##_fn( vsf_fsm(__type) *vsf_pthis, vsf_evt_t evt );

extern fsm task function and provide function prototype as <__name>_fn, E.g extern_vsf_fsm_implementation( demo_fsm ); we extern a function called: fsm_rt_t demo_fsm( fsm_demo_fsm_t *fsm_ptr ) and a prototype definition: typedef fsm_rt_t demo_fsm_fn (fsm_demo_fsm_t *fsm_ptr); We can then use demo_fsm_fn to define function pointer

declare_vsf_fsm_implementation_ex

#define declare_vsf_fsm_implementation_ex	(		__name,
			__type )

Value:

            __extern_fsm_implementation_ex(__name, __type)

Declare the entry function of an fsm implementation and provide the corresponding function prototype, with a dedicated fsm type.

Parameters

[in]	__name	name of the fsm entry function
[in]	__type	name of the fsm type

Note

It declares a function <__name>() returning fsm_rt_t, and a function prototype typedef <__name>_fn, which can be used to define function pointers.

extern_vsf_fsm_implementation_ex

#define extern_vsf_fsm_implementation_ex	(		__name,
			__type )

Value:

            __extern_fsm_implementation_ex(__name, __type)

Alias of declare_vsf_fsm_implementation_ex().

Parameters

[in]	__name	name of the fsm entry function
[in]	__type	name of the fsm type

extern_vsf_fsm_implementation

#define extern_vsf_fsm_implementation

(

__name

)

Value:

            __extern_fsm_implementation_ex(__name, __name)

Declare the entry function of an fsm implementation and provide the corresponding function prototype.

Parameters

[in]

__name

name of the fsm

declare_vsf_fsm_implementation

#define declare_vsf_fsm_implementation

(

__name

)

Value:

            __extern_fsm_implementation_ex(__name, __name)

Alias of extern_vsf_fsm_implementation().

Parameters

[in]

__name

name of the fsm

call_vsf_fsm

#define call_vsf_fsm	(		__name,
			__fsm )

Value:

            vsf_task_call_task(__name, __fsm)

Call a sub-fsm from the current fsm, and wait until it finishes.

Parameters

[in]	__name	name of the sub-fsm
[in]	__fsm	pointer to the control block of the sub-fsm

Returns

fsm_rt_t: the return value of the sub-fsm when it finishes

Note

Based on vsf_task_call_task().

____state

#define ____state	(		__state,
			... )

Value:

            case __state:                                                       \
        __state_entry_##__state:{                                               \
                __VA_ARGS__;                                                    \
            };

vsf_state

#define vsf_state	(		__state,
			... )

Value:

break; ____state(__state, __VA_ARGS__)

Define a state of the fsm inside vsf_fsm_body() (or between vsf_fsm_begin() and vsf_fsm_end()).

Parameters

[in]	__state	name of the state, defined by def_states()
[in]	...	the code executed in this state

on_start

#define on_start

(

...

)

Value:

{__VA_ARGS__;}

Define the code executed once when the fsm starts (state START).

Parameters

[in]

...

the code executed on start

reset_vsf_fsm

#define reset_vsf_fsm

(

)

Value:

do { vsf_this.fsm_state = 0; } while(0);

Reset the fsm to its initial state.

vsf_fsm_cpl

#define vsf_fsm_cpl

(

)

Value:

do {reset_vsf_fsm(); return fsm_rt_cpl;} while(0);

Reset the fsm and return fsm_rt_cpl to report completion.

vsf_fsm_report

#define vsf_fsm_report

(

__ERROR

)

Value:

do {reset_vsf_fsm(); return (fsm_rt_t)(__ERROR); } while(0);

Reset the fsm and return the given value to report an error (or a user-defined result).

Parameters

[in]

__ERROR

the value returned as fsm_rt_t

vsf_fsm_wait_for_obj

#define vsf_fsm_wait_for_obj

(

)

Value:

return fsm_rt_wait_for_obj;

Return fsm_rt_wait_for_obj, so the fsm waits for an object (e.g. a semaphore or a mutex).

vsf_fsm_on_going

#define vsf_fsm_on_going

(

)

Value:

return fsm_rt_on_going;

Return fsm_rt_on_going, so the fsm keeps running and resumes at the current state next time.

update_state_to

#define update_state_to

(

__state

)

Value:

        { vsf_this.fsm_state = (__state); goto __state_entry_##__state;}

fsm_continue is deprecated, should not be used anymore

Set the fsm to the given state and jump to its entry within the current call.

Parameters

[in]

__state

name of the target state, defined by def_states()

Note

The code of the target state is executed immediately in the current call, without returning from the entry function.

transfer_to

#define transfer_to

(

__state

)

Value:

         { vsf_this.fsm_state = (__state); vsf_fsm_on_going() }

Set the fsm to the given state and return fsm_rt_on_going, so the target state is executed the next time the fsm runs.

Parameters

[in]

__state

name of the target state, defined by def_states()

__fsm_initialiser

#define __fsm_initialiser	(		__name,
			... )

Value:

        vsf_fsm(__name) *__name##_init(vsf_fsm(__name) *vsf_pthis __VA_ARGS__)  \
        {                                                                       \
            VSF_KERNEL_ASSERT (NULL != vsf_pthis);                              \
            vsf_this.fsm_state = 0;

vsf_fsm_initialiser

#define vsf_fsm_initialiser	(		__name,
			... )

Value:

            __fsm_initialiser(__name, __VA_ARGS__)

Start the implementation of the fsm initialiser function <__name>_init().

Parameters

[in]	__name	name of the fsm
[in]	...	optional extra parameters of the initialiser, declared with def_params()

Note

The fsm control block is checked against NULL and reset first. The body must be closed by vsf_fsm_init_body().

abort_vsf_fsm_init

#define abort_vsf_fsm_init

(

)

Value:

return NULL;

Abort the fsm initialiser by returning NULL.

Note

Used inside the fsm initialiser when the initialisation fails.

vsf_fsm_init_body

#define vsf_fsm_init_body

(

...

)

Value:

            __VA_ARGS__                                                         \
            return &vsf_this;                                                   \
        }

The body of the fsm initialiser, closed with returning the fsm control block pointer.

Parameters

[in]

...

the initialisation code

init_vsf_fsm

#define init_vsf_fsm	(		__name,
			__fsm,
			... )

Value:

        __name##_init(__fsm __VA_ARGS__)

Initialize an fsm by calling its initialiser <__name>_init().

Parameters

[in]	__name	name of the fsm
[in]	__fsm	pointer to the fsm control block
[in]	...	optional extra arguments of the initialiser

Returns

pointer to the fsm control block, or NULL if aborted

init_simple_fsm

#define init_simple_fsm	(		__name,
			__fsm,
			... )

Value:

        init_vsf_fsm(__name, __fsm, __VA_ARGS__)

Initialize a simple fsm, mapped to init_vsf_fsm().

Parameters

[in]	__name	name of the fsm
[in]	__fsm	pointer to the fsm control block
[in]	...	optional extra arguments of the initialiser

start_vsf_fsm

#define start_vsf_fsm	(		__name,
			__fsm,
			__pri,
			... )

Value:

            init_vsf_task(__name, (__fsm), (__pri), __VA_ARGS__)

Prepare and start an fsm as a vsf task.

Parameters

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

Note

Mapped to init_vsf_task(); the fsm entry function will receive a VSF_EVT_INIT event.

start_simple_fsm

#define start_simple_fsm	(		__name,
			__fsm,
			__pri,
			... )

Value:

            start_vsf_fsm(__name, (__fsm), (__pri), __VA_ARGS__)

Alias of start_vsf_fsm().

Parameters

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

__implement_fsm_ex

#define __implement_fsm_ex	(		__name,
			__type )

Value:

    implement_vsf_task(__name)                                                  \
    {                                                                           \
        vsf_task_begin();                                                       \
        if (NULL == vsf_pthis) {                                                \
            return fsm_rt_err;                                                  \
        }

__body

#define __body

(

...

)

Value:

        switch (vsf_this.fsm_state) {                                           \
            case 0:                                                             \
                vsf_this.fsm_state++;                                           \
            __VA_ARGS__                                                         \
            break;                                                              \
            default:                                                            \
            return fsm_rt_err;                                                  \
        }                                                                       \
                                                                                \
        vsf_task_end();                                                         \
    }

vsf_fsm_body

#define vsf_fsm_body

(

...

)

Value:

__body(__VA_ARGS__)

The state-switch body of the fsm, containing all the states.

Parameters

[in]

...

the states defined by vsf_state()

Note

It dispatches on the current fsm state; an unknown state returns fsm_rt_err. Used inside implement_vsf_fsm().

vsf_fsm_begin

#define vsf_fsm_begin

(

)

Value:

            switch (vsf_this.fsm_state) {                                       \
                case 0:                                                         \
                    vsf_this.fsm_state++;

Begin the state-switch of the fsm, used together with vsf_fsm_end() instead of vsf_fsm_body().

Note

Compared with vsf_fsm_body(), the code between vsf_fsm_begin() and vsf_fsm_end() can be debugged (break points and single-step).

vsf_fsm_end

#define vsf_fsm_end

(

)

Value:

                break;                                                          \
                default:                                                        \
                return fsm_rt_err;                                              \
            }                                                                   \
        }vsf_task_end()

End the state-switch started by vsf_fsm_begin().

Note

An unknown state returns fsm_rt_err.

implement_fsm_ex

#define implement_fsm_ex	(		__name,
			__type )

Value:

            __implement_fsm_ex(__name, __type)

Start the implementation of the fsm entry function, with a dedicated fsm type.

Note

Debug Support: You can use body_begin() together with body_end() ! to enable debug, this means you are ale to set break ! points and single-step into those states. ! ! Example:

  vsf_fsm_begin()
      vsf_state(xxxxx,

the range no debug is allowed )

vsf_state(xxxxx){ the range you can debug with }

vsf_fsm_end()

Parameters

[in]	__name	name of the fsm entry function
[in]	__type	name of the fsm type

Note

Based on implement_vsf_task(); the entry returns fsm_rt_err if the fsm control block pointer is NULL. The body is formed by vsf_fsm_body() or vsf_fsm_begin()/vsf_fsm_end().

__implement_fsm

#define __implement_fsm

(

__name

)

Value:

            implement_fsm_ex(__name, __name)

implement_vsf_fsm

#define implement_vsf_fsm	(		__name,
			... )

Value:

__implement_fsm(__name)

Start the implementation of the fsm entry function.

Parameters

[in]	__name	name of the fsm
[in]	...	unused, kept for symmetry

Note

Based on implement_vsf_task(); the entry returns fsm_rt_err if the fsm control block pointer is NULL. The body is formed by vsf_fsm_body() or vsf_fsm_begin()/vsf_fsm_end().

__privilege_state

#define __privilege_state	(		__state,
			... )

Value:

            break;do {                                                          \
                do {                                                            \
                    ____state(__state, __VA_ARGS__)                             \
                } while(0); /* add extra while(0) to catch the fsm_continue()*/ \
                if (vsf_this.fsm_state != (__state)) {                          \
                    break;                                                      \
                }                                                               \
            } while(1);

privilege_state

#define privilege_state	(		__state,
			... )

Value:

            __privilege_state(__state, __VA_ARGS__)

Define a privilege state of the fsm: the state code is executed repeatedly within the current call until the state is changed (e.g. by update_state_to() or transfer_to()).

Parameters

[in]	__state	name of the state, defined by def_states()
[in]	...	the code executed in this state

privilege_group

#define privilege_group

(

...

)

Value:

{ __VA_ARGS__;}

Define a group of privilege states.

Parameters

[in]

...

the privilege states defined by privilege_state()

privilege_body

#define privilege_body

(

...

)

Value:

        do {                                                                    \
            switch (vsf_this.fsm_state) {                                       \
                case 0:                                                         \
                    vsf_this.fsm_state++;                                       \
                __VA_ARGS__                                                     \
            }                                                                   \
        while(1);                                                               \
                                                                                \
        return fsm_rt_on_going;                                                 \
    }

The privilege state-switch body of the fsm: the states are executed in a loop within the current call, until a state returns (e.g. by transfer_to() or vsf_fsm_cpl()).

Parameters

[in]

...

the states defined by vsf_state() or privilege_state()

Note

If the loop ever breaks, fsm_rt_on_going is returned.

__FSM_RT_TYPE__

#define __FSM_RT_TYPE__

Enumeration Type Documentation

fsm_rt_t

enum fsm_rt_t

Enumerator
fsm_rt_err	fsm error, error code can be get from other interface
fsm_rt_cpl	fsm complete
fsm_rt_on_going	fsm on-going
fsm_rt_wait_for_obj	fsm wait for object
fsm_rt_asyn	fsm asynchronose complete, you can check it later.