| <!-- |
| Documentation/_templates/layout.html |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. The |
| ASF licenses this file to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance with the |
| License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| License for the specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| |
| |
| <!DOCTYPE html> |
| <html class="writer-html5" lang="en" > |
| <head> |
| <meta charset="utf-8"> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| <title>SYSLOG — NuttX latest documentation</title> |
| |
| |
| |
| <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> |
| <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> |
| <link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/segment.min.css" type="text/css" /> |
| <link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/menu.min.css" type="text/css" /> |
| <link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/tab.min.css" type="text/css" /> |
| <link rel="stylesheet" href="../_static/sphinx_tabs/tabs.css" type="text/css" /> |
| <link rel="stylesheet" href="../_static/custom.css" type="text/css" /> |
| |
| |
| |
| <link rel="shortcut icon" href="../_static/favicon.ico"/> |
| |
| |
| |
| |
| |
| <!--[if lt IE 9]> |
| <script src="../_static/js/html5shiv.min.js"></script> |
| <![endif]--> |
| |
| |
| <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> |
| <script src="../_static/jquery.js"></script> |
| <script src="../_static/underscore.js"></script> |
| <script src="../_static/doctools.js"></script> |
| <script src="../_static/language_data.js"></script> |
| |
| <script type="text/javascript" src="../_static/js/theme.js"></script> |
| |
| |
| <link rel="index" title="Index" href="../genindex.html" /> |
| <link rel="search" title="Search" href="../search.html" /> |
| <link rel="next" title="Binary Loader" href="binfmt.html" /> |
| <link rel="prev" title="SocketCAN Device Drivers" href="socketcan.html" /> |
| </head> |
| |
| <body class="wy-body-for-nav"> |
| |
| |
| <div class="wy-grid-for-nav"> |
| |
| <nav data-toggle="wy-nav-shift" class="wy-nav-side"> |
| <div class="wy-side-scroll"> |
| <div class="wy-side-nav-search" > |
| |
| |
| <a href="../index.html" class="icon icon-home"> NuttX |
| |
| |
| |
| |
| <img src="../_static/NuttX.png" class="logo" alt="Logo"/> |
| |
| </a> |
| |
| <!-- this version selector is quite ugly, should be probably replaced by something |
| more modern --> |
| |
| <div class="version-selector"> |
| <select onchange="javascript:location.href = this.value;"> |
| |
| <option value="../../latest" selected="selected">latest</option> |
| |
| <option value="../../10.0.0" >10.0.0</option> |
| |
| <option value="../../10.0.1" >10.0.1</option> |
| |
| <option value="../../10.1.0" >10.1.0</option> |
| |
| <option value="../../10.2.0" >10.2.0</option> |
| |
| <option value="../../10.3.0" >10.3.0</option> |
| |
| <option value="../../11.0.0" >11.0.0</option> |
| |
| <option value="../../12.0.0" >12.0.0</option> |
| |
| <option value="../../12.1.0" >12.1.0</option> |
| |
| <option value="../../12.2.0" >12.2.0</option> |
| |
| <option value="../../12.2.1" >12.2.1</option> |
| |
| <option value="../../12.3.0" >12.3.0</option> |
| |
| <option value="../../12.4.0" >12.4.0</option> |
| |
| <option value="../../12.5.0" >12.5.0</option> |
| |
| <option value="../../12.5.1" >12.5.1</option> |
| |
| <option value="../../12.6.0" >12.6.0</option> |
| |
| <option value="../../12.7.0" >12.7.0</option> |
| |
| <option value="../../12.8.0" >12.8.0</option> |
| |
| <option value="../../12.9.0" >12.9.0</option> |
| |
| <option value="../../12.10.0" >12.10.0</option> |
| |
| <option value="../../12.11.0" >12.11.0</option> |
| |
| </select> |
| </div> |
| |
| |
| <div role="search"> |
| <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> |
| <input type="text" name="q" placeholder="Search docs" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| |
| </div> |
| |
| |
| <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> |
| |
| |
| |
| |
| |
| |
| <p class="caption"><span class="caption-text">Table of Contents</span></p> |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="../index.html">Home</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../introduction/index.html">Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Getting Started</a></li> |
| <li class="toctree-l1 current"><a class="reference internal" href="index.html">OS Components</a><ul class="current"> |
| <li class="toctree-l2"><a class="reference internal" href="nsh/index.html">NuttShell (NSH)</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="power.html">Power Management</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="socketcan.html">SocketCAN Device Drivers</a></li> |
| <li class="toctree-l2 current"><a class="current reference internal" href="#">SYSLOG</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#syslog-interfaces">SYSLOG Interfaces</a><ul> |
| <li class="toctree-l4"><a class="reference internal" href="#standard-syslog-interfaces">Standard SYSLOG Interfaces</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#debug-interfaces">Debug Interfaces</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l3"><a class="reference internal" href="#syslog-channels">SYSLOG Channels</a><ul> |
| <li class="toctree-l4"><a class="reference internal" href="#syslog-channel-interfaces">SYSLOG Channel Interfaces</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#syslog-channel-initialization">SYSLOG Channel Initialization</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#interrupt-level-syslog-output">Interrupt Level SYSLOG Output</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l3"><a class="reference internal" href="#syslog-channel-options">SYSLOG Channel Options</a><ul> |
| <li class="toctree-l4"><a class="reference internal" href="#syslog-console-device">SYSLOG Console Device</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#syslog-character-device">SYSLOG Character Device</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#syslog-file-device">SYSLOG File Device</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#syslog-ramlog-device">SYSLOG RAMLOG Device</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l3"><a class="reference internal" href="#ram-logging-device">RAM Logging Device</a><ul> |
| <li class="toctree-l4"><a class="reference internal" href="#dmesg-command"><code class="docutils literal notranslate"><span class="pre">dmesg</span></code> command</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#ramlog-configuration-options">RAMLOG Configuration options</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="binfmt.html">Binary Loader</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="drivers/index.html">Device Drivers</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="filesystem.html">NuttX File System</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="nxflat.html">NXFLAT</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="nxgraphics/index.html">NX Graphics Subsystem</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="nxwidgets.html">NxWidgets</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="paging.html">On-Demand Paging</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../applications/index.html">Applications</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../boards/index.html">Supported Boards</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API Reference</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../guides/index.html">Guides</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../releases/index.html">Releases</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../contributing/index.html">Contributing</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> |
| </ul> |
| |
| |
| |
| </div> |
| |
| </div> |
| </nav> |
| |
| <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> |
| |
| |
| <nav class="wy-nav-top" aria-label="top navigation"> |
| |
| <i data-toggle="wy-nav-top" class="fa fa-bars"></i> |
| <a href="../index.html">NuttX</a> |
| |
| </nav> |
| |
| |
| <div class="wy-nav-content"> |
| |
| <div class="rst-content"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div role="navigation" aria-label="breadcrumbs navigation"> |
| |
| <ul class="wy-breadcrumbs"> |
| |
| <li><a href="../index.html" class="icon icon-home"></a> »</li> |
| |
| <li><a href="index.html">OS Components</a> »</li> |
| |
| <li>SYSLOG</li> |
| |
| |
| <li class="wy-breadcrumbs-aside"> |
| |
| |
| <a href="../_sources/components/syslog.rst.txt" rel="nofollow"> View page source</a> |
| |
| |
| </li> |
| |
| </ul> |
| |
| |
| <hr/> |
| </div> |
| <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> |
| <div itemprop="articleBody"> |
| |
| <div class="section" id="syslog"> |
| <h1>SYSLOG<a class="headerlink" href="#syslog" title="Permalink to this headline">¶</a></h1> |
| <div class="section" id="syslog-interfaces"> |
| <h2>SYSLOG Interfaces<a class="headerlink" href="#syslog-interfaces" title="Permalink to this headline">¶</a></h2> |
| <div class="section" id="standard-syslog-interfaces"> |
| <h3>Standard SYSLOG Interfaces<a class="headerlink" href="#standard-syslog-interfaces" title="Permalink to this headline">¶</a></h3> |
| <p>The NuttX SYSLOG is an architecture for getting debug and status |
| information from the system. The syslogging interfaces are defined |
| in the header file <code class="docutils literal notranslate"><span class="pre">include/syslog.h</span></code>. The primary interface to |
| SYSLOG sub-system is the function <code class="docutils literal notranslate"><span class="pre">syslog()</span></code> and, to a lesser |
| extent, its companion <code class="docutils literal notranslate"><span class="pre">vsyslog()</span></code>:</p> |
| <p>The above are all standard interfaces as defined at |
| <a class="reference external" href="http://pubs.opengroup.org/onlinepubs/009695399/functions/closelog.html">OpenGroup.org</a>. |
| Those interfaces are available for use by application software. |
| The remaining interfaces discussed in this section are non-standard, OS-internal interfaces.</p> |
| </div> |
| <div class="section" id="debug-interfaces"> |
| <h3>Debug Interfaces<a class="headerlink" href="#debug-interfaces" title="Permalink to this headline">¶</a></h3> |
| <p>In NuttX, syslog output is really synonymous to debug output and, |
| therefore, the debugging interface macros defined in the header |
| file <code class="docutils literal notranslate"><span class="pre">include/debug.h</span></code> are also syslogging interfaces. Those |
| macros are simply wrappers around <code class="docutils literal notranslate"><span class="pre">syslog()</span></code>. The debugging |
| interfaces differ from the syslog interfaces in that:</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p>They do not take a priority parameter; the priority is inherent |
| in the debug macro name.</p></li> |
| <li><p>They decorate the output stream with information such as the |
| file name</p></li> |
| <li><p>They can each be disabled via configuration options.</p></li> |
| </ul> |
| </div></blockquote> |
| <p>Each debug macro has a base name that represents the priority and |
| a prefix that represents the sub-system. Each macro is |
| individually initialized by both priority and sub-system. For |
| example, <code class="docutils literal notranslate"><span class="pre">uerr()</span></code> is the macro used for error level messages |
| from the USB subsystem and is enabled with |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_USB_ERROR</span></code>.</p> |
| <p>The base debug macro names, their priority, and configuration |
| variable are summarized below:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">info()</span></code>. The <code class="docutils literal notranslate"><span class="pre">info()</span></code> macro is the lowest priority |
| (<code class="docutils literal notranslate"><span class="pre">LOG_INFO</span></code>) and is intended to provide general information |
| about the flow of program execution so that you can get an |
| overview of the behavior of the program. <code class="docutils literal notranslate"><span class="pre">info()</span></code> is often |
| very chatty and voluminous and usually more information than |
| you may want to see. The <code class="docutils literal notranslate"><span class="pre">info()</span></code> macro is controlled via |
| CONFIG_DEBUG_subsystem_INFO</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">warn()</span></code>. The <code class="docutils literal notranslate"><span class="pre">warn()</span></code> macro has medium priority |
| (<code class="docutils literal notranslate"><span class="pre">LOG_WARN</span></code>) and is controlled by |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_subsystem_WARN</span></code>. The <code class="docutils literal notranslate"><span class="pre">warn()</span></code> is intended to |
| note exceptional or unexpected conditions that might be |
| potential errors or, perhaps, minor errors that easily |
| recovered.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">err()</span></code>. This is a high priority debug macro (<code class="docutils literal notranslate"><span class="pre">LOG_ERROR</span></code>) |
| and controlled by <code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_subsystem_ERROR</span></code>. The |
| <code class="docutils literal notranslate"><span class="pre">err()</span></code> is reserved to indicate important error conditions.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">alert()</span></code>. The highest priority debug macro (<code class="docutils literal notranslate"><span class="pre">LOG_EMERG</span></code>) |
| and is controlled by <code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_ALERT</span></code>. The <code class="docutils literal notranslate"><span class="pre">alert()</span></code> |
| macro is reserved for use solely by assertion and crash |
| handling logic. It also differs from the other macros in that |
| it cannot be enabled or disabled per subsystem.</p></li> |
| </ul> |
| </div> |
| </div> |
| <div class="section" id="syslog-channels"> |
| <h2>SYSLOG Channels<a class="headerlink" href="#syslog-channels" title="Permalink to this headline">¶</a></h2> |
| <div class="section" id="syslog-channel-interfaces"> |
| <h3>SYSLOG Channel Interfaces<a class="headerlink" href="#syslog-channel-interfaces" title="Permalink to this headline">¶</a></h3> |
| <p>In the NuttX SYSLOG implementation, the underlying device logic |
| the supports the SYSLOG output is referred to as a SYSLOG |
| <em>channel</em>. Each SYSLOG channel is represented by an interface |
| defined in <code class="docutils literal notranslate"><span class="pre">include/nuttx/syslog/syslog.h</span></code>:</p> |
| <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* This structure provides the interface to a SYSLOG device */</span> |
| |
| <span class="k">typedef</span> <span class="n">CODE</span> <span class="nf">int</span> <span class="p">(</span><span class="o">*</span><span class="n">syslog_putc_t</span><span class="p">)(</span><span class="kt">int</span> <span class="n">ch</span><span class="p">);</span> |
| <span class="k">typedef</span> <span class="n">CODE</span> <span class="nf">int</span> <span class="p">(</span><span class="o">*</span><span class="n">syslog_flush_t</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span> |
| |
| <span class="k">struct</span> <span class="n">syslog_channel_s</span> |
| <span class="p">{</span> |
| <span class="cm">/* I/O redirection methods */</span> |
| |
| <span class="n">syslog_putc_t</span> <span class="n">sc_putc</span><span class="p">;</span> <span class="cm">/* Normal buffered output */</span> |
| <span class="n">syslog_putc_t</span> <span class="n">sc_force</span><span class="p">;</span> <span class="cm">/* Low-level output for interrupt handlers */</span> |
| <span class="n">syslog_flush_t</span> <span class="n">sc_flush</span><span class="p">;</span> <span class="cm">/* Flush buffered output (on crash) */</span> |
| |
| <span class="cm">/* Implementation specific logic may follow */</span> |
| <span class="p">};</span> |
| </pre></div> |
| </div> |
| <p>The channel interface is instantiated by calling |
| <a class="reference internal" href="#c.syslog_channel" title="syslog_channel"><code class="xref c c-func docutils literal notranslate"><span class="pre">syslog_channel()</span></code></a>.</p> |
| <dl class="c function"> |
| <dt id="c.syslog_channel"> |
| int <code class="sig-name descname">syslog_channel</code><span class="sig-paren">(</span>FAR <em class="property">const</em> <em class="property">struct</em> syslog_channel_s *<em>channel</em><span class="sig-paren">)</span>;<a class="headerlink" href="#c.syslog_channel" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Configure the SYSLOG function to use the provided |
| channel to generate SYSLOG output.</p> |
| <p><code class="docutils literal notranslate"><span class="pre">syslog_channel()</span></code> is a non-standard, internal OS interface and |
| is not available to applications. It may be called numerous times |
| as necessary to change channel interfaces. By default, all system |
| log output goes to console (<code class="docutils literal notranslate"><span class="pre">/dev/console</span></code>).</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters</dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>channel</strong> – Describes the interface to the channel to be used.</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns</dt> |
| <dd class="field-even"><p>Zero (OK)is returned on success. A negated errno value is |
| returned on any failure.</p> |
| </dd> |
| </dl> |
| </dd></dl> |
| |
| </div> |
| <div class="section" id="syslog-channel-initialization"> |
| <h3>SYSLOG Channel Initialization<a class="headerlink" href="#syslog-channel-initialization" title="Permalink to this headline">¶</a></h3> |
| <p>The initial, default SYSLOG channel is established with statically |
| initialized global variables so that some level of SYSLOG output |
| may be available immediately upon reset. This initialized data is |
| in the file <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_channel.c</span></code>. The initial |
| SYSLOG capability is determined by the selected SYSLOG channel:</p> |
| <ul class="simple"> |
| <li><p><em>In-Memory Buffer (RAMLOG)</em>. Full SYSLOG capability as |
| available at reset.</p></li> |
| <li><p><em>Serial Console</em>. If the serial implementation provides the |
| low-level character output function <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code>, then that |
| low level serial output is available as soon as the serial |
| device has been configured.</p></li> |
| <li><p>For all other SYSLOG channels, all SYSLOG output goes to the |
| bit- bucket until the SYSLOG channel device has been |
| initialized.</p></li> |
| </ul> |
| <p>The syslog channel device is initialized when the bring-up logic |
| calls <a class="reference internal" href="#c.syslog_initialize" title="syslog_initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">syslog_initialize()</span></code></a>.</p> |
| <dl class="c function"> |
| <dt id="c.syslog_initialize"> |
| int <code class="sig-name descname">syslog_initialize</code><span class="sig-paren">(</span>void<span class="sig-paren">)</span><a class="headerlink" href="#c.syslog_initialize" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><nuttx/syslog/syslog.h></span><span class="cp"></span> |
| <span class="cp">#ifndef CONFIG_ARCH_SYSLOG</span> |
| <span class="kt">int</span> <span class="nf">syslog_initialize</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span> |
| <span class="cp">#else</span> |
| <span class="cp"># define syslog_initialize()</span> |
| <span class="cp">#endif</span> |
| </pre></div> |
| </div> |
| <p>One power up, the SYSLOG facility is non-existent |
| or limited to very low-level output. This function is called later |
| in the initialization sequence after full driver support has been |
| initialized. It installs the configured SYSLOG drivers and enables |
| full SYSLOG capability.</p> |
| <p>This function performs these basic operations:</p> |
| <ul class="simple"> |
| <li><p>Initialize the SYSLOG device</p></li> |
| <li><p>Call <a class="reference internal" href="#c.syslog_channel" title="syslog_channel"><code class="xref c c-func docutils literal notranslate"><span class="pre">syslog_channel()</span></code></a> to begin using that device.</p></li> |
| <li><p>If <code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_SYSLOG</span></code> is selected, then the |
| architecture-specific logic will provide its own SYSLOG device |
| initialize which must include as a minimum a call to |
| <a class="reference internal" href="#c.syslog_channel" title="syslog_channel"><code class="xref c c-func docutils literal notranslate"><span class="pre">syslog_channel()</span></code></a> to use the device.</p></li> |
| </ul> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Returns</dt> |
| <dd class="field-odd"><p>Zero (<code class="docutils literal notranslate"><span class="pre">OK</span></code>) is returned on success; a |
| negated <code class="docutils literal notranslate"><span class="pre">errno</span></code> value is returned on any failure.</p> |
| </dd> |
| </dl> |
| </dd></dl> |
| |
| <p>Different types of SYSLOG devices have different OS initialization |
| requirements. Some are available immediately at reset, some are |
| available after some basic OS initialization, and some only after |
| OS is fully initialized.</p> |
| <p>There are other types of SYSLOG channel devices that may require |
| even further initialization. For example, the file SYSLOG channel |
| (described below) cannot be initialized until the necessary file |
| systems have been mounted.</p> |
| </div> |
| <div class="section" id="interrupt-level-syslog-output"> |
| <h3>Interrupt Level SYSLOG Output<a class="headerlink" href="#interrupt-level-syslog-output" title="Permalink to this headline">¶</a></h3> |
| <p>As a general statement, SYSLOG output only supports <em>normal</em> |
| output from NuttX tasks. However, for debugging purposes, it is |
| also useful to get SYSLOG output from interrupt level logic. In an |
| embedded system, that is often where the most critical operations |
| are performed.</p> |
| <p>There are three conditions under which SYSLOG output generated |
| from interrupt level processing can a included the SYSLOG output |
| stream:</p> |
| <blockquote> |
| <div><ol class="arabic"> |
| <li><p><strong>Low-Level Serial Output</strong>. If you are using a SYSLOG console |
| channel (<code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_CONSOLE</span></code>) and if the underlying |
| architecture supports the low-level <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> |
| interface(<code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_LOWPUTC</span></code>), then the SYSLOG logic |
| will direct the output to <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> which is capable of |
| generating the serial output within the context of an interrupt |
| handler.</p> |
| <p>There are a few issues in doing this however:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> is able to generate debug output in any |
| context because it disables serial interrupts and polls the |
| hardware directly. These polls may take many milliseconds |
| and during that time, all interrupts are disable within the |
| interrupt handler. This, of course, interferes with the |
| real-time behavior of the RTOS.</p></li> |
| <li><p>The output generated by <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> is immediate and in |
| real-time. The normal SYSLOG output, on the other hand, is |
| buffered in the serial driver and may be delayed with |
| respect to the immediate output by many lines. Therefore, |
| the interrupt level SYSLOG output provided through |
| <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> is grossly out of synchronization with other |
| debug output</p></li> |
| </ul> |
| </li> |
| <li><p><strong>In-Memory Buffering</strong>. If the RAMLOG SYSLOG channel is |
| supported, then all SYSLOG output is buffered in memory. |
| Interrupt level SYSLOG output is no different than normal |
| SYSLOG output in this case.</p></li> |
| <li><p><strong>Serialization Buffer</strong>. A final option is the use of an |
| <em>interrupt buffer</em> to buffer the interrupt level SYSLOG output. |
| In this case:</p> |
| <ul class="simple"> |
| <li><p>SYSLOG output generated from interrupt level process in not |
| sent to the SYSLOG channel immediately. Rather, it is |
| buffered in the interrupt serialization buffer.</p></li> |
| <li><p>Later, when the next normal syslog output is generated, it |
| will first empty the content of the interrupt buffer to the |
| SYSLOG device in the proper context. It will then be |
| followed by the normal syslog output. In this case, the |
| interrupt level SYSLOG output will interrupt the normal |
| output stream and the interrupt level SYSLOG output will be |
| inserted into the correct position in the SYSLOG output when |
| the next normal SYSLOG output is generated.</p></li> |
| </ul> |
| </li> |
| </ol> |
| </div></blockquote> |
| <p>The SYSLOG interrupt buffer is enabled with |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_INTBUFFER</span></code>. When the interrupt buffer is |
| enabled, you must also provide the size of the interrupt buffer |
| with <code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_INTBUFSIZE</span></code>.</p> |
| </div> |
| </div> |
| <div class="section" id="syslog-channel-options"> |
| <h2>SYSLOG Channel Options<a class="headerlink" href="#syslog-channel-options" title="Permalink to this headline">¶</a></h2> |
| <div class="section" id="syslog-console-device"> |
| <h3>SYSLOG Console Device<a class="headerlink" href="#syslog-console-device" title="Permalink to this headline">¶</a></h3> |
| <p>The typical SYSLOG device is the system console. If you are using |
| a serial console, for example, then the SYSLOG output will appear |
| on that serial port.</p> |
| <p>This SYSLOG channel is automatically selected by |
| <code class="docutils literal notranslate"><span class="pre">syslog_initialize()</span></code> in the LATE initialization phase based on |
| configuration options. The configuration options that affect this |
| channel selection include:</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_DEV_CONSOLE</span></code>. This setting indicates that the system |
| supports a console device, i.e., that the character device |
| <code class="docutils literal notranslate"><span class="pre">/dev/console</span></code> exists.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SERIAL_CONSOLE</span></code>. This configuration option is |
| automatically selected when a UART or USART is configured as |
| the system console. There is no user selection.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_CONSOLE</span></code>. This configuration option is |
| manually selected from the SYSLOG menu. This is the option that |
| actually enables the SYSLOG console device. It depends on |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_DEV_CONSOLE</span></code>.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_LOWPUTC</span></code>. This is an indication from the |
| architecture configuration that the platform supports the |
| <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> interface. <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> is a very low level UART |
| interface that can even be used from interrupt handling.</p></li> |
| </ul> |
| </div></blockquote> |
| <p>Interrupt level SYSLOG output will be lost unless: (1) the |
| interrupt buffer is enabled to support serialization, or (2) a |
| serial console is used and <code class="docutils literal notranslate"><span class="pre">up_putc()</span></code> is supported.</p> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>The console channel uses the fixed character device at |
| <code class="docutils literal notranslate"><span class="pre">/dev/console</span></code>. The console channel is not synonymous with |
| <code class="docutils literal notranslate"><span class="pre">stdout</span></code> (or file descriptor 1). <code class="docutils literal notranslate"><span class="pre">stdout</span></code> is the current |
| output from a task when, say, <code class="docutils literal notranslate"><span class="pre">printf()</span></code> if used. Initially, |
| <code class="docutils literal notranslate"><span class="pre">stdout</span></code> does, indeed, use the <code class="docutils literal notranslate"><span class="pre">/dev/console</span></code> device. However, |
| <code class="docutils literal notranslate"><span class="pre">stdout</span></code> may subsequently be redirected to some other device or |
| file. This is always the case, for example, when a transient |
| device is used for a console – such as a USB console or a Telnet |
| console. The SYSLOG channel is not redirected as <code class="docutils literal notranslate"><span class="pre">stdout</span></code> is; |
| the SYSLOG channel will stayed fixed (unless it is explicitly |
| changed via <code class="docutils literal notranslate"><span class="pre">syslog_channel()</span></code>).</p> |
| </div> |
| <p>References: <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_consolechannel.c</span></code> and |
| <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_device.c</span></code></p> |
| </div> |
| <div class="section" id="syslog-character-device"> |
| <h3>SYSLOG Character Device<a class="headerlink" href="#syslog-character-device" title="Permalink to this headline">¶</a></h3> |
| <p>The system console device, <code class="docutils literal notranslate"><span class="pre">/dev/console</span></code>, is a character driver |
| with some special properties. However, any character driver may be |
| used as the SYSLOG output channel. For example, suppose you have a |
| serial console on <code class="docutils literal notranslate"><span class="pre">/dev/ttyS0</span></code> and you want SYSLOG output on |
| <code class="docutils literal notranslate"><span class="pre">/dev/ttyS1</span></code>. Or suppose you support only a Telnet console but |
| want to capture debug output <code class="docutils literal notranslate"><span class="pre">/dev/ttyS0</span></code>.</p> |
| <p>This SYSLOG device channel is selected with <code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_CHAR</span></code> |
| and has no other dependencies. Differences from the SYSLOG console |
| channel include:</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_DEVPATH</span></code>. This configuration option string |
| must be set provide the full path to the character device to be |
| used.</p></li> |
| <li><p>The forced SYSLOG output always goes to the bit-bucket. This |
| means that interrupt level SYSLOG output will be lost unless |
| the interrupt buffer is enabled to support serialization.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_CHAR_CRLF</span></code>. If <code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_CHAR_CRLF</span></code> is |
| selected, then linefeeds in the SYSLOG output will be expanded |
| to Carriage Return plus Linefeed. Since the character device is |
| not a console device, the addition of carriage returns to line |
| feeds would not be performed otherwise. You would probably want |
| this expansion if you use a serial terminal program with the |
| character device output.</p></li> |
| </ul> |
| </div></blockquote> |
| <p>References: <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_devchannel.c</span></code> and |
| <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_device.c</span></code></p> |
| </div> |
| <div class="section" id="syslog-file-device"> |
| <h3>SYSLOG File Device<a class="headerlink" href="#syslog-file-device" title="Permalink to this headline">¶</a></h3> |
| <p>Files can also be used as the sink for SYSLOG output. There is, |
| however, a very fundamental difference in using a file as opposed |
| the system console, a RAM buffer, or character device: You must |
| first mount the file system that supports the SYSLOG file. That |
| difference means that the file SYSLOG channel cannot be supported |
| during the boot-up phase but can be instantiated later when board |
| level logic configures the application environment, including |
| mounting of the file systems.</p> |
| <p>The interface <code class="docutils literal notranslate"><span class="pre">syslog_file_channel()</span></code> is used to configure the |
| SYSLOG file channel:</p> |
| <dl class="c function"> |
| <dt id="c.syslog_file_channel"> |
| int <code class="sig-name descname">syslog_file_channel</code><span class="sig-paren">(</span>FAR <em class="property">const</em> char *<em>devpath</em><span class="sig-paren">)</span>;<a class="headerlink" href="#c.syslog_file_channel" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Configure to use a file in a mounted file system |
| at <code class="docutils literal notranslate"><span class="pre">devpath</span></code> as the SYSLOG channel.</p> |
| <p>This tiny function is simply a wrapper around |
| <code class="docutils literal notranslate"><span class="pre">syslog_dev_initialize()</span></code> and <code class="docutils literal notranslate"><span class="pre">syslog_channel()</span></code>. It calls |
| <code class="docutils literal notranslate"><span class="pre">syslog_dev_initialize()</span></code> to configure the character file at |
| <code class="docutils literal notranslate"><span class="pre">devpath</span></code> then calls <code class="docutils literal notranslate"><span class="pre">syslog_channel()</span></code> to use that device as |
| the SYSLOG output channel.</p> |
| <p>File SYSLOG channels differ from other SYSLOG channels in that |
| they cannot be established until after fully booting and mounting |
| the target file system. This function would need to be called from |
| board-specific bring-up logic AFTER mounting the file system |
| containing <code class="docutils literal notranslate"><span class="pre">devpath</span></code>.</p> |
| <p>SYSLOG data generated prior to calling <code class="docutils literal notranslate"><span class="pre">syslog_file_channel()</span></code> |
| will, of course, not be included in the file.</p> |
| <p>NOTE interrupt level SYSLOG output will be lost in this case |
| unless the interrupt buffer is used.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters</dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>devpath</strong> – The full path to the file to be used for SYSLOG |
| output. This may be an existing file or not. If the file |
| exists, <code class="docutils literal notranslate"><span class="pre">syslog_file_channel()</span></code> will append new SYSLOG data |
| to the end of the file. If it does not, then |
| <code class="docutils literal notranslate"><span class="pre">syslog_file_channel()</span></code> will create the file.</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns</dt> |
| <dd class="field-even"><p>Zero (<code class="docutils literal notranslate"><span class="pre">OK</span></code>) is returned on success; a |
| negated <code class="docutils literal notranslate"><span class="pre">errno</span></code> value is returned on any failure.</p> |
| </dd> |
| </dl> |
| <p>References: <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_filechannel.c</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">drivers/syslog/syslog_device.c</span></code>, and |
| <code class="docutils literal notranslate"><span class="pre">include/nuttx/syslog/syslog.h</span></code>.</p> |
| </dd></dl> |
| |
| </div> |
| <div class="section" id="syslog-ramlog-device"> |
| <h3>SYSLOG RAMLOG Device<a class="headerlink" href="#syslog-ramlog-device" title="Permalink to this headline">¶</a></h3> |
| <p>The RAMLOG is a standalone feature that can be used to buffer any |
| character data in memory. There are, however, special |
| configurations that can be used to configure the RAMLOG as a |
| SYSLOG channel. The RAMLOG functionality is described in a more |
| general way in the following paragraphs.</p> |
| </div> |
| </div> |
| <div class="section" id="ram-logging-device"> |
| <h2>RAM Logging Device<a class="headerlink" href="#ram-logging-device" title="Permalink to this headline">¶</a></h2> |
| <p>The RAM logging driver is a driver that was intended to support |
| debugging output (SYSLOG) when the normal serial output is not |
| available. For example, if you are using a Telnet or USB serial |
| console, the debug output will get lost – or worse. For example, |
| what if you want to debug the network over Telnet? |
| The RAM logging driver can also accept debug output data from |
| interrupt handler with no special serialization buffering. As an |
| added benefit, the RAM logging driver is much less invasive. Since |
| no actual I/O is performed with the debug output is generated, the |
| RAM logger tends to be much faster and will interfere much less |
| when used with time critical drivers.</p> |
| <p>The RAM logging driver is similar to a pipe in that it saves the |
| debugging output in a circular buffer in RAM. It differs from a |
| pipe in numerous details as needed to support logging.</p> |
| <p>This driver is built when <code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG</span></code> is defined in the |
| Nuttx configuration.</p> |
| <div class="section" id="dmesg-command"> |
| <h3><code class="docutils literal notranslate"><span class="pre">dmesg</span></code> command<a class="headerlink" href="#dmesg-command" title="Permalink to this headline">¶</a></h3> |
| <p>When the RAMLOG (with SYSLOG) is enabled, a new NuttShell (NSH) |
| command will appear: <code class="docutils literal notranslate"><span class="pre">dmesg</span></code>. The <code class="docutils literal notranslate"><span class="pre">dmesg</span></code> command will dump |
| the contents of the circular buffer to the console (and also clear |
| the circular buffer).</p> |
| </div> |
| <div class="section" id="ramlog-configuration-options"> |
| <h3>RAMLOG Configuration options<a class="headerlink" href="#ramlog-configuration-options" title="Permalink to this headline">¶</a></h3> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG</span></code>: Enables the RAM logging feature</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_SYSLOG</span></code>: Use the RAM logging device for the |
| SYSLOG interface. If this feature is enabled, then all debug |
| output will be re-directed to the circular buffer in RAM. This |
| RAM log can be viewed from NSH using the <code class="docutils literal notranslate"><span class="pre">dmesg</span></code> command. |
| NOTE: Unlike the limited, generic character driver SYSLOG |
| device, the RAMLOG <em>can</em> be used to capture debug output from |
| interrupt level handlers.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_NPOLLWAITERS</span></code>: The number of threads than can |
| be waiting for this driver on <code class="docutils literal notranslate"><span class="pre">poll()</span></code>. Default: 4</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_BUFSIZE</span></code>: The size of the circular buffer to |
| use. Default: 1024 bytes.</p></li> |
| </ul> |
| <p>Other miscellaneous settings</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_CRLF</span></code>: Pre-pend a carriage return before every |
| linefeed that goes into the RAM log.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_NONBLOCKING</span></code>: Reading from the RAMLOG will |
| never block if the RAMLOG is empty. If the RAMLOG is empty, |
| then zero is returned (usually interpreted as end-of-file). If |
| you do not define this, the NSH <code class="docutils literal notranslate"><span class="pre">dmesg</span></code> command will lock up |
| when called! So you probably do want this!</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_RAMLOG_NPOLLWAITERS</span></code>: The maximum number of threads |
| that may be waiting on the poll method.</p></li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| |
| |
| </div> |
| |
| </div> |
| <footer> |
| |
| |
| <hr/> |
| |
| <div role="contentinfo"> |
| <p> |
| |
| © Copyright 2020, The Apache Software Foundation |
| |
| </p> |
| </div> |
| |
| </footer> |
| |
| </div> |
| </div> |
| |
| </section> |
| |
| </div> |
| |
| |
| <script type="text/javascript"> |
| jQuery(function () { |
| SphinxRtdTheme.Navigation.enable(true); |
| }); |
| </script> |
| |
| |
| |
| |
| |
| |
| </body> |
| </html> |
