#include "component/vsf_component_cfg.h"
#include "utilities/vsf_utilities.h"
#include "./vsf_test_shell.h"

Data Structures
class	vsf_test_wdt_t

class	vsf_test_suite_t

struct	vsf_test_i2c_slave_ctx_t

struct	vsf_test_gpio_pinmux_ctx_t

struct	vsf_test_inst_t

struct	vsf_test_t

Macros
#define	VSF_TEST_CFG_LONGJMP ENABLED
	< Using longjmp/setjmp for assertions

#define	VSF_TEST_CFG_INTERNAL_TIMEOUT_MS 1000
	External Watchdog Default Timeout.

#define	VSF_TEST_CFG_EXTERNAL_TIMEOUT_MS 1500
	Using the hal wdt device.

#define	VSF_TEST_CFG_USE_HAL_WDT DISABLED
	Enable trace output for test framework.

#define	VSF_TEST_CFG_USE_TRACE ENABLED

#define	VSF_TEST_CFG_EMIT_MARKERS DISABLED

#define	VSF_TEST_CFG_HW_CONFIG_LOG_ONLY DISABLED

#define	VSF_TEST_MARKER_DELAY_MS 2

#define	VSF_TEST_CFG_BUSY_WAIT_CYCLES_PER_MS 22000

#define	VSF_TEST_POLL_TICK_MS 1

#define	VSF_TEST_ASSERT(__v)
	Add an assertion to the test case.

#define	VSF_TEST_ASSERT_INST(_inst, _pt, _field)
	Validate a test instance matches expected type and has non-null fixture.

#define	VSF_TEST_ASSERT_ERR(__err, __expected, ...)
	Assert that an error code equals the expected value, with a pre-assertion TRACE_ERROR if it does not.

#define	VSF_TEST_ASSERT_ERR_NONE(__err, ...) VSF_TEST_ASSERT_ERR(__err, VSF_ERR_NONE, __VA_ARGS__)
	Convenience wrapper: assert err == VSF_ERR_NONE with TRACE_ERROR.

#define	VSF_TEST_WAIT_FOR(__cond, __timeout_ms)
	Busy-wait for a condition with a 1ms polling tick and timeout.

#define	VSF_TEST_SPIN_FOR(__cond, __iterations)
	Tight spin-wait for a condition with an iteration limit (no delay)

#define	VSF_TEST_TRACE_ERROR(...) vsf_test_trace(VSF_TRACE_ERROR, __VA_ARGS__)

#define	VSF_TEST_TRACE_WARNING(...) vsf_test_trace(VSF_TRACE_WARNING, __VA_ARGS__)

#define	VSF_TEST_TRACE_INFO(...) vsf_test_trace(VSF_TRACE_INFO, __VA_ARGS__)
	Level-filtered trace output via the test shell's trace_level.

#define	VSF_TEST_TRACE_DEBUG(...) vsf_test_trace(VSF_TRACE_DEBUG, __VA_ARGS__)

Typedefs
typedef enum vsf_test_result_t	vsf_test_result_t

typedef enum vsf_peripheral_type_t	vsf_peripheral_type_t

typedef void	vsf_test_reboot_t(void)

typedef struct vsf_test_case_t	vsf_test_case_t

typedef void	vsf_test_jmp_fn_t(const vsf_test_suite_t suite, const vsf_test_case_t tc, const vsf_test_inst_t *inst)

typedef struct vsf_i2c_t	vsf_i2c_t

typedef struct vsf_usart_t	vsf_usart_t

typedef struct vsf_spi_t	vsf_spi_t

typedef struct vsf_adc_t	vsf_adc_t

typedef struct vsf_pwm_t	vsf_pwm_t

typedef struct vsf_dma_t	vsf_dma_t

typedef struct vsf_timer_t	vsf_timer_t

typedef struct vsf_rtc_t	vsf_rtc_t

typedef struct vsf_flash_t	vsf_flash_t

typedef struct vsf_wdt_t	vsf_wdt_t

typedef struct vsf_rng_t	vsf_rng_t

typedef struct vsf_gpio_t	vsf_gpio_t

