vsf_simple.h File Reference

#include "kernel/vsf_kernel_cfg.h"
#include "../../vsf_eda.h"
#include "./vsf_simple_bmpevt.h"
#include "../../task/vsf_task.h"

Go to the source code of this file.

Macros
#define	static_task_instance(...)
	Declare the per-invocation static task-local control block and fetch the current event.
#define	features_used(...)
	Non-IAR variant; shares the documentation of the first variant above.
#define	mem_sharable(...)
	Non-IAR variant; shares the documentation of the first variant above.
#define	mem_nonsharable(...)
	Non-IAR variant; shares the documentation of the first variant above.
#define	vsf_yield()
	Yield the CPU cooperatively so that other tasks of the same event queue can run before this task continues.
#define	vsf_delay(__tick)
	Delay for a given number of system timer ticks (cooperative, non-blocking for other tasks).
#define	vsf_delay_ms(__ms)
	Delay for a given number of milliseconds (cooperative, non-blocking for other tasks).
#define	vsf_delay_us(__us)
	Delay for a given number of microseconds (cooperative, non-blocking for other tasks).
#define	on_timeout()
	Catch the timeout case of a preceding *_timeout wait macro.
#define	vsf_mutex_init(__mutex_addr)
	Initialize a mutex.
#define	vsf_mutex_leave(__mutex_addr)
	Leave (release) a mutex previously entered by the current task.
#define	vsf_mutex_enter(__mutex_addr)
	Enter (lock) a mutex, waiting forever until it is obtained (cooperative, non-blocking for other tasks).
#define	vsf_mutex_try_enter_timeout(__mutex_addr, __timeout)
	Try to enter (lock) a mutex with a timeout in system timer ticks (cooperative, non-blocking for other tasks).
#define	vsf_mutex_try_enter_timeout_ms(__mutex_addr, __timeout)
	Try to enter (lock) a mutex with a timeout in milliseconds (cooperative, non-blocking for other tasks).
#define	vsf_mutex_try_enter_timeout_us(__mutex_addr, __timeout)
	Try to enter (lock) a mutex with a timeout in microseconds (cooperative, non-blocking for other tasks).
#define	vsf_crit_init(__crit_addr)
	Initialize a critical section object.
#define	vsf_crit_leave(__crit_addr)
	Leave a critical section previously entered by the current task.
#define	vsf_crit_enter(__crit_addr)
	Enter a critical section, waiting forever until it is obtained (cooperative, non-blocking for other tasks).
#define	vsf_crit_try_enter_timeout(__crit_addr, __timeout)
	Try to enter a critical section with a timeout in system timer ticks (cooperative, non-blocking for other tasks).
#define	vsf_crit_try_enter_timeout_ms(__crit_addr, __timeout)
	Try to enter a critical section with a timeout in milliseconds (cooperative, non-blocking for other tasks).
#define	vsf_crit_try_enter_timeout_us(__crit_addr, __timeout)
	Try to enter a critical section with a timeout in microseconds (cooperative, non-blocking for other tasks).
#define	vsf_sem_init(__psem, __cnt)
	Initialize a semaphore with an initial count; the count is auto-reset and limited by VSF_SYNC_MAX.
#define	vsf_sem_post(__psem)
	Post (increase) a semaphore, waking up one pending task if any.
#define	vsf_sem_pend(__psem)
	Wait for (pend on) a semaphore, waiting forever until it is obtained (cooperative, non-blocking for other tasks).
#define	vsf_sem_pend_timeout(__psem, __timeout)
	Wait for (pend on) a semaphore with a timeout in system timer ticks (cooperative, non-blocking for other tasks).
#define	vsf_sem_pend_timeout_ms(__psem, __timeout)
	Wait for (pend on) a semaphore with a timeout in milliseconds (cooperative, non-blocking for other tasks).
#define	vsf_sem_pend_timeout_us(__psem, __timeout)
	Wait for (pend on) a semaphore with a timeout in microseconds (cooperative, non-blocking for other tasks).
#define	vsf_trig_init(__ptrig, __set, __auto_rst)
	Initialize a trigger.
#define	vsf_trig_set(__ptrig)
	Set a trigger, waking up the tasks waiting for it (all waiters for a manual-reset trigger, one waiter otherwise).
