parameter.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Data Structures
union	kfsw_param_scalar
struct	kfsw_param_value
struct	kfsw_param_info
struct	kfsw_param_table_info
struct	kfsw_param_definition
struct	kfsw_param_definition_set
struct	kfsw_param_stats

Macros
#define	KFSW_PARAM_STRING_MAX   CONFIG_KFSW_PARAM_STRING_MAX
#define	KFSW_PARAM_NAME_MAX   32U
#define	KFSW_PARAM_TABLE_INVALID   0U
#define	KFSW_PARAM_TABLE_CORE_FIRST   1U
#define	KFSW_PARAM_TABLE_CORE_LAST   24U
#define	KFSW_PARAM_TABLE_SERVICE_FIRST   25U
#define	KFSW_PARAM_TABLE_SERVICE_LAST   49U
#define	KFSW_PARAM_TABLE_MODULE_FIRST   50U
#define	KFSW_PARAM_TABLE_MODULE_LAST   99U
#define	KFSW_PARAM_OFFSET_MAX   255U
#define	KFSW_PARAM_FLAG_READ_ONLY   0x00000001UL
#define	KFSW_PARAM_FLAG_CONFIGURATION   0x00000004UL
#define	KFSW_PARAM_FLAG_SYSTEM_INFO   0x00000040UL
#define	KFSW_PARAM_FLAG_DEBUG   0x00000200UL
#define	KFSW_PARAM_FLAG_PERSISTENT   0x00010000UL
#define	KFSW_PARAM_FLAG_LIVE   0x00020000UL
#define	KFSW_PARAM_FLAG_LOCAL_ONLY   0x00040000UL
#define	KFSW_PARAM_ID(table, offset)   ((uint16_t)(((uint16_t)(table) << 8) | (uint8_t)(offset)))
#define	KFSW_PARAM_PARAM_TABLE_ID   26U
#define	KFSW_PARAM_PARAM_TABLE_NAME   "param"

Types
typedef int(*	kfsw_param_validator_t) (const union kfsw_param_scalar *value)
typedef int(*	kfsw_param_text_validator_t) (const char *text)
typedef int(*	kfsw_param_data_validator_t) (const uint8_t *data, size_t size)
typedef void(*	kfsw_param_changed_t) (const union kfsw_param_scalar *value)
typedef void(*	kfsw_param_text_changed_t) (const char *text)
typedef void(*	kfsw_param_data_changed_t) (const uint8_t *data, size_t size)
typedef void(*	kfsw_param_sample_t) (void *value)
typedef bool(*	kfsw_param_visitor_t) (const struct kfsw_param_info *info, void *context)
typedef bool(*	kfsw_param_table_visitor_t) (const struct kfsw_param_table_info *info, void *context)

Enumerations
enum	kfsw_param_type {   KFSW_PARAM_U8 , KFSW_PARAM_U16 , KFSW_PARAM_U32 , KFSW_PARAM_U64 ,   KFSW_PARAM_I8 , KFSW_PARAM_I16 , KFSW_PARAM_I32 , KFSW_PARAM_I64 ,   KFSW_PARAM_X8 , KFSW_PARAM_X16 , KFSW_PARAM_X32 , KFSW_PARAM_X64 ,   KFSW_PARAM_FLOAT , KFSW_PARAM_DOUBLE , KFSW_PARAM_STRING , KFSW_PARAM_DATA ,   KFSW_PARAM_INVALID }

