Statistics

Track and report subsystem event counters. More...

Files
file	stats.h
	Statistics.

Data Structures
struct	stats_name_map
	Describe one generated statistic entry name. More...
struct	stats_hdr
	Store metadata for one statistics group. More...

Walking and lookup
typedef int	stats_walk_fn(struct stats_hdr *hdr, void *arg, const char *name, uint16_t off)
	Function that gets applied to every stat entry during a walk.
typedef int	stats_group_walk_fn(struct stats_hdr *hdr, void *arg)
	Function that gets applied to every registered stats group.
int	stats_walk (struct stats_hdr *hdr, stats_walk_fn *walk_cb, void *arg)
	Applies a function to every stat entry in a group.
int	stats_group_walk (stats_group_walk_fn *walk_cb, void *arg)
	Applies a function every registered statistics group.
struct stats_hdr *	stats_group_get_next (const struct stats_hdr *cur)
	Retrieves the next registered statistics group.
struct stats_hdr *	stats_group_find (const char *name)
	Retrieves the statistics group with the specified name.

Initialization and registration
void	stats_init (struct stats_hdr *shdr, uint8_t size, uint16_t cnt, const struct stats_name_map *map, uint16_t map_cnt)
	Initializes a statistics group.
int	stats_register (const char *name, struct stats_hdr *shdr)
	Registers a statistics group to be managed.
int	stats_init_and_reg (struct stats_hdr *hdr, uint8_t size, uint16_t cnt, const struct stats_name_map *map, uint16_t map_cnt, const char *name)
	Initializes and registers a statistics group.
void	stats_reset (struct stats_hdr *shdr)
	Zeroes the specified statistics group.
#define	STATS_INIT_AND_REG(group__, size__, name__)
	Initializes and registers a statistics group.

Statistics group declarations
#define	STATS_SECT_DECL(group__)
	Declares a stat group struct.
#define	STATS_SECT_END   }
	Ends a stats group struct definition.
#define	STATS_SECT_START(group__)
	Begins a stats group struct definition.
#define	STATS_SECT_ENTRY(var__)
	Declares a 32-bit stat entry inside a group struct.
#define	STATS_SECT_ENTRY16(var__)
	Declares a 16-bit stat entry inside a group struct.
#define	STATS_SECT_ENTRY32(var__)
	Declares a 32-bit stat entry inside a group struct.
#define	STATS_SECT_ENTRY64(var__)
	Declares a 64-bit stat entry inside a group struct.
#define	STATS_SIZE_16   (sizeof(uint16_t))
	16-bit statistics entry size, in bytes.
#define	STATS_SIZE_32   (sizeof(uint32_t))
	32-bit statistics entry size, in bytes.
#define	STATS_SIZE_64   (sizeof(uint64_t))
	64-bit statistics entry size, in bytes.

Counter update helpers
#define	STATS_INCN(group__, var__, n__)
	Increases a statistic entry by the specified amount.
#define	STATS_INC(group__, var__)
	Increments a statistic entry.
#define	STATS_SET(group__, var__, n__)
	Set a statistic entry to the specified amount.
#define	STATS_CLEAR(group__, var__)
	Sets a statistic entry to zero.

Optional statistic names
These macros define the optional entry-name map used when CONFIG_STATS_NAMES is enabled. When the option is disabled, the name macros compile out and statistics entries are reported as generated names such as "s0" and "s1".
#define	STATS_NAME_START(sectname__)
	Begin a statistics entry name map.
#define	STATS_NAME(sectname__, entry__)
	Add an entry name to a statistics entry name map.
#define	STATS_NAME_END(sectname__)
	End a statistics entry name map.
#define	STATS_NAME_INIT_PARMS(name__)
	Expand name-map arguments for stats_init().

Detailed Description

Track and report subsystem event counters.

Statistics are per-module event counters for troubleshooting, maintenance, and usage monitoring. Statistics are organized into named "groups", with each group consisting of a set of "entries". An entry corresponds to an individual counter. Each entry can optionally be named if the CONFIG_STATS_NAMES setting is enabled. Statistics can be retrieved with the Statistics Management subsystem.

Statistics are useful for counting runtime events such as transfer attempts, bytes processed, recoverable errors, threshold hits, or other values that help diagnose behavior without adding custom management commands.

There are two, largely duplicated, statistics sections here, in order to provide the optional ability to name statistics.

