VSF Documented
vsf_eda.c File Reference

Data Structures

struct  vsf_local_t
 

Macros

#define __VSF_EDA_CLASS_IMPLEMENT
 
#define __VSF_KERNEL_TASK
 
#define __EDA_GADGET__
 

Typedefs

typedef struct vsf_local_t vsf_local_t
 

Functions

vsf_evtq_t__vsf_os_evtq_get (vsf_prio_t priority)
 
vsf_err_t __vsf_os_evtq_set_priority (vsf_evtq_t *pthis, vsf_prio_t priority)
 
vsf_err_t __vsf_os_evtq_activate (vsf_evtq_t *pthis)
 
vsf_err_t __vsf_os_evtq_init (vsf_evtq_t *pthis)
 
vsf_prio_t __vsf_os_evtq_get_priority (vsf_evtq_t *pthis)
 
void __vsf_eda_task_evthandler_process_return_value (vsf_eda_t *eda, vsf_evt_t evt)
 
__vsf_eda_frame_tvsf_eda_new_frame (size_t local_size)
 should be provided by user
 
void vsf_eda_free_frame (__vsf_eda_frame_t *frame)
 
void vsf_kernel_err_report (enum vsf_kernel_error_t err)
 Report a kernel error.
 
uintptr_t vsf_irq_enter (void)
 Notify the kernel of entering interrupt context.
 
void vsf_irq_leave (uintptr_t ctx)
 Notify the kernel of leaving interrupt context.
 
void __vsf_eda_on_terminate (vsf_eda_t *pthis)
 
void vsf_kernel_init (const vsf_kernel_cfg_t *cfg_ptr)
 
void __vsf_dispatch_evt (vsf_eda_t *pthis, vsf_evt_t evt)
 
vsf_evtq_t__vsf_get_cur_evtq (void)
 
vsf_evtq_t__vsf_set_cur_evtq (vsf_evtq_t *evtq)
 
vsf_eda_tvsf_eda_get_cur (void)
 Get the eda task currently being dispatched.
 
bool vsf_eda_polling_state_get (vsf_eda_t *pthis)
 
void vsf_eda_polling_state_set (vsf_eda_t *pthis, bool state)
 
bool vsf_eda_is_stack_owner (vsf_eda_t *pthis)
 Check whether an eda owns a dedicated stack.
 
vsf_evt_t vsf_eda_get_cur_evt (void)
 Get the event currently being processed by the current task.
 
void * vsf_eda_get_cur_msg (void)
 Get the pointer message carried by the current event (e.g. VSF_EVT_MESSAGE)
 
uintptr_t vsf_eda_get_return_value (void)
 Get the return value passed back by the sub-called task.
 
bool __vsf_eda_return (uintptr_t return_value)
 Return from the current (sub-called) eda with the given return value.
 
void __vsf_eda_yield (void)
 Yield the current task by posting VSF_EVT_YIELD to itself, so that it is dispatched again later.
 
void vsf_eda_set_user_value (uint8_t value)
 Set the user-defined bits in the feature of the current eda.
 
uint8_t vsf_eda_get_user_value (void)
 Get the user-defined bits in the feature of the current eda.
 
uintptr_t __vsf_eda_get_local (vsf_eda_t *pthis)
 Get the local variable storage of a frame-based eda.
 
vsf_err_t vsf_eda_target_set (uintptr_t param)
 Set the target parameter of the current frame of the current task.
 
uintptr_t vsf_eda_target_get (void)
 Get the target parameter of the current frame of the current task.
 
vsf_err_t __vsf_eda_call_eda_ex_prepare (uintptr_t func, uintptr_t param, __vsf_eda_frame_state_t state, bool is_sub_call)
 Prepare an extended sub-call frame without dispatching VSF_EVT_INIT.
 
vsf_err_t __vsf_eda_call_eda_prepare (uintptr_t evthandler, uintptr_t param, size_t local_size)
 Prepare a sub-call frame without dispatching VSF_EVT_INIT.
 