Functions
int	kfsw_param_init (const struct kfsw_param_definition_set *const *sets, size_t set_count)
bool	kfsw_param_is_initialized (void)
int	kfsw_param_get (const char *name, struct kfsw_param_value *value)
int	kfsw_param_set (const char *name, const struct kfsw_param_value *value)
int	kfsw_param_get_by_id (uint16_t id, struct kfsw_param_value *value)
int	kfsw_param_get_info (const char *name, struct kfsw_param_info *info)
int	kfsw_param_visit (kfsw_param_visitor_t visitor, void *context)
int	kfsw_param_visit_tables (kfsw_param_table_visitor_t visitor, void *context)
size_t	kfsw_param_table_count (void)
int	kfsw_param_get_stats (struct kfsw_param_stats *stats)
bool	kfsw_param_autosave_enabled (void)
const char *	kfsw_param_band_name (uint8_t table)
const char *	kfsw_param_mode_name (uint32_t flags)
int	kfsw_param_persist_save (void)
int	kfsw_param_persist_load (void)
int	kfsw_param_persist_clear (void)
int	kfsw_param_persist_table_count (uint8_t table, uint16_t *count)
uint32_t	kfsw_param_persist_bytes (void)
uint32_t	kfsw_param_persist_max_bytes (void)
int	kfsw_param_restore_defaults (void)
int	kfsw_param_server_start (void)
int	kfsw_param_remote_refresh (uint16_t node)
int	kfsw_param_remote_get (uint16_t node, const char *name, struct kfsw_param_value *value)
int	kfsw_param_remote_get_many (uint16_t node, const char *const *names, size_t count, struct kfsw_param_value *values)
int	kfsw_param_remote_get_many_until (uint16_t node, const char *const *names, size_t count, struct kfsw_param_value *values, int64_t deadline)
int	kfsw_param_remote_visit_until (uint16_t node, kfsw_param_visitor_t visitor, void *context, int64_t deadline)
int	kfsw_param_remote_set (uint16_t node, const char *name, const struct kfsw_param_value *value)
int	kfsw_param_remote_visit (uint16_t node, kfsw_param_visitor_t visitor, void *context)
const char *	kfsw_param_type_name (enum kfsw_param_type type)

Variables
const struct kfsw_param_definition_set	kfsw_param_param_definitions

Description

Local, remote, and persistent parameter API.

Macro Documentation

KFSW_PARAM_FLAG_CONFIGURATION

#define KFSW_PARAM_FLAG_CONFIGURATION   0x00000004UL

Parameter controls operator-selected configuration.

KFSW_PARAM_FLAG_DEBUG

#define KFSW_PARAM_FLAG_DEBUG   0x00000200UL

Parameter exists for diagnostic or test behavior.

KFSW_PARAM_FLAG_LIVE

#define KFSW_PARAM_FLAG_LIVE   0x00020000UL

User flag: a write takes effect immediately.

Set for every definition with a change callback; a definition that reads its value every cycle can set it too.

KFSW_PARAM_FLAG_LOCAL_ONLY

#define KFSW_PARAM_FLAG_LOCAL_ONLY   0x00040000UL

Parameter may be configured locally, but remote writes are refused.

KFSW_PARAM_FLAG_PERSISTENT

#define KFSW_PARAM_FLAG_PERSISTENT   0x00010000UL

User flag: the value is saved in the snapshot.

KFSW_PARAM_FLAG_READ_ONLY

#define KFSW_PARAM_FLAG_READ_ONLY   0x00000001UL

Parameter cannot be changed through local or remote set operations.

KFSW_PARAM_FLAG_SYSTEM_INFO

#define KFSW_PARAM_FLAG_SYSTEM_INFO   0x00000040UL

Parameter reports build or runtime system identity.

KFSW_PARAM_ID

#define KFSW_PARAM_ID	(		table,
			offset
	)		((uint16_t)(((uint16_t)(table) << 8) | (uint8_t)(offset)))

Build the wire ID for a table and offset.

KFSW_PARAM_NAME_MAX

#define KFSW_PARAM_NAME_MAX   32U

Longest parameter name, excluding the terminator.

Longer names are refused.

KFSW_PARAM_OFFSET_MAX

#define KFSW_PARAM_OFFSET_MAX   255U

Largest offset addressable within one table.

KFSW_PARAM_PARAM_TABLE_ID

#define KFSW_PARAM_PARAM_TABLE_ID   26U

Parameter table of the parameter service, in the service band.

KFSW_PARAM_PARAM_TABLE_NAME

#define KFSW_PARAM_PARAM_TABLE_NAME   "param"

Parameter table name.

KFSW_PARAM_STRING_MAX

#define KFSW_PARAM_STRING_MAX   CONFIG_KFSW_PARAM_STRING_MAX

Longest string parameter, including the terminator.

KFSW_PARAM_TABLE_CORE_FIRST

#define KFSW_PARAM_TABLE_CORE_FIRST   1U

