[GitHub] michal-narajowski commented on a change in pull request #217: MYNEWT-767 Update OS Guide for New Shell

[gi...@git.apache.org]

michal-narajowski commented on a change in pull request #217: MYNEWT-767 Update OS Guide for New Shell
URL: https://github.com/apache/mynewt-site/pull/217#discussion_r125573529
 
 

 ##########
 File path: docs/os/modules/shell/shell.md
 ##########
 @@ -2,49 +2,171 @@
 
 The shell runs above the console and provides two functionalities:
 
-* Processes console input. See the [Enabling the Console and Shell Tutorial](/os/tutorials/add_shell.md) for an example of the shell.
-* Implements the [newtmgr](../../../newtmgr/overview.md) line protocol over serial transport. 
+* Processes console input.  See the [Enabling the Console and Shell tutorial](/os/tutorials/add_shell.md) for example of the shell. 
+* Implements the [newtmgr](../../../newtmgr/overview.md) line protocol over serial transport.  
 
-The `sys/shell` package implements the shell.  The shell uses the OS default event queue 
-for shell events and runs in the context of the main task. An application can, optionally, 
-specify a dedicated event queue for the shell to use.
+The shell uses the OS default event queue for shell events and runs in the context of the main task. An application can, optionally, specify a dedicated event queue for the shell to use.
 
-###Description
+The `sys/shell` package implements the shell.  To use the shell you must:
 
-* The shell's first job is to direct incoming commands to other subsystems. It parses the incoming character string 
-into tokens and uses the first token to determine the subsystem command handler to call to process the command.
+* Include the `sys/shell` package.
+* Set the `SHELL_TASK` syscfg setting value to 1 to enable the shell.
+  
+**Note:** The functions for the shell API are only compiled and linked with the application when the `SHELL_TASK` setting is enabled. When you develop a package that supports shell commands, we recommend that your pakcage  define:
 
-    * Subsystems register their command handlers using the `shell_cmd_register()` 
-      function.  When shell calls the command handler, it passes the other tokens as arguments.
+1.  A syscfg setting that enables shell command processing for your package, with a restriction that when this setting is enabled, the `SHELL_TASK` setting must also be enabled. 
+2. A conditional dependency on the `sys/shell` package when the setting defined in 1 above is enabled.  
 
-    * A few commands are currently available in the shell - `tasks`, `log`, `echo`, `date` and `prompt`.
+Here are example definitions from the `syscfg.yml` and `pkg.yml` files for the `sys/log/full` package. It defines the `LOG_CLI` setting to enable the log command in the shell:
+
+```no-highlight
+# sys/log/full syscfg.yml
+ LOG_CLI:
+        description: 'Expose "log" command in shell.'
+        value: 0
+        restrictions:
+            - SHELL_TASK
+
+# sys/log/full pkg.yml
+pkg.deps.LOG_CLI:
+    - sys/shell
+
+```
+
+##Description
+
+### Processing Console Input Commands
+The shell's first job is to direct incoming commands to other subsystems. It parses the incoming character string into tokens and uses the first token to determine the subsystem  command handler to call to process the command. When the shell calls the command handler, it passes the other tokens as arguments to the handler.  
+
+#### Registering Command Handlers
+
+A package that implements a shell command must register a command handler to process the command. 
+
+**New in release 1.1**: The shell supports the concept of modules and allows a package to group shell commands under a name space. To run a command in the shell, you enter the module name and the command name. You can set a default module, using the `select` command, so that you only need to enter the command name to run a command from the default module. You can switch the module you designate as the default module. 
+
+There are two methods to register command handlers in Mynewt 1.1:
+
+* Method 1 (New in release 1.1): Define and register a set of commands for a module. This method allows grouping shell commands into namespaces. A package calls the `shell_register()` function to define a module and register the command handlers for the module.  
+
+	**Note:** The `SHELL_MAX_MODULES` syscfg setting specifies the maximum number of modules that can be registered. You can increase this value if your application and the packages it includes register more than the default value. 
+
+* Method 2: Register a command handler without defining a module. A package calls the `shell_cmd_register()` function defined in Mynewt 1.0 to register a command handler.  When a shell command is registered using this method, the command is automatically added to the `compat` module. The `compat` module supports backwards compatibility for all the shell commands that are registered using the `shell_cmd_register()` function.
+
+	**Notes:** 
+
+	* The `SHELL_COMPAT` syscfg setting must be set to 1 to enable backwards compatibility support and the `shell_cmd_register()` function.  Since Mynewt packages use method 2 to register shell commands and Mynewt plans to continue this support in future releases, you must keep the default setting value of 1. 
+
+  	* The `SHELL_MAX_COMPAT_COMMANDS` syscfg setting specifies the maximum number of command handlers that can be registered using this method. You can increase this value if your application and the packages it includes register more than the default value.
 