vsf_err_t __vsf_eda_call_eda_ex (uintptr_t func, uintptr_t param, __vsf_eda_frame_state_t state, bool is_sub_call)
 Extended sub-call: prepare a frame and dispatch VSF_EVT_INIT.
 
vsf_err_t __vsf_eda_go_to_ex (uintptr_t evthandler, uintptr_t param)
 Switch the current frame to a new event handler with a target parameter and dispatch VSF_EVT_INIT.
 
vsf_err_t __vsf_eda_call_eda (uintptr_t evthandler, uintptr_t param, size_t local_size)
 Sub-call an event handler: prepare a frame and dispatch VSF_EVT_INIT.
 
vsf_err_t vsf_eda_set_evthandler (vsf_eda_t *pthis, vsf_eda_evthandler_t evthandler)
 
vsf_err_t vsf_eda_go_to (uintptr_t evthandler)
 Switch the current task to a new event handler and post VSF_EVT_INIT to it.
 
vsf_err_t __vsf_eda_init (vsf_eda_t *pthis, vsf_prio_t priority, vsf_eda_feature_t feature)
 
vsf_err_t vsf_eda_start (vsf_eda_t *pthis, vsf_eda_cfg_t *cfg_ptr)
 Start an eda task with the given configuration and post VSF_EVT_INIT to it.
 
vsf_err_t vsf_eda_fini (vsf_eda_t *pthis)
 
vsf_err_t vsf_eda_post_evt (vsf_eda_t *pthis, vsf_evt_t evt)
 Post an event to an eda task.
 
vsf_err_t __vsf_eda_post_evt_ex (vsf_eda_t *pthis, vsf_evt_t evt, bool force)
 
vsf_err_t vsf_eda_post_msg (vsf_eda_t *pthis, void *msg)
 Post a pointer message to an eda task; the task receives VSF_EVT_MESSAGE and retrieves the pointer with vsf_eda_get_cur_msg()
 
vsf_err_t vsf_eda_post_evt_msg (vsf_eda_t *pthis, vsf_evt_t evt, void *msg)
 Post an event carrying a pointer message to an eda task; the pointer is retrieved with vsf_eda_get_cur_msg()
 
void vsf_eda_cpu_usage_start (vsf_eda_t *pthis, vsf_cpu_usage_ctx_t *ctx)
 Start measuring the CPU usage of an eda task.
 
void vsf_eda_cpu_usage_stop (vsf_eda_t *pthis)
 Stop measuring the CPU usage of an eda task.
 
vsf_err_t vsf_kernel_start (void)
 

Macro Definition Documentation

◆ __VSF_EDA_CLASS_IMPLEMENT

#define __VSF_EDA_CLASS_IMPLEMENT

◆ __VSF_KERNEL_TASK

#define __VSF_KERNEL_TASK

◆ __EDA_GADGET__

#define __EDA_GADGET__

Typedef Documentation

◆ vsf_local_t

typedef struct vsf_local_t vsf_local_t

Function Documentation

◆ __vsf_os_evtq_get()

vsf_evtq_t * __vsf_os_evtq_get ( vsf_prio_t priority)
extern

◆ __vsf_os_evtq_set_priority()

vsf_err_t __vsf_os_evtq_set_priority ( vsf_evtq_t * pthis,
vsf_prio_t priority )
extern

◆ __vsf_os_evtq_activate()

vsf_err_t __vsf_os_evtq_activate ( vsf_evtq_t * pthis)
extern

◆ __vsf_os_evtq_init()

vsf_err_t __vsf_os_evtq_init ( vsf_evtq_t * pthis)
extern

◆ __vsf_os_evtq_get_priority()

vsf_prio_t __vsf_os_evtq_get_priority ( vsf_evtq_t * pthis)
extern

◆ __vsf_eda_task_evthandler_process_return_value()

void __vsf_eda_task_evthandler_process_return_value ( vsf_eda_t * eda,
vsf_evt_t evt )
extern

< no param

< no local

< it is a pure eda