#define	vsf_trig_reset(__ptrig)
	Reset a trigger.
#define	vsf_trig_wait(__ptrig)
	Wait for a trigger to be set, waiting forever (cooperative, non-blocking for other tasks).
#define	vsf_trig_wait_timeout(__ptrig, __timeout)
	Wait for a trigger to be set with a timeout in system timer ticks (cooperative, non-blocking for other tasks).
#define	vsf_trig_wait_timeout_ms(__ptrig, __timeout)
	Wait for a trigger to be set with a timeout in milliseconds (cooperative, non-blocking for other tasks).
#define	vsf_trig_wait_timeout_us(__ptrig, __timeout)
	Wait for a trigger to be set with a timeout in microseconds (cooperative, non-blocking for other tasks).
#define	vsf_call_eda(__entry, __param_addr)
	Call a sub eda task (event handler) from the current task.
#define	vsf_call_fsm(__entry, __param_addr, ...)
	Call a sub fsm task from the current task, and wait until it finishes. Internally mapped to __vsf_call_task(); an fsm is a vsf task in this codebase.
#define	vsf_call_peda4(__peda_name, __entry, __private_local_size, __peda_param_addr, __buff)
	Call a sub peda task (eda task with private local variables and argument buffer) from the current task.
#define	vsf_call_peda3(__peda_name, __entry, __private_local_size, __peda_param_addr)
	Helper of vsf_call_peda() with explicit entry and private local size, without the argument buffer; shares the documentation of vsf_call_peda4.
#define	vsf_call_peda2(__peda_name, __peda_param_addr, __buff)
	Helper of vsf_call_peda() with an explicit argument buffer, using the peda's own entry; shares the documentation of vsf_call_peda4.
#define	vsf_call_peda1(__peda_name, __peda_param_addr)
	Helper of vsf_call_peda() using the peda's own entry without the argument buffer; shares the documentation of vsf_call_peda4.
#define	vsf_call_peda(__peda_name, ...)

Functions
vsf_evt_t	__vsf_delay (vsf_systimer_tick_t tick)
	Low-level delay helper backing the vsf_delay() statement macros.
vsf_sync_reason_t	__vsf_sem_pend (vsf_sem_t *sem_ptr, vsf_timeout_tick_t time_out)
	Low-level semaphore-pend helper backing the vsf_sem_pend() and vsf_trig_wait() statement macros.
vsf_sync_reason_t	__vsf_mutex_enter (vsf_mutex_t *mtx_ptr, vsf_timeout_tick_t time_out)
	Low-level mutex-enter helper backing the vsf_mutex_enter() and vsf_crit_enter() statement macros.
vsf_evt_t	__vsf_yield (void)
	Low-level yield helper backing the vsf_yield() statement macro.
vsf_err_t	__vsf_call_eda (uintptr_t evthandler, uintptr_t param, size_t local_size, size_t local_buff_size, uintptr_t local_buff)
	Low-level sub-task-call helper backing the vsf_call_eda() and vsf_call_peda() macros.
fsm_rt_t	__vsf_call_task (vsf_task_entry_t entry, uintptr_t param, size_t local_size)
	Low-level helper for calling a sub task with a return value.

Macro Definition Documentation

static_task_instance

#define static_task_instance

(

...

)

Value:

        struct {                                                                \
            uint_fast8_t fsm_state;                                             \
            __VA_ARGS__                                                         \
        } static VSF_MACRO_SAFE_NAME(local_cb),                                 \
            *this_ptr = &VSF_MACRO_SAFE_NAME(local_cb);                         \
             vsf_evt_t evt = vsf_eda_get_cur_evt();                             \
             VSF_UNUSED_PARAM(evt);                                             \
             VSF_UNUSED_PARAM(this_ptr);

Declare the per-invocation static task-local control block and fetch the current event.

Parameters

[in]

...

user local variable declarations appended to the control block

Note

Expands to an anonymous struct with a static instance and a pointer this_ptr to it; the first member fsm_state is reserved for the simple-shell state machine. Also defines a local variable evt holding the current event (vsf_eda_get_cur_evt()).

Must be placed at the beginning of a simple-shell event handler.

features_used

#define features_used

(

...

)

Value:

__VA_ARGS__