First and last table of the application, platform and comms layers.

KFSW_PARAM_TABLE_INVALID

#define KFSW_PARAM_TABLE_INVALID   0U

Table ID bands.

A parameter is addressed by table and offset, and the band shows whether a table is core, service or module. Zero is reserved.

KFSW_PARAM_TABLE_MODULE_FIRST

#define KFSW_PARAM_TABLE_MODULE_FIRST   50U

First and last module table.

KFSW_PARAM_TABLE_SERVICE_FIRST

#define KFSW_PARAM_TABLE_SERVICE_FIRST   25U

First and last service table.

Type Documentation

kfsw_param_changed_t

typedef void(* kfsw_param_changed_t) (const union kfsw_param_scalar *value)

Called after the stored scalar changes.

kfsw_param_data_changed_t

typedef void(* kfsw_param_data_changed_t) (const uint8_t *data, size_t size)

Called after the stored byte array changes.

kfsw_param_data_validator_t

typedef int(* kfsw_param_data_validator_t) (const uint8_t *data, size_t size)

Validate the whole proposed byte array; return zero to accept it.

kfsw_param_sample_t

typedef void(* kfsw_param_sample_t) (void *value)

Refresh the stored value just before it is read.

Runs under the table lock, so it must not call the parameter API.

kfsw_param_text_changed_t

typedef void(* kfsw_param_text_changed_t) (const char *text)

Called after the stored string changes.

kfsw_param_text_validator_t

typedef int(* kfsw_param_text_validator_t) (const char *text)

Validate a proposed string; return zero to accept it.

Separate from the scalar validator because a string does not fit the scalar union.

kfsw_param_validator_t

typedef int(* kfsw_param_validator_t) (const union kfsw_param_scalar *value)

Validate a proposed scalar value; return zero to accept it.

Enumeration Documentation

kfsw_param_type

enum kfsw_param_type

Enumerator
KFSW_PARAM_DATA	Fixed-length byte array, such as per-module log levels.

Function Documentation

kfsw_param_autosave_enabled()

bool kfsw_param_autosave_enabled

(

void

)

Whether an accepted change to a persistent value writes a snapshot.

kfsw_param_band_name()

const char * kfsw_param_band_name

(

uint8_t

table

)

Name of the band a table ID falls in.

Returns

"core", "service", "module", or "invalid" for an unallocated value.

kfsw_param_get()

int kfsw_param_get	(	const char *	name,
		struct kfsw_param_value *	value
	)

Read a scalar local parameter by name.

kfsw_param_get_by_id()

int kfsw_param_get_by_id	(	uint16_t	id,
		struct kfsw_param_value *	value
	)

Read a parameter by its wire ID.

Samples the value like kfsw_param_get().

kfsw_param_get_info()

int kfsw_param_get_info	(	const char *	name,
		struct kfsw_param_info *	info
	)

Read one local parameter's description by name.

Parameters

	name	Parameter name.
[out]	info	Destination description.

Return values

0	The description was written.
-EINVAL	name or info is NULL.
-EACCES	The local table is not initialized.
-ENOENT	No parameter of that name is registered.

kfsw_param_get_stats()

int kfsw_param_get_stats

(

struct kfsw_param_stats *

stats

)

Read service counters.

Returns -EINVAL for a NULL destination.

kfsw_param_init()

int kfsw_param_init	(	const struct kfsw_param_definition_set *const *	sets,
		size_t	set_count
	)

Aggregate, validate, and enable the supplied component definition sets.

kfsw_param_is_initialized()

bool kfsw_param_is_initialized

(

void

)

Return whether the local parameter table was initialized successfully.

kfsw_param_mode_name()

const char * kfsw_param_mode_name

(

uint32_t

flags

)

Write behaviour implied by a parameter's flags.

Returns

"r" read-only, "w" applied immediately, "b" stored until reboot, "wb" both.

How a parameter can be written, as letters.

r read-only w writable p persistent: the value survives a reset b boot: the write is read when the node next starts

The returned pointer is a string literal.

kfsw_param_persist_bytes()

uint32_t kfsw_param_persist_bytes

(

void

)

Space the last built snapshot occupied, in bytes.