return fsm_rt_err

call sub fsm later

delay, wait_for, mutex_pend, sem_pend and etc...

◆ vsf_eda_new_frame()

__vsf_eda_frame_t * vsf_eda_new_frame ( size_t local_size)
extern

should be provided by user

make sure local_size is aligned with sizeof(uintalu_t);

this is important, don't remove it.

add watermark for local buffer overflow detection, please never remove this!!! as local size could be zero

◆ vsf_eda_free_frame()

void vsf_eda_free_frame ( __vsf_eda_frame_t * frame)
extern

◆ vsf_kernel_err_report()

void vsf_kernel_err_report ( enum vsf_kernel_error_t err)
extern

Report a kernel error.

Parameters
[in]errthe kernel error of type vsf_kernel_error_t
Note
Weak function, can be re-implemented by defining WEAK_VSF_KERNEL_ERR_REPORT.

◆ vsf_irq_enter()

uintptr_t vsf_irq_enter ( void )

Notify the kernel of entering interrupt context.

Returns
uintptr_t: a context value which must be passed back to vsf_irq_leave()

◆ vsf_irq_leave()

void vsf_irq_leave ( uintptr_t ctx)

Notify the kernel of leaving interrupt context.

Parameters
[in]ctxthe context value returned by vsf_irq_enter()
Returns
none

◆ __vsf_eda_on_terminate()

void __vsf_eda_on_terminate ( vsf_eda_t * pthis)

◆ vsf_kernel_init()

void vsf_kernel_init ( const vsf_kernel_cfg_t * cfg_ptr)

◆ __vsf_dispatch_evt()

void __vsf_dispatch_evt ( vsf_eda_t * pthis,
vsf_evt_t evt )

< no param

< no local

< this is a pure eda

◆ __vsf_get_cur_evtq()

vsf_evtq_t * __vsf_get_cur_evtq ( void )

◆ __vsf_set_cur_evtq()

vsf_evtq_t * __vsf_set_cur_evtq ( vsf_evtq_t * evtq)

◆ vsf_eda_get_cur()

vsf_eda_t * vsf_eda_get_cur ( void )

Get the eda task currently being dispatched.

Returns
vsf_eda_t *: pointer to the current vsf_eda_t, NULL if not in task context
Note
Can be called in any context; returns NULL when not in eda task context.

◆ vsf_eda_polling_state_get()

bool vsf_eda_polling_state_get ( vsf_eda_t * pthis)

◆ vsf_eda_polling_state_set()

void vsf_eda_polling_state_set ( vsf_eda_t * pthis,
bool state )

◆ vsf_eda_is_stack_owner()

bool vsf_eda_is_stack_owner ( vsf_eda_t * pthis)

Check whether an eda owns a dedicated stack.

Parameters
[in]pthisa pointer to structure vsf_eda_t
Returns
bool: true if the eda owns a dedicated stack
Note
Only available when VSF_KERNEL_USE_SIMPLE_SHELL is ENABLED.

◆ vsf_eda_get_cur_evt()

vsf_evt_t vsf_eda_get_cur_evt ( void )

Get the event currently being processed by the current task.

Returns
vsf_evt_t: the current event
Note
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ vsf_eda_get_cur_msg()

void * vsf_eda_get_cur_msg ( void )

Get the pointer message carried by the current event (e.g. VSF_EVT_MESSAGE)

Returns
void *: the message pointer posted with the current event
Note
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ vsf_eda_get_return_value()

uintptr_t vsf_eda_get_return_value ( void )

Get the return value passed back by the sub-called task.

Returns
uintptr_t: the return value set by vsf_eda_return()
Note
Only available when VSF_KERNEL_CFG_EDA_SUPPORT_SUB_CALL is ENABLED.
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ __vsf_eda_return()

bool __vsf_eda_return ( uintptr_t return_value)

Return from the current (sub-called) eda with the given return value.