typedef struct vsf_test_i2c_slave_ctx_t	vsf_test_i2c_slave_ctx_t

typedef struct vsf_test_gpio_pinmux_ctx_t	vsf_test_gpio_pinmux_ctx_t

typedef struct vsf_test_inst_t	vsf_test_inst_t

typedef struct vsf_test_t	vsf_test_t

Enumerations
enum	vsf_test_result_t { VSF_TEST_RESULT_PASS = 0 , VSF_TEST_RESULT_SKIP = 1 , VSF_TEST_RESULT_FAIL = 2 }

enum	vsf_peripheral_type_t { VSF_PERIPHERAL_TYPE_NONE = 0 , VSF_PERIPHERAL_TYPE_GPIO , VSF_PERIPHERAL_TYPE_USART , VSF_PERIPHERAL_TYPE_SPI , VSF_PERIPHERAL_TYPE_I2C , VSF_PERIPHERAL_TYPE_ADC , VSF_PERIPHERAL_TYPE_PWM , VSF_PERIPHERAL_TYPE_TIMER , VSF_PERIPHERAL_TYPE_RTC , VSF_PERIPHERAL_TYPE_WDT , VSF_PERIPHERAL_TYPE_RNG , VSF_PERIPHERAL_TYPE_DMA , VSF_PERIPHERAL_TYPE_FLASH , VSF_PERIPHERAL_TYPE_I2C_SLAVE , VSF_PERIPHERAL_TYPE_GPIO_PINMUX , VSF_PERIPHERAL_TYPE_ARCH }

Functions
void	vsf_test_trace (uint8_t level, const char *format,...)

	dcl_simple_class (vsf_test_suite_t) class vsf_test_case_t
	Test Suite — pure logic, no HAL binding.

void	vsf_test_run (vsf_test_t *test)
	initialize vsf test

void	vsf_test_assert (vsf_test_result_t result, const char file_name, uint32_t line, const char function_name, const char *condition)
	rong jump. the user does not need to directly call this API

void	vsf_test_reboot (vsf_test_result_t result, const char file_name, uint32_t line, const char function_name, const char *additional_str)
	reboot, usually called inside an exception.

void	vsf_test_busy_wait_ms (uint32_t ms)
	Busy-wait for approximately the given milliseconds. Useful for simple inter-step delays in test scenarios where vsf_systimer is not initialized. Calibrated by VSF_TEST_CFG_BUSY_WAIT_CYCLES_PER_MS.

void	vsf_test_busy_wait_us (uint32_t us)

void	vsf_test_hw_setup (vsf_test_t *test)
	Board-provided hardware init for the test framework. Fills wdt, reboot entries, peripheral instances, and instance count. Called once from main before vsf_test_run().

void	vsf_test_hw_config (vsf_peripheral_type_t peripheral_type, const vsf_test_inst_t *inst, bool init)
	GPIO config hook called before/after running test cases on an instance. Board override (weak): configure pinmux / GPIO for the peripheral under test.

vsf_test_result_t	vsf_test_run_suite_case (const vsf_test_suite_t suite, uint16_t local_idx, const vsf_test_inst_t inst)
	Run a single test case within a suite. No setup/teardown is performed — the caller is responsible for calling setup before the first case and teardown after the last case.

void	vsf_test_run_suite (const vsf_test_suite_t *suite)
	Run all cases in a suite. Calls setup before the first case and teardown after the last case. If setup returns false, all cases are skipped.

Macro Definition Documentation

◆ VSF_TEST_CFG_LONGJMP

#define VSF_TEST_CFG_LONGJMP ENABLED

< Using longjmp/setjmp for assertions

Note: do not move this pre-processor statement to other places Internal watchdog default timeout

◆ VSF_TEST_CFG_INTERNAL_TIMEOUT_MS

#define VSF_TEST_CFG_INTERNAL_TIMEOUT_MS 1000

External Watchdog Default Timeout.

◆ VSF_TEST_CFG_EXTERNAL_TIMEOUT_MS

#define VSF_TEST_CFG_EXTERNAL_TIMEOUT_MS 1500

Using the hal wdt device.