STATS_SECT_START and STATS_SECT_END actually declare the statistics structure definition, STATS_SECT_DECL creates the structure declaration so you can declare these statistics as a global structure, and STATS_NAME_START and STATS_NAME_END are how you name the statistics themselves.

Statistics entries can be declared as any of several integer types. However, all statistics in a given structure must be of the same size, and they are all unsigned.

• STATS_SECT_ENTRY(): default statistic entry, 32-bits.
• STATS_SECT_ENTRY16(): 16-bits. Smaller statistics if you need to fit into specific RAM or code size numbers.
• STATS_SECT_ENTRY32(): 32-bits.
• STATS_SECT_ENTRY64(): 64-bits. Useful for storing chunks of data.

Following the static entry declaration is the statistic names declaration. This is compiled out when the CONFIG_STATS_NAMES setting is undefined.

When CONFIG_STATS_NAMES is defined, the statistics names are stored and returned to the management APIs. When the setting is undefined, temporary names are generated as needed with the following format:

s<stat-idx>

E.g., "s0", "s1", etc.

Example:

STATS_SECT_START(my_driver_stats)
STATS_SECT_ENTRY(rx_packets)
STATS_SECT_ENTRY(rx_bytes)
STATS_SECT_ENTRY(errors)
STATS_SECT_END;
 
STATS_NAME_START(my_driver_stats)
STATS_NAME(my_driver_stats, rx_packets)
STATS_NAME(my_driver_stats, rx_bytes)
STATS_NAME(my_driver_stats, errors)
STATS_NAME_END(my_driver_stats);
 
static STATS_SECT_DECL(my_driver_stats) stats;
 
static int my_driver_init(void)
{
    int rc;
 
    rc = STATS_INIT_AND_REG(stats, STATS_SIZE_32, "my_driver");
    if (rc != 0) {
        return rc;
    }
 
    return 0;
}
 
static void my_driver_rx_complete(size_t len)
{
    STATS_INC(stats, rx_packets);
    STATS_INCN(stats, rx_bytes, len);
}
 
static void my_driver_error(void)
{
    STATS_INC(stats, errors);
}

Macro Definition Documentation

STATS_CLEAR

#define STATS_CLEAR	(		group__,
			var__ )

#include <zephyr/stats/stats.h>

Value:

((group__).var__ = 0)

Sets a statistic entry to zero.

Sets a statistic entry to zero. Compiled out if CONFIG_STATS is not defined.

Parameters

group__	The group containing the entry to clear.
var__	The statistic entry to clear.

STATS_INC

#define STATS_INC	(		group__,
			var__ )

#include <zephyr/stats/stats.h>

Value:

STATS_INCN(group__, var__, 1)

Increments a statistic entry.

Increments a statistic entry by one. Compiled out if CONFIG_STATS is not defined.

Parameters

group__	The group containing the entry to increase.
var__	The statistic entry to increase.

STATS_INCN

#define STATS_INCN	(		group__,
			var__,
			n__ )

#include <zephyr/stats/stats.h>

Value:

((group__).var__ += (n__))

Increases a statistic entry by the specified amount.

Increases a statistic entry by the specified amount. Compiled out if CONFIG_STATS is not defined.

Parameters

group__	The group containing the entry to increase.
var__	The statistic entry to increase.
n__	The amount to increase the statistic entry by.

STATS_INIT_AND_REG

#define STATS_INIT_AND_REG	(		group__,
			size__,
			name__ )

#include <zephyr/stats/stats.h>

Value:

stats_init_and_reg(                                              \
        &(group__).s_hdr,                                        \
        (size__),                                                \
        (sizeof(group__) - sizeof(struct stats_hdr)) / (size__), \
        STATS_NAME_INIT_PARMS(group__),                          \
        (name__))

Initializes and registers a statistics group.

Parameters

group__	The statistics group to initialize and register.
size__	The size of each entry in the statistics group, in bytes. Must be one of: 2 (16-bits), 4 (32-bits) or 8 (64-bits).
name__	The name of the statistics group to register. This name must be unique among all statistics groups.

Return values

0	Success.
-EALREADY	A statistics group with the same name has already been registered.

STATS_NAME

#define STATS_NAME	(		sectname__,
			entry__ )

#include <zephyr/stats/stats.h>

Value:

{ offsetof(STATS_SECT_DECL(sectname__), entry__), #entry__ },

Add an entry name to a statistics entry name map.

Parameters

sectname__	Statistics group name passed to STATS_NAME_START.
entry__	Entry name declared in the statistics group.

STATS_NAME_END

#define STATS_NAME_END

(

sectname__

)

#include <zephyr/stats/stats.h>

Value:

}

End a statistics entry name map.

Parameters

sectname__

Statistics group name passed to STATS_NAME_START.

STATS_NAME_INIT_PARMS

#define STATS_NAME_INIT_PARMS

(

name__

)

#include <zephyr/stats/stats.h>

Value:

&(STATS_NAME_MAP_NAME(name__)[0]), \
(sizeof(STATS_NAME_MAP_NAME(name__)) / sizeof(struct stats_name_map))

Expand name-map arguments for stats_init().

This macro expands to the map pointer and map entry count expected by stats_init() or stats_init_and_reg(). When CONFIG_STATS_NAMES is disabled, it expands to NULL, 0.

Parameters

name__

Statistics group name passed to STATS_NAME_START.

STATS_NAME_START

#define STATS_NAME_START

(

sectname__

)

#include <zephyr/stats/stats.h>

Value:

static const struct stats_name_map STATS_NAME_MAP_NAME(sectname__)[] = {

Begin a statistics entry name map.

Use this macro with STATS_NAME and STATS_NAME_END to define names for entries declared in a statistics group.

Parameters

sectname__

Statistics group name passed to STATS_SECT_START.

STATS_SECT_DECL

#define STATS_SECT_DECL

(

group__

)

#include <zephyr/stats/stats.h>

Value:

struct stats_ ## group__

Declares a stat group struct.

Parameters

group__

The name to assign to the structure tag.

STATS_SECT_END

#define STATS_SECT_END   }

#include <zephyr/stats/stats.h>

Ends a stats group struct definition.

STATS_SECT_ENTRY

#define STATS_SECT_ENTRY

(

var__

)

#include <zephyr/stats/stats.h>

Value:

uint32_t var__;

Declares a 32-bit stat entry inside a group struct.

Parameters

var__

The name to assign to the entry.

STATS_SECT_ENTRY16

#define STATS_SECT_ENTRY16

(

var__

)

#include <zephyr/stats/stats.h>

Value:

uint16_t var__;

Declares a 16-bit stat entry inside a group struct.

Parameters

var__

The name to assign to the entry.

STATS_SECT_ENTRY32

#define STATS_SECT_ENTRY32

(

var__

)

#include <zephyr/stats/stats.h>

Value:

uint32_t var__;

Declares a 32-bit stat entry inside a group struct.

Parameters

var__

The name to assign to the entry.

STATS_SECT_ENTRY64

#define STATS_SECT_ENTRY64

(

var__

)

#include <zephyr/stats/stats.h>

Value:

uint64_t var__;

Declares a 64-bit stat entry inside a group struct.

Parameters

var__

The name to assign to the entry.

STATS_SECT_START

#define STATS_SECT_START

(

group__

)

#include <zephyr/stats/stats.h>

Value:

STATS_SECT_DECL(group__) { \
        struct stats_hdr s_hdr;

Begins a stats group struct definition.

Parameters

group__

The stats group struct name.

STATS_SET

#define STATS_SET	(		group__,
			var__,
			n__ )

#include <zephyr/stats/stats.h>

Value:

((group__).var__ = (n__))

Set a statistic entry to the specified amount.

Set a statistic entry to the specified amount. Compiled out if CONFIG_STATS is not defined.

Parameters

group__	The group containing the entry to increase.
var__	The statistic entry to increase.
n__	The amount to set the statistic entry to.

STATS_SIZE_16

#define STATS_SIZE_16   (sizeof(uint16_t))

#include <zephyr/stats/stats.h>

16-bit statistics entry size, in bytes.

STATS_SIZE_32

#define STATS_SIZE_32   (sizeof(uint32_t))

#include <zephyr/stats/stats.h>

32-bit statistics entry size, in bytes.

STATS_SIZE_64

#define STATS_SIZE_64   (sizeof(uint64_t))

#include <zephyr/stats/stats.h>

64-bit statistics entry size, in bytes.

Typedef Documentation

stats_group_walk_fn

typedef int stats_group_walk_fn(struct stats_hdr *hdr, void *arg)

#include <zephyr/stats/stats.h>

Function that gets applied to every registered stats group.

Parameters

hdr	The stats group being walked.
arg	Optional argument.

Returns

0 if the walk should proceed; nonzero to abort the walk.

stats_walk_fn

typedef int stats_walk_fn(struct stats_hdr *hdr, void *arg, const char *name, uint16_t off)

#include <zephyr/stats/stats.h>

Function that gets applied to every stat entry during a walk.

Parameters

hdr	The group containing the stat entry being walked.
arg	Optional argument.
name	The name of the statistic entry to process
off	The offset of the entry, from hdr.

Returns

0 if the walk should proceed; nonzero to abort the walk.

Function Documentation

stats_group_find()

struct stats_hdr * stats_group_find

(

const char *

name

)

#include <zephyr/stats/stats.h>

Retrieves the statistics group with the specified name.

Parameters

name	The name of the statistics group to look up.

Returns

Pointer to the retrieved group on success; NULL if there is no matching registered group.

stats_group_get_next()

struct stats_hdr * stats_group_get_next

(

const struct stats_hdr *

cur

)

#include <zephyr/stats/stats.h>

Retrieves the next registered statistics group.

Parameters

cur	The group whose successor is being retrieved, or NULL to retrieve the first group.

Returns

Pointer to the retrieved group on success; NULL if no more groups remain.

stats_group_walk()

int stats_group_walk	(	stats_group_walk_fn *	walk_cb,
		void *	arg )

#include <zephyr/stats/stats.h>

Applies a function every registered statistics group.

Parameters

walk_cb	The function to apply to each stat group.
arg	Optional argument to pass to the callback.

Returns

0 if the walk completed; nonzero if the walk was aborted.

stats_init()

void stats_init	(	struct stats_hdr *	shdr,
		uint8_t	size,
		uint16_t	cnt,
		const struct stats_name_map *	map,
		uint16_t	map_cnt )

#include <zephyr/stats/stats.h>

Initializes a statistics group.

Parameters

shdr	The header of the statistics structure, contains things like statistic section name, size of statistics entries, number of statistics, etc.
size	The size of each individual statistics element, in bytes. Must be one of: 2 (16-bits), 4 (32-bits) or 8 (64-bits).
cnt	The number of elements in the stats group.
map	The mapping of stat offset to name.
map_cnt	The number of items in the statistics map

stats_init_and_reg()

int stats_init_and_reg	(	struct stats_hdr *	hdr,
		uint8_t	size,
		uint16_t	cnt,
		const struct stats_name_map *	map,
		uint16_t	map_cnt,
		const char *	name )

#include <zephyr/stats/stats.h>

Initializes and registers a statistics group.

Initializes and registers a statistics group. Note: it is recommended to use the STATS_INIT_AND_REG macro instead of this function.

Parameters

hdr	The header of the statistics group to initialize and register.
size	The size of each individual statistics element, in bytes. Must be one of: 2 (16-bits), 4 (32-bits) or 8 (64-bits).
cnt	The number of elements in the stats group.
map	The mapping of stat offset to name.
map_cnt	The number of items in the statistics map
name	The name of the statistics group to register. This name must be unique among all statistics groups. If the name is a duplicate, this function will return -EALREADY.

Return values

0	Success.
-EALREADY	A statistics group with the same name has already been registered.

See also

STATS_INIT_AND_REG

stats_register()

int stats_register	(	const char *	name,
		struct stats_hdr *	shdr )

#include <zephyr/stats/stats.h>

Registers a statistics group to be managed.

Parameters

name	The name of the statistics group to register. This name must be unique among all statistics groups. If the name is a duplicate, this function will return -EALREADY.
shdr	The statistics group to register.

Return values

0	Success.
-EALREADY	A statistics group with the same name has already been registered.

stats_reset()

void stats_reset

(

struct stats_hdr *

shdr

)

#include <zephyr/stats/stats.h>

Zeroes the specified statistics group.

Parameters

shdr	The statistics group to clear.

stats_walk()

int stats_walk	(	struct stats_hdr *	hdr,
		stats_walk_fn *	walk_cb,
		void *	arg )

#include <zephyr/stats/stats.h>

Applies a function to every stat entry in a group.

Parameters

hdr	The stats group to operate on.
walk_cb	The function to apply to each stat entry.
arg	Optional argument to pass to the callback.

Returns

0 if the walk completed; nonzero if the walk was aborted.