Ztest ztress macros

This module provides test stress when using Ztest. More...

Data Structures
struct	ztress_context_data

Macros
#define	ZTRESS_TIMER(handler, user_data, exec_cnt, init_timeout)
	Descriptor of a k_timer handler execution context.
#define	ZTRESS_THREAD(handler, user_data, exec_cnt, preempt_cnt, init_timeout)
	Descriptor of a thread execution context.
#define	ZTRESS_CONTEXT_INITIALIZER(_handler, _user_data, _exec_cnt, _preempt_cnt, _t)
	Initialize context structure.
#define	ZTRESS_EXECUTE(...)
	Setup and run stress test.

Typedefs
typedef bool(*	ztress_handler) (void *user_data, uint32_t cnt, bool last, int prio)
	User handler called in one of the configured contexts.

Functions
int	ztress_execute (struct ztress_context_data *timer_data, struct ztress_context_data *thread_data, size_t cnt)
	Execute contexts.
void	ztress_abort (void)
	Abort ongoing stress test.
void	ztress_set_timeout (k_timeout_t t)
	Set test timeout.
void	ztress_report (void)
	Print last test report.
int	ztress_exec_count (uint32_t id)
	Get number of executions of a given context in the last test.
int	ztress_preempt_count (uint32_t id)
	Get number of preemptions of a given context in the last test.
uint32_t	ztress_optimized_ticks (uint32_t id)
	Get optimized timeout base of a given context in the last test.

Detailed Description

This module provides test stress when using Ztest.

Macro Definition Documentation

ZTRESS_CONTEXT_INITIALIZER

#define ZTRESS_CONTEXT_INITIALIZER	(		_handler,
			_user_data,
			_exec_cnt,
			_preempt_cnt,
			_t )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Value:

        { \
                .handler = (_handler), \
                .user_data = (_user_data), \
                .exec_cnt = (_exec_cnt), \
                .preempt_cnt = (_preempt_cnt), \
                .t = (_t) \
        }

Initialize context structure.

For argument types see ztress_context_data. For more details see ZTRESS_THREAD.

Parameters

_handler	Handler.
_user_data	User data passed to the handler.
_exec_cnt	Execution count limit.
_preempt_cnt	Preemption count limit.
_t	Initial timeout.

ZTRESS_EXECUTE

#define ZTRESS_EXECUTE

(

...

)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Value:

        do {                                                    \
        Z_ZTRESS_TIMER_CONTEXT_VALIDATE(__VA_ARGS__);                                   \
        int has_timer = Z_ZTRESS_HAS_TIMER(__VA_ARGS__);                                \
        struct ztress_context_data _ctx_data1[] = {                                  \
                FOR_EACH(Z_ZTRESS_GET_HANDLER_DATA, (,), __VA_ARGS__)                   \
        };                                                                              \
        size_t cnt = ARRAY_SIZE(_ctx_data1) - has_timer;                              \
        static struct ztress_context_data _ctx_data[ARRAY_SIZE(_ctx_data1)];               \
        for (size_t i = 0; i < ARRAY_SIZE(_ctx_data1); i++) {                         \
                _ctx_data[i] = _ctx_data1[i];                                           \
        }                                                                               \
        int exec_err = ztress_execute(has_timer ? &_ctx_data[0] : NULL,                       \
                                 &_ctx_data[has_timer], cnt);                           \
                                                                                        \
        zassert_equal(exec_err, 0, "ztress_execute failed (err: %d)", exec_err);        \
} while (0)

Setup and run stress test.

It initialises all contexts and calls ztress_execute.

Parameters

...

List of contexts. Contexts are configured using ZTRESS_TIMER and ZTRESS_THREAD macros. ZTRESS_TIMER must be the first argument if used. Each thread context has an assigned priority. The priority is assigned in a descending order (first listed thread context has the highest priority). The maximum number of supported thread contexts, including the timer context, is configurable in Kconfig (ZTRESS_MAX_THREADS).

ZTRESS_THREAD