◆ VSF_TEST_CFG_USE_HAL_WDT

#define VSF_TEST_CFG_USE_HAL_WDT DISABLED

Enable trace output for test framework.

◆ VSF_TEST_CFG_USE_TRACE

#define VSF_TEST_CFG_USE_TRACE ENABLED

Emit Capture Markers (CASE:N / READY / DONE / :END) for host-side LA decode. Disabled by default — only needed when vsf-bench decodes LA captures.

◆ VSF_TEST_CFG_EMIT_MARKERS

#define VSF_TEST_CFG_EMIT_MARKERS DISABLED

Behaviour of the weak (un-overridden) vsf_test_hw_config(). DISABLED (default): assert — a board that needs per-test pin muxing but forgot to provide vsf_test_hw_config() fails loud instead of silently leaving pins unconfigured. ENABLED: just log, for boards that intentionally configure all pins elsewhere (e.g. boot-time pinmux).

◆ VSF_TEST_CFG_HW_CONFIG_LOG_ONLY

#define VSF_TEST_CFG_HW_CONFIG_LOG_ONLY DISABLED

Marker settle delay in milliseconds. Framework emits CASE/READY then waits this long before invoking the test function, ensuring marker bytes are fully on the wire before any test-driven UART activity begins. Overridden by test_params_generated.h when the test-params generator runs.

◆ VSF_TEST_MARKER_DELAY_MS

#define VSF_TEST_MARKER_DELAY_MS 2

Loop iterations per millisecond for vsf_test_busy_wait_ms. CPU-frequency dependent; default tuned for RP2040 @ 133MHz. Override per-board if needed.

◆ VSF_TEST_CFG_BUSY_WAIT_CYCLES_PER_MS

#define VSF_TEST_CFG_BUSY_WAIT_CYCLES_PER_MS 22000

Default poll tick (ms) used by vsf_test_busy_wait_ms() in polling loops. All test suites share this granularity; change globally in one place.

◆ VSF_TEST_POLL_TICK_MS

#define VSF_TEST_POLL_TICK_MS 1

◆ VSF_TEST_ASSERT

#define VSF_TEST_ASSERT ( __v )

Value:

            do {                                                               \
                if (!(__v)) {                                                  \
                    vsf_test_assert(VSF_TEST_RESULT_FAIL, __FILE__,         \
                                       __LINE__, __FUNCTION__, #__v);          \
                }                                                              \
            } while (0)

Add an assertion to the test case.

Parameters

__v	expressions for test conditions

◆ VSF_TEST_ASSERT_INST

#define VSF_TEST_ASSERT_INST	(	_inst,
		_pt,
		_field
	)

Value:

            do {                                                                   \
                VSF_TEST_ASSERT((_inst) != NULL);                                  \
                VSF_TEST_ASSERT((_inst)->peripheral_type == (_pt));                \
                VSF_TEST_ASSERT((_inst)->fixture._field != NULL);                  \
                VSF_TEST_ASSERT((_inst)->name != NULL);                            \
            } while (0)

Validate a test instance matches expected type and has non-null fixture.

Parameters

_inst	const vsf_test_inst_t pointer
_pt	expected vsf_peripheral_type_t value
_field	fixture union field name (e.g. gpio, usart, i2c)

◆ VSF_TEST_ASSERT_ERR

#define VSF_TEST_ASSERT_ERR	(	__err,
		__expected,
		...
	)

Value:

            do {                                                                   \
                vsf_err_t _vsf_err = (vsf_err_t)(__err);                           \
                if (_vsf_err != (vsf_err_t)(__expected)) {                         \
                    VSF_TEST_TRACE_ERROR(__VA_ARGS__);                             \
                }                                                                  \
                VSF_TEST_ASSERT(_vsf_err == (vsf_err_t)(__expected));              \
            } while (0)

Assert that an error code equals the expected value, with a pre-assertion TRACE_ERROR if it does not.

Parameters

__err	vsf_err_t expression (evaluated once)
__expected	expected vsf_err_t value
__VA_ARGS__	format string and args for VSF_TEST_TRACE_ERROR

◆ VSF_TEST_ASSERT_ERR_NONE