kfsw_param_persist_clear()

int kfsw_param_persist_clear

(

void

)

Delete the active persistent snapshot and any abandoned temporary file.

kfsw_param_persist_load()

int kfsw_param_persist_load

(

void

)

Load a valid snapshot, ignoring unknown names and incompatible entries.

kfsw_param_persist_max_bytes()

uint32_t kfsw_param_persist_max_bytes

(

void

)

Most space a snapshot is allowed to occupy, in bytes.

kfsw_param_persist_save()

int kfsw_param_persist_save

(

void

)

Save all explicitly persistent local parameters as one atomic snapshot.

kfsw_param_persist_table_count()

int kfsw_param_persist_table_count	(	uint8_t	table,
		uint16_t *	count
	)

Count persistent parameters in a table.

Parameters

	table	Table identifier.
[out]	count	Persistent parameters in that table.

Return values

0	Counted.
-EINVAL	NULL destination.
-ENOENT	No such table.

kfsw_param_remote_get()

int kfsw_param_remote_get	(	uint16_t	node,
		const char *	name,
		struct kfsw_param_value *	value
	)

Read a scalar parameter from a selected CSP node.

kfsw_param_remote_get_many()

int kfsw_param_remote_get_many	(	uint16_t	node,
		const char *const *	names,
		size_t	count,
		struct kfsw_param_value *	values
	)

Read several parameters from one node in as few exchanges as possible.

The whole operation shares one time budget, and each receive is also limited by CONFIG_KFSW_PARAM_TIMEOUT_MS. values must hold count entries. All names are resolved before anything is requested. Returns 0 with every value filled, or an errno if any value is missing.

kfsw_param_remote_get_many_until()

int kfsw_param_remote_get_many_until	(	uint16_t	node,
		const char *const *	names,
		size_t	count,
		struct kfsw_param_value *	values,
		int64_t	deadline
	)

Same read with an absolute k_uptime_get() deadline, including mutex waits.

kfsw_param_remote_refresh()

int kfsw_param_remote_refresh

(

uint16_t

node

)

Refresh a node's indexed v4 list; publish it only after count and CRC verification.

kfsw_param_remote_set()

int kfsw_param_remote_set	(	uint16_t	node,
		const char *	name,
		const struct kfsw_param_value *	value
	)

Write a scalar parameter on a selected CSP node.

kfsw_param_remote_visit()

int kfsw_param_remote_visit	(	uint16_t	node,
		kfsw_param_visitor_t	visitor,
		void *	context
	)

Visit a node's descriptors.

Copy borrowed strings before the callback returns.

kfsw_param_remote_visit_until()

int kfsw_param_remote_visit_until	(	uint16_t	node,
		kfsw_param_visitor_t	visitor,
		void *	context,
		int64_t	deadline
	)

Visit within an absolute uptime deadline.

Copy names before returning from the callback. The callback must not call remote PARAM operations or block indefinitely.

kfsw_param_restore_defaults()

int kfsw_param_restore_defaults

(

void

)

Restore persistent parameters to their compiled defaults in RAM only.

kfsw_param_server_start()

int kfsw_param_server_start

(

void

)

Register the optional CSP parameter and parameter-list endpoints once.

kfsw_param_set()

int kfsw_param_set	(	const char *	name,
		const struct kfsw_param_value *	value
	)

Write a scalar local parameter after exact type/size validation.

kfsw_param_table_count()

size_t kfsw_param_table_count

(

void

)

Registered local tables.

kfsw_param_type_name()

const char * kfsw_param_type_name

(

enum kfsw_param_type

type

)

Return a stable printable name for a K-FSW parameter type.

kfsw_param_visit()

int kfsw_param_visit	(	kfsw_param_visitor_t	visitor,
		void *	context
	)

Visit local parameter descriptions, ordered by table then offset.

kfsw_param_visit_tables()

int kfsw_param_visit_tables	(	kfsw_param_table_visitor_t	visitor,
		void *	context
	)

Visit each registered local table once, in ascending identifier order.

Variable Documentation

kfsw_param_param_definitions

const struct kfsw_param_definition_set kfsw_param_param_definitions

extern

Parameter service counters and settings.