Parameters
[in]return_valuereturn value passed back to the caller
Returns
bool: true if the current task is terminated (no caller), false if control is returned to the caller
Note
Internal use only. Use the macro vsf_eda_return() instead.
Operates on the current task; must be called in the current eda/teda task's event handler context.
Note
automatically free a frame if the top eda doesn't set ! is_use_frame

< top frame

< not force frame

◆ __vsf_eda_yield()

void __vsf_eda_yield ( void )

Yield the current task by posting VSF_EVT_YIELD to itself, so that it is dispatched again later.

Returns
none
Note
Internal use only.
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ vsf_eda_set_user_value()

void vsf_eda_set_user_value ( uint8_t value)

Set the user-defined bits in the feature of the current eda.

Parameters
[in]valuethe user value to set, up to VSF_KERNEL_CFG_EDA_USER_BITLEN bits
Returns
none
Note
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ vsf_eda_get_user_value()

uint8_t vsf_eda_get_user_value ( void )

Get the user-defined bits in the feature of the current eda.

Returns
uint8_t: the user value previously set by vsf_eda_set_user_value()
Note
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ __vsf_eda_get_local()

uintptr_t __vsf_eda_get_local ( vsf_eda_t * pthis)

Get the local variable storage of a frame-based eda.

Parameters
[in]pthisa pointer to structure vsf_eda_t
Returns
uintptr_t: address of the local storage, NULL if the task has no local storage
Note
Internal use only. Use the macro vsf_eda_get_local() instead. Only available when VSF_KERNEL_CFG_EDA_SUPPORT_SUB_CALL is ENABLED.
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ vsf_eda_target_set()

vsf_err_t vsf_eda_target_set ( uintptr_t param)

Set the target parameter of the current frame of the current task.

Parameters
[in]paramthe target parameter to set
Returns
vsf_err_t: VSF_ERR_NONE if successful, VSF_ERR_NOT_ENOUGH_RESOURCES if no frame is available
Note
Only available when VSF_KERNEL_CFG_EDA_SUPPORT_SUB_CALL is ENABLED.
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ vsf_eda_target_get()

uintptr_t vsf_eda_target_get ( void )

Get the target parameter of the current frame of the current task.

Returns
uintptr_t: the target parameter, NULL if the current task uses no frame
Note
Only available when VSF_KERNEL_CFG_EDA_SUPPORT_SUB_CALL is ENABLED.
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ __vsf_eda_call_eda_ex_prepare()

vsf_err_t __vsf_eda_call_eda_ex_prepare ( uintptr_t func,
uintptr_t param,
__vsf_eda_frame_state_t state,
bool is_sub_call )

Prepare an extended sub-call frame without dispatching VSF_EVT_INIT.

Parameters
[in]funcaddress of the handler function to call
[in]paramtarget parameter of the new frame
[in]stateframe state __vsf_eda_frame_state_t (feature and local size)
[in]is_sub_calltrue for a sub-call (new frame), false to reuse the current frame
Returns
vsf_err_t: VSF_ERR_NONE if the frame is prepared, VSF_ERR_NOT_ENOUGH_RESOURCES if no frame is available
Note
Internal use only. Only available when VSF_KERNEL_CFG_EDA_SUPPORT_SUB_CALL is ENABLED.
Operates on the current task; must be called in the current eda/teda task's event handler context.
Note
please NEVER do following things. If param is NULL, please let frame->param to be NULL