#define VSF_TEST_ASSERT_ERR_NONE	(	__err,
		...
	)	VSF_TEST_ASSERT_ERR(__err, VSF_ERR_NONE, __VA_ARGS__)

Convenience wrapper: assert err == VSF_ERR_NONE with TRACE_ERROR.

◆ VSF_TEST_WAIT_FOR

#define VSF_TEST_WAIT_FOR	(	__cond,
		__timeout_ms
	)

Value:

            do {                                                               \
                uint32_t _vsf_t = (uint32_t)(__timeout_ms);                    \
                while (!(__cond) && _vsf_t-- > 0) {                            \
                    vsf_test_busy_wait_ms(1);                                  \
                }                                                              \
            } while (0)

Busy-wait for a condition with a 1ms polling tick and timeout.

Parameters

__cond	expression that becomes true when ready
__timeout_ms	timeout in milliseconds

◆ VSF_TEST_SPIN_FOR

#define VSF_TEST_SPIN_FOR	(	__cond,
		__iterations
	)

Value:

            do {                                                               \
                uint32_t _vsf_i = (uint32_t)(__iterations);                    \
                while (!(__cond) && _vsf_i-- > 0) {}                           \
            } while (0)

Tight spin-wait for a condition with an iteration limit (no delay)

Parameters

__cond	expression that becomes true when ready
__iterations	max loop iterations

◆ VSF_TEST_TRACE_ERROR

#define VSF_TEST_TRACE_ERROR ( ... ) vsf_test_trace(VSF_TRACE_ERROR, __VA_ARGS__)

◆ VSF_TEST_TRACE_WARNING

#define VSF_TEST_TRACE_WARNING ( ... ) vsf_test_trace(VSF_TRACE_WARNING, __VA_ARGS__)

◆ VSF_TEST_TRACE_INFO

#define VSF_TEST_TRACE_INFO ( ... ) vsf_test_trace(VSF_TRACE_INFO, __VA_ARGS__)

Level-filtered trace output via the test shell's trace_level.

◆ VSF_TEST_TRACE_DEBUG

#define VSF_TEST_TRACE_DEBUG ( ... ) vsf_test_trace(VSF_TRACE_DEBUG, __VA_ARGS__)

Typedef Documentation

◆ vsf_test_result_t

typedef enum vsf_test_result_t vsf_test_result_t

◆ vsf_peripheral_type_t

typedef enum vsf_peripheral_type_t vsf_peripheral_type_t

◆ vsf_test_reboot_t

typedef void vsf_test_reboot_t(void)

◆ vsf_test_case_t

typedef struct vsf_test_case_t vsf_test_case_t

◆ vsf_test_jmp_fn_t

typedef void vsf_test_jmp_fn_t(const vsf_test_suite_t *suite, const vsf_test_case_t *tc, const vsf_test_inst_t *inst)

◆ vsf_i2c_t

typedef struct vsf_i2c_t vsf_i2c_t

◆ vsf_usart_t

typedef struct vsf_usart_t vsf_usart_t

◆ vsf_spi_t

typedef struct vsf_spi_t vsf_spi_t

◆ vsf_adc_t

typedef struct vsf_adc_t vsf_adc_t

◆ vsf_pwm_t

typedef struct vsf_pwm_t vsf_pwm_t

◆ vsf_dma_t

typedef struct vsf_dma_t vsf_dma_t

◆ vsf_timer_t

typedef struct vsf_timer_t vsf_timer_t

◆ vsf_rtc_t

typedef struct vsf_rtc_t vsf_rtc_t

◆ vsf_flash_t

typedef struct vsf_flash_t vsf_flash_t

◆ vsf_wdt_t

typedef struct vsf_wdt_t vsf_wdt_t

◆ vsf_rng_t

typedef struct vsf_rng_t vsf_rng_t

◆ vsf_gpio_t

typedef struct vsf_gpio_t vsf_gpio_t

◆ vsf_test_i2c_slave_ctx_t

typedef struct vsf_test_i2c_slave_ctx_t vsf_test_i2c_slave_ctx_t

Multi-device context for I2C slave test scenarios (master + slave pair).

