Moved last libs, drivers and headers, cleaned up IO build

2 files changed, 1141 insertions, 0 deletions

diff --git a/src/modules/systemlib/param/param.c b/src/modules/systemlib/param/param.c
new file mode 100644
index 000000000..69a9bdf9b
--- /dev/null
+++ b/src/modules/systemlib/param/param.c
@@ -0,0 +1,805 @@
+/****************************************************************************
+ *
+ *   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.c
+ *
+ * Global parameter store.
+ *
+ * Note that it might make sense to convert this into a driver.  That would
+ * offer some interesting options regarding state for e.g. ORB advertisements
+ * and background parameter saving.
+ */
+
+#include <debug.h>
+#include <string.h>
+#include <stdbool.h>
+#include <fcntl.h>
+#include <unistd.h>
+#include <systemlib/err.h>
+#include <errno.h>
+
+#include <sys/stat.h>
+
+#include <drivers/drv_hrt.h>
+
+#include "systemlib/param/param.h"
+#include "systemlib/uthash/utarray.h"
+#include "systemlib/bson/tinybson.h"
+
+#include "uORB/uORB.h"
+#include "uORB/topics/parameter_update.h"
+
+#if 1
+# define debug(fmt, args...)		do { warnx(fmt, ##args); } while(0)
+#else
+# define debug(fmt, args...)		do { } while(0)
+#endif
+
+/**
+ * Array of static parameter info.
+ */
+extern char __param_start, __param_end;
+static const struct param_info_s	*param_info_base = (struct param_info_s *) &__param_start;
+static const struct param_info_s	*param_info_limit = (struct param_info_s *) &__param_end;
+#define	param_info_count		((unsigned)(param_info_limit - param_info_base))
+
+/**
+ * Storage for modified parameters.
+ */
+struct param_wbuf_s {
+	param_t			param;
+	union param_value_u	val;
+	bool			unsaved;
+};
+
+/** flexible array holding modified parameter values */
+UT_array	*param_values;
+
+/** array info for the modified parameters array */
+const UT_icd	param_icd = {sizeof(struct param_wbuf_s), NULL, NULL, NULL};
+
+/** parameter update topic */
+ORB_DEFINE(parameter_update, struct parameter_update_s);
+
+/** parameter update topic handle */
+static orb_advert_t param_topic = -1;
+
+/** lock the parameter store */
+static void
+param_lock(void)
+{
+	/* XXX */
+}
+
+/** unlock the parameter store */
+static void
+param_unlock(void)
+{
+	/* XXX */
+}
+
+/** assert that the parameter store is locked */
+static void
+param_assert_locked(void)
+{
+	/* XXX */
+}
+
+/**
+ * Test whether a param_t is value.
+ *
+ * @param param			The parameter handle to test.
+ * @return			True if the handle is valid.
+ */
+static bool
+handle_in_range(param_t param)
+{
+	return (param < param_info_count);
+}
+
+/**
+ * Compare two modifid parameter structures to determine ordering.
+ *
+ * This function is suitable for passing to qsort or bsearch.
+ */
+static int
+param_compare_values(const void *a, const void *b)
+{
+	struct param_wbuf_s *pa = (struct param_wbuf_s *)a;
+	struct param_wbuf_s *pb = (struct param_wbuf_s *)b;
+
+	if (pa->param < pb->param)
+		return -1;
+
+	if (pa->param > pb->param)
+		return 1;
+
+	return 0;
+}
+
+/**
+ * Locate the modified parameter structure for a parameter, if it exists.
+ *
+ * @param param			The parameter being searched.
+ * @return			The structure holding the modified value, or
+ *				NULL if the parameter has not been modified.
+ */
+static struct param_wbuf_s *
+param_find_changed(param_t param) {
+	struct param_wbuf_s	*s = NULL;
+
+	param_assert_locked();
+
+	if (param_values != NULL) {
+#if 0	/* utarray_find requires bsearch, not available */
+		struct param_wbuf_s key;
+		key.param = param;
+		s = utarray_find(param_values, &key, param_compare_values);
+#else
+
+		while ((s = (struct param_wbuf_s *)utarray_next(param_values, s)) != NULL) {
+			if (s->param == param)
+				break;
+		}
+
+#endif
+	}
+
+	return s;
+}
+
+static void
+param_notify_changes(void)
+{
+	struct parameter_update_s pup = { .timestamp = hrt_absolute_time() };
+
+	/*
+	 * If we don't have a handle to our topic, create one now; otherwise
+	 * just publish.
+	 */
+	if (param_topic == -1) {
+		param_topic = orb_advertise(ORB_ID(parameter_update), &pup);
+
+	} else {
+		orb_publish(ORB_ID(parameter_update), param_topic, &pup);
+	}
+}
+
+param_t
+param_find(const char *name)
+{
+	param_t param;
+
+	/* perform a linear search of the known parameters */
+	for (param = 0; handle_in_range(param); param++) {
+		if (!strcmp(param_info_base[param].name, name))
+			return param;
+	}
+
+	/* not found */
+	return PARAM_INVALID;
+}
+
+unsigned
+param_count(void)
+{
+	return param_info_count;
+}
+
+param_t
+param_for_index(unsigned index)
+{
+	if (index < param_info_count)
+		return (param_t)index;
+
+	return PARAM_INVALID;
+}
+
+int
+param_get_index(param_t param)
+{
+	if (handle_in_range(param))
+		return (unsigned)param;
+
+	return -1;
+}
+
+const char *
+param_name(param_t param)
+{
+	if (handle_in_range(param))
+		return param_info_base[param].name;
+
+	return NULL;
+}
+
+bool
+param_value_is_default(param_t param)
+{
+	return param_find_changed(param) ? false : true;
+}
+
+bool
+param_value_unsaved(param_t param)
+{
+	static struct param_wbuf_s *s;
+
+	s = param_find_changed(param);
+
+	if (s && s->unsaved)
+		return true;
+
+	return false;
+}
+
+enum param_type_e
+param_type(param_t param)
+{
+	if (handle_in_range(param))
+		return param_info_base[param].type;
+
+	return PARAM_TYPE_UNKNOWN;
+}
+
+size_t
+param_size(param_t param)
+{
+	if (handle_in_range(param)) {
+		switch (param_type(param)) {
+		case PARAM_TYPE_INT32:
+		case PARAM_TYPE_FLOAT:
+			return 4;
+
+		case PARAM_TYPE_STRUCT ... PARAM_TYPE_STRUCT_MAX:
+			/* decode structure size from type value */
+			return param_type(param) - PARAM_TYPE_STRUCT;
+
+		default:
+			return 0;
+		}
+	}
+
+	return 0;
+}
+
+/**
+ * Obtain a pointer to the storage allocated for a parameter.
+ *
+ * @param param			The parameter whose storage is sought.
+ * @return			A pointer to the parameter value, or NULL
+ *				if the parameter does not exist.
+ */
+static const void *
+param_get_value_ptr(param_t param)
+{
+	const void *result = NULL;
+
+	param_assert_locked();
+
+	if (handle_in_range(param)) {
+
+		const union param_value_u *v;
+
+		/* work out whether we're fetching the default or a written value */
+		struct param_wbuf_s *s = param_find_changed(param);
+
+		if (s != NULL) {
+			v = &s->val;
+
+		} else {
+			v = &param_info_base[param].val;
+		}
+
+		if (param_type(param) == PARAM_TYPE_STRUCT) {
+			result = v->p;
+
+		} else {
+			result = v;
+		}
+	}
+
+	return result;
+}
+
+int
+param_get(param_t param, void *val)
+{
+	int result = -1;
+
+	param_lock();
+
+	const void *v = param_get_value_ptr(param);
+
+	if (val != NULL) {
+		memcpy(val, v, param_size(param));
+		result = 0;
+	}
+
+	param_unlock();
+
+	return result;
+}
+
+static int
+param_set_internal(param_t param, const void *val, bool mark_saved)
+{
+	int result = -1;
+	bool params_changed = false;
+
+	param_lock();
+
+	if (param_values == NULL)
+		utarray_new(param_values, &param_icd);
+
+	if (param_values == NULL) {
+		debug("failed to allocate modified values array");
+		goto out;
+	}
+
+	if (handle_in_range(param)) {
+
+		struct param_wbuf_s *s = param_find_changed(param);
+
+		if (s == NULL) {
+
+			/* construct a new parameter */
+			struct param_wbuf_s buf = {
+				.param = param,
+				.val.p = NULL,
+				.unsaved = false
+			};
+
+			/* add it to the array and sort */
+			utarray_push_back(param_values, &buf);
+			utarray_sort(param_values, param_compare_values);
+
+			/* find it after sorting */
+			s = param_find_changed(param);
+		}
+
+		/* update the changed value */
+		switch (param_type(param)) {
+		case PARAM_TYPE_INT32:
+			s->val.i = *(int32_t *)val;
+			break;
+
+		case PARAM_TYPE_FLOAT:
+			s->val.f = *(float *)val;
+			break;
+
+		case PARAM_TYPE_STRUCT ... PARAM_TYPE_STRUCT_MAX:
+			if (s->val.p == NULL) {
+				s->val.p = malloc(param_size(param));
+
+				if (s->val.p == NULL) {
+					debug("failed to allocate parameter storage");
+					goto out;
+				}
+			}
+
+			memcpy(s->val.p, val, param_size(param));
+			break;
+
+		default:
+			goto out;
+		}
+
+		s->unsaved = !mark_saved;
+		params_changed = true;
+		result = 0;
+	}
+
+out:
+	param_unlock();
+
+	/*
+	 * If we set something, now that we have unlocked, go ahead and advertise that
+	 * a thing has been set.
+	 */
+	if (params_changed)
+		param_notify_changes();
+
+	return result;
+}
+
+int
+param_set(param_t param, const void *val)
+{
+	return param_set_internal(param, val, false);
+}
+
+void
+param_reset(param_t param)
+{
+	struct param_wbuf_s *s = NULL;
+
+	param_lock();
+
+	if (handle_in_range(param)) {
+
+		/* look for a saved value */
+		s = param_find_changed(param);
+
+		/* if we found one, erase it */
+		if (s != NULL) {
+			int pos = utarray_eltidx(param_values, s);
+			utarray_erase(param_values, pos, 1);
+		}
+	}
+
+	param_unlock();
+
+	if (s != NULL)
+		param_notify_changes();
+}
+
+void
+param_reset_all(void)
+{
+	param_lock();
+
+	if (param_values != NULL) {
+		utarray_free(param_values);
+	}
+
+	/* mark as reset / deleted */
+	param_values = NULL;
+
+	param_unlock();
+
+	param_notify_changes();
+}
+
+static const char *param_default_file = "/eeprom/parameters";
+static char *param_user_file = NULL;
+
+int
+param_set_default_file(const char* filename)
+{
+	if (param_user_file != NULL) {
+		free(param_user_file);
+		param_user_file = NULL;
+	}
+	if (filename)
+		param_user_file = strdup(filename);
+	return 0;
+}
+
+const char *
+param_get_default_file(void)
+{
+	return (param_user_file != NULL) ? param_user_file : param_default_file;
+}
+
+int
+param_save_default(void)
+{
+	/* delete the file in case it exists */
+	unlink(param_get_default_file());
+
+	/* create the file */
+	int fd = open(param_get_default_file(), O_WRONLY | O_CREAT | O_EXCL);
+
+	if (fd < 0) {
+		warn("opening '%s' for writing failed", param_get_default_file());
+		return -1;
+	}
+
+	int result = param_export(fd, false);
+	close(fd);
+
+	if (result != 0) {
+		warn("error exporting parameters to '%s'", param_get_default_file());
+		unlink(param_get_default_file());
+		return -2;
+	}
+
+	return 0;
+}
+
+/**
+ * @return 0 on success, 1 if all params have not yet been stored, -1 if device open failed, -2 if writing parameters failed
+ */
+int
+param_load_default(void)
+{
+	int fd = open(param_get_default_file(), O_RDONLY);
+
+	if (fd < 0) {
+		/* no parameter file is OK, otherwise this is an error */
+		if (errno != ENOENT) {
+			warn("open '%s' for reading failed", param_get_default_file());
+			return -1;
+		}
+		return 1;
+	}
+
+	int result = param_load(fd);
+	close(fd);
+
+	if (result != 0) {
+		warn("error reading parameters from '%s'", param_get_default_file());
+		return -2;
+	}
+
+	return 0;
+}
+
+int
+param_export(int fd, bool only_unsaved)
+{
+	struct param_wbuf_s *s = NULL;
+	struct bson_encoder_s encoder;
+	int	result = -1;
+
+	param_lock();
+
+	bson_encoder_init_file(&encoder, fd);
+
+	/* no modified parameters -> we are done */
+	if (param_values == NULL) {
+		result = 0;
+		goto out;
+	}
+
+	while ((s = (struct param_wbuf_s *)utarray_next(param_values, s)) != NULL) {
+
+		int32_t	i;
+		float	f;
+
+		/*
+		 * If we are only saving values changed since last save, and this
+		 * one hasn't, then skip it
+		 */
+		if (only_unsaved && !s->unsaved)
+			continue;
+
+		s->unsaved = false;
+
+		/* append the appropriate BSON type object */
+		switch (param_type(s->param)) {
+		case PARAM_TYPE_INT32:
+			param_get(s->param, &i);
+
+			if (bson_encoder_append_int(&encoder, param_name(s->param), i)) {
+				debug("BSON append failed for '%s'", param_name(s->param));
+				goto out;
+			}
+
+			break;
+
+		case PARAM_TYPE_FLOAT:
+			param_get(s->param, &f);
+
+			if (bson_encoder_append_double(&encoder, param_name(s->param), f)) {
+				debug("BSON append failed for '%s'", param_name(s->param));
+				goto out;
+			}
+
+			break;
+
+		case PARAM_TYPE_STRUCT ... PARAM_TYPE_STRUCT_MAX:
+			if (bson_encoder_append_binary(&encoder,
+						       param_name(s->param),
+						       BSON_BIN_BINARY,
+						       param_size(s->param),
+						       param_get_value_ptr(s->param))) {
+				debug("BSON append failed for '%s'", param_name(s->param));
+				goto out;
+			}
+
+			break;
+
+		default:
+			debug("unrecognized parameter type");
+			goto out;
+		}
+	}
+
+	result = 0;
+
+out:
+	param_unlock();
+
+	if (result == 0)
+		result = bson_encoder_fini(&encoder);
+
+	return result;
+}
+
+struct param_import_state {
+	bool mark_saved;
+};
+
+static int
+param_import_callback(bson_decoder_t decoder, void *private, bson_node_t node)
+{
+	float f;
+	int32_t i;
+	void *v, *tmp = NULL;
+	int result = -1;
+	struct param_import_state *state = (struct param_import_state *)private;
+
+	/*
+	 * EOO means the end of the parameter object. (Currently not supporting
+	 * nested BSON objects).
+	 */
+	if (node->type == BSON_EOO) {
+		debug("end of parameters");
+		return 0;
+	}
+
+	/*
+	 * Find the parameter this node represents.  If we don't know it,
+	 * ignore the node.
+	 */
+	param_t param = param_find(node->name);
+
+	if (param == PARAM_INVALID) {
+		debug("ignoring unrecognised parameter '%s'", node->name);
+		return 1;
+	}
+
+	/*
+	 * Handle setting the parameter from the node
+	 */
+
+	switch (node->type) {
+	case BSON_INT32:
+		if (param_type(param) != PARAM_TYPE_INT32) {
+			debug("unexpected type for '%s", node->name);
+			goto out;
+		}
+
+		i = node->i;
+		v = &i;
+		break;
+
+	case BSON_DOUBLE:
+		if (param_type(param) != PARAM_TYPE_FLOAT) {
+			debug("unexpected type for '%s", node->name);
+			goto out;
+		}
+
+		f = node->d;
+		v = &f;
+		break;
+
+	case BSON_BINDATA:
+		if (node->subtype != BSON_BIN_BINARY) {
+			debug("unexpected subtype for '%s", node->name);
+			goto out;
+		}
+
+		if (bson_decoder_data_pending(decoder) != param_size(param)) {
+			debug("bad size for '%s'", node->name);
+			goto out;
+		}
+
+		/* XXX check actual file data size? */
+		tmp = malloc(param_size(param));
+
+		if (tmp == NULL) {
+			debug("failed allocating for '%s'", node->name);
+			goto out;
+		}
+
+		if (bson_decoder_copy_data(decoder, tmp)) {
+			debug("failed copying data for '%s'", node->name);
+			goto out;
+		}
+
+		v = tmp;
+		break;
+
+	default:
+		debug("unrecognised node type");
+		goto out;
+	}
+
+	if (param_set_internal(param, v, state->mark_saved)) {
+		debug("error setting value for '%s'", node->name);
+		goto out;
+	}
+
+	if (tmp != NULL) {
+		free(tmp);
+		tmp = NULL;
+	}
+
+	/* don't return zero, that means EOF */
+	result = 1;
+
+out:
+
+	if (tmp != NULL)
+		free(tmp);
+
+	return result;
+}
+
+static int
+param_import_internal(int fd, bool mark_saved)
+{
+	struct bson_decoder_s decoder;
+	int result = -1;
+	struct param_import_state state;
+
+	if (bson_decoder_init_file(&decoder, fd, param_import_callback, &state)) {
+		debug("decoder init failed");
+		goto out;
+	}
+
+	state.mark_saved = mark_saved;
+
+	do {
+		result = bson_decoder_next(&decoder);
+
+	} while (result > 0);
+
+out:
+
+	if (result < 0)
+		debug("BSON error decoding parameters");
+
+	return result;
+}
+
+int
+param_import(int fd)
+{
+	return param_import_internal(fd, false);
+}
+
+int
+param_load(int fd)
+{
+	param_reset_all();
+	return param_import_internal(fd, true);
+}
+
+void
+param_foreach(void (*func)(void *arg, param_t param), void *arg, bool only_changed)
+{
+	param_t	param;
+
+	for (param = 0; handle_in_range(param); param++) {
+
+		/* if requested, skip unchanged values */
+		if (only_changed && (param_find_changed(param) == NULL))
+			continue;
+
+		func(arg, param);
+	}
+}
diff --git a/src/modules/systemlib/param/param.h b/src/modules/systemlib/param/param.h
new file mode 100644
index 000000000..084cd931a
--- /dev/null
+++ b/src/modules/systemlib/param/param.h
@@ -0,0 +1,336 @@
+/****************************************************************************
+ *
+ *   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
+#define _SYSTEMLIB_PARAM_PARAM_H
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <sys/types.h>
+
+/** Maximum size of the parameter backing file */
+#define PARAM_FILE_MAXSIZE	4096
+
+__BEGIN_DECLS
+
+/**
+ * Parameter types.
+ */
+typedef enum param_type_e {
+	/* globally-known parameter types */
+	PARAM_TYPE_INT32 = 0,
+	PARAM_TYPE_FLOAT,
+
+	/* structure parameters; size is encoded in the type value */
+	PARAM_TYPE_STRUCT = 100,
+	PARAM_TYPE_STRUCT_MAX = 16384 + PARAM_TYPE_STRUCT,
+
+	PARAM_TYPE_UNKNOWN = 0xffff
+} param_type_t;
+
+/**
+ * Parameter handle.
+ *
+ * Parameters are represented by parameter handles, which can
+ * be obtained by looking up (or creating?) parameters.
+ */
+typedef uintptr_t	param_t;
+
+/**
+ * Handle returned when a parameter cannot be found.
+ */
+#define PARAM_INVALID	((uintptr_t)0xffffffff)
+
+/**
+ * Look up a parameter by name.
+ *
+ * @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);
+
+/**
+ * Return the total number of parameters.
+ *
+ * @return		The number of parameters.
+ */
+__EXPORT unsigned	param_count(void);
+
+/**
+ * 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);
+
+/**
+ * Look up the index of a parameter.
+ *
+ * @param param		The parameter to obtain the index for.
+ * @return		The index, or -1 if the parameter does not exist.
+ */
+__EXPORT int		param_get_index(param_t param);
+
+/**
+ * Obtain the name of a parameter.
+ *
+ * @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);
+
+/**
+ * Test whether a parameter's value has changed from the default.
+ *
+ * @return		If true, the parameter's value has not been changed from the default.
+ */
+__EXPORT bool		param_value_is_default(param_t param);
+
+/**
+ * Test whether a parameter's value has been changed but not saved.
+ *
+ * @return		If true, the parameter's value has not been saved.
+ */
+__EXPORT bool		param_value_unsaved(param_t param);
+
+/**
+ * Obtain the type of a parameter.
+ *
+ * @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);
+
+/**
+ * Determine the size of a parameter.
+ *
+ * @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);
+
+/**
+ * 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 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);
+
+/**
+ * Set the value of a parameter.
+ *
+ * @param param		A handle returned by param_find or passed by param_foreach.
+ * @param 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.
+ * @return		Zero if the parameter's value could be set from a scalar, nonzero otherwise.
+ */
+__EXPORT int		param_set(param_t param, const void *val);
+
+/**
+ * Reset a parameter to its default value.
+ *
+ * This function frees any storage used by struct parameters, and returns the parameter
+ * to its default value.
+ *
+ * @param param		A handle returned by param_find or passed by param_foreach.
+ */
+__EXPORT void		param_reset(param_t param);
+
+/**
+ * Reset all parameters to their default values.
+ *
+ * This function also releases the storage used by struct parameters.
+ */
+__EXPORT void		param_reset_all(void);
+
+/**
+ * Export changed parameters to a file.
+ *
+ * @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(int fd, bool only_unsaved);
+
+/**
+ * Import parameters from a file, discarding any unrecognized parameters.
+ *
+ * This function merges the imported parameters with the current parameter set.
+ *
+ * @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(int fd);
+
+/**
+ * Load parameters from a file.
+ *
+ * This function resets all parameters to their default values, then loads new
+ * values from a file.
+ *
+ * @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_load(int fd);
+
+/**
+ * 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.
+ *
+ * @param func		The function to invoke for each parameter.
+ * @param arg		Argument passed to the function.
+ * @param only_changed	If true, the function is only called for parameters whose values have
+ *			been changed from the default.
+ */
+__EXPORT void		param_foreach(void (*func)(void *arg, param_t param), void *arg, bool only_changed);
+
+/**
+ * Set the default parameter file name.
+ *
+ * @param filename	Path to the default parameter file.  The file is not require to
+ *			exist.
+ * @return		Zero on success.
+ */
+__EXPORT int 		param_set_default_file(const char* filename);
+
+/**
+ * Get the default parameter file name.
+ *
+ * @return		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.
+ */
+__EXPORT const char*	param_get_default_file(void);
+
+/**
+ * Save parameters to the default file.
+ *
+ * This function saves all parameters with non-default values.
+ *
+ * @return		Zero on success.
+ */
+__EXPORT int 		param_save_default(void);
+
+/**
+ * Load parameters from the default parameter file.
+ *
+ * @return		Zero on success.
+ */
+__EXPORT int 		param_load_default(void);
+
+/*
+ * Macros creating static parameter definitions.
+ *
+ * Note that these structures are not known by name; they are
+ * collected into a section that is iterated by the parameter
+ * code.
+ *
+ * Note that these macros cannot be used in C++ code due to
+ * their use of designated initializers.  They should probably
+ * be refactored to avoid the use of a union for param_value_u.
+ */
+
+/** define an int32 parameter */
+#define PARAM_DEFINE_INT32(_name, _default)		\
+	static const					\
+	__attribute__((used, section("__param")))	\
+	struct param_info_s __param__##_name = {	\
+		#_name,					\
+		PARAM_TYPE_INT32,			\
+		.val.i = _default			\
+	}
+
+/** define a float parameter */
+#define PARAM_DEFINE_FLOAT(_name, _default)		\
+	static const					\
+	__attribute__((used, section("__param")))	\
+	struct param_info_s __param__##_name = {	\
+		#_name,					\
+		PARAM_TYPE_FLOAT,			\
+		.val.f = _default			\
+	}
+
+/** define a parameter that points to a structure */
+#define PARAM_DEFINE_STRUCT(_name, _default)		\
+	static const					\
+	__attribute__((used, section("__param")))	\
+	struct param_info_s __param__##_name = {	\
+		#_name,					\
+		PARAM_TYPE_STRUCT + sizeof(_default),	\
+		.val.p = &_default;			\
+	}
+
+/**
+ * Parameter value union.
+ */
+union param_value_u {
+	void		*p;
+	int32_t		i;
+	float		f;
+};
+
+/**
+ * Static parameter definition structure.
+ *
+ * This is normally not used by user code; see the PARAM_DEFINE macros
+ * instead.
+ */
+struct param_info_s {
+	const char	*name;
+	param_type_t	type;
+	union param_value_u val;
+};
+
+__END_DECLS
+
+#endif