Normalizing the modules More editing, formatting and normalizing of documents. Some just splitting lines so they fit in an editor.
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/79707346 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/79707346 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/79707346 Branch: refs/heads/develop Commit: 7970734600fc3cd522ee6431bb49f630ffaf239f Parents: aac53ed Author: David G. Simmons <[email protected]> Authored: Thu Nov 3 15:20:07 2016 -0400 Committer: David G. Simmons <[email protected]> Committed: Thu Nov 3 15:20:07 2016 -0400 ---------------------------------------------------------------------- docs/os/modules/baselibc.md | 21 ++- docs/os/modules/console/console.md | 37 +++- .../os/modules/console/console_blocking_mode.md | 12 +- docs/os/modules/console/console_echo.md | 13 +- docs/os/modules/console/console_init.md | 18 +- docs/os/modules/console/console_is_init.md | 8 +- docs/os/modules/console/console_printf.md | 22 ++- docs/os/modules/console/console_read.md | 18 +- docs/os/modules/console/console_write.md | 11 +- docs/os/modules/shell/shell.md | 30 ++-- docs/os/modules/shell/shell_cmd_register.md | 13 +- .../modules/shell/shell_nlip_input_register.md | 15 +- docs/os/modules/shell/shell_nlip_output.md | 6 +- docs/os/modules/shell/shell_task_init.md | 18 +- docs/os/modules/split/split.md | 173 +++++++++++++------ 15 files changed, 271 insertions(+), 144 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/baselibc.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/baselibc.md b/docs/os/modules/baselibc.md index fe650ac..377eca8 100644 --- a/docs/os/modules/baselibc.md +++ b/docs/os/modules/baselibc.md @@ -1,6 +1,8 @@ # Baselibc -Baselibc is a very simple libc for embedded systems geared primarily for 32-bit microcontrollers in the 10-100kB memory range. The library of basic system calls and facilities compiles to less than 5kB total on Cortex-M3, and much less if some functions aren't used. +Baselibc is a very simple libc for embedded systems geared primarily for 32-bit microcontrollers in the +10-100kB memory range. The library of basic system calls and facilities compiles to less than 5kB total +on Cortex-M3, and much less if some functions aren't used. The code is based on klibc and tinyprintf modules, and licensed under the BSD license. @@ -8,11 +10,17 @@ Baselibc comes from https://github.com/PetteriAimonen/Baselibc.git ###Description -Mynewt OS can utilize libc which comes with compiler (e.g. newlib bundled with some binary distributions of arm-none-eabi-gcc). However, you may choose to replace the libc with baselibc for a reduced image size. Baselibc optimizes for size rather than performance, which is usually a more important goal in embedded environments. +Mynewt OS can utilize libc which comes with the compiler (e.g. newlib bundled with some binary +distributions of arm-none-eabi-gcc). However, you may choose to replace the libc with baselibc +for a reduced image size. Baselibc optimizes for size rather than performance, which is usually +a more important goal in embedded environments. ###How to switch to baselibc -In order to switch from using libc to using baselibc you have to add the baselibc pkg as a dependency in the project pkg. Specifying this dependency ensures that the linker first looks for the functions in baselibc before falling back to libc while creating the executable. For example, project `boot` uses baselibc. Its project description file `boot.yml` looks like the following: +In order to switch from using libc to using baselibc you have to add the baselibc pkg as a dependency +in the project pkg. Specifying this dependency ensures that the linker first looks for the functions +in baselibc before falling back to libc while creating the executable. For example, project `boot` +uses baselibc. Its project description file `boot.yml` looks like the following: ```no-highlight project.name: boot @@ -24,12 +32,13 @@ In order to switch from using libc to using baselibc you have to add the baselib - libs/console/stub - libs/util - libs/baselibc - ``` +``` ###List of Functions -Documentation for libc functions is available from multiple places. One example are the on-line manual pages at [https://www.freebsd.org/cgi/man.cgi](#https://www.freebsd.org/cgi/man.cgi). +Documentation for libc functions is available from multiple places. One example is the on-line manual +pages at [https://www.freebsd.org/cgi/man.cgi](#https://www.freebsd.org/cgi/man.cgi). -baselibc supports most libc functionality; malloc(), printf-family, string handling, and conversion routines. +baselibc supports most libc functionality; `malloc()`, printf-family, string handling, and conversion routines. There is some functionality which is not available, e.g. support for floating point numbers, and limited support for 'long long'. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/console/console.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/console/console.md b/docs/os/modules/console/console.md index 53d195b..9d5b738 100644 --- a/docs/os/modules/console/console.md +++ b/docs/os/modules/console/console.md @@ -1,7 +1,10 @@ #Console -The console is an operating system window where users interact with system programs of the operating system or a console application by entering text input (typically from a keyboard) and reading text output (typically on the computer terminal or monitor). The text written on the console brings some information and is a sequence of characters sent by the OS or programs running on the OS. +The console is an operating system window where users interact with system programs of the operating system +or a console application by entering text input (typically from a keyboard) and reading text output +(typically on the computer terminal or monitor). The text written on the console brings some information +and is a sequence of characters sent by the OS or programs running on the OS. Support is currently available for console access via the serial port on the hardware board. @@ -13,8 +16,10 @@ In the Mynewt OS, the console library comes in two versions: * full - containing the full implementation * stub - containing stubs for the API -Both of these have `pkg.yml` file which states that they provide the `console` API. If a pkg uses this API, it should list `console` as a requirement. -For example, the shell pkg is defined by the following pkg.yml file: +Both of these have a `pkg.yml` file which states that they provide the `console` API. If a pkg uses +this API, it should list `console` as a requirement. For example, the shell pkg is defined by the +following pkg.yml file: + ```no-highlight pkg.name: libs/shell pkg.vers: 0.1 @@ -26,11 +31,19 @@ For example, the shell pkg is defined by the following pkg.yml file: pkg.identities: - SHELL ``` + The project .yml file decides which version of the console pkg should be included. -If project requires the full console capability it lists dependency `libs/console/full` in its pkg.yml file. On the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) but may have a dependency on a pkg that has console capability. In that case you would use a console stub. +If a project requires the full console capability it lists dependency `libs/console/full` in its pkg.yml +file. On the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) +but may have a dependency on a pkg that has console capability. In that case you would use a console stub. + +Another example would be the bootloader project where we want to keep the size of the image small. It includes +the `libs/os` pkg that can print out messages on a console (e.g. if there is a hard fault) and the `libs/util` +pkg that uses the full console (but only if SHELL is present to provide a CLI). However, we do not want to use +any console I/O capability in this particular bootloader project to keep the size small. We simply use the console +stub instead, and the pkg.yml file for the project boot pkg looks like the following: -Another example would be the bootloader project where we want to keep the size of the image small. It includes the `libs/os` pkg that can print out messages on a console (e.g. if there is a hard fault) and the `libs/util` pkg that uses full console (but only if SHELL is present to provide a CLI). However, we do not want to use any console I/O capability in this particular bootloader project to keep the size small. We simply use the console stub instead, and the pkg.yml file for the project boot pkg looks like the following: ```no-highlight project.name: boot project.identities: bootloader @@ -42,10 +55,18 @@ Another example would be the bootloader project where we want to keep the size o - libs/util ``` -Console has 2 modes for transmit; *blocking mode* and *non-blocking mode*. Usually the *non-blocking mode* is the active one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added based on these interrupts. -*Blocking mode* is used when we don't want TX completion interrupts. It is used when system crashes, and we still want to output info related to that crash. +Console has 2 modes for transmit; *blocking mode* and *non-blocking mode*. Usually the *non-blocking mode* is the +active one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added +based on these interrupts. + +*Blocking mode* is used when we don't want TX completion interrupts. It is used when system crashes, and we still +want to output info related to that crash. + +Console, by default, echoes everything it receives back. Terminal programs expect this, and is a way for the user to +know that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically. -Console, by default, echoes everything it receives back. Terminal programs expect this, and is a way for the user to know that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically. +The Console also has a prompt that is configurable. It is off by default but can be turned on programatically. The +prompt cahracter can also be changed by the user. ###Data structures http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/console/console_blocking_mode.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/console/console_blocking_mode.md b/docs/os/modules/console/console_blocking_mode.md index ea1c7d7..01568ea 100644 --- a/docs/os/modules/console/console_blocking_mode.md +++ b/docs/os/modules/console/console_blocking_mode.md @@ -1,10 +1,12 @@ ## <font color="#F2853F" style="font-size:24pt"> console_blocking_mode </font> -```no-highlight - void - console_blocking_mode(void) +```c +void console_blocking_mode(void) ``` - Calls the `console_blocking_tx` function to flush the buffered console output (transmit) queue. The function `OS_ENTER_CRITICAL()` is called to disable interrupts and `OS_EXIT_CRITICAL()` is called to enable interrupts back again once the buffer is flushed. + +Calls the `console_blocking_tx` function to flush the buffered console output (transmit) queue. +The function `OS_ENTER_CRITICAL()` is called to disable interrupts and `OS_EXIT_CRITICAL()` +is called to enable interrupts back again once the buffer is flushed. #### Arguments @@ -20,7 +22,7 @@ N/A Here is an example of calling `console_blocking_mode` and printing crash information from an assert to help debug. -```no-highlight +```c void _assert_func(const char *file, int line, const char *func, const char *e) { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/console/console_echo.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/console/console_echo.md b/docs/os/modules/console/console_echo.md index 6d58c67..086307c 100644 --- a/docs/os/modules/console/console_echo.md +++ b/docs/os/modules/console/console_echo.md @@ -1,7 +1,7 @@ ## <font color="#F2853F" style="font-size:24pt"> console_echo </font> -```no-highlight - void console_echo(int on) +```c +void console_echo(int on) ``` Controls whether echoing is on or off for the console. When echoing is on, all characters received are transmitted back. @@ -10,7 +10,7 @@ Controls whether echoing is on or off for the console. When echoing is on, all c | Arguments | Description | |-----------|-------------| -| on | 1 turns on echoing, 0 turns it off | +| `on` | 1 turns on echoing, 0 turns it off | #### Returned values @@ -19,11 +19,14 @@ None #### Notes +None + #### Example -Here is an example where newtmgr protocol handler is controlling whether echoing is on or off. Newtmgr, the tool, turns echoing off when it's transmitting large chunks of data to target board. +Here is an example where newtmgr protocol handler is controlling whether echoing is on or off. [Newtmgr](../../../newtmgr/overview.md) +turns echoing off when it is transmitting large chunks of data to a target board. -```no-highlight +```c static int nmgr_def_console_echo(struct nmgr_jbuf *njb) { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/console/console_init.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/console/console_init.md b/docs/os/modules/console/console_init.md index d56b2b6..9438208 100644 --- a/docs/os/modules/console/console_init.md +++ b/docs/os/modules/console/console_init.md @@ -1,19 +1,21 @@ ## <font color="#F2853F" style="font-size:24pt"> console_init </font> -```no-highlight - int - console_init(console_rx_cb rx_cb) +```c +int console_init(console_rx_cb rx_cb) ``` + +Initializes the console receive buffer and calls hal funtions `hal_uart_init_cbs` and `hal_uart_config` to +initialize the serial port connection and configure it (e.g. baud rate, flow control etc.) - Initializes console receive buffer and calls hal funtions `hal_uart_init_cbs` and `hal_uart_config` to initialize serial port connection and configure it (e.g. baud rate, flow control etc.) - -Caller registers a function pointer of `type void (*console_rx_cb)(int full_line)`. This function will be called when console receives either a) full line of data or b) when RX buffer in console is full. Note that this function is most likely getting called from interrupt context. +Caller registers a function pointer of `type void (*console_rx_cb)(int full_line)`. This function will be +called when the console receives either a) full line of data or b) when RX buffer in console is full. +Note that this function is most likely getting called from an interrupt context. #### Arguments | Arguments | Description | |-----------|-------------| -| rx_cb | Function pointer, which gets called input is received. | +| `rx_cb` | Function pointer, which gets called when input is received. | #### Returned values @@ -22,7 +24,7 @@ Non-zero if HAL UART function calls fail. #### Example -```no-highlight +```c int main(int argc, char **argv) { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/console/console_is_init.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/console/console_is_init.md b/docs/os/modules/console/console_is_init.md index 3ec0698..b781b6d 100644 --- a/docs/os/modules/console/console_is_init.md +++ b/docs/os/modules/console/console_is_init.md @@ -1,10 +1,10 @@ ## <font color="#F2853F" style="font-size:24pt"> console_is_init </font> -```no-highlight - int console_is_init(void) +```c +int console_is_init(void) ``` - Returns whether console has been initialized or not. I.e. whether `console_init()` has been called yet. +Returns whether console has been initialized or not. I.e. whether `console_init()` has been called yet. #### Arguments @@ -17,7 +17,7 @@ Returns 1 if console has been initialized. 0 if not. #### Example -```no-highlight +```c static int log_console_append(struct log *log, void *buf, int len) { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/console/console_printf.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/console/console_printf.md b/docs/os/modules/console/console_printf.md index 8eb2280..0cda207 100644 --- a/docs/os/modules/console/console_printf.md +++ b/docs/os/modules/console/console_printf.md @@ -1,19 +1,21 @@ ## <font color="F2853F" style="font-size:24pt"> console_printf</font> -```no-highlight - void - console_printf(const char *fmt, ...) +```c +void console_printf(const char *fmt, ...) ``` -Writes a formatted message instead of raw output to the console. It first composes a C string containing text specified as arguments to the function or containing the elements in the variable argument list passed to it using snprintf or vsnprintf, respectively. It then uses function `console_write` to output the formatted data (messages) on the console. +Writes a formatted message instead of raw output to the console. It first composes a C string containing +the text specified as arguments to the function or containing the elements in the variable argument list +passed to it using `snprintf` or `vsnprintf`, respectively. It then uses the function `console_write` to +output the formatted data (messages) on the console. #### Arguments | Arguments | Description | |-----------|-------------| -| fmt | Pointer to C string that contains a format string that follows the same specifications as format in printf. The string is printed to console. | -| ... | Depending on the format string, the function may expect either a sequence of additional arguments to be used to replace a format specifier in the format string or a variable arguments list. va_list is a special type defined in <cstdarg> in stdarg.h. | +| `fmt` | Pointer to C string that contains a format string that follows the same specifications as format in printf. The string is printed to console. | +| ... | Depending on the format string, the function may expect either a sequence of additional arguments to be used to replace a format specifier in the format string or a variable arguments list. `va_list` is a special type defined in <cstdarg> in `stdarg.h`. | #### Returned values @@ -21,12 +23,14 @@ None #### Notes -While `console_printf`, with its well understood formatting options in C, is more convenient and easy on the eyes than the raw output of `console_write`, the associated code size is considerably larger. +While `console_printf`, with its well understood formatting options in C, is more convenient and easy on the +eyes than the raw output of `console_write`, the associated code size is considerably larger. #### Example + Example #1: -```no-highlight +```c char adv_data_buf[32]; void @@ -40,7 +44,7 @@ task() Example #2: -```no-highlight +```c struct exception_frame { uint32_t r0; uint32_t r1; http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/console/console_read.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/console/console_read.md b/docs/os/modules/console/console_read.md index 1e6600d..8ddc3d8 100644 --- a/docs/os/modules/console/console_read.md +++ b/docs/os/modules/console/console_read.md @@ -1,18 +1,18 @@ ## <font color="#F2853F" style="font-size:24pt"> console_read </font> -```no-highlight - int - console_read(char *str, int cnt) +```c +int console_read(char *str, int cnt) ``` -Copies up to *cnt* bytes of received data to buffer pointed by *str*. Function tries to break the input into separate lines; once it encounters a newline character, it replaces that with end-of-string and returns. +Copies up to `cnt` bytes of received data to buffer pointed by `str`. Function tries to break the input into +separate lines; once it encounters a newline character, it replaces that with end-of-string and returns. #### Arguments | Arguments | Description | |-----------|-------------| -| str | Buffer where data is copied to. | -| cnt | Maximum number of characters to copy. | +| `str` | Buffer where data is copied to. | +| `cnt` | Maximum number of characters to copy. | #### Returned values @@ -22,7 +22,7 @@ available, or if the first received character was '\n'. #### Example -```no-highlight +```c void task1_loop(void *arg) { @@ -39,4 +39,8 @@ task1_loop(void *arg) if (!strncmp(rx_msg, "reset", rx_len)) { assert(0); } + } + } + } +} ``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/console/console_write.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/console/console_write.md b/docs/os/modules/console/console_write.md index 3d38529..51f73aa 100644 --- a/docs/os/modules/console/console_write.md +++ b/docs/os/modules/console/console_write.md @@ -1,8 +1,7 @@ ## <font color="#F2853F" style="font-size:24pt"> console_write </font> -```no-highlight - void - console_write(char *str, int cnt) +```c +void console_write(char *str, int cnt) ``` Queues characters to console display over serial port. @@ -10,8 +9,8 @@ Queues characters to console display over serial port. | Arguments | Description | |-----------|-------------| -| *str | pointer to the character or packet to be transmitted | -| cnt | number of characters in *str* | +| `*str` | pointer to the character or packet to be transmitted | +| `cnt` | number of characters in `str` | #### Returned values @@ -22,7 +21,7 @@ N/A Here is an example of the function being used in an echo command with a newline at the end. -```no-highlight +```c static int shell_echo_cmd(int argc, char **argv) { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/shell/shell.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/shell/shell.md b/docs/os/modules/shell/shell.md index d3b50f5..208f9fb 100644 --- a/docs/os/modules/shell/shell.md +++ b/docs/os/modules/shell/shell.md @@ -1,16 +1,20 @@ # Shell -The shell is package sitting on top of console, handling 2 jobs: processing console input and implementing newtmgr line protocol over serial line. Shell runs on its own task. +The shell is package sitting on top of console, handling 2 jobs: processing console input and implementing +[newtmgr](../../../newtmgr/overview.md) line protocol over serial line. Shell runs in its own task. ###Description -* Shell's first job is directing incoming commands to other subsystems. It parses the incoming character string, and splits it into tokens. Then it looks for the subsystem to handle this command based on the first token of input. +* Shell's first job is directing incoming commands to other subsystems. It parses the incoming character string +and splits it into tokens. Then it looks for the subsystem to handle this command based on the first token of input. - Subsystems register their command handlers using `shell_cmd_register()`. When shell calls the command handler, it passes the other tokens as arguments. + * Subsystems register their command handlers using `shell_cmd_register()`. When shell calls the command handler, it passes the other tokens as arguments. - A few commands are currently available in the shell - `tasks`, `log`, and `stat stat`. A $ prompt sign will be coming soon! + * A few commands are currently available in the shell - `tasks`, `log`, `echo`, `date` and `prompt`. -* Shell's second job is doing framing, encoding and decoding newtmgr protocol when it's carried over the console. Protocol handler (libs/newtmgr) registers itself using `shell_nlip_input_register()`, and shell calls the registered handler for every frame. Outgoing frames for the protocol are sent using `shell_nlip_output()`. +* Shell's second job is doing framing, encoding and decoding newtmgr protocol when it's carried over the console. +Protocol handler (libs/newtmgr) registers itself using `shell_nlip_input_register()`, and shell calls the registered +handler for every frame. Outgoing frames for the protocol are sent using `shell_nlip_output()`. <br> @@ -81,8 +85,12 @@ tasks 217953: os_sanity (prio: 254, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms) 218010: task2 (prio: 2, nw: 217709, flags: 0x3, ssize: 0, cswcnt: 218, tot_run_time: 0ms) -stat stat -229881:s0: 1 + +prompt +Usage: prompt [set|show] [prompt_char] +prompt set > +Prompt set to: > +229370: > ``` @@ -91,7 +99,7 @@ stat stat This data structure is used in holding information about registered command handlers. -```no-highlight +```c struct shell_cmd { char *sc_cmd; shell_cmd_func_t sc_cmd_func; @@ -101,9 +109,9 @@ struct shell_cmd { | Element | Description | |---------|-------------| -| sc_cmd | Character string of the command | -| sc_cmd_func | Pointer to the command handler | -| sc_next | Bookkeeping linkage internal for shell | +| `sc_cmd` | Character string of the command | +| `sc_cmd_func` | Pointer to the command handler | +| `sc_next` | Bookkeeping linkage internal for shell | ###List of Functions http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/shell/shell_cmd_register.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/shell/shell_cmd_register.md b/docs/os/modules/shell/shell_cmd_register.md index aea4c16..5becffd 100644 --- a/docs/os/modules/shell/shell_cmd_register.md +++ b/docs/os/modules/shell/shell_cmd_register.md @@ -1,18 +1,21 @@ ## <font color="#F2853F" style="font-size:24pt"> shell_cmd_register </font> -```no-highlight +```c int shell_cmd_register(struct shell_cmd *sc) ``` -Registers a handler for incoming console commands. Within the structure there is the command string and the handler for those commands. Caller must allocate the memory for this structure and keep it around as shell links this to its own internal data structures. +Registers a handler for incoming console commands. Within the structure there is the command string +and the handler for those commands. Caller must allocate the memory for this structure and keep it around +as shell links this to its own internal data structures. -Command handler is of type `int(*shell_cmd_func_t)(int argc, char **argv)`. Command line arguments are passed to it as an array of character pointers. +Command handler is of type `int(*shell_cmd_func_t)(int argc, char **argv)`. Command line arguments +are passed to it as an array of character pointers. #### Arguments | Arguments | Description | |-----------|-------------| -| sc | Structure containing info about the command. | +| `sc` | Structure containing info about the command. | #### Returned values @@ -21,7 +24,7 @@ Non-zero on failure. #### Example -```no-highlight +```c static int fs_ls_cmd(int argc, char **argv); static struct shell_cmd fs_ls_struct = { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/shell/shell_nlip_input_register.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/shell/shell_nlip_input_register.md b/docs/os/modules/shell/shell_nlip_input_register.md index abc64d6..ab2912a 100644 --- a/docs/os/modules/shell/shell_nlip_input_register.md +++ b/docs/os/modules/shell/shell_nlip_input_register.md @@ -1,19 +1,22 @@ ## <font color="#F2853F" style="font-size:24pt"> shell_nlip_input_register </font> -```no-highlight +```c int shell_nlip_input_register(shell_nlip_input_func_t nf, void *arg) ``` -Registers a handler for incoming newtmgr messages. Shell receives incoming data stream from UART and when it detects NLIP frame, it decodes it and passes it on by calling the function `nf`. +Registers a handler for incoming newtmgr messages. Shell receives incoming data stream from +UART and when it detects NLIP frame, it decodes it and passes it on by calling the function `nf`. -Handler function is of type `int (*shell_nlip_input_func_t)(struct os_mbuf *m, void *arg)`. Shell passes the incoming newtmgr message inside os_mbuf *m*, and *arg* is the argument that was passed in during handler registration. +Handler function is of type `int (*shell_nlip_input_func_t)(struct os_mbuf *m, void *arg)`. +Shell passes the incoming newtmgr message inside `os_mbuf` `m`, and `arg` is the argument that +was passed in during handler registration. #### Arguments | Arguments | Description | |-----------|-------------| -| nf | Handler for incoming newtmgr datagrams. | -| arg | Argument that gets passed to this handler, along with the datagram | +| `nf` | Handler for incoming newtmgr datagrams. | +| `arg` | Argument that gets passed to this handler, along with the datagram | #### Returned values @@ -21,7 +24,7 @@ Returns 0 on success. #### Example -```no-highlight +```c static int nmgr_shell_in(struct os_mbuf *m, void *arg) { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/shell/shell_nlip_output.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/shell/shell_nlip_output.md b/docs/os/modules/shell/shell_nlip_output.md index 4880de0..a905b63 100644 --- a/docs/os/modules/shell/shell_nlip_output.md +++ b/docs/os/modules/shell/shell_nlip_output.md @@ -1,6 +1,6 @@ ## <font color="#F2853F" style="font-size:24pt"> shell_nlip_output </font> -```no-highlight +```c int shell_nlip_output(struct os_mbuf *m) ``` @@ -10,7 +10,7 @@ Queue outgoing newtmgr message for transmission. Shell package will encode this | Arguments | Description | |-----------|-------------| -| m | os_mbuf containing the message | +| `m` | os_mbuf containing the message | #### Returned values @@ -18,7 +18,7 @@ Returns 0 on success. #### Example -```no-highlight +```c static int nmgr_shell_out(struct nmgr_transport *nt, struct os_mbuf *m) { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/shell/shell_task_init.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/shell/shell_task_init.md b/docs/os/modules/shell/shell_task_init.md index ce2985a..63b854d 100644 --- a/docs/os/modules/shell/shell_task_init.md +++ b/docs/os/modules/shell/shell_task_init.md @@ -1,20 +1,20 @@ ## <font color="F2853F" style="font-size:24pt"> shell_task_init</font> -```no-highlight -int shell_task_init(uint8_t prio, os_stack_t *stack, uint16_t stack_size, - int max_input_length); +```c +int shell_task_init(uint8_t prio, os_stack_t *stack, uint16_t stack_size, int max_input_length); ``` -Initializes the shell package. This creates a task for shell, and registers few commands on its own (*echo*, *?*, for example). It also allocates memory for buffering console input. +Initializes the shell package. This creates a task for shell, and registers a few commands on its own +(`echo`, `?`, `prompt` for example). It also allocates memory for buffering console input. #### Arguments | Arguments | Description | |-----------|-------------| -| prio | Priority of the shell task | -| stack | Pointer to shell tasks's stack | -| stack_size | Size of the aforementioned stack (in units of os_stack_t) | -| max_input_length | the maximum expected length of line for input | +| `prio` | Priority of the shell task | +| `stack` | Pointer to shell tasks's stack | +| `stack_size` | Size of the aforementioned stack (in units of os_stack_t) | +| `max_input_length` | the maximum expected length of line for input | #### Returned values @@ -28,7 +28,7 @@ You can register commands before calling this, but only if OS has not been start Here's an example of stand-alone code which allows the user to execute regression tests for sys/config package only. -```no-highlight +```c #define SHELL_TASK_PRIO (3) #define SHELL_MAX_INPUT_LEN (256) #define SHELL_TASK_STACK_SIZE (OS_STACK_ALIGN(384)) http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/79707346/docs/os/modules/split/split.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/split/split.md b/docs/os/modules/split/split.md index 0733e6f..bd54dde 100644 --- a/docs/os/modules/split/split.md +++ b/docs/os/modules/split/split.md @@ -4,18 +4,25 @@ ## Description -Split images allow the user to build the application content separate from the library content by splitting an application into two pieces: +Split images allow the user to build the application content separate from the library content by +splitting an application into two pieces: -* A "loader" which contains a separate application that can perform upgrades and manage split images. The "loader" resides in slot 1. -* A "split app" which contains the main application content and references the libraries in the loader by static linkage. The "split app" resides in slot 2. +* A "loader" which contains a separate application that can perform upgrades and manage split images. +The "loader" resides in slot 1. +* A "split app" which contains the main application content and references the libraries in the loader +by static linkage. The "split app" resides in slot 2. ## Goals -The goal of split images is to allow a larger application to run along with large components of mynewt such as [nimble BLE stack](../../../network/ble/ble_intro/) and [neutron flash file system(nffs)](../fs/nffs/nffs.md). +The goal of split images is to allow a larger application to run along with large components of +mynewt such as [nimble BLE stack](../../../network/ble/ble_intro/) and [neutron flash file system(nffs)](../fs/nffs/nffs.md). ## Concept -In a typical mynewt application, an application is contained wholly within an image slot. Typically there are at least two image slots since the image runs from one slot while uploading new code into the second slot. Each image is capable of erasing and uploading another image. Each image is completely stand-alone; that is, each image contains all of the libraries and components that it needs. +In a typical mynewt application, an application is contained wholly within an image slot. Typically +there are at least two image slots since the image runs from one slot while uploading new code into +the second slot. Each image is capable of erasing and uploading another image. Each image is completely +stand-alone; that is, each image contains all of the libraries and components that it needs. On a typical 256 kbyte flash, a flash layout might look like this: @@ -40,18 +47,25 @@ Now, suppose the desired image contains: | newtmgr | 7 k | -which total 106k. With an image slot size of 108k this leaves only a small amount of code space remaining for the application. +which total 106k. With an image slot size of 108k this leaves only a small amount of code space +remaining for the application. -However, we can see that these packages contain everything you need to upgrade and configure, so if we build a stand-alone loader with these components, we can build the app as a split image and get the entire second image slot to store application code and constant data. +However, we can see that these packages contain everything you need to upgrade and configure, so +if we build a stand-alone loader with these components, we can build the app as a split image and +get the entire second image slot to store application code and constant data. ## When do I use split images -If your application fits into the available image slots, there is no advantage to using split images. In general, split images are harder to debug and more complicated to upload. However for a larger application, there may not be enough flash space to have two copies of the entire application. This is when split image becomes necessary. +If your application fits into the available image slots, there is no advantage to using split +images. In general, split images are harder to debug and more complicated to upload. However +for a larger application, there may not be enough flash space to have two copies of the entire +application. This is when split image becomes necessary. ## How do I tell Newt I am building a split image? -Newt looks for the variable `loader` in your target file. If it finds `loader` variable, it will build a split image. For example, +Newt looks for the variable `loader` in your target file. If it finds `loader` variable, it +will build a split image. For example, ``` targets/app @@ -75,14 +89,16 @@ Split image requires BSP support. The following BSPs support split images: ## Loaders -The following applications have been enabled as loaders. You may choose to build your own loader application, and these can serve as samples. +The following applications have been enabled as loaders. You may choose to build your own loader +application, and these can serve as samples. * @apache-mynewt-core/apps/slinky * @apache-mynewt-core/apps/bleprph ## Split Apps -The following applications have been enabled as split applications. If you choose to build your own split application these can serve as samples. Note that slinky can be either a loader image or a split app image. +The following applications have been enabled as split applications. If you choose to build your own +split application these can serve as samples. Note that slinky can be either a loader image or a split app image. * @apache-mynewt-core/apps/slinky * @apache-mynewt-core/apps/splitty @@ -91,58 +107,81 @@ The following applications have been enabled as split applications. If you choos A split image is built as follows: -First newt builds the `app` and `loader` images separately to ensure they are consistent (no errors) and to generate elf files which can inform newt of the symbols used by each part. +First newt builds the `app` and `loader` images separately to ensure they are consistent (no errors) and +to generate elf files which can inform newt of the symbols used by each part. -Then newt collects the symbols used by both `app` and `loader` in two ways. It collects the set of symbols from the `.elf` files. It also collects all the possible symbols from the `.a` files for each application. +Then newt collects the symbols used by both `app` and `loader` in two ways. It collects the set of +symbols from the `.elf` files. It also collects all the possible symbols from the `.a` files for +each application. -Newt builds the set of packages that the two applications share. It ensures that all the symbols used in those packages are matching. NOTE: because of features and #ifdefs, its possible for the two package to have symbols that are not the same. In this case newt generates an error and will not build a split image. +Newt builds the set of packages that the two applications share. It ensures that all the symbols +used in those packages are matching. NOTE: because of features and #ifdefs, its possible for the +two package to have symbols that are not the same. In this case newt generates an error and will +not build a split image. Then newt creates the list of symbols that the two applications share from those packages (using the .elf files). -Newt re-links the loader to ensure all of these symbols are present in the loader application (by forcing the linker to include them in the `.elf`). +Newt re-links the loader to ensure all of these symbols are present in the loader application (by +forcing the linker to include them in the `.elf`). -Newt builds a special copy of the loader.elf with only these symbols (and the handful of symbols discussed in the linking section above). +Newt builds a special copy of the loader.elf with only these symbols (and the handful of symbols +discussed in the linking section above). -Finally, newt links the application, replacing the common .a libraries with the special loader.elf image during the link. +Finally, newt links the application, replacing the common .a libraries with the special loader.elf +image during the link. ## Design ### Bootloader -The bootloader has been modified to support "non bootable" images like split app images. A flag in the image header denotes the image as "non-bootable". When this flag is set, the bootloader will not boot the split app image, nor will it copy it to the slot 1 location. Loader images are bootable, split app images are not. +The [bootloader](../bootloader/bootloader.md) has been modified to support "non bootable" images like split app images. A flag in +the image header denotes the image as "non-bootable". When this flag is set, the bootloader will +not boot the split app image, nor will it copy it to the slot 1 location. Loader images are bootable, +split app images are not. ### Newt Newt builds a split image when the token `loader=@apache-mynewt-core/apps/slinky` is present in the target file. -Newt has a `Builder` object that is responsible for building an image. This features a `targetBuilder` object that contains two builders (one for the app and one for the loader). +Newt has a `Builder` object that is responsible for building an image. This features a `targetBuilder` +object that contains two builders (one for the app and one for the loader). The `Builder` object has been expanded to include options for building as part of a split image. * Ability to specify the linker file during the link * Ability to specify a set of keep_symbols during the link -Newt commands like download, size, create-image have been expanded to perform operations twice (once for loader and once for app) if the loader target is present. +Newt commands like download, size, create-image have been expanded to perform operations twice +(once for loader and once for app) if the loader target is present. -During normal single-image builds, the `targetBuilder` initializes and builds the application `builder`. During the split image build, the `targetBuilder` performs the steps outlined in the section above using the two `builder`s for the loader and app. +During normal single-image builds, the `targetBuilder` initializes and builds the application +`builder`. During the split image build, the `targetBuilder` performs the steps outlined in the +section above using the two `builder`s for the loader and app. Special symbol and link features are designed as follows: * Newt uses objdump to parse the symbol maps in the `.a` and `.elf` files. -* Newt uses the `--undefined=` option of the linker to force the loader to keep symbols used by the app (but not used by the linker) +* Newt uses the `--undefined=` option of the linker to force the loader to keep symbols used by +the app (but not used by the linker) * Newt uses objcopy with the `-K` (keep) option when building the special linker `.elf`. * Newt uses the `--just-symbols` option of the linker to link against the loader `.elf` file. #### newt create-image -`create-image` uses two different methods to compute the image hash for standard and split images. For split images, the hash is computed starting with the 32-byte hash of the loader, then continuing with the hashing algorithm used by the standard application. This ensures that the split app can be "validated" against a loader image specifically. +`create-image` uses two different methods to compute the image hash for standard and split images. +For split images, the hash is computed starting with the 32-byte hash of the loader, then continuing +with the hashing algorithm used by the standard application. This ensures that the split app can be "validated" against a loader image specifically. #### newt errors Newt has several new build errors when building split images. -* Linker script undefined. If the BSP for your application does not define a split image linker script the build will fail. +* Linker script undefined. If the BSP for your application does not define a split image linker script +the build will fail. -If newt finds that the same library (for example libs/os) has a different implementaiton in the loader and app, it will generate an error and fail to build. These differences can arise when `#ifdef` or features are included in one app and not the other. For example, it the loader includes `libs/console/stubs` and the app includes `libs/console/full` this may change implementations of certain functions within other packages. +If newt finds that the same library (for example libs/os) has a different implementaiton in the loader +and app, it will generate an error and fail to build. These differences can arise when `#ifdef` or features +are included in one app and not the other. For example, it the loader includes `libs/console/stubs` and the +app includes `libs/console/full` this may change implementations of certain functions within other packages. ### Image manifest @@ -156,15 +195,18 @@ newt builds a single manifest for split images, adding extra tags to the manifes ] ``` -The manifest lists packages in both the loader and app. The app package list only contains those packages that reside in the app image itself. +The manifest lists packages in both the loader and app. The app package list only contains those +packages that reside in the app image itself. ### libs/bootutil -Bootutil has been expanded to include a function that looks for a split app image in slot 2, verifies that it matches the loader image in slot 1 and then fetches the entry information for the split app. +Bootutil has been expanded to include a function that looks for a split app image in slot 2, verifies +that it matches the loader image in slot 1 and then fetches the entry information for the split app. ### libs/split -A small split image library was created to provide newtmgr commands for split image and to hold the configuration for split image. See newtmgr below for details. +A small split image library was created to provide newtmgr commands for split image and to hold the +configuration for split image. See newtmgr below for details. It also contains the function used by a loader to validate and boot a split image. @@ -180,17 +222,23 @@ A sample app that can be built as a split image with slinky. A BSP needs additional components to be "split image ready". -The split image requires a special linker script. The split image needs to run from the second image partition (since it's using the loader library that is linked to be placed in the first partition). It needs to reserve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it). +The split image requires a special linker script. The split image needs to run from the second image +partition (since it's using the loader library that is linked to be placed in the first partition). +It needs to reserve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it). -The startup of the split image is different than a typical image. It needs to copy `.data` from the loader image, and zero the loader image bss. For this, it must reference symbols defined in the linker script of the loader. It has a special entry symbol that differentiates it from the entry symbol in the loader application. +The startup of the split image is different than a typical image. It needs to copy `.data` from the +loader image, and zero the loader image bss. For this, it must reference symbols defined in the linker +script of the loader. It has a special entry symbol that differentiates it from the entry symbol in the +loader application. -Several of the bsp scripts need to handle additional agruments to deal with the two images produced by newt when building split images - mainly download and debug. +Several of the bsp scripts need to handle additional agruments to deal with the two images produced +by newt when building split images - mainly download and debug. Add the following components to enable your BSP for split images: 1. A split image linker file 2. A startup file for the split image -3. A property in the pkg.yml file to tell newt what linker script to use for partition 2 images. The property is defined as `pkg.part2linkerscript: "split-nrf52dk.ld` for example. +3. A property in the pkg.yml file to tell newt what linker script to use for partition 2 images. The property is defined as `pkg.part2linkerscript: "split-nrf52dk.ld` for example. 4. Modified download script 5. Modified sbrk functionality @@ -202,7 +250,7 @@ The split image linker script must have the following. The split linker must be linked to run from the second flash image slot. For example: -``` +```c MEMORY { FLASH (rx) : ORIGIN = 0x00042000, LENGTH = 0x3a000 @@ -212,11 +260,13 @@ MEMORY The split linker must define the entry symbol as Reset_Handler_split. For example: -``` +```c ENTRY(Reset_Handler_split) ``` -The split linker must define the first two words in the vector table (initial SP and Reset Vector). The additional vector entries are part of the loader and are not needed in the split image. The bootloader accesses these entries at the beginning of the image slot (first 2 words). For example: +The split linker must define the first two words in the vector table (initial SP and Reset Vector). The additional +vector entries are part of the loader and are not needed in the split image. The bootloader accesses these +entries at the beginning of the image slot (first 2 words). For example: ``` .text : @@ -224,10 +274,15 @@ The split linker must define the first two words in the vector table (initial SP __split_isr_vector_start = .; KEEP(*(.isr_vector_split)) __split_isr_vector_end = .; - ... + ... + } ``` -The split linker must ensure that it doesn't overwrite the BSS and DATA sections of the loader (they are both using RAM). Note, the two apps don't run at the same time, but the loader has global data that its libraries use. This cannot be overwritten by the application. An example linker section that accomplishes this can be found in `/hw/bsp/nrf52dk/split-nrf52dk.ld`. When linking against the loader, the loader exports the following symbosl which can be used by the split app code: +The split linker must ensure that it doesn't overwrite the BSS and DATA sections of the loader (they are +both using RAM). Note, the two apps don't run at the same time, but the loader has global data that its +libraries use. This cannot be overwritten by the application. An example linker section that accomplishes +this can be found in `/hw/bsp/nrf52dk/split-nrf52dk.ld`. When linking against the loader, the loader exports +the following symbosl which can be used by the split app code: * `__HeapBase_loader` * `__bss_start___loader` @@ -238,7 +293,7 @@ The split linker must ensure that it doesn't overwrite the BSS and DATA sections The split app linker can use `__HeapBase_loader` to skip RAM used by the loader as follows. -``` +```c /* save RAM used by the split image. This assumes that * the loader uses all the RAM up to its HeapBase */ .loader_ram_contents : @@ -253,36 +308,44 @@ The split app linker can use `__HeapBase_loader` to skip RAM used by the loader ### split image startup code -The split application needs separate startup code to intialize the split image before running main. THe split image is specially linked so that _start and main are included individually for the loader and split app. +The split application needs separate startup code to intialize the split image before running main. The +split image is specially linked so that `_start` and `main` are included individually for the loader and split app. The split app startup code must have the following. 1. A definition of the split image vector table (first two words). 2. The entry point function to start the code `Reset_Handler_split` -3. Code that copies the .data section for the loader from Flash to RAM -4. Code that zeros the .bss section for the loader. -5. Code that calls _sbrkInit to set the heap pointers for the application (see below) +3. Code that copies the `.data` section for the loader from Flash to RAM +4. Code that zeros the `.bss` section for the loader. +5. Code that calls `_sbrkInit` to set the heap pointers for the application (see below) 6. Code that calls the `bsp_slot_init_split_application` function (see below) An example can be found in the `/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s` ### Download script -The download script needs to be modified to include support for passing the image slot number in the build. Image slots are referenced as 0 and 1. Loading bootloaders ignore the image slot numbers. +The download script needs to be modified to include support for passing the image slot number in the build. +Image slots are referenced as 0 and 1. Loading bootloaders ignore the image slot numbers. See and example in `/hw/bsp/bmd300eval/bmd300eval_download.sh`. ### Sbrk functionality -Split image (either a loader or app) references a single set of heap managment functions. But the heap location and size is different depending which image is running. Special functionality is needed to handle the dynamic setting of the heap base and limit. +Split image (either a loader or app) references a single set of heap managment functions. But the heap location and +size is different depending which image is running. Special functionality is needed to handle the dynamic +setting of the heap base and limit. -Instead of hard-coding the heap base and limit at link time (depending on the size of data and bss), sbrk needs to be dynamically initialized with these values from the startup code. +Instead of hard-coding the heap base and limit at link time (depending on the size of data and bss), sbrk +needs to be dynamically initialized with these values from the startup code. -See an example in `/hw/bsp/bmd300eval/src/sbrk.c` in the core repository. The function `_sbrkInit` must be called from the startup code of the split image and normal image startup code with the appropriate values of heap base and limit. +See an example in `/hw/bsp/bmd300eval/src/sbrk.c` in the core repository. The function `_sbrkInit` must be +called from the startup code of the split image and normal image startup code with the appropriate +values of heap base and limit. ### Slot Init -A global variable tells mynewt whether the split image is runnning as just a stand-alone loader, or as the combined loader/app image. Its the responsibility of the startup code to set this global variable. +A global variable tells Mynewt whether the split image is runnning as just a stand-alone loader, or as +the combined loader/app image. Its the responsibility of the startup code to set this global variable. See `hw/bsp/bmd300eval/src/os_bsp.c` for and implementation of the functionality. @@ -304,15 +367,19 @@ Images: hash=1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe ``` -The bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the `boot2` command to instruct mynewt to boot slot 2. +The bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the `boot2` +command to instruct mynewt to boot slot 2. -Instead, use the new `split status` command to see the status of split images and to set their boot status. The split status command with no arguments returns status of the split image. The Split Value tells the loader how to boot the split app. Options are: +Instead, use the new `split status` command to see the status of split images and to set their boot status. +The split status command with no arguments returns status of the split image. The Split Value tells the loader +how to boot the split app. Options are: * `none` Don't boot the split application. Just remain running in the loader. * `test` Boot the split application, but revert back to the loader on the next reset. * `run` Boot the split application. -The split status command also verified the hash of the split application (using the hash of the loader as shown above) and returns the status of the check (matching or non-matching). +The split status command also verified the hash of the split application (using the hash of the loader +as shown above) and returns the status of the check (matching or non-matching). ``` newtmgr -c connection split status @@ -320,7 +387,8 @@ newtmgr -c connection split status Split status is matching ``` -When the split image application is running, the active hash in the boot2 command will match the hash of the split application (in slot 2). For example: +When the split image application is running, the active hash in the `boot2` command will match the +hash of the split application (in slot 2). For example: ``` prompt$ newtmgr -c foo1 image boot @@ -333,7 +401,8 @@ prompt$ newtmgr -c foo1 image boot When running via newt, the `newt load` command will load both parts of a split image, the loader and application. -When running via newtmgr a sequence of commands is required to upgrade. Assuming you are running the split app in `run` mode the following sequence will upgrade +When running via newtmgr a sequence of commands is required to upgrade. Assuming you are running the +split app in `run` mode the following sequence will upgrade 1. newtmgr split status none 2. newtmgr reboot