◆ vsf_test_gpio_pinmux_ctx_t

typedef struct vsf_test_gpio_pinmux_ctx_t vsf_test_gpio_pinmux_ctx_t

Multi-device context for GPIO pinmux test scenarios (GPIO + alternate-function peripheral).

◆ vsf_test_inst_t

typedef struct vsf_test_inst_t vsf_test_inst_t

◆ vsf_test_t

typedef struct vsf_test_t vsf_test_t

Enumeration Type Documentation

◆ vsf_test_result_t

enum vsf_test_result_t

Enumerator
VSF_TEST_RESULT_PASS
VSF_TEST_RESULT_SKIP
VSF_TEST_RESULT_FAIL

◆ vsf_peripheral_type_t

enum vsf_peripheral_type_t

Enumerator
VSF_PERIPHERAL_TYPE_NONE
VSF_PERIPHERAL_TYPE_GPIO
VSF_PERIPHERAL_TYPE_USART
VSF_PERIPHERAL_TYPE_SPI
VSF_PERIPHERAL_TYPE_I2C
VSF_PERIPHERAL_TYPE_ADC
VSF_PERIPHERAL_TYPE_PWM
VSF_PERIPHERAL_TYPE_TIMER
VSF_PERIPHERAL_TYPE_RTC
VSF_PERIPHERAL_TYPE_WDT
VSF_PERIPHERAL_TYPE_RNG
VSF_PERIPHERAL_TYPE_DMA
VSF_PERIPHERAL_TYPE_FLASH
VSF_PERIPHERAL_TYPE_I2C_SLAVE
VSF_PERIPHERAL_TYPE_GPIO_PINMUX
VSF_PERIPHERAL_TYPE_ARCH

Function Documentation

◆ vsf_test_trace()

void vsf_test_trace	(	uint8_t	level,
		const char *	format,
			...
	)

extern

◆ dcl_simple_class()

dcl_simple_class ( vsf_test_suite_t )

Test Suite — pure logic, no HAL binding.

Each scenario extends vsf_test_suite_t via PLOOC and adds its scenario-specific fields (typically a HAL handle slot that the framework fills at runtime from the matching instance).

◆ vsf_test_run()

void vsf_test_run ( vsf_test_t * test )

extern

initialize vsf test

Parameters

[in] test test instance pointer (must not be NULL)

◆ vsf_test_assert()

void vsf_test_assert	(	vsf_test_result_t	result,
		const char *	file_name,
		uint32_t	line,
		const char *	function_name,
		const char *	condition
	)

extern

rong jump. the user does not need to directly call this API

Parameters

[in]	result	test result, vsf_test_result_t
[in]	file_name	then name of the file where the assertion occurred
[in]	line	the line number of the code where the assertion occurred
[in]	function_name	the name of the function where the assertion occurred
[in]	condition	String of asserted code

Note: This function will be called when the test case asserts that the condition is not satisfied.

◆ vsf_test_reboot()

void vsf_test_reboot	(	vsf_test_result_t	result,
		const char *	file_name,
		uint32_t	line,
		const char *	function_name,
		const char *	additional_str
	)

extern

reboot, usually called inside an exception.

Parameters

[in]	result	test result, vsf_test_result_t
[in]	file_name	then name of the file where the assertion occurred
[in]	line	the line number of the code where the assertion occurred
[in]	function_name	the name of the function where the assertion occurred
[in]	additional_str	provide additional exception information

◆ vsf_test_busy_wait_ms()

void vsf_test_busy_wait_ms ( uint32_t ms )

extern

Busy-wait for approximately the given milliseconds. Useful for simple inter-step delays in test scenarios where vsf_systimer is not initialized. Calibrated by VSF_TEST_CFG_BUSY_WAIT_CYCLES_PER_MS.

Parameters

[in] ms milliseconds to wait

◆ vsf_test_busy_wait_us()

void vsf_test_busy_wait_us ( uint32_t us )

extern

◆ vsf_test_hw_setup()

void vsf_test_hw_setup ( vsf_test_t * test )

extern