Non-IAR variant; shares the documentation of the first variant above.

mem_sharable

#define mem_sharable

(

...

)

Value:

union {__VA_ARGS__};

Non-IAR variant; shares the documentation of the first variant above.

mem_nonsharable

#define mem_nonsharable

(

...

)

Value:

__VA_ARGS__

Non-IAR variant; shares the documentation of the first variant above.

vsf_yield

#define vsf_yield

(

)

Value:

            for (   vsf_evt_t result = VSF_EVT_INVALID;                         \
                    result == VSF_EVT_INVALID;)                                 \
                if ((result =__vsf_yield(), result == VSF_EVT_YIELD))

Yield the CPU cooperatively so that other tasks of the same event queue can run before this task continues.

Note

Statement macro: the following brace block runs after the task is resumed. Usage: vsf_yield() { ... }. Must be used inside a simple-shell event handler.

vsf_delay

#define vsf_delay

(

__tick

)

Value:

    if (VSF_EVT_TIMER == __vsf_delay((vsf_systimer_tick_t)__tick))

Delay for a given number of system timer ticks (cooperative, non-blocking for other tasks).

Parameters

[in]

__tick

delay time in system timer ticks

Note

Statement macro: the following brace block runs after the delay expires. Usage: vsf_delay(tick) { ... }. Must be used inside a simple-shell event handler.

vsf_delay_ms

#define vsf_delay_ms

(

__ms

)

Value:

    if (VSF_EVT_TIMER == __vsf_delay((vsf_systimer_tick_t)vsf_systimer_ms_to_tick(__ms)))

Delay for a given number of milliseconds (cooperative, non-blocking for other tasks).

Parameters

[in]

__ms

delay time in milliseconds, converted to ticks via vsf_systimer_ms_to_tick()

Note

Statement macro: the following brace block runs after the delay expires. Usage: vsf_delay_ms(ms) { ... }. Must be used inside a simple-shell event handler.

vsf_delay_us

#define vsf_delay_us

(

__us

)

Value:

    if (VSF_EVT_TIMER == __vsf_delay((vsf_systimer_tick_t)vsf_systimer_us_to_tick(__us)))

Delay for a given number of microseconds (cooperative, non-blocking for other tasks).

Parameters

[in]

__us

delay time in microseconds, converted to ticks via vsf_systimer_us_to_tick()

Note

Statement macro: the following brace block runs after the delay expires. Usage: vsf_delay_us(us) { ... }. Must be used inside a simple-shell event handler.

on_timeout

#define on_timeout

(

)

Value:

                if (VSF_EVT_TIMER == vsf_eda_get_cur_evt())

Catch the timeout case of a preceding *_timeout wait macro.

Note

Statement macro: the following brace block runs when the preceding wait timed out, i.e. the current event is VSF_EVT_TIMER. Usage: on_timeout() { ... }. Must be used inside a simple-shell event handler, right after a *_timeout() statement macro.

vsf_mutex_init

#define vsf_mutex_init

(

__mutex_addr

)

Value:

vsf_eda_mutex_init(__mutex_addr)

Initialize a mutex.

Parameters

[in]

__mutex_addr

pointer to the mutex vsf_mutex_t

Returns

vsf_err_t: always VSF_ERR_NONE (invalid parameters trigger an assertion)

Note

Must be called in task (or initialization) context, NOT in interrupt context.

vsf_mutex_leave

#define vsf_mutex_leave

(

__mutex_addr

)

Value:

vsf_eda_mutex_leave(__mutex_addr)

Leave (release) a mutex previously entered by the current task.

Parameters

[in]

__mutex_addr

pointer to the mutex vsf_mutex_t

Returns

vsf_err_t: VSF_ERR_NONE if successful; VSF_ERR_OVERRUN if the mutex is not owned

Note

Must be called in task context, NOT in interrupt context (in interrupt context use the corresponding _isr API if available).

vsf_mutex_enter

#define vsf_mutex_enter

(

__mutex_addr

)

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_mutex_enter((__mutex_addr),                  \
                    (-1)), reason == VSF_SYNC_GET))

Enter (lock) a mutex, waiting forever until it is obtained (cooperative, non-blocking for other tasks).

Parameters

[in]

__mutex_addr

