Global flash based parameter store. More...

#include <stdint.h>
#include <stdbool.h>
#include <sys/types.h>

Classes
union	param_value_u
	Parameter value union. More...

struct	param_info_s
	Static parameter definition structure. More...

Macros
#define	PARAM_FILE_MAXSIZE 4096
	Maximum size of the parameter backing file.

#define	PARAM_TYPE_INT32 0
	Parameter types.

#define	PARAM_TYPE_FLOAT 1

#define	PARAM_TYPE_STRUCT 100

#define	PARAM_TYPE_STRUCT_MAX (16384 + PARAM_TYPE_STRUCT)

#define	PARAM_TYPE_UNKNOWN (0xffff)

#define	PARAM_INVALID ((uint32_t)0xffffffff)
	Handle returned when a parameter cannot be found.

#define	PARAM_HASH ((uint32_t)INT32_MAX)
	Magic handle for hash check param.

#define	PARAM_DEFINE_INT32(_name, _default)
	define an int32 parameter

#define	PARAM_DEFINE_FLOAT(_name, _default)
	define a float parameter

#define	PARAM_DEFINE_STRUCT(_name, _default)
	define a parameter that points to a structure

Typedefs
typedef uint16_t	param_type_t

typedef uint32_t	param_t
	Parameter handle. More...

Functions
__EXPORT void	param_init (void)
	Initialize the param backend. More...

__EXPORT param_t	param_find (const char *name)
	Look up a parameter by name. More...

__EXPORT param_t	param_find_no_notification (const char *name)
	Look up a parameter by name. More...

__EXPORT unsigned	param_count (void)
	Return the total number of parameters. More...

__EXPORT unsigned	param_count_used (void)
	Return the actually used number of parameters. More...

__EXPORT bool	param_used (param_t param)
	Wether a parameter is in use in the system. More...

__EXPORT param_t	param_for_index (unsigned index)
	Look up a parameter by index. More...

__EXPORT param_t	param_for_used_index (unsigned index)
	Look up an used parameter by index. More...

__EXPORT int	param_get_index (param_t param)
	Look up the index of a parameter. More...

__EXPORT int	param_get_used_index (param_t param)
	Look up the index of an used parameter. More...

__EXPORT const char *	param_name (param_t param)
	Obtain the name of a parameter. More...

__EXPORT bool	param_is_volatile (param_t param)
	Obtain the volatile state of a parameter. More...

__EXPORT bool	param_value_is_default (param_t param)
	Test whether a parameter's value has changed from the default. More...

__EXPORT bool	param_value_unsaved (param_t param)
	Test whether a parameter's value has been changed but not saved. More...

__EXPORT param_type_t	param_type (param_t param)
	Obtain the type of a parameter. More...

__EXPORT size_t	param_size (param_t param)
	Determine the size of a parameter. More...

__EXPORT int	param_get (param_t param, void *val)
	Copy the value of a parameter. More...

__EXPORT int	param_set (param_t param, const void *val)
	Set the value of a parameter. More...

__EXPORT void	param_set_used (param_t param)
	Mark a parameter as used. More...

__EXPORT int	param_set_no_notification (param_t param, const void *val)
	Set the value of a parameter, but do not notify the system about the change. More...

__EXPORT void	param_notify_changes (void)
	Notify the system about parameter changes. More...

__EXPORT int	param_reset (param_t param)
	Reset a parameter to its default value. More...

__EXPORT void	param_reset_all (void)
	Reset all parameters to their default values. More...

__EXPORT void	param_reset_excludes (const char *excludes[], int num_excludes)
	Reset all parameters to their default values except for excluded parameters. More...

__EXPORT int	param_export (int fd, bool only_unsaved)
	Export changed parameters to a file. More...

__EXPORT int	param_import (int fd)
	Import parameters from a file, discarding any unrecognized parameters. More...

__EXPORT int	param_load (int fd)
	Load parameters from a file. More...

__EXPORT void	param_foreach (void(func)(void arg, param_t param), void *arg, bool only_changed, bool only_used)
	Apply a function to each parameter. More...

__EXPORT int	param_set_default_file (const char *filename)
	Set the default parameter file name. More...

__EXPORT const char *	param_get_default_file (void)
	Get the default parameter file name. More...

__EXPORT int	param_save_default (void)
	Save parameters to the default file. More...

__EXPORT int	param_load_default (void)
	Load parameters from the default parameter file. More...

__EXPORT uint32_t	param_hash_check (void)
	Generate the hash of all parameters and their values. More...

__EXPORT void	param_print_status (void)
	Print the status of the param system. More...

__EXPORT void	param_control_autosave (bool enable)
	Enable/disable the param autosaving. More...

Detailed Description

Global flash based parameter store.

Global parameter store.

This provides the mechanisms to interface to the PX4 parameter system but replace the IO with non file based flash i/o routines. So that the code my be implemented on a SMALL memory foot print device.

