Google Git
Sign in
apache / mynewt-site / refs/heads/asf-site / . / v1_1_0 / os / modules / shell / shell / index.html
blob: 7f726de1599beb5461b89f1d42fbf53279e30536 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../../../img/favicon.ico">
<title>toc - Apache Mynewt</title>
<link href="../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
<link rel="stylesheet" href="../../../../css/highlight.css">
<link href="../../../../css/base.css" rel="stylesheet">
<link href="../../../../css/custom.css" rel="stylesheet">
<link href="../../../../css/v2.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="toc">
<div class="container">
<div class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.12.0, Apache NimBLE 1.7.0 </a> released (April 4, 2024)
</div>
</div>
</div>
</div>
<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li
class=""
>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li
class="important"
>
<a href="/quick-start/">Quick Start</a>
</li>
<li
class=""
>
<a href="/about/">About</a>
</li>
<li
class=""
>
<a href="/talks/">Talks</a>
</li>
<li
class="active"
>
<a href="/documentation/">Documentation</a>
</li>
<li
class=""
>
<a href="/download/">Download</a>
</li>
<li
class=""
>
<a href="/community/">Community</a>
</li>
<li
class=""
>
<a href="/events/">Events</a>
</li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary">
<div class="top">
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../../search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search documentation" />
</div>
</form>
</div>
</div>
<ul class="toc-nav">
<li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest">
Version: master
</option>
<option value="/v1_12_0/" >
Version: 1.12.0
</option>
<option value="/v1_11_0/" >
Version: 1.11.0
</option>
<option value="/v1_10_0/" >
Version: 1.10.0
</option>
<option value="/v1_9_0/" >
Version: 1.9.0
</option>
<option value="/v1_8_0/" >
Version: 1.8.0
</option>
<option value="/v1_7_0/" >
Version: 1.7.0
</option>
<option value="/v1_6_0/" >
Version: 1.6.0
</option>
<option value="/v1_5_0/" >
Version: 1.5.0
</option>
<option value="/v1_4_0/" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" selected="selected" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select></li>
<li ><a href="../../../introduction/">Mynewt Documentation</a>
<ul>
<li ><a href="../../../get_started/get_started/">Basic Setup</a>
</li>
<li >
<a href="../../../get_started/vocabulary/">Concepts</a>
</li>
<li ><a href="../../../tutorials/tutorials/">Tutorials</a>
</li>
<li ><a href="../../../os_user_guide/">OS User Guide</a>
<ul>
<li ><a href="../../../core_os/mynewt_os/">OS Core</a>
</li>
<li ><a href="../../../core_os/porting/port_os/">Porting to your Platform</a>
</li>
<li ><a href="../../console/console/">Console</a>
</li>
<li class="active"><a href="./">Shell</a>
<ul>
<li><a href="
../shell_cmd_register/
">Functions</a>
</li>
</ul>
</li>
<li ><a href="../../split/split/">Split Images</a>
</li>
<li ><a href="../../bootloader/bootloader/">Bootloader</a>
</li>
<li><a href="
../../fs/fs/fs/
">File System</a>
</li>
<li ><a href="../../hal/hal/">Hardware Abstraction Layer</a>
</li>
<li ><a href="../../sensor_framework/sensor_framework_overview/">Sensor Framework</a>
</li>
<li ><a href="../../drivers/driver/">Drivers</a>
</li>
<li ><a href="../../testutil/testutil/">Test Utilities</a>
</li>
<li ><a href="../../devmgmt/newtmgr/">Device Management with Newt Manager</a>
</li>
<li ><a href="../../imgmgr/imgmgr/">Image Manager</a>
</li>
<li >
<a href="../../baselibc/">Baselibc library</a>
</li>
<li ><a href="../../json/json/">JSON</a>
</li>
<li ><a href="../../fcb/fcb/">Flash Circular Buffer</a>
</li>
<li ><a href="../../stats/stats/">Stats</a>
</li>
<li ><a href="../../logs/logs/">Logs</a>
</li>
<li ><a href="../../sysinitconfig/sysinitconfig/">System Configuration And Initialization</a>
</li>
</ul>
</li>
<li><a href="
../../../../network/ble/ble_intro/
">BLE User Guide</a>
</li>
<li ><a href="../../../../newt/newt_intro/">Newt Tool Guide</a>
</li>
<li ><a href="../../../../newtmgr/overview/">Newt Manager Guide</a>
</li>
<li >
<a href="../../../../known_issues/">Known Issues</a>
</li>
</ul>
</li>
<li><a href="
../../../../faq/go_env/
">Appendix</a>
</li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<div class="doc-header">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; Shell</li>
<li>&raquo; <a href="os/os_user_guide/">OS User Guide</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/mynewt-site/blob/master/docs/os/modules/shell/shell.md"
class="icon icon-github"> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.1.0 is not the most recent version of the Apache Mynewt
documentation. Click <a href="/latest">here</a> to read the latest
version.
</p>
</div>
<h1 id="shell">Shell</h1>
<p>The shell runs above the console and provides two functionalities:</p>
<ul>
<li>Processes console input. See the <a href="/os/tutorials/blinky_console.md">Enabling the Console and Shell tutorial</a> for example of the shell. </li>
<li>Implements the <a href="../../../../newtmgr/overview/">newtmgr</a> line protocol over serial transport. </li>
</ul>
<p>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.</p>
<p>The <code>sys/shell</code> package implements the shell. To use the shell you must:</p>
<ul>
<li>Include the <code>sys/shell</code> package.</li>
<li>Set the <code>SHELL_TASK</code> syscfg setting value to 1 to enable the shell.</li>
</ul>
<p><strong>Note:</strong> The functions for the shell API are only compiled and linked with the application when the <code>SHELL_TASK</code> setting is enabled. When you develop a package that supports shell commands, we recommend that your pakcage define:</p>
<ol>
<li>A syscfg setting that enables shell command processing for your package, with a restriction that when this setting is enabled, the <code>SHELL_TASK</code> setting must also be enabled. </li>
<li>A conditional dependency on the <code>sys/shell</code> package when the setting defined in 1 above is enabled. </li>
</ol>
<p>Here are example definitions from the <code>syscfg.yml</code> and <code>pkg.yml</code> files for the <code>sys/log/full</code> package. It defines the <code>LOG_CLI</code> setting to enable the log command in the shell:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code># sys/log/full syscfg.yml
LOG_CLI:
description: &#39;Expose &quot;log&quot; command in shell.&#39;
value: 0
restrictions:
- SHELL_TASK
# sys/log/full pkg.yml
pkg.deps.LOG_CLI:
- sys/shell
</code></pre></div>
<h2 id="description">Description</h2>
<h3 id="processing-console-input-commands">Processing Console Input Commands</h3>
<p>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. </p>
<h4 id="registering-command-handlers">Registering Command Handlers</h4>
<p>A package that implements a shell command must register a command handler to process the command. </p>
<p><strong>New in release 1.1</strong>: 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 <code>select</code> 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. </p>
<p>There are two methods to register command handlers in Mynewt 1.1:</p>
<ul>
<li>
<p>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 <code>shell_register()</code> function to define a module and register the command handlers for the module. </p>
<p><strong>Note:</strong> The <code>SHELL_MAX_MODULES</code> 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. </p>
</li>
<li>
<p>Method 2: Register a command handler without defining a module. A package calls the <code>shell_cmd_register()</code> 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 <code>compat</code> module. The <code>compat</code> module supports backward compatibility for all the shell commands that are registered using the <code>shell_cmd_register()</code> function.</p>
<p><strong>Notes:</strong> </p>
<ul>
<li>
<p>The <code>SHELL_COMPAT</code> syscfg setting must be set to 1 to enable backward compatibility support and the <code>shell_cmd_register()</code> 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. </p>
</li>
<li>
<p>The <code>SHELL_MAX_COMPAT_COMMANDS</code> 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.</p>
</li>
</ul>
</li>
</ul>
<p><br></p>
<h4 id="enabling-help-information-for-shell-commands">Enabling Help Information for Shell Commands</h4>
<p>The shell supports command help. A package that supports command help initializes the <code>struct shell_cmd</code> data structure with help text for the command before it registers the command with the shell. The <code>SHELL_CMD_HELP</code> syscfg setting enables or disbles help support for all shell commands. The feature is enabled by default.</p>
<p><strong>Note:</strong> A package that implements help for a shell command should only initialize the help data structures within the <code>#if MYNEWT_VAL(SHELL_CMD_HELP)</code> preprocessor directive. </p>
<p><br></p>
<h4 id="enabling-the-os-and-prompt-shell-modules">Enabling the OS and Prompt Shell Modules</h4>
<p>The shell implements the <code>os</code> and <code>prompt</code> modules. These modules support the shell commands to view OS resources. </p>
<p>The <code>os</code> module implements commands to list task and mempool usage information and to view and change the time of day. The <code>SHELL_OS_MODULE</code> syscfg setting enables or disables the module. The module is enabled by default. </p>
<p>The <code>prompt</code> module implements the <code>ticks</code> command that controls whether to print the current os ticks in the prompt. The <code>SHELL_PROMPT_MODULE</code> syscfg setting enables or disables this module. The module is disabled by default. </p>
<p><br></p>
<h4 id="enabling-command-name-completion">Enabling Command Name Completion</h4>
<p>The shell supports command name completion. The <code>SHELL_COMPLETION</code> syscfg setting enables or disables the feature. The feature is enabled by default.</p>
<p><br></p>
<h3 id="processing-newtmgr-line-protocol-over-serial-transport">Processing Newtmgr Line Protocol Over Serial Transport</h3>
<p>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 (<code>mgmt/newtmgr/transport/newtmgr_shell</code>) calls the <code>shell_nlip_input_register()</code> function to register a handler that the shell calls when it receives newtmgr request messages.</p>
<p>The <code>SHELL_NEWTMGR</code> syscfg setting specifies whether newtmgr is enabled over shell. The setting is enabled by default.
<br></p>
<h2 id="data-structures">Data Structures</h2>
<p><br>
The <code>struct shell_cmd</code> data structure represents a shell command and is used to register a command. </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>struct shell_cmd {
const char *sc_cmd;
shell_cmd_func_t sc_cmd_func;
const struct shell_cmd_help *help;
};
</code></pre></div>
<table>
<thead>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>sc_cmd</code></td>
<td>Character string of the command name.</td>
</tr>
<tr>
<td><code>sc_cmd_func_t</code></td>
<td>Pointer to the command handler that processes the command.</td>
</tr>
<tr>
<td><code>help</code></td>
<td>Pointer to the shell_cmd_help structure. If the pointer is NULL, help information is not provided.</td>
</tr>
</tbody>
</table>
<p><br></p>
<p>The <code>sc_cmd_func_t</code> is the command handler function type. </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">typedef</span> <span style="color: #A90D91">int</span> (<span style="color: #000000">*shell_cmd_func_t</span>)(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">*argv</span>[]);
</code></pre></div>
<p>The <code>argc</code> parameter specifies the number of command line arguments and the <code>argv</code> parameter is an array of character pointers to the command arguments. The <code>SHELL_CMD_ARGC_MAX</code> 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 <code>SHELL_CMD_ARGC_MAX</code> number of command line arguments. </p>
<p><br></p>
<p>The <code>struct shell_module</code> data structure represents a shell module. It is used to register a shell module and the shell commands for the module.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">struct</span> <span style="color: #3F6E75">shell_module</span> {
<span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*name</span>;
<span style="color: #A90D91">const</span> <span style="color: #A90D91">struct</span> <span style="color: #3F6E75">shell_cmd</span> <span style="color: #000000">*commands</span>;
};
</code></pre></div>
<table>
<thead>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>Character string of the module name.</td>
</tr>
<tr>
<td><code>commands</code></td>
<td>Array of <code>shell_cmd</code> structures that specify the commands for the module. The <code>sc_cmd</code>, <code>sc_cmd_func</code>, and <code>help</code> fields in the last entry must be set to NULL to indicate the last entry in the array.</td>
</tr>
</tbody>
</table>
<p><strong>Note</strong>: A command handler registered via the <code>shell_cmd_register()</code> function is automatically added to the <code>compat</code> module.</p>
<p><br>
The <code>struct shell_param</code> and <code>struct shell_cmd_help</code> data structures hold help texts for a shell command. </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">struct</span> <span style="color: #3F6E75">shell_param</span> {
<span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*param_name</span>;
<span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*help</span>;
};<span style="color: #000000">`</span>
</code></pre></div>
<table>
<thead>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>param_name</code></td>
<td>Character string of the command parameter name.</td>
</tr>
<tr>
<td><code>help</code></td>
<td>Character string of the help text for the parameter.</td>
</tr>
</tbody>
</table>
<p><br></p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">struct</span> <span style="color: #3F6E75">shell_cmd_help</span> {
<span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*summary</span>;
<span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*usage</span>;
<span style="color: #A90D91">const</span> <span style="color: #A90D91">struct</span> <span style="color: #3F6E75">shell_param</span> <span style="color: #000000">*params</span>;
};
</code></pre></div>
<table>
<thead>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>summary</code></td>
<td>Character string of a short description of the command.</td>
</tr>
<tr>
<td><code>usage</code></td>
<td>Character string of a usage description for the command.</td>
</tr>
<tr>
<td><code>params</code></td>
<td>Array of <code>shell_param</code> structures that describe each parameter for the command. The last <code>struct shell_param</code> in the array must have the <code>param_name</code> and <code>help</code> fields set to NULL to indicate the last entry in the array.</td>
</tr>
</tbody>
</table>
<p><br></p>
<h2 id="list-of-functions">List of Functions</h2>
<p><Comments such as these instructions are placed within angle brackets. List all the functions here. Note how the anchors work. You put the text you want to show up as a link within [] and the relevant #heading within (). Note that the header has to have at least 2 words for the anchor to work - that's how it is. "no-highlight" disables syntax highlighting. You can enable it for a particular language by specifying what the language is instead of "no-highlight". Be warned that this highlighting or no-highlighting specification may not show up nicely on Mou.></p>
<p>The functions available in this OS feature are:</p>
<table>
<thead>
<tr>
<th>Function</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="../shell_cmd_register/">shell_cmd_register</a></td>
<td>Registers a handler for incoming console commands.</td>
</tr>
<tr>
<td><a href="../shell_evq_set/">shell_evq_set</a></td>
<td>Specifies a dedicated event queue for shell events.</td>
</tr>
<tr>
<td><a href="../shell_nlip_input_register/">shell_nlip_input_register</a></td>
<td>Registers a handler for incoming newtmgr messages.</td>
</tr>
<tr>
<td><a href="../shell_nlip_output/">shell_nlip_output</a></td>
<td>Queue outgoing newtmgr message for transmission.</td>
</tr>
<tr>
<td><a href="../shell_register/">shell_register</a></td>
<td>Registers a shell module and the commands for the module.</td>
</tr>
<tr>
<td><a href="../shell_register_app_cmd_handler/">shell_register_app_cmd_handler</a></td>
<td>Registers a command handler as an application handler. The shell calls this handler when a command does not have a handler registered.</td>
</tr>
<tr>
<td><a href="../shell_register_default_module/">shell_register_default_module</a></td>
<td>Registers a module with a specified name as the default module.</td>
</tr>
</tbody>
</table>
<div class="row">
<ul class="nav nav-pills" style="margin-bottom: 10px">
<li>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<a href="https://www.apache.org/">
<img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
</a>
<p>
Copyright © 2015-2021 The Apache Software Foundation.<br>
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt
project logo are either registered trademarks or trademarks of the Apache
Software Foundation in the United States and other countries.
</small>
</p>
<a href="">
<img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
<a href="https://www.apache.org/licenses/">
<button class="button-footer-asf">
License
</button>
</a>
<a href="https://www.apache.org/foundation/sponsorship.html">
<button class="button-footer-asf">
Sponsorship
</button>
</a>
<a href="https://www.apache.org/foundation/thanks.html">
<button class="button-footer-asf">
Thanks
</button>
</a>
<a href="https://www.apache.org/security/">
<button class="button-footer-asf">
Security
</button>
</a>
<a href="https://apache.org/events/current-event">
<button class="button-footer-asf">
ASF Events
</button>
</a>
</footer>
</div>
</div>
</div>
<script src="../../../../js/jquery-1.10.2.min.js"></script>
<script src="../../../../js/bootstrap-3.0.3.min.js"></script>
<script src="../../../../js/highlight.pack.js"></script>
<script src="../../../../js/base.js"></script>
<script src="../../../../js/custom.js"></script>
<script src="search/main.js"></script>
</body>
</html>