pointer to the mutex vsf_mutex_t

Note

Statement macro: the following brace block runs after the mutex is obtained. Usage: vsf_mutex_enter(pmtx) { ... }. Must be used inside a simple-shell event handler.

vsf_mutex_try_enter_timeout

#define vsf_mutex_try_enter_timeout	(		__mutex_addr,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_mutex_enter((__mutex_addr),                  \
                    (__timeout)),                                               \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Try to enter (lock) a mutex with a timeout in system timer ticks (cooperative, non-blocking for other tasks).

Parameters

[in]	__mutex_addr	pointer to the mutex vsf_mutex_t
[in]	__timeout	timeout in system timer ticks; a negative value waits forever

Note

Statement macro: the following brace block runs when the mutex is obtained (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_mutex_try_enter_timeout(pmtx, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_mutex_try_enter_timeout_ms

#define vsf_mutex_try_enter_timeout_ms	(		__mutex_addr,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_mutex_enter((__mutex_addr),                  \
                    vsf_systimer_ms_to_tick(__timeout)),                        \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Try to enter (lock) a mutex with a timeout in milliseconds (cooperative, non-blocking for other tasks).

Parameters

[in]	__mutex_addr	pointer to the mutex vsf_mutex_t
[in]	__timeout	timeout in milliseconds, converted to ticks via vsf_systimer_ms_to_tick()

Note

Statement macro: the following brace block runs when the mutex is obtained (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_mutex_try_enter_timeout_ms(pmtx, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_mutex_try_enter_timeout_us

#define vsf_mutex_try_enter_timeout_us	(		__mutex_addr,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_mutex_enter((__mutex_addr),                  \
                    vsf_systimer_us_to_tick(__timeout)),                        \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Try to enter (lock) a mutex with a timeout in microseconds (cooperative, non-blocking for other tasks).

Parameters

[in]	__mutex_addr	pointer to the mutex vsf_mutex_t
[in]	__timeout	timeout in microseconds, converted to ticks via vsf_systimer_us_to_tick()

Note

Statement macro: the following brace block runs when the mutex is obtained (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_mutex_try_enter_timeout_us(pmtx, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_crit_init

#define vsf_crit_init

(

__crit_addr

)

Value:

vsf_eda_crit_init(__crit_addr)

Initialize a critical section object.

Parameters

[in]

__crit_addr

pointer to the critical section object vsf_crit_t

Returns

vsf_err_t: always VSF_ERR_NONE (invalid parameters trigger an assertion)

Note

Must be called in task (or initialization) context, NOT in interrupt context.

vsf_crit_leave

#define vsf_crit_leave

(

__crit_addr

)

Value:

vsf_eda_crit_leave(__crit_addr)

Leave a critical section previously entered by the current task.

Parameters

[in]

__crit_addr

pointer to the critical section object vsf_crit_t

Returns

vsf_err_t: VSF_ERR_NONE if successful; VSF_ERR_OVERRUN if the critical section is not owned

Note

Must be called in task context, NOT in interrupt context (in interrupt context use the corresponding _isr API if available).

vsf_crit_enter

#define vsf_crit_enter

(

__crit_addr

)

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_mutex_enter((__crit_addr),                   \
                    (-1)), reason == VSF_SYNC_GET))

Enter a critical section, waiting forever until it is obtained (cooperative, non-blocking for other tasks).

Parameters

[in]

__crit_addr

pointer to the critical section object vsf_crit_t

Note

Statement macro: the following brace block runs after the critical section is entered. Usage: vsf_crit_enter(pcrit) { ... }. Must be used inside a simple-shell event handler.

vsf_crit_try_enter_timeout

#define vsf_crit_try_enter_timeout	(		__crit_addr,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_mutex_enter((__crit_addr),                   \
                    (__timeout)),                                               \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Try to enter a critical section with a timeout in system timer ticks (cooperative, non-blocking for other tasks).

Parameters

[in]	__crit_addr	pointer to the critical section object vsf_crit_t
[in]	__timeout	timeout in system timer ticks; a negative value waits forever

Note

Statement macro: the following brace block runs when the critical section is entered (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_crit_try_enter_timeout(pcrit, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_crit_try_enter_timeout_ms

#define vsf_crit_try_enter_timeout_ms	(		__crit_addr,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_mutex_enter((__crit_addr),                   \
                    vsf_systimer_ms_to_tick(__timeout)),                        \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Try to enter a critical section with a timeout in milliseconds (cooperative, non-blocking for other tasks).

Parameters

[in]	__crit_addr	pointer to the critical section object vsf_crit_t
[in]	__timeout	timeout in milliseconds, converted to ticks via vsf_systimer_ms_to_tick()

Note

Statement macro: the following brace block runs when the critical section is entered (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_crit_try_enter_timeout_ms(pcrit, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_crit_try_enter_timeout_us

#define vsf_crit_try_enter_timeout_us	(		__crit_addr,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_mutex_enter((__crit_addr),                   \
                    vsf_systimer_us_to_tick(__timeout)),                        \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Try to enter a critical section with a timeout in microseconds (cooperative, non-blocking for other tasks).

Parameters

[in]	__crit_addr	pointer to the critical section object vsf_crit_t
[in]	__timeout	timeout in microseconds, converted to ticks via vsf_systimer_us_to_tick()

Note

Statement macro: the following brace block runs when the critical section is entered (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_crit_try_enter_timeout_us(pcrit, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_sem_init

#define vsf_sem_init	(		__psem,
			__cnt )

Value:

            vsf_eda_sync_init((__psem), (__cnt), VSF_SYNC_MAX | VSF_SYNC_AUTO_RST)

Initialize a semaphore with an initial count; the count is auto-reset and limited by VSF_SYNC_MAX.

Parameters

[in]	__psem	pointer to the semaphore vsf_sem_t
[in]	__cnt	initial count of the semaphore

Returns

vsf_err_t: always VSF_ERR_NONE (invalid parameters trigger an assertion)

Note

Must be called in task (or initialization) context, NOT in interrupt context.

vsf_sem_post

#define vsf_sem_post

(

__psem

)

Value:

vsf_eda_sem_post((__psem))

Post (increase) a semaphore, waking up one pending task if any.

Parameters

[in]

__psem

pointer to the semaphore vsf_sem_t

Returns

vsf_err_t: VSF_ERR_NONE if successful; VSF_ERR_OVERRUN if the count has reached the maximum

Note

Must be called in task context, NOT in interrupt context (in interrupt context use the corresponding _isr API if available).

vsf_sem_pend

#define vsf_sem_pend

(

__psem

)

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_sem_pend((__psem),                           \
                    (-1)), reason == VSF_SYNC_GET))

Wait for (pend on) a semaphore, waiting forever until it is obtained (cooperative, non-blocking for other tasks).

Parameters

[in]

__psem

pointer to the semaphore vsf_sem_t

Note

Statement macro: the following brace block runs after the semaphore is obtained. Usage: vsf_sem_pend(psem) { ... }. Must be used inside a simple-shell event handler.

vsf_sem_pend_timeout

#define vsf_sem_pend_timeout	(		__psem,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_sem_pend((__psem),                           \
                    (__timeout)),                                               \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Wait for (pend on) a semaphore with a timeout in system timer ticks (cooperative, non-blocking for other tasks).

Parameters

[in]	__psem	pointer to the semaphore vsf_sem_t
[in]	__timeout	timeout in system timer ticks; a negative value waits forever

Note

Statement macro: the following brace block runs when the semaphore is obtained (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_sem_pend_timeout(psem, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_sem_pend_timeout_ms

#define vsf_sem_pend_timeout_ms	(		__psem,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_sem_pend((__psem),                           \
                    vsf_systimer_ms_to_tick(__timeout)),                        \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Wait for (pend on) a semaphore with a timeout in milliseconds (cooperative, non-blocking for other tasks).

Parameters

[in]	__psem	pointer to the semaphore vsf_sem_t
[in]	__timeout	timeout in milliseconds, converted to ticks via vsf_systimer_ms_to_tick()

Note

Statement macro: the following brace block runs when the semaphore is obtained (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_sem_pend_timeout_ms(psem, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_sem_pend_timeout_us

#define vsf_sem_pend_timeout_us	(		__psem,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_sem_pend((__psem),                           \
                    vsf_systimer_us_to_tick(__timeout)),                        \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Wait for (pend on) a semaphore with a timeout in microseconds (cooperative, non-blocking for other tasks).

Parameters

[in]	__psem	pointer to the semaphore vsf_sem_t
[in]	__timeout	timeout in microseconds, converted to ticks via vsf_systimer_us_to_tick()

Note

Statement macro: the following brace block runs when the semaphore is obtained (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_sem_pend_timeout_us(psem, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_trig_init

#define vsf_trig_init	(		__ptrig,
			__set,
			__auto_rst )

Value:

            vsf_eda_trig_init(__ptrig, __set, __auto_rst)

Initialize a trigger.

Parameters

[in]	__ptrig	pointer to the trigger vsf_trig_t
[in]	__set	initial state, non-zero for set, zero for reset
[in]	__auto_rst	non-zero to reset the trigger automatically after it is obtained, zero to reset it manually with vsf_trig_reset()

Returns

vsf_err_t: always VSF_ERR_NONE (invalid parameters trigger an assertion)

Note

Must be called in task (or initialization) context, NOT in interrupt context.

vsf_trig_set

#define vsf_trig_set

(

__ptrig

)

Value:

vsf_eda_trig_set((__ptrig))

Set a trigger, waking up the tasks waiting for it (all waiters for a manual-reset trigger, one waiter otherwise).

Parameters

[in]

__ptrig

pointer to the trigger vsf_trig_t

Returns

vsf_err_t: VSF_ERR_NONE if successful; VSF_ERR_OVERRUN if the trigger is already set

Note

Must be called in task context, NOT in interrupt context (in interrupt context use the corresponding _isr API if available).

vsf_trig_reset

#define vsf_trig_reset

(

__ptrig

)

Value:

vsf_eda_trig_reset((__ptrig))

Reset a trigger.

Parameters

[in]

__ptrig

pointer to the trigger vsf_trig_t

Returns

none

Note

Must be called in task context, NOT in interrupt context (in interrupt context use the corresponding _isr API if available).

vsf_trig_wait

#define vsf_trig_wait

(

__ptrig

)

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_sem_pend((__ptrig),                          \
                    (-1)), reason == VSF_SYNC_GET))

Wait for a trigger to be set, waiting forever (cooperative, non-blocking for other tasks).

Parameters

[in]

__ptrig

pointer to the trigger vsf_trig_t

Note

Statement macro: the following brace block runs after the trigger is set. Usage: vsf_trig_wait(ptrig) { ... }. Must be used inside a simple-shell event handler.

vsf_trig_wait_timeout

#define vsf_trig_wait_timeout	(		__ptrig,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_sem_pend((__ptrig),                          \
                    (__timeout)),                                               \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Wait for a trigger to be set with a timeout in system timer ticks (cooperative, non-blocking for other tasks).

Parameters

[in]	__ptrig	pointer to the trigger vsf_trig_t
[in]	__timeout	timeout in system timer ticks; a negative value waits forever

Note

Statement macro: the following brace block runs when the trigger is set (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_trig_wait_timeout(ptrig, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_trig_wait_timeout_ms

#define vsf_trig_wait_timeout_ms	(		__ptrig,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_sem_pend((__ptrig),                          \
                    vsf_systimer_ms_to_tick(__timeout)),                        \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Wait for a trigger to be set with a timeout in milliseconds (cooperative, non-blocking for other tasks).

Parameters

[in]	__ptrig	pointer to the trigger vsf_trig_t
[in]	__timeout	timeout in milliseconds, converted to ticks via vsf_systimer_ms_to_tick()

Note

Statement macro: the following brace block runs when the trigger is set (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_trig_wait_timeout_ms(ptrig, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_trig_wait_timeout_us

#define vsf_trig_wait_timeout_us	(		__ptrig,
			__timeout )

Value:

            for (   vsf_sync_reason_t reason = VSF_SYNC_CANCEL;                 \
                    reason == VSF_SYNC_CANCEL;)                                 \
                if ((reason =__vsf_sem_pend((__ptrig),                          \
                    vsf_systimer_us_to_tick(__timeout)),                        \
                    (reason == VSF_SYNC_GET || reason == VSF_SYNC_TIMEOUT)))

Wait for a trigger to be set with a timeout in microseconds (cooperative, non-blocking for other tasks).

Parameters

[in]	__ptrig	pointer to the trigger vsf_trig_t
[in]	__timeout	timeout in microseconds, converted to ticks via vsf_systimer_us_to_tick()

Note

Statement macro: the following brace block runs when the trigger is set (VSF_SYNC_GET) or the wait times out (VSF_SYNC_TIMEOUT); use on_timeout() to catch the timeout case. Usage: vsf_trig_wait_timeout_us(ptrig, timeout) { ... }. Must be used inside a simple-shell event handler.

vsf_call_eda

#define vsf_call_eda	(		__entry,
			__param_addr )

Value:

            __vsf_call_eda( (uintptr_t)(__entry),                               \
                            (__param_addr),                                     \
                            0, 0, 0)

Call a sub eda task (event handler) from the current task.

Parameters

[in]	__entry	entry function of the sub task
[in]	__param_addr	parameter passed to the sub task

Returns

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

Note

Must be used inside a simple-shell event handler. After the sub task returns, the caller resumes with the VSF_EVT_RETURN event.

vsf_call_fsm

#define vsf_call_fsm	(		__entry,
			__param_addr,
			... )

Value:

            __vsf_call_task( (vsf_task_entry_t)(__entry),                       \
                             (uintptr_t)(__param_addr),                         \
                             (0, ##__VA_ARGS__))

Call a sub fsm task from the current task, and wait until it finishes. Internally mapped to __vsf_call_task(); an fsm is a vsf task in this codebase.

Parameters

[in]	__entry	entry function of the sub task
[in]	__param_addr	parameter passed to 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 fsm task when it finishes, or fsm_rt_yield while the sub task is scheduled to run

Note

Must be used inside a simple-shell event handler. Only available when VSF_KERNEL_CFG_EDA_SUPPORT_TASK and VSF_KERNEL_CFG_EDA_SUBCALL_HAS_RETURN_VALUE are ENABLED (the same requirements as the simple-fsm module).

vsf_call_peda4

#define vsf_call_peda4	(		__peda_name,
			__entry,
			__private_local_size,
			__peda_param_addr,
			__buff )

Value:

            __vsf_call_eda((uintptr_t)__entry,                                  \
                (uintptr_t)(__peda_param_addr),                                 \
                ((sizeof(vsf_peda_local(__peda_name)) + 7) & ~0x07) + (__private_local_size),\
                sizeof(vsf_peda_arg(__peda_name)),                              \
                (uintptr_t)(__buff))

Call a sub peda task (eda task with private local variables and argument buffer) from the current task.

Parameters

[in]	__peda_name	name of the peda task declared with the peda macros
[in]	__entry	(vsf_call_peda4/3 only) entry function of the sub task
[in]	__private_local_size	(vsf_call_peda4/3 only) extra private local size appended to the peda local variables
[in]	__peda_param_addr	parameter passed to the sub task
[in]	__buff	(vsf_call_peda4/2 only) buffer used to initialize the argument area of the sub task

Returns

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

Note

vsf_call_peda() dispatches to vsf_call_peda1/2/3/4 according to the argument count; the four helpers share this documentation.

Must be used inside a simple-shell event handler. After the sub task returns, the caller resumes with the VSF_EVT_RETURN event.

vsf_call_peda3

#define vsf_call_peda3	(		__peda_name,
			__entry,
			__private_local_size,
			__peda_param_addr )

Value:

            __vsf_call_eda((uintptr_t)__entry,                                  \
                (uintptr_t)(__peda_param_addr),                                 \
                ((sizeof(vsf_peda_local(__peda_name)) + 7) & ~0x07) + (__private_local_size),\
                sizeof(vsf_peda_arg(__peda_name)),                              \
                0)

Helper of vsf_call_peda() with explicit entry and private local size, without the argument buffer; shares the documentation of vsf_call_peda4.

vsf_call_peda2

#define vsf_call_peda2	(		__peda_name,
			__peda_param_addr,
			__buff )