Note that a number of API members are marked const or pure; these assume that the set of parameters cannot change, or that a parameter cannot change type or size over its lifetime. If any of these assumptions are invalidated, the attributes should be re-evaluated.

Typedef Documentation

§ param_t

typedef uint32_t param_t

Parameter handle.

Parameters are represented by parameter handles, which can be obtained by looking up parameters. They are an offset into a global constant parameter array.

Function Documentation

§ param_control_autosave()

__EXPORT void param_control_autosave ( bool enable )

Enable/disable the param autosaving.

Re-enabling with changed params will not cause an autosave.

Parameters

enable true: enable autosaving, false: disable autosaving

§ param_count()

__EXPORT unsigned param_count ( void )

Return the total number of parameters.

Returns: The number of parameters.

§ param_count_used()

__EXPORT unsigned param_count_used ( void )

Return the actually used number of parameters.

Returns: The number of parameters.

§ param_export()

__EXPORT int param_export	(	int	fd,
		bool	only_unsaved
	)

Export changed parameters to a file.

Note: this method requires a large amount of stack size!

Parameters

fd	File descriptor to export to (-1 selects the FLASH storage).
only_unsaved	Only export changed parameters that have not yet been exported.

Returns: Zero on success, nonzero on failure.

§ param_find()

__EXPORT param_t param_find ( const char * name )

Look up a parameter by name.

Parameters

name	The canonical name of the parameter being looked up.

Returns: A handle to the parameter, or PARAM_INVALID if the parameter does not exist. This call will also set the parameter as "used" in the system, which is used to e.g. show the parameter via the RC interface

§ param_find_no_notification()

__EXPORT param_t param_find_no_notification ( const char * name )

Look up a parameter by name.

Parameters

name	The canonical name of the parameter being looked up.

Returns: A handle to the parameter, or PARAM_INVALID if the parameter does not exist.

§ param_for_index()

__EXPORT param_t param_for_index ( unsigned index )

Look up a parameter by index.

Parameters

index An index from 0 to n, where n is param_count()-1.

Returns: A handle to the parameter, or PARAM_INVALID if the index is out of range.

§ param_for_used_index()

__EXPORT param_t param_for_used_index ( unsigned index )

Look up an used parameter by index.

Parameters

index The parameter to obtain the index for.

Returns: The index of the parameter in use, or -1 if the parameter does not exist.

§ param_foreach()

__EXPORT void param_foreach	(	void()(void arg, param_t param)	func,
		void *	arg,
		bool	only_changed,
		bool	only_used
	)

Apply a function to each parameter.

Note that the parameter set is not locked during the traversal. It also does not hold an internal state, so the callback function can block or sleep between parameter callbacks.

Parameters

func	The function to invoke for each parameter.
arg	Argument passed to the function.
only_changed	If true, the function is only called for parameters whose values have been changed from the default.
only_used	If true, the function is only called for parameters which have been used in one of the running applications.

§ param_get()

__EXPORT int param_get	(	param_t	param,
		void *	val
	)

Copy the value of a parameter.

Parameters

param	A handle returned by param_find or passed by param_foreach.
val	Where to return the value, assumed to point to suitable storage for the parameter type. For structures, a bitwise copy of the structure is performed to this address.

Returns: Zero if the parameter's value could be returned, nonzero otherwise.

§ param_get_default_file()

__EXPORT const char* param_get_default_file ( void )

Get the default parameter file name.

Returns: The path to the current default parameter file; either as a result of a call to param_set_default_file, or the built-in default.

§ param_get_index()

__EXPORT int param_get_index ( param_t param )

Look up the index of a parameter.

Parameters

param The parameter to obtain the index for.

Returns: The index, or -1 if the parameter does not exist.

§ param_get_used_index()

__EXPORT int param_get_used_index ( param_t param )

Look up the index of an used parameter.

Parameters

param The parameter to obtain the index for.

Returns: The index of the parameter in use, or -1 if the parameter does not exist.

§ param_hash_check()

__EXPORT uint32_t param_hash_check ( void )

Generate the hash of all parameters and their values.

Returns: CRC32 hash of all param_ids and values

§ param_import()

__EXPORT int param_import ( int fd )

Import parameters from a file, discarding any unrecognized parameters.

This function merges the imported parameters with the current parameter set.

Parameters

fd	File descriptor to import from (-1 selects the FLASH storage).

Returns: Zero on success, nonzero if an error occurred during import. Note that in the failure case, parameters may be inconsistent.

§ param_init()

__EXPORT void param_init ( void )

Initialize the param backend.

Call this on startup before calling any other methods.

§ param_is_volatile()

__EXPORT bool param_is_volatile ( param_t param )

Obtain the volatile state of a parameter.

Parameters

param A handle returned by param_find or passed by param_foreach.

Returns: true if the parameter is volatile

§ param_load()

__EXPORT int param_load ( int fd )

Load parameters from a file.

This function resets all parameters to their default values, then loads new values from a file.

Parameters

fd	File descriptor to import from (-1 selects the FLASH storage).