Board-provided hardware init for the test framework. Fills wdt, reboot entries, peripheral instances, and instance count. Called once from main before vsf_test_run().

Parameters

[in,out] test pointer to vsf_test_t to initialize hardware fields

◆ vsf_test_hw_config()

void vsf_test_hw_config	(	vsf_peripheral_type_t	peripheral_type,
		const vsf_test_inst_t *	inst,
		bool	init
	)

extern

GPIO config hook called before/after running test cases on an instance. Board override (weak): configure pinmux / GPIO for the peripheral under test.

Parameters

[in]	peripheral_type	VSF_PERIPHERAL_TYPE_* of the instance under test
[in]	arg	HAL handle (or array of handles) for the instance, same as suite->arg
[in]	init	true before cases, false after cases (teardown)

< Board intentionally configures all pins elsewhere (e.g. boot-time pinmux); just record that the default hook ran.

◆ vsf_test_run_suite_case()

vsf_test_result_t vsf_test_run_suite_case	(	const vsf_test_suite_t *	suite,
		uint16_t	local_idx,
		const vsf_test_inst_t *	inst
	)

extern

Run a single test case within a suite. No setup/teardown is performed — the caller is responsible for calling setup before the first case and teardown after the last case.

Parameters

[in]	suite	pointer to the suite containing the case
[in]	local_idx	index of the case within the suite's cases array

◆ vsf_test_run_suite()

void vsf_test_run_suite ( const vsf_test_suite_t * suite )

extern

Run all cases in a suite. Calls setup before the first case and teardown after the last case. If setup returns false, all cases are skipped.

Parameters

[in] suite pointer to the suite to run

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ VSF_TEST_CFG_LONGJMP

◆ VSF_TEST_CFG_INTERNAL_TIMEOUT_MS

◆ VSF_TEST_CFG_EXTERNAL_TIMEOUT_MS

◆ VSF_TEST_CFG_USE_HAL_WDT

◆ VSF_TEST_CFG_USE_TRACE

◆ VSF_TEST_CFG_EMIT_MARKERS

◆ VSF_TEST_CFG_HW_CONFIG_LOG_ONLY

◆ VSF_TEST_MARKER_DELAY_MS

◆ VSF_TEST_CFG_BUSY_WAIT_CYCLES_PER_MS

◆ VSF_TEST_POLL_TICK_MS

◆ VSF_TEST_ASSERT

◆ VSF_TEST_ASSERT_INST

◆ VSF_TEST_ASSERT_ERR

◆ VSF_TEST_ASSERT_ERR_NONE

◆ VSF_TEST_WAIT_FOR

◆ VSF_TEST_SPIN_FOR

◆ VSF_TEST_TRACE_ERROR

◆ VSF_TEST_TRACE_WARNING

◆ VSF_TEST_TRACE_INFO

◆ VSF_TEST_TRACE_DEBUG

Typedef Documentation

◆ vsf_test_result_t

◆ vsf_peripheral_type_t

◆ vsf_test_reboot_t

◆ vsf_test_case_t

◆ vsf_test_jmp_fn_t

◆ vsf_i2c_t

◆ vsf_usart_t

◆ vsf_spi_t

◆ vsf_adc_t

◆ vsf_pwm_t

◆ vsf_dma_t

◆ vsf_timer_t

◆ vsf_rtc_t

◆ vsf_flash_t

◆ vsf_wdt_t

◆ vsf_rng_t

◆ vsf_gpio_t

◆ vsf_test_i2c_slave_ctx_t

◆ vsf_test_gpio_pinmux_ctx_t

◆ vsf_test_inst_t

◆ vsf_test_t

Enumeration Type Documentation

◆ vsf_test_result_t

◆ vsf_peripheral_type_t

Function Documentation

◆ vsf_test_trace()

◆ dcl_simple_class()

◆ vsf_test_run()

◆ vsf_test_assert()

◆ vsf_test_reboot()

◆ vsf_test_busy_wait_ms()

◆ vsf_test_busy_wait_us()

◆ vsf_test_hw_setup()

◆ vsf_test_hw_config()

◆ vsf_test_run_suite_case()

◆ vsf_test_run_suite()