You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/02/28 23:52:09 UTC
[2/4] incubator-mynewt-site git commit: finish sanity documentation
finish sanity documentation
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/bc8b37b1
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/bc8b37b1
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/bc8b37b1
Branch: refs/heads/master
Commit: bc8b37b169a514e9498841632fb89e2e9c5d1d6b
Parents: ac247fc
Author: Sterling Hughes <st...@apache.org>
Authored: Fri Feb 26 18:37:19 2016 -0800
Committer: Sterling Hughes <st...@apache.org>
Committed: Fri Feb 26 18:37:19 2016 -0800
----------------------------------------------------------------------
docs/os/core_os/sanity/os_sanity_check_init.md | 34 +++++++++
.../core_os/sanity/os_sanity_check_register.md | 34 +++++++++
docs/os/core_os/sanity/os_sanity_check_reset.md | 35 +++++++++
.../os/core_os/sanity/os_sanity_task_checkin.md | 4 +-
docs/os/core_os/sanity/os_sanity_task_init.md | 36 ++++++++++
docs/os/core_os/sanity/sanity.md | 75 +++++++++++++++++++-
docs/os/core_os/task/task.md | 1 -
mkdocs.yml | 4 +-
8 files changed, 215 insertions(+), 8 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bc8b37b1/docs/os/core_os/sanity/os_sanity_check_init.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/sanity/os_sanity_check_init.md b/docs/os/core_os/sanity/os_sanity_check_init.md
index e69de29..2073647 100644
--- a/docs/os/core_os/sanity/os_sanity_check_init.md
+++ b/docs/os/core_os/sanity/os_sanity_check_init.md
@@ -0,0 +1,34 @@
+## <font color="F2853F" style="font-size:24pt"> os_sanity_check_init</font>
+
+```no-highlight
+int os_sanity_check_init(struct os_sanity_check *sc)
+```
+Initialize the sanity check pointed to by `sc`. Sets default values, and ensures
+memory is cleared out.
+
+<br>
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| `sc` | Pointer to sanity check |
+
+<br>
+#### Returned values
+
+`OS_OK`: sanity check initialization is successful
+
+All other error codes indicate an error.
+
+<br>
+#### Example
+
+```no-highlight
+ int rc;
+
+ rc = os_sanity_task_check_init(&my_sanity_check);
+ assert(rc == OS_OK);
+
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bc8b37b1/docs/os/core_os/sanity/os_sanity_check_register.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/sanity/os_sanity_check_register.md b/docs/os/core_os/sanity/os_sanity_check_register.md
index e69de29..8674766 100644
--- a/docs/os/core_os/sanity/os_sanity_check_register.md
+++ b/docs/os/core_os/sanity/os_sanity_check_register.md
@@ -0,0 +1,34 @@
+## <font color="F2853F" style="font-size:24pt"> os_sanity_check_register</font>
+
+```no-highlight
+int os_sanity_check_register(struct os_sanity_check *sc)
+```
+Register the sanity check pointed to by `sc` with the sanity task. After registration
+the sanity task will check this sanity check with every run of the sanity task.
+
+<br>
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| `sc` | Pointer to sanity check |
+
+<br>
+#### Returned values
+
+`OS_OK`: sanity check successfully registered
+
+All other error codes indicate an error.
+
+<br>
+#### Example
+
+```no-highlight
+ int rc;
+
+ rc = os_sanity_check_register(&my_sc);
+ assert(rc == OS_OK);
+
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bc8b37b1/docs/os/core_os/sanity/os_sanity_check_reset.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/sanity/os_sanity_check_reset.md b/docs/os/core_os/sanity/os_sanity_check_reset.md
index e69de29..f945a66 100644
--- a/docs/os/core_os/sanity/os_sanity_check_reset.md
+++ b/docs/os/core_os/sanity/os_sanity_check_reset.md
@@ -0,0 +1,35 @@
+## <font color="F2853F" style="font-size:24pt"> os_sanity_check_reset</font>
+
+```no-highlight
+int os_sanity_check_reset(struct os_sanity_check *sc)
+```
+Reset the sanity check pointed to by sc. This tells the sanity task that
+this sanity check is considered valid for another `sc_checkin_itvl` time
+ticks.
+
+<br>
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| `sc` | Pointer to sanity check |
+
+<br>
+#### Returned values
+
+`OS_OK`: sanity check reset successful
+
+All other error codes indicate an error.
+
+<br>
+#### Example
+
+```no-highlight
+ int rc;
+
+ rc = os_sanity_check_reset(&my_sc);
+ assert(rc == OS_OK);
+
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bc8b37b1/docs/os/core_os/sanity/os_sanity_task_checkin.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/sanity/os_sanity_task_checkin.md b/docs/os/core_os/sanity/os_sanity_task_checkin.md
index 6160d3d..2d797d7 100644
--- a/docs/os/core_os/sanity/os_sanity_task_checkin.md
+++ b/docs/os/core_os/sanity/os_sanity_task_checkin.md
@@ -11,12 +11,12 @@ Used by a task to check in to the sanity task. This informs the sanity task that
| Arguments | Description |
|-----------|-------------|
-| t | Pointer to task |
+| `t` | Pointer to task |
<br>
#### Returned values
-OS_OK: sanity check-in successful
+`OS_OK`: sanity check-in successful
All other error codes indicate an error.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bc8b37b1/docs/os/core_os/sanity/os_sanity_task_init.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/sanity/os_sanity_task_init.md b/docs/os/core_os/sanity/os_sanity_task_init.md
index e69de29..dce0e1a 100644
--- a/docs/os/core_os/sanity/os_sanity_task_init.md
+++ b/docs/os/core_os/sanity/os_sanity_task_init.md
@@ -0,0 +1,36 @@
+## <font color="F2853F" style="font-size:24pt"> os_sanity_task_init</font>
+
+```no-highlight
+int os_sanity_task_init(int num_secs);
+```
+Initialize the os sanity task. `num_secs` is the number of seconds to wait
+in between runs of the sanity task.
+
+<br>
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| `num_secs` | Number of seconds to wait in between running sanity checks. |
+
+<br>
+#### Returned values
+
+`OS_OK`: Sanity task was successfully created.
+
+All other error codes indicate an error.
+
+<br>
+#### Example
+
+```no-highlight
+/* Run sanity checks every 50 seconds */
+
+#define SANITY_TASK_INTERVAL (50)
+ int rc;
+
+ rc = os_sanity_task_init(SANITY_TASK_INTERVAL);
+ assert(rc == OS_OK);
+```
+
+---------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bc8b37b1/docs/os/core_os/sanity/sanity.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/sanity/sanity.md b/docs/os/core_os/sanity/sanity.md
index 369b300..2c33211 100644
--- a/docs/os/core_os/sanity/sanity.md
+++ b/docs/os/core_os/sanity/sanity.md
@@ -101,16 +101,87 @@ task1(void *arg)
### Registering a Custom Sanity Check
-
If a particular task wants to further hook into the sanity framework, to
perform other checks during the sanity task's operation, it can do so by
registering a `struct os_sanity_check` using the `os_sanity_check_register`
function.
+```no-highlight
+static int
+mymodule_perform_sanity_check(struct os_sanity_check *sc, void *arg)
+{
+ /* Perform your checking here. In this case, we check if there
+ * are available buffers in mymodule, and return 0 (all good)
+ * if true, and -1 (error) if not.
+ */
+ if (mymodule_has_buffers()) {
+ return (0);
+ } else {
+ return (-1);
+ }
+}
+
+static int
+mymodule_register_sanity_check(void)
+{
+ struct os_sanity_check sc;
+
+ os_sanity_check_init(&sc);
+ /* Only assert() if mymodule_perform_sanity_check() fails 50
+ * times. SANITY_TASK_INTERVAL is defined by the user, and
+ * is the frequency at which the sanity_task runs in seconds.
+ */
+ OS_SANITY_CHECK_SETFUNC(&sc, mymodule_perform_sanity_check, NULL,
+ 50 * SANITY_TASK_INTERVAL);
+
+ rc = os_sanity_check_register(&sc);
+ if (rc != 0) {
+ goto err;
+ }
+
+ return (0);
+err:
+ return (rc);
+}
+```
+
+In the above example, every time the custom sanity check
+`mymodule_perform_sanity_check` returns successfully (0),
+the sanity check is reset. In the `OS_SANITY_CEHCK_SETFUNC` macro,
+the sanity checkin interval is specified as 50 * SANITY_TASK_INTERVAL
+(which is the interval at which the sanity task runs.) This means
+that the `mymodule_perform_sanity_check()` function needs to fail
+50 times consecutively before the sanity task will crash the system.
+
+**TIP:** When checking things like memory buffers, which can be temporarily
+be exhausted, its a good idea to have the sanity check fail multiple
+consecutive times before crashing the system. This will avoid crashing
+for temporary failures.
## Data structures
-Replace this with the list of data structures used, why, any neat features
+### OS Sanity Check
+
+```no-highlight
+struct os_sanity_check {
+ os_time_t sc_checkin_last;
+ os_time_t sc_checkin_itvl;
+ os_sanity_check_func_t sc_func;
+ void *sc_arg;
+
+ SLIST_ENTRY(os_sanity_check) sc_next;
+};
+```
+
+
+| **Element** | **Description** |
+|-----------|-------------|
+| `sc_checkin_last` | The last time this sanity check, checked in with the sanity task in OS time ticks. |
+| `sc_checkin_itvl` | How frequently the sanity check is supposed to check in with the sanity task, in OS time ticks. |
+| `sc_func` | If not `NULL`, call this function when running the sanity task. If the function returns 0, reset the sanity check. |
+| `sc_arg` | Argument to pass to `sc_func` when calling it. |
+| `sc_next` | Sanity checks are chained in the sanity task when `os_sanity_check_register()` is called. |
+
## List of Functions
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bc8b37b1/docs/os/core_os/task/task.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/task/task.md b/docs/os/core_os/task/task.md
index 6a2a591..06e904b 100644
--- a/docs/os/core_os/task/task.md
+++ b/docs/os/core_os/task/task.md
@@ -224,4 +224,3 @@ The functions available in task are:
* [os_task_init](os_task_init.md)
* [os_task_count](os_task_count.md)
* [os_task_info_get_next](os_task_info_get_next.md)
-* [os_task_sanity_checkin](os_task_sanity_checkin.md)
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bc8b37b1/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index dd291b9..3e895c7 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -51,7 +51,6 @@ pages:
- 'os_task_count': 'os/core_os/task/os_task_count.md'
- 'os_task_info_get_next': 'os/core_os/task/os_task_info_get_next.md'
- 'os_task_init': 'os/core_os/task/os_task_init.md'
- - 'os_task_sanity_checkin': 'os/core_os/task/os_task_sanity_checkin.md'
- Event Queues:
- 'Overview': 'os/core_os/event_queue/event_queue.md'
- 'Functions':
@@ -119,10 +118,9 @@ pages:
- 'Overview': 'os/core_os/sanity/sanity.md'
- 'Functions':
- 'os_sanity_check_init': 'os/core_os/sanity/os_sanity_check_init.md'
- - 'os_sanity_check_list_lock': 'os/core_os/sanity/os_sanity_check_list_lock.md'
- - 'os_sanity_check_list_unlock': 'os/core_os/sanity/os_sanity_check_list_unlock.md'
- 'os_sanity_check_register': 'os/core_os/sanity/os_sanity_check_register.md'
- 'os_sanity_check_reset': 'os/core_os/sanity/os_sanity_check_reset.md'
+ - 'os_sanity_task_checkin': 'os/core_os/sanity/os_sanity_task_checkin.md'
- 'os_sanity_task_init': 'os/core_os/sanity/os_sanity_task_init.md'
- Callouts:
- 'Overview': 'os/core_os/callout/callout.md'