Major cleanup of the param code; more layering, more comments. Parameter import.

1 files changed, 80 insertions, 27 deletions

diff --git a/apps/systemlib/param/param.h b/apps/systemlib/param/param.h
index 0d94ce6e3..29857b46b 100644
--- a/apps/systemlib/param/param.h
+++ b/apps/systemlib/param/param.h
@@ -1,7 +1,45 @@
+/****************************************************************************
+ *
+ *   Copyright (C) 2012 PX4 Development Team. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ * 3. Neither the name PX4 nor the names of its contributors may be
+ *    used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ ****************************************************************************/
+
 /**
  * @file param.h
  *
  * Global parameter store.
+ *
+ * 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.
  */
 
 #ifndef _SYSTEMLIB_PARAM_PARAM_H
@@ -10,16 +48,18 @@
 #include <stdint.h>
 #include <stdbool.h>
 
+/** Maximum size of the parameter backing file */
+#define PARAM_FILE_MAXSIZE	4096
+
 /**
  * Parameter types.
  */
-typedef enum param_type_e
-{
+typedef enum param_type_e {
 	/* globally-known parameter types */
 	PARAM_TYPE_INT32 = 0,
 	PARAM_TYPE_FLOAT,
 
-	/* structure parameters; these are expected to be identified by name */
+	/* structure parameters; size is encoded in the type value */
 	PARAM_TYPE_STRUCT = 100,
 	PARAM_TYPE_STRUCT_MAX = 16384 + PARAM_TYPE_STRUCT,
 
@@ -45,7 +85,22 @@ typedef uintptr_t	param_t;
  * @param name		The canonical name of the parameter being looked up.
  * @return		A handle to the parameter, or PARAM_INVALID if the parameter does not exist.
  */
-__EXPORT param_t	param_find(const char *name);
+__EXPORT param_t	param_find(const char *name) __attribute__((const));
+
+/**
+ * Return the total number of parameters.
+ *
+ * @return		The number of parameters.
+ */
+__EXPORT unsigned	param_count(void) __attribute__((const));
+
+/**
+ * Look up a parameter by index.
+ *
+ * @param index		An index from 0 to n, where n is param_count()-1.
+ * @return		A handle to the parameter, or PARAM_INVALID if the index is out of range.
+ */
+__EXPORT param_t	param_for_index(unsigned index) __attribute__((const));
 
 /**
  * Obtain the name of a parameter.
@@ -53,7 +108,7 @@ __EXPORT param_t	param_find(const char *name);
  * @param param		A handle returned by param_find or passed by param_foreach.
  * @return		The name assigned to the parameter, or NULL if the handle is invalid.
  */
-__EXPORT const char	*param_name(param_t param);
+__EXPORT const char	*param_name(param_t param) __attribute__((const));
 
 /**
  * Obtain the type of a parameter.
@@ -61,7 +116,7 @@ __EXPORT const char	*param_name(param_t param);
  * @param param		A handle returned by param_find or passed by param_foreach.
  * @return		The type assigned to the parameter.
  */
-__EXPORT param_type_t	param_type(param_t param);
+__EXPORT param_type_t	param_type(param_t param) __attribute__((const));
 
 /**
  * Determine the size of a parameter.
@@ -69,15 +124,15 @@ __EXPORT param_type_t	param_type(param_t param);
  * @param param		A handle returned by param_find or passed by param_foreach.
  * @return		The size of the parameter's value.
  */
-__EXPORT size_t		param_size(param_t param);
+__EXPORT size_t		param_size(param_t param) __attribute__((const));
 
 /**
- * Obtain the scalar value of a parameter.
+ * Copy the value of a parameter.
  *
  * @param param		A handle returned by param_find or passed by param_foreach.
  * @param val		Where to return the value, assumed to point to suitable storage for the parameter type.
- *			For structures, a pointer to the structure is returned.
- * @return		Zero if the parameter's value could be returned as a scalar, nonzero otherwise.
+ *			For structures, a bitwise copy of the structure is performed to this address.
+ * @return		Zero if the parameter's value could be returned, nonzero otherwise.
  */
 __EXPORT int		param_get(param_t param, void *val);
 
@@ -89,25 +144,25 @@ __EXPORT int		param_get(param_t param, void *val);
  *			For structures, the pointer is assumed to point to a copy of the structure.
  * @return		Zero if the parameter's value could be set from a scalar, nonzero otherwise.
  */
-__EXPORT int		param_set(param_t param, void *val);
+__EXPORT int		param_set(param_t param, const void *val);
 
 /**
  * Export changed parameters to a file.
  *
- * @param filename	The name of the file to export to.  If it exists, it will be overwritten.
+ * @param fd		File descriptor to export to.
  * @param only_unsaved	Only export changed parameters that have not yet been exported.
  * @return		Zero on success, nonzero on failure.
  */
-__EXPORT int		param_export(const char *filename, bool only_unsaved);
+__EXPORT int		param_export(int fd, bool only_unsaved);
 
 /**
  * Import parameters from a file, discarding any unrecognised parameters.
  *
- * @param filename	The name of the file to import from.
+ * @param fd		File descriptor to import from.  (Currently expected to be a file.)
  * @return		Zero on success, nonzero if an error occurred during import.
  *			Note that in the failure case, parameters may be inconsistent.
  */
-__EXPORT int		param_import(const char *filename);
+__EXPORT int		param_import(int fd);
 
 /**
  * Apply a function to each parameter.
@@ -124,7 +179,7 @@ __EXPORT void		param_foreach(void (*func)(void *arg, param_t param), void *arg,
 /*
  * Macros creating static parameter definitions.
  *
- * Note that these structures are not known by name; they are 
+ * Note that these structures are not known by name; they are
  * collected into a section that is iterated by the parameter
  * code.
  */
@@ -135,8 +190,8 @@ __EXPORT void		param_foreach(void (*func)(void *arg, param_t param), void *arg,
 	__attribute__((used, section("__param")))	\
 	struct param_info_s __param__##_name = {	\
 		.name = #_name,				\
-		.type = PARAM_TYPE_INT32,		\
-		.val.i = _default			\
+			.type = PARAM_TYPE_INT32,	\
+				.val.i = _default	\
 	}
 
 /** define a float parameter */
@@ -145,8 +200,8 @@ __EXPORT void		param_foreach(void (*func)(void *arg, param_t param), void *arg,
 	__attribute__((used, section("__param")))	\
 	struct param_info_s __param__##_name = {	\
 		.name = #_name,				\
-		.type = PARAM_TYPE_FLOAT,		\
-		.val.f = _default			\
+			.type = PARAM_TYPE_FLOAT,	\
+				.val.f = _default	\
 	}
 
 /** define a parameter that points to a structure */
@@ -155,18 +210,17 @@ __EXPORT void		param_foreach(void (*func)(void *arg, param_t param), void *arg,
 	__attribute__((used, section("__param")))	\
 	struct param_info_s __param__##_name = {	\
 		.name = #_name,				\
-		.type = PARAM_TYPE_STRUCT + sizeof(_default), \
-		.val.p = &_default;			\
+			.type = PARAM_TYPE_STRUCT + sizeof(_default), \
+				.val.p = &_default;	\
 	}
 
 /**
  * Parameter value union.
  */
-union param_value_u
-{
+union param_value_u {
 	void		*p;
 	int32_t		i;
-	float		f;	
+	float		f;
 };
 
 /**
@@ -175,8 +229,7 @@ union param_value_u
  * This is normally not used by user code; see the PARAM_DEFINE macros
  * instead.
  */
-struct param_info_s
-{
+struct param_info_s {
 	const char	*name;
 	param_type_t	type;
 	union param_value_u val;