sterlinghughes closed pull request #994: Add configuration documentation
URL: https://github.com/apache/mynewt-core/pull/994
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/os/modules/config/config.rst
b/docs/os/modules/config/config.rst
index 0fca99f81..0121d315e 100644
--- a/docs/os/modules/config/config.rst
+++ b/docs/os/modules/config/config.rst
@@ -96,20 +96,20 @@ storage (or dump to console).
static int8 foo_val;
struct conf_handler my_conf = {
- .ch_name = "foo",
- .ch_set = foo_conf_set,
- .ch_export = foo_conf_export
+ .ch_name = "foo",
+ .ch_set = foo_conf_set,
+ .ch_export = foo_conf_export
}
static int
foo_conf_set(int argc, char **argv, char *val)
{
- if (argc == 1) {
- if (!strcmp(argv[0], "bar")) {
- return CONF_VALUE_SET(val, CONF_INT8, foo_val);
- }
- }
- return OS_ENOENT;
+ if (argc == 1) {
+ if (!strcmp(argv[0], "bar")) {
+ return CONF_VALUE_SET(val, CONF_INT8, foo_val);
+ }
+ }
+ return OS_ENOENT;
}
static int
@@ -118,8 +118,8 @@ storage (or dump to console).
char buf[4];
conf_str_from_value(CONF_INT8, &foo_val, buf, sizeof(buf));
- func("foo/bar", buf)
- return 0;
+ func("foo/bar", buf)
+ return 0;
}
Example: Persist Runtime State
@@ -138,19 +138,19 @@ foo_val will continue counting up from where it was
before restart.
static int8 foo_val;
struct conf_handler my_conf = {
- .ch_name = "foo",
- .ch_set = foo_conf_set
+ .ch_name = "foo",
+ .ch_set = foo_conf_set
}
static int
foo_conf_set(int argc, char **argv, char *val)
{
- if (argc == 1) {
- if (!strcmp(argv[0], "bar")) {
- return CONF_VALUE_SET(val, CONF_INT8, foo_val);
- }
- }
- return OS_ENOENT;
+ if (argc == 1) {
+ if (!strcmp(argv[0], "bar")) {
+ return CONF_VALUE_SET(val, CONF_INT8, foo_val);
+ }
+ }
+ return OS_ENOENT;
}
static void
@@ -159,15 +159,16 @@ foo_val will continue counting up from where it was
before restart.
struct os_callout *c = (struct os_callout *)ev;
char buf[4];
- foo_val++;
+ foo_val++;
conf_str_from_value(CONF_INT8, &foo_val, buf, sizeof(buf));
- conf_save_one("foo/bar", bar);
+ conf_save_one("foo/bar", bar);
- callout_reset(c, OS_TICKS_PER_SEC * 120);
+ callout_reset(c, OS_TICKS_PER_SEC * 120);
}
API
-~~~
+----------
-.. doxygengroup:: sys_config
+.. doxygengroup:: SysConfig
:content-only:
+ :members:
diff --git a/docs/os/modules/sysinitconfig/sysinitconfig.rst
b/docs/os/modules/sysinitconfig/sysinitconfig.rst
index 9bb3cf5ea..f91f8f730 100644
--- a/docs/os/modules/sysinitconfig/sysinitconfig.rst
+++ b/docs/os/modules/sysinitconfig/sysinitconfig.rst
@@ -1,5 +1,5 @@
-System Configuration and Initialization
----------------------------------------
+Compile-Time Configuration and Initialization
+-----------------------------------------------
.. toctree::
:hidden:
diff --git a/docs/os/modules/system_modules.rst
b/docs/os/modules/system_modules.rst
new file mode 100644
index 000000000..25f82c507
--- /dev/null
+++ b/docs/os/modules/system_modules.rst
@@ -0,0 +1,12 @@
+System Modules
+=============
+
+.. toctree::
+ :hidden:
+
+ Config <config/config>
+
+This section covers the core system functionality of the Apache Mynewt
+Operating System outside of the Kernel itself. This includes how you
+count statistics, log data and manage configuration of a device in the
+Apache Mynewt platform.
diff --git a/docs/os/os_user_guide.rst b/docs/os/os_user_guide.rst
index 66e3c9066..85cdaba85 100644
--- a/docs/os/os_user_guide.rst
+++ b/docs/os/os_user_guide.rst
@@ -5,9 +5,10 @@ OS User Guide
:hidden:
Kernel <core_os/mynewt_os>
+ System <modules/system_modules>
Hardware Abstraction <modules/hal/hal>
Porting Guide <core_os/porting/port_os>
- System Configuration <modules/sysinitconfig/sysinitconfig>
+ Compile-Time Configuration <modules/sysinitconfig/sysinitconfig>
Console <modules/console/console>
This guide provides comprehensive information about Mynewt OS, the
diff --git a/sys/config/include/config/config.h
b/sys/config/include/config/config.h
index 3d4beceda..91604803b 100644
--- a/sys/config/include/config/config.h
+++ b/sys/config/include/config/config.h
@@ -19,17 +19,19 @@
#ifndef __SYS_CONFIG_H_
#define __SYS_CONFIG_H_
+/**
+ * @addtogroup SysConfig Configuration of Apache Mynewt System
+ * @{
+ */
+
+#include <os/queue.h>
#include <stdint.h>
-#include "os/mynewt.h"
#ifdef __cplusplus
extern "C" {
#endif
-/**
- * @defgroup sys_config sys/config package
- * @{
- */
+/** @cond INTERNAL_HIDDEN */
#define CONF_MAX_DIR_DEPTH 8 /* max depth of config tree */
#define CONF_MAX_NAME_LEN (8 * CONF_MAX_DIR_DEPTH)
@@ -38,39 +40,131 @@ extern "C" {
#define CONF_NMGR_OP 0
+/** @endcond */
+
/**
* Type of configuration value.
*/
-enum conf_type {
+typedef enum conf_type {
CONF_NONE = 0,
CONF_DIR,
+ /** 8-bit signed integer */
CONF_INT8,
+ /** 16-bit signed integer */
CONF_INT16,
+ /** 32-bit signed integer */
CONF_INT32,
+ /** 64-bit signed integer */
CONF_INT64,
+ /** String */
CONF_STRING,
+ /** Bytes */
CONF_BYTES,
+ /** Floating point */
CONF_FLOAT,
+ /** Double precision */
CONF_DOUBLE,
+ /** Boolean */
CONF_BOOL,
-} __attribute__((__packed__));
+} __attribute__((__packed__)) conf_type_t;
/**
* Parameter to commit handler describing where data is going to.
*/
enum conf_export_tgt {
- CONF_EXPORT_PERSIST, /* Value is to be persisted. */
- CONF_EXPORT_SHOW /* Value is to be displayed. */
+ /** Value is to be persisted */
+ CONF_EXPORT_PERSIST,
+ /** Value is to be display */
+ CONF_EXPORT_SHOW
};
+typedef enum conf_export_tgt conf_export_tgt_t;
+
+/**
+ * Handler for getting configuration items, this handler is called
+ * per-configuration section. Configuration sections are delimited
+ * by '/', for example:
+ *
+ * - section/name/value
+ *
+ * Would be passed as:
+ *
+ * - argc = 3
+ * - argv[0] = section
+ * - argv[1] = name
+ * - argv[2] = value
+ *
+ * The handler returns the value into val, null terminated, up to
+ * val_len_max.
+ *
+ * @param argc The number of sections in the configuration variable
+ * @param argv The array of configuration sections
+ * @param val A pointer to the buffer to return the configuration
+ * value into.
+ * @param val_len_max The maximum length of the val buffer to copy into.
+ *
+ * @return A pointer to val or NULL if error.
+ */
+typedef char *(*conf_get_handler_t)(int argc, char **argv, char *val, int
val_len_max);
+
+/**
+ * Set the configuration variable pointed to by argc and argv. See
+ * description of ch_get_handler_t for format of these variables. This sets
the
+ * configuration variable to the shadow value, but does not apply the
configuration
+ * change. In order to apply the change, call the ch_commit() handler.
+ *
+ * @param argc The number of sections in the configuration variable.
+ * @param argv The array of configuration sections
+ * @param val The value to configure that variable to
+ *
+ * @return 0 on success, non-zero error code on failure.
+ */
+typedef int (*conf_set_handler_t)(int argc, char **argv, char *val);
+
+/**
+ * Commit shadow configuration state to the active configuration.
+ *
+ * @return 0 on success, non-zero error code on failure.
+ */
+typedef int (*conf_commit_handler_t)(void);
+
+/**
+ * Called per-configuration variable being exported.
+ *
+ * @param name The name of the variable to export
+ * @param val The value of the variable to export
+ */
+typedef void (*conf_export_func_t)(char *name, char *val);
+
+/**
+ * Export all of the configuration variables, calling the export_func
+ * per variable being exported.
+ *
+ * @param export_func The export function to call.
+ * @param tgt The target of the export, either for persistence or
display.
+ *
+ * @return 0 on success, non-zero error code on failure.
+ */
+typedef int (*conf_export_handler_t)(conf_export_func_t export_func,
+ conf_export_tgt_t tgt);
+
+/**
+ * Configuration handler, used to register a config item/subtree.
+ */
struct conf_handler {
SLIST_ENTRY(conf_handler) ch_list;
+ /**
+ * The name of the conifguration item/subtree
+ */
char *ch_name;
- char *(*ch_get)(int argc, char **argv, char *val, int val_len_max);
- int (*ch_set)(int argc, char **argv, char *val);
- int (*ch_commit)(void);
- int (*ch_export)(void (*export_func)(char *name, char *val),
- enum conf_export_tgt tgt);
+ /** Get configuration value */
+ conf_get_handler_t ch_get;
+ /** Set configuration value */
+ conf_set_handler_t ch_set;
+ /** Commit configuration value */
+ conf_commit_handler_t ch_commit;
+ /** Export configuration value */
+ conf_export_handler_t ch_export;
};
void conf_init(void);
@@ -205,6 +299,8 @@ int conf_bytes_from_str(char *val_str, void *vp, int *len);
*/
char *conf_str_from_value(enum conf_type type, void *vp, char *buf,
int buf_len);
+
+/** Return the length of a configuration string from buffer length. */
#define CONF_STR_FROM_BYTES_LEN(len) (((len) * 4 / 3) + 4)
/**
@@ -220,12 +316,11 @@ char *conf_str_from_value(enum conf_type type, void *vp,
char *buf,
*/
char *conf_str_from_bytes(void *vp, int vp_len, char *buf, int buf_len);
-#define CONF_VALUE_SET(str, type, val) \
- conf_value_from_str((str), (type), &(val), sizeof(val))
-
/**
- * @} sys_config
+ * Convert a string into a value of type
*/
+#define CONF_VALUE_SET(str, type, val) \
+ conf_value_from_str((str), (type), &(val), sizeof(val))
/*
* Config storage
@@ -240,4 +335,9 @@ struct conf_store {
}
#endif
+/**
+ * @} SysConfig
+ */
+
+
#endif /* __SYS_CONFIG_H_ */
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