Value:

            __vsf_call_eda((uintptr_t)vsf_peda_func(__peda_name),               \
                        (uintptr_t)(__peda_param_addr),                         \
                        sizeof(vsf_peda_local(__peda_name)),                    \
                        sizeof(vsf_peda_arg(__peda_name)),                      \
                        (uintptr_t)(__buff))

Helper of vsf_call_peda() with an explicit argument buffer, using the peda's own entry; shares the documentation of vsf_call_peda4.

vsf_call_peda1

#define vsf_call_peda1	(		__peda_name,
			__peda_param_addr )

Value:

            __vsf_call_eda((uintptr_t)vsf_peda_func(__peda_name),               \
                        (uintptr_t)(__peda_param_addr),                         \
                        sizeof(vsf_peda_local(__peda_name)),                    \
                        sizeof(vsf_peda_arg(__peda_name)),                      \
                        0)

Helper of vsf_call_peda() using the peda's own entry without the argument buffer; shares the documentation of vsf_call_peda4.

vsf_call_peda

#define vsf_call_peda	(		__peda_name,
			... )

Value:

            __PLOOC_EVAL(vsf_call_peda, __VA_ARGS__) (__peda_name, __VA_ARGS__)

Function Documentation

__vsf_delay()

vsf_evt_t __vsf_delay ( vsf_systimer_tick_t tick )