#define ZTRESS_THREAD	(		handler,
			user_data,
			exec_cnt,
			preempt_cnt,
			init_timeout )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Value:

        (ZTRESS_ID_THREAD, handler, user_data, exec_cnt, preempt_cnt, init_timeout)

Descriptor of a thread execution context.

The handler is executed in the thread context. The priority of the thread is determined based on the order in which contexts are listed in ZTRESS_EXECUTE.

Note

thread sleeps for random amount of time. Additionally, the thread busy-waits for a random length of time to further increase randomization in the test.

Parameters

handler	User handler of type ztress_handler.
user_data	User data passed to the handler.
exec_cnt	Number of handler executions to complete the test. If 0 then this is not included in completion criteria.
preempt_cnt	Number of preemptions of that context to complete the test. If 0 then this is not included in completion criteria.
init_timeout	Initial backoff time base (given in k_timeout_t). It is adjusted during the test to optimize CPU load. The actual timeout used for sleeping is randomized.

ZTRESS_TIMER

#define ZTRESS_TIMER	(		handler,
			user_data,
			exec_cnt,
			init_timeout )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Value:

        (ZTRESS_ID_K_TIMER, handler, user_data, exec_cnt, 0, init_timeout)

Descriptor of a k_timer handler execution context.

The handler is executed in the k_timer handler context which typically means interrupt context. This context will preempt any other used in the set.

Note

There can only be up to one k_timer context in the set and it must be the first argument of ZTRESS_EXECUTE.

Parameters

handler	User handler of type ztress_handler.
user_data	User data passed to the handler.
exec_cnt	Number of handler executions to complete the test. If 0 then this is not included in completion criteria.
init_timeout	Initial backoff time base (given in k_timeout_t). It is adjusted during the test to optimize CPU load. The actual timeout used for the timer is randomized.

Typedef Documentation

ztress_handler

typedef bool(* ztress_handler) (void *user_data, uint32_t cnt, bool last, int prio)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

User handler called in one of the configured contexts.

Parameters

user_data	User data provided in the context descriptor.
cnt	Current execution counter. Counted from 0.
last	Flag set to true indicates that it is the last execution because completion criteria are met, test timed out or was aborted.
prio	Context priority counting from 0 which indicates the highest priority.

Return values

true	continue test.
false	stop executing the current context.

Function Documentation

ztress_abort()

void ztress_abort

(

void

)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Abort ongoing stress test.

ztress_exec_count()

int ztress_exec_count

(

uint32_t

id

)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Get number of executions of a given context in the last test.

Parameters

id	Context id. 0 means the highest priority.

Returns

Number of executions.

ztress_execute()

int ztress_execute	(	struct ztress_context_data *	timer_data,
		struct ztress_context_data *	thread_data,
		size_t	cnt )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Execute contexts.

The test runs until all completion requirements are met or until the test times out (use ztress_set_timeout to configure timeout) or until the test is aborted (ztress_abort).

on test completion a report is printed (ztress_report is called internally).

Parameters

timer_data	Timer context. NULL if timer context is not used.
thread_data	List of thread contexts descriptors in priority descending order.
cnt	Number of thread contexts.

Return values

-EINVAL	If configuration is invalid.
0	if test is successfully performed.

ztress_optimized_ticks()

uint32_t ztress_optimized_ticks

(

uint32_t

id

)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Get optimized timeout base of a given context in the last test.

Optimized value can be used to update initial value. It will improve the test since optimal CPU load will be reach immediately.

Parameters

id	Context id. 0 means the highest priority.

Returns

Optimized timeout base.

ztress_preempt_count()

int ztress_preempt_count

(

uint32_t

id

)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Get number of preemptions of a given context in the last test.

Parameters

id	Context id. 0 means the highest priority.

Returns

Number of preemptions.

ztress_report()

void ztress_report

(

void

)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Print last test report.

Report contains number of executions and preemptions for each context, initial and adjusted timeouts and CPU load during the test.

ztress_set_timeout()

void ztress_set_timeout

(

k_timeout_t

t

)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

Set test timeout.

Test is terminated after timeout disregarding completion criteria. Setting is persistent between executions.

Parameters

t

Timeout.