if (NULL == param) { frame->param = pthis; //!< point to the current eda } else { frame->param = param; }

◆ __vsf_eda_call_eda_prepare()

vsf_err_t __vsf_eda_call_eda_prepare ( uintptr_t evthandler,
uintptr_t param,
size_t local_size )

Prepare a sub-call frame without dispatching VSF_EVT_INIT.

Parameters
[in]evthandleraddress of the event handler to call
[in]paramtarget parameter of the new frame
[in]local_sizesize of the local variable storage
Returns
vsf_err_t: VSF_ERR_NONE if the frame is prepared, VSF_ERR_NOT_ENOUGH_RESOURCES if no frame is available
Note
Internal use only. Only available when VSF_KERNEL_CFG_EDA_SUPPORT_SUB_CALL is ENABLED.
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ __vsf_eda_call_eda_ex()

vsf_err_t __vsf_eda_call_eda_ex ( uintptr_t func,
uintptr_t param,
__vsf_eda_frame_state_t state,
bool is_sub_call )

Extended sub-call: prepare a frame and dispatch VSF_EVT_INIT.

Parameters
[in]funcaddress of the handler function to call
[in]paramtarget parameter of the new frame
[in]stateframe state __vsf_eda_frame_state_t (feature and local size)
[in]is_sub_calltrue for a sub-call (new frame), false to reuse the current frame
Returns
vsf_err_t: VSF_ERR_NONE if the call is started, VSF_ERR_NOT_ENOUGH_RESOURCES if no frame is available
Note
Internal use only. Only available when VSF_KERNEL_CFG_EDA_SUPPORT_SUB_CALL is ENABLED.
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ __vsf_eda_go_to_ex()

vsf_err_t __vsf_eda_go_to_ex ( uintptr_t evthandler,
uintptr_t param )

Switch the current frame to a new event handler with a target parameter and dispatch VSF_EVT_INIT.

Parameters
[in]evthandleraddress of the new event handler
[in]paramtarget parameter
Returns
vsf_err_t: VSF_ERR_NONE if started successfully; VSF_ERR_NOT_ENOUGH_RESOURCES if no frame is available
Note
Internal use only. Only available when VSF_KERNEL_CFG_EDA_SUPPORT_SUB_CALL is ENABLED.
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ __vsf_eda_call_eda()

vsf_err_t __vsf_eda_call_eda ( uintptr_t evthandler,
uintptr_t param,
size_t local_size )

Sub-call an event handler: prepare a frame and dispatch VSF_EVT_INIT.

Parameters
[in]evthandleraddress of the event handler to call
[in]paramtarget parameter of the new frame
[in]local_sizesize of the local variable storage
Returns
vsf_err_t: VSF_ERR_NONE if the sub-call is started, VSF_ERR_NOT_ENOUGH_RESOURCES if no frame is available
Note
Internal use only. Use the macros vsf_eda_call_eda() or vsf_eda_call_param_eda() instead. Only available when VSF_KERNEL_CFG_EDA_SUPPORT_SUB_CALL is ENABLED.
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ vsf_eda_set_evthandler()

vsf_err_t vsf_eda_set_evthandler ( vsf_eda_t * pthis,
vsf_eda_evthandler_t evthandler )

◆ vsf_eda_go_to()

vsf_err_t vsf_eda_go_to ( uintptr_t evthandler)

Switch the current task to a new event handler and post VSF_EVT_INIT to it.

Parameters
[in]evthandleraddress of the new event handler vsf_eda_evthandler_t
Returns
vsf_err_t: always VSF_ERR_NONE
Note
Operates on the current task; must be called in the current eda/teda task's event handler context.

◆ __vsf_eda_init()

vsf_err_t __vsf_eda_init ( vsf_eda_t * pthis,
vsf_prio_t priority,
vsf_eda_feature_t feature )

◆ vsf_eda_start()

vsf_err_t vsf_eda_start ( vsf_eda_t * pthis,
vsf_eda_cfg_t * cfg )

Start an eda task with the given configuration and post VSF_EVT_INIT to it.

Parameters
[in]pthisa pointer to structure vsf_eda_t
[in]cfga pointer to structure vsf_eda_cfg_t holding the task configuration
Returns
vsf_err_t: VSF_ERR_NONE if successful, VSF_ERR_NOT_ENOUGH_RESOURCES if no frame is available for a frame-based task
Note
Must be called in task (or initialization) context, NOT in interrupt context.

override the is_use_frame flag

◆ vsf_eda_fini()

vsf_err_t vsf_eda_fini ( vsf_eda_t * pthis)

◆ vsf_eda_post_evt()

vsf_err_t vsf_eda_post_evt ( vsf_eda_t * pthis,
vsf_evt_t evt )

Post an event to an eda task.

Parameters
[in]pthisa pointer to structure vsf_eda_t
[in]evtthe event to post
Returns
vsf_err_t: VSF_ERR_NONE if posted; VSF_ERR_FAIL if the eda is limited and already has a pending event; VSF_ERR_NOT_ENOUGH_RESOURCES if no event node is available
Note
Can be called in task or interrupt context.

◆ __vsf_eda_post_evt_ex()

vsf_err_t __vsf_eda_post_evt_ex ( vsf_eda_t * pthis,
vsf_evt_t evt,
bool force )

◆ vsf_eda_post_msg()

vsf_err_t vsf_eda_post_msg ( vsf_eda_t * pthis,
void * msg )

Post a pointer message to an eda task; the task receives VSF_EVT_MESSAGE and retrieves the pointer with vsf_eda_get_cur_msg()

Parameters
[in]pthisa pointer to structure vsf_eda_t
[in]msgthe message pointer to post, must be aligned (LSB must be 0)
Returns
vsf_err_t: VSF_ERR_NONE if posted; VSF_ERR_FAIL if the eda is limited and already has a pending event; VSF_ERR_NOT_ENOUGH_RESOURCES if no event node is available
Note
Can be called in task or interrupt context.

◆ vsf_eda_post_evt_msg()

vsf_err_t vsf_eda_post_evt_msg ( vsf_eda_t * pthis,
vsf_evt_t evt,
void * msg )

Post an event carrying a pointer message to an eda task; the pointer is retrieved with vsf_eda_get_cur_msg()

Parameters
[in]pthisa pointer to structure vsf_eda_t
[in]evtthe event to post
[in]msgthe message pointer carried with the event
Returns
vsf_err_t: VSF_ERR_NONE if posted; VSF_ERR_FAIL if the eda is limited and already has a pending event; VSF_ERR_NOT_ENOUGH_RESOURCES if no event node is available
Note
Only available when VSF_KERNEL_CFG_SUPPORT_EVT_MESSAGE is ENABLED.
Can be called in task or interrupt context.

◆ vsf_eda_cpu_usage_start()

void vsf_eda_cpu_usage_start ( vsf_eda_t * pthis,
vsf_cpu_usage_ctx_t * ctx )

Start measuring the CPU usage of an eda task.

Parameters
[in]pthisa pointer to structure vsf_eda_t
[in]ctxa pointer to user-provided structure vsf_cpu_usage_ctx_t, which must be kept valid until vsf_eda_cpu_usage_stop() is called
Returns
none
Note
Only available when VSF_KERNEL_CFG_EDA_CPU_USAGE is ENABLED. The measured ticks actually include ticks from all higher priority tasks and interrupts.

◆ vsf_eda_cpu_usage_stop()

void vsf_eda_cpu_usage_stop ( vsf_eda_t * pthis)

Stop measuring the CPU usage of an eda task.

Parameters
[in]pthisa pointer to structure vsf_eda_t
Returns
none
Note
Only available when VSF_KERNEL_CFG_EDA_CPU_USAGE is ENABLED.

◆ vsf_kernel_start()

vsf_err_t vsf_kernel_start ( void )
Note
Priority of kernel task generally should be the highest priority of ! tasks(__vsf_eda.highest_prio, or vsf_prio_highest). ! If a task with vsf_prio_highest priority will not exit, eg: call yield ! and never go to idle state(yield will yield to the same priority, not lower). ! So if priority of kernel task is lower than vsf_prio_highest, the kernel ! task will never have a change to run. ! Basically, we don't recommend to use this design pattern, a task should ! not takes all the CPU resources, which will deprive tasks with lower priority ! of the chance to run. If there is no such tasks, priority of kernel ! task can be lower than vsf_prio_highest. Please use VSF_KERNEL_CFG_KERNEL_TASK_PRIORITY ! to configure the priority of the kernel task.
Generated from commit: vsfteam/vsf@a5104db