You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ma...@apache.org on 2016/02/24 17:33:00 UTC

incubator-mynewt-site git commit: Image manager documentation.

Repository: incubator-mynewt-site
Updated Branches:
  refs/heads/master 554c01adf -> aad4cef02


Image manager 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/aad4cef0
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/aad4cef0
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/aad4cef0

Branch: refs/heads/master
Commit: aad4cef023a558f7f772b41c4c7bb63dea38886c
Parents: 554c01a
Author: Marko Kiiskila <ma...@runtime.io>
Authored: Wed Feb 24 08:25:18 2016 -0800
Committer: Marko Kiiskila <ma...@runtime.io>
Committed: Wed Feb 24 08:27:03 2016 -0800

----------------------------------------------------------------------
 docs/os/modules/imgmgr/imgmgr.md             | 29 +++++++--------
 docs/os/modules/imgmgr/imgmgr_module_init.md | 36 +++++++++++++++++++
 docs/os/modules/imgmgr/imgr_boot_read.md     |  0
 docs/os/modules/imgmgr/imgr_boot_write.md    |  0
 docs/os/modules/imgmgr/imgr_file_download.md |  0
 docs/os/modules/imgmgr/imgr_file_upload.md   |  0
 docs/os/modules/imgmgr/imgr_list.md          |  0
 docs/os/modules/imgmgr/imgr_noop.md          |  0
 docs/os/modules/imgmgr/imgr_read_file.md     |  0
 docs/os/modules/imgmgr/imgr_read_main.md     |  0
 docs/os/modules/imgmgr/imgr_read_test.md     |  0
 docs/os/modules/imgmgr/imgr_read_ver.md      |  0
 docs/os/modules/imgmgr/imgr_upload.md        |  0
 docs/os/modules/imgmgr/imgr_ver_jsonstr.md   |  0
 docs/os/modules/imgmgr/imgr_ver_parse.md     | 44 +++++++++++++++++++++++
 docs/os/modules/imgmgr/imgr_ver_str.md       | 41 +++++++++++++++++++++
 docs/os/modules/imgmgr/imgr_write_file.md    |  0
 17 files changed, 134 insertions(+), 16 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgmgr.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgmgr.md b/docs/os/modules/imgmgr/imgmgr.md
index 650314b..fb4e359 100644
--- a/docs/os/modules/imgmgr/imgmgr.md
+++ b/docs/os/modules/imgmgr/imgmgr.md
@@ -1,15 +1,25 @@
 # Image Manager
 
-Insert synopsis here
+
 
 
 ## Description
 
-Describe module here, special features, how pieces fit together etc.
+This library accepts incoming image management commands from newtmgr and acts on them.
+
+Images can be uploaded, present images listed, and system can be told to switch to another image.
+
+Currently the package assumes that there are 2 image slots, one active one and another one in standby. When new image is uploaded, it replaces the one in standby slot. This is the model for scenario when MCU has internal flash only, it executes the code from that flash, and there is enough space to store 2 full images.
+
+Image manager interacts with bootloader by telling it to boot to a specific image. At the moment this has to be done by writing a file which contains a version number of the image to boot. Note that image manager itself does not replace the active image.
+
+Image manager also can upload files to filesystem as well as download them.
+
+Note that commands accessing filesystems (next boot target, file upload/download) will not be available unless project includes filesystem implementation.
 
 ## Data structures
 
-Replace this with the list of data structures used, why, any neat features
+N/A.
 
 ## List of Functions
 
@@ -18,18 +28,5 @@ Replace this with the list of data structures used, why, any neat features
 The functions available in imgmgr are:
 
 * [imgmgr_module_init](imgmgr_module_init.md)
-* [imgr_boot_read](imgr_boot_read.md)
-* [imgr_boot_write](imgr_boot_write.md)
-* [imgr_file_download](imgr_file_download.md)
-* [imgr_file_upload](imgr_file_upload.md)
-* [imgr_list](imgr_list.md)
-* [imgr_noop](imgr_noop.md)
-* [imgr_read_file](imgr_read_file.md)
-* [imgr_read_main](imgr_read_main.md)
-* [imgr_read_test](imgr_read_test.md)
-* [imgr_read_ver](imgr_read_ver.md)
-* [imgr_upload](imgr_upload.md)
-* [imgr_ver_jsonstr](imgr_ver_jsonstr.md)
 * [imgr_ver_parse](imgr_ver_parse.md)
 * [imgr_ver_str](imgr_ver_str.md)