extern

Low-level delay helper backing the vsf_delay() statement macros.

Parameters

[in]

tick

delay time in system timer ticks

Returns

vsf_evt_t: VSF_EVT_TIMER when the delay expires, otherwise VSF_EVT_INVALID while the delay is still pending

Note

Internal use only.

__vsf_sem_pend()

vsf_sync_reason_t __vsf_sem_pend ( vsf_sem_t * sem_ptr, vsf_timeout_tick_t time_out )

extern

Low-level semaphore-pend helper backing the vsf_sem_pend() and vsf_trig_wait() statement macros.

Parameters

[in]	sem_ptr	pointer to the semaphore vsf_sem_t
[in]	time_out	timeout in system timer ticks; a negative value waits forever

Returns

vsf_sync_reason_t: VSF_SYNC_GET when the semaphore is obtained, VSF_SYNC_TIMEOUT on timeout, VSF_SYNC_CANCEL when the wait is cancelled, VSF_SYNC_FAIL on error, otherwise VSF_SYNC_PENDING while the wait is still in progress

Note

Internal use only.

__vsf_mutex_enter()

vsf_sync_reason_t __vsf_mutex_enter ( vsf_mutex_t * mtx_ptr, vsf_timeout_tick_t time_out )

extern

Low-level mutex-enter helper backing the vsf_mutex_enter() and vsf_crit_enter() statement macros.

