Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

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)    (ZTRESS_ID_K_TIMER, handler, user_data, exec_cnt, 0, init_timeout)
 Descriptor of a k_timer handler execution context.
 
#define ZTRESS_THREAD(handler, user_data, exec_cnt, preempt_cnt, init_timeout)    (ZTRESS_ID_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 </home/runner/work/sdk-nrf/sdk-nrf/ncs/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
_handlerHandler.
_user_dataUser data passed to the handler.
_exec_cntExecution count limit.
_preempt_cntPreemption count limit.
_tInitial timeout.

◆ ZTRESS_EXECUTE

#define ZTRESS_EXECUTE (   ...)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/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)
#define ARRAY_SIZE(array)
Number of elements in the given array.
Definition: util.h:127
int ztress_execute(struct ztress_context_data *timer_data, struct ztress_context_data *thread_data, size_t cnt)
Execute contexts.
Definition: ztress.h:100

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 
)     (ZTRESS_ID_THREAD, handler, user_data, exec_cnt, preempt_cnt, init_timeout)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

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
handlerUser handler of type ztress_handler.
user_dataUser data passed to the handler.
exec_cntNumber of handler executions to complete the test. If 0 then this is not included in completion criteria.
preempt_cntNumber of preemptions of that context to complete the test. If 0 then this is not included in completion criteria.
init_timeoutInitial 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 
)     (ZTRESS_ID_K_TIMER, handler, user_data, exec_cnt, 0, init_timeout)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

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
handlerUser handler of type ztress_handler.
user_dataUser data passed to the handler.
exec_cntNumber of handler executions to complete the test. If 0 then this is not included in completion criteria.
init_timeoutInitial 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 </home/runner/work/sdk-nrf/sdk-nrf/ncs/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

User handler called in one of the configured contexts.

Parameters
user_dataUser data provided in the context descriptor.
cntCurrent execution counter. Counted from 0.
lastFlag set to true indicates that it is the last execution because completion criteria are met, test timed out or was aborted.
prioContext priority counting from 0 which indicates the highest priority.
Return values
truecontinue test.
falsestop executing the current context.

Function Documentation

◆ ztress_abort()

void ztress_abort ( void  )

◆ ztress_exec_count()

int ztress_exec_count ( uint32_t  id)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

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

Parameters
idContext 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 </home/runner/work/sdk-nrf/sdk-nrf/ncs/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_dataTimer context. NULL if timer context is not used.
thread_dataList of thread contexts descriptors in priority descending order.
cntNumber of thread contexts.
Return values
-EINVALIf configuration is invalid.
0if test is successfully performed.

◆ ztress_optimized_ticks()

uint32_t ztress_optimized_ticks ( uint32_t  id)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/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
idContext id. 0 means the highest priority.
Returns
Optimized timeout base.

◆ ztress_preempt_count()

int ztress_preempt_count ( uint32_t  id)

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/zephyr/subsys/testsuite/ztest/include/zephyr/ztress.h>

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

Parameters
idContext id. 0 means the highest priority.
Returns
Number of preemptions.

◆ ztress_report()

void ztress_report ( void  )

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/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 </home/runner/work/sdk-nrf/sdk-nrf/ncs/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
tTimeout.