Returns: Zero on success, nonzero if an error occurred during import. Note that in the failure case, parameters may be inconsistent.

§ param_load_default()

__EXPORT int param_load_default ( void )

Load parameters from the default parameter file.

Returns: Zero on success.; 0 on success, 1 if all params have not yet been stored, -1 if device open failed, -2 if writing parameters failed

§ param_name()

__EXPORT const char* param_name ( param_t param )

Obtain the name of a parameter.

Parameters

param A handle returned by param_find or passed by param_foreach.

Returns: The name assigned to the parameter, or NULL if the handle is invalid.

§ param_notify_changes()

__EXPORT void param_notify_changes ( void )

Notify the system about parameter changes.

Can be used for example after several calls to param_set_no_notification() to avoid unnecessary system notifications.

§ param_print_status()

__EXPORT void param_print_status ( void )

Print the status of the param system.

§ param_reset()

__EXPORT int param_reset ( param_t param )

Reset a parameter to its default value.

This function frees any storage used by struct parameters, and returns the parameter to its default value.

Parameters

param A handle returned by param_find or passed by param_foreach.

Returns: Zero on success, nonzero on failure

§ param_reset_all()

__EXPORT void param_reset_all ( void )

Reset all parameters to their default values.

This function also releases the storage used by struct parameters.

§ param_reset_excludes()

__EXPORT void param_reset_excludes	(	const char *	excludes[],
		int	num_excludes
	)

Reset all parameters to their default values except for excluded parameters.

This function also releases the storage used by struct parameters.

Parameters

excludes	Array of param names to exclude from resetting. Use a wildcard at the end to exclude parameters with a certain prefix.
num_excludes	The number of excludes provided.

§ param_save_default()

__EXPORT int param_save_default ( void )

Save parameters to the default file.

Note: this method requires a large amount of stack size!

This function saves all parameters with non-default values.

Returns: Zero on success.

§ param_set()

__EXPORT int param_set	(	param_t	param,
		const void *	val
	)

Set the value of a parameter.

Parameters

param	A handle returned by param_find or passed by param_foreach.
val	The value to set; assumed to point to a variable of the parameter type. For structures, the pointer is assumed to point to a structure to be copied.

Returns: Zero if the parameter's value could be set from a scalar, nonzero otherwise.

§ param_set_default_file()

__EXPORT int param_set_default_file ( const char * filename )

Set the default parameter file name.

This has no effect if the FLASH-based storage is enabled.

Parameters

filename Path to the default parameter file. The file is not required to exist.

Returns: Zero on success.

§ param_set_no_notification()

__EXPORT int param_set_no_notification	(	param_t	param,
		const void *	val
	)

Set the value of a parameter, but do not notify the system about the change.

Parameters

param	A handle returned by param_find or passed by param_foreach.
val	The value to set; assumed to point to a variable of the parameter type. For structures, the pointer is assumed to point to a structure to be copied.

Returns: Zero if the parameter's value could be set from a scalar, nonzero otherwise.

§ param_set_used()

__EXPORT void param_set_used ( param_t param )

Mark a parameter as used.

Only marked parameters will be sent to a GCS. A call to param_find() will mark a param as used as well.

Parameters

param A handle returned by param_find or passed by param_foreach.

§ param_size()

__EXPORT size_t param_size ( param_t param )

Determine the size of a parameter.

Parameters

param A handle returned by param_find or passed by param_foreach.

Returns: The size of the parameter's value.

§ param_type()

__EXPORT param_type_t param_type ( param_t param )

Obtain the type of a parameter.

Parameters

param A handle returned by param_find or passed by param_foreach.

Returns: The type assigned to the parameter.

§ param_used()

__EXPORT bool param_used ( param_t param )

Wether a parameter is in use in the system.

Returns: True if it has been written or read

§ param_value_is_default()

__EXPORT bool param_value_is_default ( param_t param )

Test whether a parameter's value has changed from the default.

Returns: If true, the parameter's value has not been changed from the default.

§ param_value_unsaved()

__EXPORT bool param_value_unsaved ( param_t param )

Test whether a parameter's value has been changed but not saved.

Returns: If true, the parameter's value has not been saved.

Classes

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

§ param_t

Function Documentation

§ param_control_autosave()

§ param_count()

§ param_count_used()

§ param_export()

§ param_find()

§ param_find_no_notification()

§ param_for_index()

§ param_for_used_index()

§ param_foreach()

§ param_get()

§ param_get_default_file()

§ param_get_index()

§ param_get_used_index()

§ param_hash_check()

§ param_import()

§ param_init()

§ param_is_volatile()

§ param_load()

§ param_load_default()

§ param_name()

§ param_notify_changes()

§ param_print_status()

§ param_reset()

§ param_reset_all()

§ param_reset_excludes()

§ param_save_default()

§ param_set()

§ param_set_default_file()

§ param_set_no_notification()

§ param_set_used()

§ param_size()

§ param_type()

§ param_used()

§ param_value_is_default()

§ param_value_unsaved()