content/docs/12.4.0/reference/os/conventions.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>Naming and Header File Conventions &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="I/O Buffer Management" href="iob.html" />
     <link rel="prev" title="APIs Exported by Board-Specific Logic to NuttX" href="board.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"><a class="reference internal" href="../../components/index.html">OS Components</a></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="../../implementation/index.html">Implementation Details</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="../index.html">API Reference</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="../user/index.html">Userspace API</a></li>
 <li class="toctree-l2 current"><a class="reference internal" href="index.html">Architecture APIs</a><ul class="current">
 <li class="toctree-l3"><a class="reference internal" href="addrenv.html">Address Environments</a></li>
 <li class="toctree-l3"><a class="reference internal" href="app_vs_os.html">Application OS vs. Internal OS Interfaces</a></li>
 <li class="toctree-l3"><a class="reference internal" href="arch.html">APIs Exported by Architecture-Specific Logic to NuttX</a></li>
 <li class="toctree-l3"><a class="reference internal" href="board.html">APIs Exported by Board-Specific Logic to NuttX</a></li>
 <li class="toctree-l3 current"><a class="current reference internal" href="#">Naming and Header File Conventions</a></li>
 <li class="toctree-l3"><a class="reference internal" href="iob.html">I/O Buffer Management</a></li>
 <li class="toctree-l3"><a class="reference internal" href="led.html">LED Support</a></li>
 <li class="toctree-l3"><a class="reference internal" href="mutex.html">Mutual Exclusion lock</a></li>
 <li class="toctree-l3"><a class="reference internal" href="nat.html">Network Address Translation (NAT)</a></li>
 <li class="toctree-l3"><a class="reference internal" href="newreno.html">Congestion Control NewReno</a></li>
 <li class="toctree-l3"><a class="reference internal" href="notifier.html">Notifier Chain</a></li>
 <li class="toctree-l3"><a class="reference internal" href="nuttx.html">APIs Exported by NuttX to Architecture-Specific Logic</a></li>
 <li class="toctree-l3"><a class="reference internal" href="paging.html">On-Demand Paging</a></li>
 <li class="toctree-l3"><a class="reference internal" href="shm.html">Shared Memory</a></li>
 <li class="toctree-l3"><a class="reference internal" href="smp.html">Symmetric Multiprocessing (SMP) Application</a></li>
 <li class="toctree-l3"><a class="reference internal" href="time_clock.html">System Time and Clock</a></li>
 <li class="toctree-l3"><a class="reference internal" href="wqueue.html">Work Queues</a></li>
 <li class="toctree-l3"><a class="reference internal" href="netdev.html">Network Devices</a></li>
 </ul>
 </li>
 </ul>
 </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">API Reference</a></li>
           <li class="breadcrumb-item"><a href="index.html">Architecture APIs</a></li>
       <li class="breadcrumb-item active">Naming and Header File Conventions</li>
       <li class="wy-breadcrumbs-aside">
             <a href="../../_sources/reference/os/conventions.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="naming-and-header-file-conventions">
 <h1>Naming and Header File Conventions<a class="headerlink" href="#naming-and-header-file-conventions" title="Permalink to this heading"></a></h1>
 <ul>
 <li><p><strong>Common Microprocessor Interfaces</strong>. Any interface that is
 common to all microprocessors should be prefixed with <code class="docutils literal notranslate"><span class="pre">up_</span></code>
 and prototyped in <code class="docutils literal notranslate"><span class="pre">include/nuttx/arch.h</span></code>. The definitions in
 that header file provide the common interface between NuttX and
 the architecture-specific implementation in <code class="docutils literal notranslate"><span class="pre">arch/</span></code>.</p>
 <blockquote>
 <div><p><code class="docutils literal notranslate"><span class="pre">up_</span></code> is supposed to stand for microprocessor; the <code class="docutils literal notranslate"><span class="pre">u</span></code>
 is like the Greek letter micron: ľ. So it would be <code class="docutils literal notranslate"><span class="pre">ľP</span></code>
 which is a common shortening of the word microprocessor. I
 don’t like that name very much. I wish I would have used a
 more obvious prefix like <code class="docutils literal notranslate"><span class="pre">arch_</span></code> instead – then I would
 not have to answer this question so often.</p>
 </div></blockquote>
 </li>
 <li><p><strong>Microprocessor-Specific Interfaces</strong>. An interface which is
 unique to a certain microprocessor should be prefixed with the
 name of the microprocessor, for example <code class="docutils literal notranslate"><span class="pre">stm32_</span></code>, and be
 prototyped in some header file in the <code class="docutils literal notranslate"><span class="pre">arch/</span></code> directories.</p>
 <p>There is also a <code class="docutils literal notranslate"><span class="pre">arch/&lt;architecture&gt;/include/&lt;chip&gt;/chip.h</span></code>
 header file that can be used to communicate other
 microprocessor-specific information between the board logic and
 even application logic. Application logic may, for example,
 need to know specific capabilities of the chip. Prototypes in
 that <code class="docutils literal notranslate"><span class="pre">chip.h</span></code> header file should follow the
 microprocessor-specific naming convention.</p>
 </li>
 <li><p><strong>Common Board Interfaces</strong>. Any interface that is common to
 all boards should be prefixed with <code class="docutils literal notranslate"><span class="pre">board_</span></code> and should also
 be prototyped in <code class="docutils literal notranslate"><span class="pre">include/nuttx/board.h</span></code>. These <code class="docutils literal notranslate"><span class="pre">board_</span></code>
 definitions provide the interface between the board-level logic
 and the commaon and architecture-specific logic.</p></li>
 <li><p><strong>Board-Specific Interfaces</strong>. Any interface which is unique to
 a board should be prefixed with the board name, for example
 <code class="docutils literal notranslate"><span class="pre">stm32f4discovery_</span></code>. Sometimes the board name is too long so
 <code class="docutils literal notranslate"><span class="pre">stm32_</span></code> would be okay too. These should be prototyped in
 <code class="docutils literal notranslate"><span class="pre">boards/&lt;arch&gt;/&lt;chip&gt;/&lt;board&gt;/src/&lt;board&gt;.h</span></code> and should not
 be used outside of that directory since board-specific
 definitions have no meaning outside of the board directory.</p></li>
 <li><p><strong>Scope of Inclusions</strong>. Header files are made accessible to
 internal OS logic and to applications through symbolic links
 and through <em>include paths</em> that are provided to the C/C++
 compiler. Through these include paths, the NuttX build system
 also enforces modularity in the design. For example, one
 important design principle is architectural <em>layering</em>. In this
 case I am referring to the OS as layered into application
 interface, common internal OS logic, and lower level
 platform-specific layers. The platform-specific layers all
 reside in the either <code class="docutils literal notranslate"><span class="pre">arch/</span></code> sub-directories on the
 <code class="docutils literal notranslate"><span class="pre">config/</span></code> subdirectories: The former sub-directories are
 reserved for microcontroller-specific logic and the latter for
 board-specific logic.</p>
 <p>In the strict, layered NuttX architecture, the upper level OS
 services are always available to platform-specific logic.
 However, the opposite is <em>not</em> true: Common OS logic must never
 have any dependency on the lower level platform-specific code.
 The OS logic must be totally agnostic about its hardware
 environment. Similarly, microcontroller-specific logic was be
 completely ignorant of board-specific logic.</p>
 <p>This strict layering is enforced in the NuttX build system by
 controlling the compiler include paths: Higher level code can
 never include header files from either; of the
 platform-specific source directories; microcontroller-specific
 code can never include header files from the board-specific
 source directories. The board-specific directories are, then,
 at the bottom of the layered hierarchy.</p>
 <p>An exception to these inclusion restrictions is the
 platform-specific <em>include/</em>. These are made available to
 higher level OS logic. The microcontroller-specific include
 directory will be linked at <code class="docutils literal notranslate"><span class="pre">include/arch/chip</span></code> and, hence,
 can be included like <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&lt;arch/hardware/chip.h</span></code>.
 Similarly, the board-specific include directory will be linked
 at <code class="docutils literal notranslate"><span class="pre">include/arch/board</span></code> and, hence, can be included like
 <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&lt;arch/board/board.h</span></code>.</p>
 <p>Keeping in the spirit of the layered architecture, these
 publicly visible header files must <em>not</em> export
 platform-specific definitions; Only platform-specific
 realizations of standardized declarations should be visible.
 Those <em>standardized declarations</em> should appear in common
 header files such as those provided by <code class="docutils literal notranslate"><span class="pre">include/nuttx/arch.h</span></code>
 and <code class="docutils literal notranslate"><span class="pre">include/nuttx/board.h</span></code>. Similarly, these publicly
 visible header file must <em>not</em> include files that reside in the
 inaccessible platform-specific source directories. For example,
 the board-specific
 <code class="docutils literal notranslate"><span class="pre">boards/&lt;arch&gt;/&lt;chip&gt;/&lt;board&gt;/include/board.h</span></code> header file
 must never include microcontroller-specific header files that
 reside in <code class="docutils literal notranslate"><span class="pre">arch/&lt;arch&gt;/src/&lt;mcu&gt;</span></code>. That practice will cause
 inclusion failures when the publicly visible file is included
 in common logic outside of the platform-specific source
 directories.</p>
 </li>
 </ul>
 </section>


            </div>
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
         <a href="board.html" class="btn btn-neutral float-left" title="APIs Exported by Board-Specific Logic to NuttX" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
         <a href="iob.html" class="btn btn-neutral float-right" title="I/O Buffer Management" 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 2023, The Apache Software Foundation.</p>
   </div>


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

 </body>
 </html>
	<!--
	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>Naming and Header File Conventions — 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="I/O Buffer Management" href="iob.html" />
	<link rel="prev" title="APIs Exported by Board-Specific Logic to NuttX" href="board.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"><a class="reference internal" href="../../components/index.html">OS Components</a></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="../../implementation/index.html">Implementation Details</a></li>
	<li class="toctree-l1 current"><a class="reference internal" href="../index.html">API Reference</a><ul class="current">
	<li class="toctree-l2"><a class="reference internal" href="../user/index.html">Userspace API</a></li>
	<li class="toctree-l2 current"><a class="reference internal" href="index.html">Architecture APIs</a><ul class="current">
	<li class="toctree-l3"><a class="reference internal" href="addrenv.html">Address Environments</a></li>
	<li class="toctree-l3"><a class="reference internal" href="app_vs_os.html">Application OS vs. Internal OS Interfaces</a></li>
	<li class="toctree-l3"><a class="reference internal" href="arch.html">APIs Exported by Architecture-Specific Logic to NuttX</a></li>
	<li class="toctree-l3"><a class="reference internal" href="board.html">APIs Exported by Board-Specific Logic to NuttX</a></li>
	<li class="toctree-l3 current"><a class="current reference internal" href="#">Naming and Header File Conventions</a></li>
	<li class="toctree-l3"><a class="reference internal" href="iob.html">I/O Buffer Management</a></li>
	<li class="toctree-l3"><a class="reference internal" href="led.html">LED Support</a></li>
	<li class="toctree-l3"><a class="reference internal" href="mutex.html">Mutual Exclusion lock</a></li>
	<li class="toctree-l3"><a class="reference internal" href="nat.html">Network Address Translation (NAT)</a></li>
	<li class="toctree-l3"><a class="reference internal" href="newreno.html">Congestion Control NewReno</a></li>
	<li class="toctree-l3"><a class="reference internal" href="notifier.html">Notifier Chain</a></li>
	<li class="toctree-l3"><a class="reference internal" href="nuttx.html">APIs Exported by NuttX to Architecture-Specific Logic</a></li>
	<li class="toctree-l3"><a class="reference internal" href="paging.html">On-Demand Paging</a></li>
	<li class="toctree-l3"><a class="reference internal" href="shm.html">Shared Memory</a></li>
	<li class="toctree-l3"><a class="reference internal" href="smp.html">Symmetric Multiprocessing (SMP) Application</a></li>
	<li class="toctree-l3"><a class="reference internal" href="time_clock.html">System Time and Clock</a></li>
	<li class="toctree-l3"><a class="reference internal" href="wqueue.html">Work Queues</a></li>
	<li class="toctree-l3"><a class="reference internal" href="netdev.html">Network Devices</a></li>
	</ul>
	</li>
	</ul>
	</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">API Reference</a></li>
	<li class="breadcrumb-item"><a href="index.html">Architecture APIs</a></li>
	<li class="breadcrumb-item active">Naming and Header File Conventions</li>
	<li class="wy-breadcrumbs-aside">
	<a href="../../_sources/reference/os/conventions.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="naming-and-header-file-conventions">
	<h1>Naming and Header File Conventions<a class="headerlink" href="#naming-and-header-file-conventions" title="Permalink to this heading"></a></h1>
	<ul>
	<li><p><strong>Common Microprocessor Interfaces</strong>. Any interface that is
	common to all microprocessors should be prefixed with <code class="docutils literal notranslate"><span class="pre">up_</span></code>
	and prototyped in <code class="docutils literal notranslate"><span class="pre">include/nuttx/arch.h</span></code>. The definitions in
	that header file provide the common interface between NuttX and
	the architecture-specific implementation in <code class="docutils literal notranslate"><span class="pre">arch/</span></code>.</p>
	<blockquote>
	<div><p><code class="docutils literal notranslate"><span class="pre">up_</span></code> is supposed to stand for microprocessor; the <code class="docutils literal notranslate"><span class="pre">u</span></code>
	is like the Greek letter micron: ľ. So it would be <code class="docutils literal notranslate"><span class="pre">ľP</span></code>
	which is a common shortening of the word microprocessor. I
	don’t like that name very much. I wish I would have used a
	more obvious prefix like <code class="docutils literal notranslate"><span class="pre">arch_</span></code> instead – then I would
	not have to answer this question so often.</p>
	</div></blockquote>
	</li>
	<li><p><strong>Microprocessor-Specific Interfaces</strong>. An interface which is
	unique to a certain microprocessor should be prefixed with the
	name of the microprocessor, for example <code class="docutils literal notranslate"><span class="pre">stm32_</span></code>, and be
	prototyped in some header file in the <code class="docutils literal notranslate"><span class="pre">arch/</span></code> directories.</p>
	<p>There is also a <code class="docutils literal notranslate"><span class="pre">arch/<architecture>/include/<chip>/chip.h</span></code>
	header file that can be used to communicate other
	microprocessor-specific information between the board logic and
	even application logic. Application logic may, for example,
	need to know specific capabilities of the chip. Prototypes in
	that <code class="docutils literal notranslate"><span class="pre">chip.h</span></code> header file should follow the
	microprocessor-specific naming convention.</p>
	</li>
	<li><p><strong>Common Board Interfaces</strong>. Any interface that is common to
	all boards should be prefixed with <code class="docutils literal notranslate"><span class="pre">board_</span></code> and should also
	be prototyped in <code class="docutils literal notranslate"><span class="pre">include/nuttx/board.h</span></code>. These <code class="docutils literal notranslate"><span class="pre">board_</span></code>
	definitions provide the interface between the board-level logic
	and the commaon and architecture-specific logic.</p></li>
	<li><p><strong>Board-Specific Interfaces</strong>. Any interface which is unique to
	a board should be prefixed with the board name, for example
	<code class="docutils literal notranslate"><span class="pre">stm32f4discovery_</span></code>. Sometimes the board name is too long so
	<code class="docutils literal notranslate"><span class="pre">stm32_</span></code> would be okay too. These should be prototyped in
	<code class="docutils literal notranslate"><span class="pre">boards/<arch>/<chip>/<board>/src/<board>.h</span></code> and should not
	be used outside of that directory since board-specific
	definitions have no meaning outside of the board directory.</p></li>
	<li><p><strong>Scope of Inclusions</strong>. Header files are made accessible to
	internal OS logic and to applications through symbolic links
	and through <em>include paths</em> that are provided to the C/C++
	compiler. Through these include paths, the NuttX build system
	also enforces modularity in the design. For example, one
	important design principle is architectural <em>layering</em>. In this
	case I am referring to the OS as layered into application
	interface, common internal OS logic, and lower level
	platform-specific layers. The platform-specific layers all
	reside in the either <code class="docutils literal notranslate"><span class="pre">arch/</span></code> sub-directories on the
	<code class="docutils literal notranslate"><span class="pre">config/</span></code> subdirectories: The former sub-directories are
	reserved for microcontroller-specific logic and the latter for
	board-specific logic.</p>
	<p>In the strict, layered NuttX architecture, the upper level OS
	services are always available to platform-specific logic.
	However, the opposite is <em>not</em> true: Common OS logic must never
	have any dependency on the lower level platform-specific code.
	The OS logic must be totally agnostic about its hardware
	environment. Similarly, microcontroller-specific logic was be
	completely ignorant of board-specific logic.</p>
	<p>This strict layering is enforced in the NuttX build system by
	controlling the compiler include paths: Higher level code can
	never include header files from either; of the
	platform-specific source directories; microcontroller-specific
	code can never include header files from the board-specific
	source directories. The board-specific directories are, then,
	at the bottom of the layered hierarchy.</p>
	<p>An exception to these inclusion restrictions is the
	platform-specific <em>include/</em>. These are made available to
	higher level OS logic. The microcontroller-specific include
	directory will be linked at <code class="docutils literal notranslate"><span class="pre">include/arch/chip</span></code> and, hence,
	can be included like <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre"><arch/hardware/chip.h</span></code>.
	Similarly, the board-specific include directory will be linked
	at <code class="docutils literal notranslate"><span class="pre">include/arch/board</span></code> and, hence, can be included like
	<code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre"><arch/board/board.h</span></code>.</p>
	<p>Keeping in the spirit of the layered architecture, these
	publicly visible header files must <em>not</em> export
	platform-specific definitions; Only platform-specific
	realizations of standardized declarations should be visible.
	Those <em>standardized declarations</em> should appear in common
	header files such as those provided by <code class="docutils literal notranslate"><span class="pre">include/nuttx/arch.h</span></code>
	and <code class="docutils literal notranslate"><span class="pre">include/nuttx/board.h</span></code>. Similarly, these publicly
	visible header file must <em>not</em> include files that reside in the
	inaccessible platform-specific source directories. For example,
	the board-specific
	<code class="docutils literal notranslate"><span class="pre">boards/<arch>/<chip>/<board>/include/board.h</span></code> header file
	must never include microcontroller-specific header files that
	reside in <code class="docutils literal notranslate"><span class="pre">arch/<arch>/src/<mcu></span></code>. That practice will cause
	inclusion failures when the publicly visible file is included
	in common logic outside of the platform-specific source
	directories.</p>
	</li>
	</ul>
	</section>


	</div>
	</div>
	<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
	<a href="board.html" class="btn btn-neutral float-left" title="APIs Exported by Board-Specific Logic to NuttX" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
	<a href="iob.html" class="btn btn-neutral float-right" title="I/O Buffer Management" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
	</div>

	<hr/>

	<div role="contentinfo">
	<p>© Copyright 2023, The Apache Software Foundation.</p>
	</div>



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

	</body>
	</html>