Parameters

[in]	mtx_ptr	pointer to the mutex vsf_mutex_t
[in]	time_out	timeout in system timer ticks; a negative value waits forever

Returns

vsf_sync_reason_t: VSF_SYNC_GET when the mutex is obtained, VSF_SYNC_TIMEOUT on timeout, VSF_SYNC_CANCEL when the wait is cancelled, VSF_SYNC_FAIL on error, otherwise VSF_SYNC_PENDING while the wait is still in progress

Note

Internal use only.

__vsf_yield()

vsf_evt_t __vsf_yield ( void )

extern

Low-level yield helper backing the vsf_yield() statement macro.

Returns

vsf_evt_t: VSF_EVT_YIELD when the task is resumed after the yield, otherwise VSF_EVT_NONE while the yield is still pending

Note

Internal use only.

__vsf_call_eda()

vsf_err_t __vsf_call_eda ( uintptr_t evthandler, uintptr_t param, size_t local_size, size_t local_buff_size, uintptr_t local_buff )

extern

Low-level sub-task-call helper backing the vsf_call_eda() and vsf_call_peda() macros.

Parameters

[in]	evthandler	entry function of the sub task
[in]	param	parameter passed to the sub task
[in]	local_size	size of the local variable area of the sub task
[in]	local_buff_size	size of the buffer pointed by local_buff
[in]	local_buff	buffer used to initialize the local variable area of the sub task, NULL if not used

Returns

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

Note

Internal use only.

__vsf_call_task()

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

extern

Low-level helper for calling a sub task with a return value.

Parameters

[in]	entry	entry function of the sub task vsf_task_entry_t
[in]	param	parameter passed to the sub task
[in]	local_size	size of the local variable area of the sub task

Returns

fsm_rt_t: return status of the sub task

Note

Internal use only.