content/docs/12.2.0/components/drivers/special/lcd.html - nuttx-website - Git at Google

 <!--
  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="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />

   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>LCD Character Drivers &mdash; NuttX latest documentation</title>
       <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="../../../_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="../../../_static/copybutton.css" type="text/css" />
       <link rel="stylesheet" href="../../../_static/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 src="../../../_static/jquery.js"></script>
         <script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script>
         <script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script>
         <script src="../../../_static/doctools.js"></script>
         <script src="../../../_static/sphinx_highlight.js"></script>
         <script src="../../../_static/clipboard.min.js"></script>
         <script src="../../../_static/copybutton.js"></script>
     <script 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="Memory Technology Device Drivers" href="mtd.html" />
     <link rel="prev" title="Frame Buffer Drivers" href="framebuffer.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


   </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>

     </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" aria-label="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="Navigation menu">
               <p class="caption" role="heading"><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="../../../quickstart/index.html">Getting Started</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="../../../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../platforms/index.html">Supported Platforms</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="../../power.html">Power Management</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../binfmt.html">Binary Loader</a></li>
 <li class="toctree-l2 current"><a class="reference internal" href="../index.html">Device Drivers</a><ul class="current">
 <li class="toctree-l3"><a class="reference internal" href="../character/index.html">Character Device Drivers</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../block/index.html">Block Device Drivers</a></li>
 <li class="toctree-l3 current"><a class="reference internal" href="index.html">Specialized Device Drivers</a><ul class="current">
 <li class="toctree-l4"><a class="reference internal" href="syslog.html">SYSLOG</a></li>
 <li class="toctree-l4"><a class="reference internal" href="spi.html">SPI Device Drivers</a></li>
 <li class="toctree-l4"><a class="reference internal" href="i2c.html">I2C Device Drivers</a></li>
 <li class="toctree-l4"><a class="reference internal" href="ethernet.html">Ethernet Device Drivers</a></li>
 <li class="toctree-l4"><a class="reference internal" href="socketcan.html">SocketCAN Device Drivers</a></li>
 <li class="toctree-l4"><a class="reference internal" href="framebuffer.html">Frame Buffer Drivers</a></li>
 <li class="toctree-l4 current"><a class="current reference internal" href="#">LCD Character Drivers</a><ul>
 <li class="toctree-l5"><a class="reference internal" href="#binding">Binding</a></li>
 <li class="toctree-l5"><a class="reference internal" href="#examples">Examples</a></li>
 </ul>
 </li>
 <li class="toctree-l4"><a class="reference internal" href="mtd.html">Memory Technology Device Drivers</a></li>
 <li class="toctree-l4"><a class="reference internal" href="sdio.html">SDIO Device Drivers</a></li>
 <li class="toctree-l4"><a class="reference internal" href="usbhost.html">USB Host-Side Drivers</a></li>
 <li class="toctree-l4"><a class="reference internal" href="usbdev.html">USB Device-Side Drivers</a></li>
 </ul>
 </li>
 <li class="toctree-l3"><a class="reference internal" href="../index.html#lower-half-and-upper-half">Lower-half and upper-half</a></li>
 </ul>
 </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="../../../reference/index.html">API Reference</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../faq/index.html">FAQ</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="../../../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="Mobile navigation menu" >
           <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="Page navigation">
   <ul class="wy-breadcrumbs">
       <li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
           <li class="breadcrumb-item"><a href="../../index.html">OS Components</a></li>
           <li class="breadcrumb-item"><a href="../index.html">Device Drivers</a></li>
           <li class="breadcrumb-item"><a href="index.html">Specialized Device Drivers</a></li>
       <li class="breadcrumb-item active">LCD Character Drivers</li>
       <li class="wy-breadcrumbs-aside">
             <a href="../../../_sources/components/drivers/special/lcd.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">

   <section id="lcd-character-drivers">
 <h1>LCD Character Drivers<a class="headerlink" href="#lcd-character-drivers" title="Permalink to this heading"></a></h1>
 <p>The LCD driver exposes the LCD interface to userspace via <code class="docutils literal notranslate"><span class="pre">ioctl()</span></code> commands.</p>
 <p>The LCD driver is intended to be used in the following scenarios:</p>
 <ol class="arabic simple">
 <li><p>On memory-constrained devices, as it doesn’t require a buffer to represent the whole display:</p>
 <ol class="arabic simple">
 <li><p>Hence, it’s an alternative to the <a class="reference internal" href="framebuffer.html"><span class="doc">Frame Buffer Drivers</span></a>;</p></li>
 </ol>
 </li>
 <li><p>For graphics libraries that draw specific areas of the displays, like <code class="docutils literal notranslate"><span class="pre">LVGL</span></code>;</p></li>
 </ol>
 <section id="binding">
 <h2>Binding<a class="headerlink" href="#binding" title="Permalink to this heading"></a></h2>
 <p>LCD drivers usually are not directly accessed by user code, but are usually bound to another, higher-level device driver.
 In general, the binding sequence is:</p>
 <ol class="arabic simple">
 <li><p>Get an instance of <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">lcd_dev_s</span></code> from the hardware-specific LCD screen driver, and</p></li>
 <li><p>Provide that instance to the initialization method of the higher-level character driver.</p></li>
 </ol>
 <section id="generic-lcd-character-driver">
 <span id="genericlcdlcd"></span><h3>Generic LCD Character Driver<a class="headerlink" href="#generic-lcd-character-driver" title="Permalink to this heading"></a></h3>
 <p>This example will walk through the path from userspace to hardware-specific details on how an LCD screen is bound to an LCD character driver.</p>
 <ol class="arabic">
 <li><p><code class="docutils literal notranslate"><span class="pre">include/nuttx/lcd/lcd.h</span></code> provides all structures and APIs needed to work with LCD screens drivers:</p>
 <ol class="arabic simple">
 <li><p>This header file also depends on some of the same definitions used for the frame buffer driver as provided in <code class="docutils literal notranslate"><span class="pre">include/nuttx/video/fb.h</span></code>;</p></li>
 </ol>
 </li>
 <li><p><code class="docutils literal notranslate"><span class="pre">drivers/lcd/lcd_dev.c</span></code> is the higher-level device driver. An instance of <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">lcd_dev_s</span></code> will be provided to it:</p>
 <ol class="arabic simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">include/nuttx/lcd/lcd_dev.h</span></code> prototypes public structures and functions;</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">lcddev_register</span></code> registers the LCD character driver as <code class="docutils literal notranslate"><span class="pre">/dev/lcdN</span></code> where N is the display number and,</p></li>
 <li><p>calls the <code class="docutils literal notranslate"><span class="pre">board_lcd_getdev</span></code>, an LCD-specific function usually defined in <code class="docutils literal notranslate"><span class="pre">boards/&lt;arch&gt;/&lt;chip&gt;/&lt;board&gt;/src</span></code> and prototyped in <code class="docutils literal notranslate"><span class="pre">include/nuttx/board.h</span></code>;</p></li>
 </ol>
 </li>
 <li><p>Finally, the LCD screen drivers are usually available at <code class="docutils literal notranslate"><span class="pre">drivers/lcd/</span></code> and implement the callbacks defined at <code class="docutils literal notranslate"><span class="pre">include/nuttx/lcd/lcd.h</span></code>:</p>
 <blockquote>
 <div><ol class="arabic simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">include/nuttx/lcd/lcd.h</span></code> provides structures and APIs needed to work with LCD screens, whether using the framebuffer adapter or the <a class="reference internal" href="#"><span class="doc">LCD Character Drivers</span></a>;</p></li>
 </ol>
 </div></blockquote>
 </li>
 </ol>
 </section>
 </section>
 <section id="examples">
 <h2>Examples<a class="headerlink" href="#examples" title="Permalink to this heading"></a></h2>
 <p>Examples apply to specific cases of the <a class="reference internal" href="#genericlcdlcd"><span class="std std-ref">Generic LCD Character Driver</span></a>:</p>
 <section id="ttgo-t-display-esp32-board">
 <span id="ttgotdisplayesp32-lcd"></span><h3>TTGO T-Display ESP32 board<a class="headerlink" href="#ttgo-t-display-esp32-board" title="Permalink to this heading"></a></h3>
 <p>This board contains an ST7789 TFT Display (135x240).
 By selecting the <code class="docutils literal notranslate"><span class="pre">ttgo_t_display_esp32:lvgl_lcd</span></code> config, the <code class="docutils literal notranslate"><span class="pre">lvgldemo</span></code> example will be built with the LCD character interface.</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">boards/xtensa/esp32/ttgo_t_display_esp32/src/esp32_bringup.c</span></code> registers the LCD character driver:</p></li>
 </ul>
 <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#ifdef CONFIG_LCD_DEV</span>
 <span class="w"> </span><span class="n">ret</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">board_lcd_initialize</span><span class="p">();</span>
 <span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">ret</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span>
 <span class="w">   </span><span class="p">{</span>
 <span class="w">     </span><span class="n">syslog</span><span class="p">(</span><span class="n">LOG_ERR</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;ERROR: board_lcd_initialize() failed: %d</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">ret</span><span class="p">);</span>
 <span class="w">   </span><span class="p">}</span>

 <span class="w"> </span><span class="n">ret</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">lcddev_register</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
 <span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">ret</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span>
 <span class="w">   </span><span class="p">{</span>
 <span class="w">     </span><span class="n">syslog</span><span class="p">(</span><span class="n">LOG_ERR</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;ERROR: lcddev_register() failed: %d</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">ret</span><span class="p">);</span>
 <span class="w">   </span><span class="p">}</span>
 <span class="cp">#endif</span>
 </pre></div>
 </div>
 <ul>
 <li><p><code class="docutils literal notranslate"><span class="pre">board_lcd_initialize</span></code> and <code class="docutils literal notranslate"><span class="pre">board_lcd_getdev</span></code> are defined at <code class="docutils literal notranslate"><span class="pre">boards/xtensa/esp32/common/src/esp32_st7789.c</span></code>;</p>
 <blockquote>
 <div><ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">board_lcd_initialize</span></code> initializes the LCD hardware on the board by defining the SPI interface which is connected to the display controller;</p></li>
 </ul>
 </div></blockquote>
 </li>
 <li><p><code class="docutils literal notranslate"><span class="pre">lcddev_register</span></code> then calls <code class="docutils literal notranslate"><span class="pre">board_lcd_getdev</span></code>:</p>
 <blockquote>
 <div><ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">board_lcd_getdev</span></code> calls the <code class="docutils literal notranslate"><span class="pre">st7789_lcdinitialize</span></code> and returns a reference to the LCD object for the specified LCD;</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">st7789_lcdinitialize</span></code> is part of the LCD screen driver at <code class="docutils literal notranslate"><span class="pre">drivers/lcd/st7789.c</span></code>;</p></li>
 </ul>
 </div></blockquote>
 </li>
 <li><p>The LVGL demo application (<code class="docutils literal notranslate"><span class="pre">lvgldemo</span></code>) makes use of the <code class="docutils literal notranslate"><span class="pre">ioctl</span></code> system call to trigger an <code class="docutils literal notranslate"><span class="pre">LCDDEVIO_PUTAREA</span></code> request to the higher-level device driver to refresh the LCD screen with data:</p></li>
 </ul>
 <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">ioctl</span><span class="p">(</span><span class="n">state</span><span class="p">.</span><span class="n">fd</span><span class="p">,</span><span class="w"> </span><span class="n">LCDDEVIO_PUTAREA</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="p">)((</span><span class="kt">uintptr_t</span><span class="p">)</span><span class="o">&amp;</span><span class="n">lcd_area</span><span class="p">));;</span>
 </pre></div>
 </div>
 </section>
 <section id="nuttx-simulator">
 <h3>NuttX Simulator<a class="headerlink" href="#nuttx-simulator" title="Permalink to this heading"></a></h3>
 <p><a class="reference internal" href="../../../platforms/sim/sim/index.html"><span class="doc">NuttX Simulator</span></a> provides a X11-based LCD character driver to simulate the LCD character displat usage into a X11-compatible host.</p>
 <p>By selecting the <code class="docutils literal notranslate"><span class="pre">sim:lvgl_lcd</span></code> config, the <code class="docutils literal notranslate"><span class="pre">lvgldemo</span></code> example will be built with the LCD character interface.</p>
 <ul>
 <li><p><code class="docutils literal notranslate"><span class="pre">boards/sim/sim/sim/src/sim_bringup.c</span></code> registers the lcd driver the same way <a class="reference internal" href="#ttgotdisplayesp32-lcd"><span class="std std-ref">TTGO T-Display ESP32 board</span></a>;</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">arch/sim/src/sim/up_lcd.c</span></code> and <code class="docutils literal notranslate"><span class="pre">arch/sim/src/sim/up_x11framebuffer.c</span></code> will be built as <code class="docutils literal notranslate"><span class="pre">CONFIG_SIM_LCDDRIVER</span> <span class="pre">=</span> <span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">CONFIG_SIM_X11FB</span> <span class="pre">=</span> <span class="pre">y</span></code> are set, respectively;</p>
 <blockquote>
 <div><ul>
 <li><p><code class="docutils literal notranslate"><span class="pre">up_lcd.c</span></code> provides <code class="docutils literal notranslate"><span class="pre">board_lcd_initialize</span></code> and <code class="docutils literal notranslate"><span class="pre">board_lcd_getdev</span></code>:</p>
 <blockquote>
 <div><ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">board_lcd_initialize</span></code> calls <code class="docutils literal notranslate"><span class="pre">up_x11initialize</span></code> from <code class="docutils literal notranslate"><span class="pre">up_x11framebuffer.c</span></code> that initializes a X11-based window as an LCD character device. This is the underlying “driver”.</p></li>
 </ul>
 </div></blockquote>
 </li>
 </ul>
 </div></blockquote>
 </li>
 <li><p>The LVGL demo application (<code class="docutils literal notranslate"><span class="pre">lvgldemo</span></code>) makes use of the <code class="docutils literal notranslate"><span class="pre">ioctl</span></code> system call to trigger an <code class="docutils literal notranslate"><span class="pre">LCDDEVIO_PUTAREA</span></code> request to the higher-level device driver to refresh the LCD screen with data as usual;</p></li>
 </ul>
 </section>
 </section>
 </section>


            </div>
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
         <a href="framebuffer.html" class="btn btn-neutral float-left" title="Frame Buffer Drivers" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
         <a href="mtd.html" class="btn btn-neutral float-right" title="Memory Technology Device Drivers" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>

   <hr/>

   <div role="contentinfo">
     <p>&#169; Copyright 2020, The Apache Software Foundation.</p>
   </div>


 </footer>
         </div>
       </div>
     </section>
   </div>
   <script>
       jQuery(function () {
           SphinxRtdTheme.Navigation.enable(true);
       });
   </script>

 </body>
 </html>