-* [imgr_write_file](imgr_write_file.md)

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgmgr_module_init.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgmgr_module_init.md b/docs/os/modules/imgmgr/imgmgr_module_init.md
index e69de29..a64d2fd 100644
--- a/docs/os/modules/imgmgr/imgmgr_module_init.md
+++ b/docs/os/modules/imgmgr/imgmgr_module_init.md
@@ -0,0 +1,36 @@
+## <font color="#F2853F" style="font-size:24pt"> console_init </font>
+
+```no-highlight
+   int
+   imgmgr_module_init(void)
+```
+
+  Registers image manager commands with newtmgr. This function should be called while initializing the project, preferably after newtmgr itself has been initialized.
+
+#### Arguments
+
+N/A
+
+#### Returned values
+
+List any values returned.
+Error codes?
+
+#### Notes
+
+
+#### Example
+
+```no-highlight
+int main(int argc, char **argv)
+{
+    ...
+    
+    nmgr_task_init(NEWTMGR_TASK_PRIO, newtmgr_stack, NEWTMGR_TASK_STACK_SIZE);
+    imgmgr_module_init();
+
+    ...
+}
+```
+
+

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_boot_read.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_boot_read.md b/docs/os/modules/imgmgr/imgr_boot_read.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_boot_write.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_boot_write.md b/docs/os/modules/imgmgr/imgr_boot_write.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_file_download.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_file_download.md b/docs/os/modules/imgmgr/imgr_file_download.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_file_upload.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_file_upload.md b/docs/os/modules/imgmgr/imgr_file_upload.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_list.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_list.md b/docs/os/modules/imgmgr/imgr_list.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_noop.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_noop.md b/docs/os/modules/imgmgr/imgr_noop.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_read_file.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_read_file.md b/docs/os/modules/imgmgr/imgr_read_file.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_read_main.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_read_main.md b/docs/os/modules/imgmgr/imgr_read_main.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_read_test.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_read_test.md b/docs/os/modules/imgmgr/imgr_read_test.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_read_ver.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_read_ver.md b/docs/os/modules/imgmgr/imgr_read_ver.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_upload.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_upload.md b/docs/os/modules/imgmgr/imgr_upload.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_ver_jsonstr.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_ver_jsonstr.md b/docs/os/modules/imgmgr/imgr_ver_jsonstr.md
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_ver_parse.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_ver_parse.md b/docs/os/modules/imgmgr/imgr_ver_parse.md
index e69de29..a3b1e85 100644
--- a/docs/os/modules/imgmgr/imgr_ver_parse.md
+++ b/docs/os/modules/imgmgr/imgr_ver_parse.md
@@ -0,0 +1,44 @@
+## <font color="#F2853F" style="font-size:24pt"> console_init </font>
+
+```no-highlight
+   int
+   imgr_ver_parse(char *src, struct image_version *ver)
+```
+
+  Parses character string containing image version number `src` and writes that to `ver`. Version number string should be in format <major>.<minor>.<revision>.<build_number>. Major and minor numbers should be within range 0-255, revision between 0-65535 and build_number 0-4294967295.
+  
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| src | Pointer to C string that contains version number being parsed |
+| ver | Image version number structure containing the returned value |
+
+#### Returned values
+
+0 on success and <0 if version number string could not be parsed.
+
+#### Notes
+
+Numbers within the string are separated by `.`. The first   number is the major number, and must be provided. Rest of the numbers (minor etc.) are optional.
+
+#### Example
+
+```no-highlight
+int main(int argc, char **argv)
+{
+    struct image_version hdr_ver;
+    int rc;
+    ...
+    
+    rc = imgr_ver_parse(argv[3], &hdr_ver);
+    if (rc != 0) {
+        print_usage(stderr);
+        return 1;
+    }
+    ...
+}
+```
+
+

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_ver_str.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_ver_str.md b/docs/os/modules/imgmgr/imgr_ver_str.md
index e69de29..31ef427 100644
--- a/docs/os/modules/imgmgr/imgr_ver_str.md
+++ b/docs/os/modules/imgmgr/imgr_ver_str.md
@@ -0,0 +1,41 @@
+## <font color="#F2853F" style="font-size:24pt"> console_init </font>
+
+```no-highlight
+   int
+   imgr_ver_str(struct image_version *ver, char *dst)
+```
+
+  Takes the version string from `ver` and formats that into a printable string to `dst`. Caller must make sure that `dst` contains enough space to hold maximum lenght version string. The convenience defininition for max length version string is named `IMGMGR_MAX_VER_STR`.
+  
+
+#### Arguments
+
+| Arguments | Description |
+|-----------|-------------|
+| ver | Image version number structure containing the value being formatted |
+| dst | Pointer to C string where results will be stored |
+
+#### Returned values
+
+Function returns the number of characters filled into the destination string.
+
+#### Notes
+
+If build number is `0` in image version structure, it will be left out of the string.
+
+#### Example
+
+```no-highlight
+static void
+imgr_ver_jsonstr(struct json_encoder *enc, char *key,
+  struct image_version *ver)
+{
+    char ver_str[IMGMGR_MAX_VER_STR];
+    int ver_len;
+    ...
+    ver_len = imgr_ver_str(ver, ver_str)
+    ...
+}
+```
+
+

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/aad4cef0/docs/os/modules/imgmgr/imgr_write_file.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/imgmgr/imgr_write_file.md b/docs/os/modules/imgmgr/imgr_write_file.md
deleted file mode 100644
index e69de29..0000000