-* The shell's second job is to handle packet framing, encoding, and decoding of newtmgr protocol messages that are
-sent over the console.  The Newtmgr serial transport package (`mgmt/newtmgr/transport/newtmgr_shell`) 
-calls the `shell_nlip_input_register()` function to register a handler that the shell calls when it 
-receives newtmgr request messages.
 
 <br>
+####Enabling Help Information for Shell Commands
 
-###Data structures
+The shell supports command help. A package that supports command help initializes the `struct shell_cmd` data structure with help text for the command before it registers the command with the shell. The `SHELL_CMD_HELP` syscfg setting enables or disbles help support for all shell commands. The feature is enabled by default.
 
-This data structure is used in holding information about registered command handlers.
+**Note:** A package that implements help for a shell command should only initialize the help data structures within the `#if MYNEWT_VAL(SHELL_CMD_HELP)` preprocessor directive.  
+
+<br>
+
+#### Enabling the OS and Prompt Shell Modules
+The shell implements the `os` and `prompt` modules. These modules support the shell commands to view OS resources.  
+
+The `os` module implements commands to list task and mempool usage information and to view and change the time of day. The `SHELL_OS_MODULE` syscfg setting enables or disables the module. The module is enabled by default. 
+
+
+The `prompt` module implements the `ticks` command that controls whether to print the current os ticks in the prompt. The `SHELL_PROMPT_MODULE` syscfg setting enables or disables this module. The module is disabled by default. 
+
+<br>
+#### Enabling Command Name Completion
+
+The shell supports command name completion. The `SHELL_COMPLETION` syscfg setting enables or disables the feature. The feature is enabled by default.
+
+<br>
+### Processing Newtmgr Line Protocol Over Serial Transport
+
+The shell's second job is to handle packet framing, encoding, and decoding of newtmgr protocol messages that are sent over the console. The Newtmgr serial transport package (`mgmt/newtmgr/transport/newtmgr_shell`) calls the `shell_nlip_input_register()` function to register a handler that the shell calls when it receives newtmgr request messages.
+
+<br>
+
+##Data Structures
+<br>
+The `struct shell_cmd` data structure represents a shell command and is used to register a command. 
 
 ```c
 struct shell_cmd {
-    char *sc_cmd;
+    const char *sc_cmd;
     shell_cmd_func_t sc_cmd_func;
-    STAILQ_ENTRY(shell_cmd) sc_next;
+    const struct shell_cmd_help *help;
+};
+```
+
+| Element | Description |
+|---------|-------------|
+| `sc_cmd` | Character string of the command name. |
+| `sc_cmd_func_t` | Pointer to the command handler that processes the command.| 
+| `help` | Pointer to the shell_cmd_help structure. If the pointer is NULL, help information is not provided.|
+
+<br>
+
+The `sc_cmd_func_t` is the command handler function type. 
+
+```c
+typedef int (*shell_cmd_func_t)(int argc, char *argv[]);
+```
+
+The `argc` parameter specifies the number of command line arguments and the `argv` parameter is an array of character pointers to the command arguments.  The `SHELL_CMD_ARGC_MAX` syscfg setting specifies the maximum number of command line arguments that any shell command can have. This value must be increased if a shell command requires more than `SHELL_CMD_MAX_ARGC_MAX` number of command line arguments. 
 
 Review comment:
   `SHELL_CMD_MAX_ARGC_MAX` I believe this is a typo
 
----------------------------------------------------------------
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:
users@infra.apache.org


With regards,
Apache Git Services