Skip to content
Snippets Groups Projects
NuttxPortingGuide.html 57.2 KiB
Newer Older
patacongo's avatar
patacongo committed
<html>

<head>
patacongo's avatar
patacongo committed
<title>NuttX Porting Manual</title>
patacongo's avatar
patacongo committed
<meta name="author" content="Gregory Nutt">
</head>

patacongo's avatar
patacongo committed
<body background="backgd.gif">
patacongo's avatar
patacongo committed
<hr><hr>
patacongo's avatar
patacongo committed
<center><h1><i>Under Construction</i></h1></center>
patacongo's avatar
patacongo committed
<hr><hr>
patacongo's avatar
patacongo committed
<center>
patacongo's avatar
patacongo committed
  <h1><big><b>
    <p>NuttX Operating System</br>
    Porting Guide</p>
  </b></big></h1>
patacongo's avatar
patacongo committed
  <p><small>by</small></p>
  <p>Gregory Nutt</p>
  <p><small>Last Update: February 15, 2008</small></p>
patacongo's avatar
patacongo committed
</center>

<center><h1>Table of Contents</h1></center>
patacongo's avatar
patacongo committed
<li><a href="#Introduction">1.0 Introduction</a></li>
<li><a href="#DirectoryStructure">2.0 Directory Structure</a></li>
patacongo's avatar
patacongo committed
<ul>
patacongo's avatar
patacongo committed
  <li><a href="#DirStructDocumentation">2.1 Documentation</a></li>
  <l1><a href="#DirStructArch">2.2 arch/</a></li>
patacongo's avatar
patacongo committed
  <ul>
    <li><a href="#archdirectorystructure">2.2.1 Subdirectory Structure</a></li>
    <li><a href="#summaryofarchfiles">2.2.2 Summary of Files</a></li>
patacongo's avatar
patacongo committed
    <li><a href="#supportedarchitectures">2.2.3 Supported Architectures</a></li>
  </ul>
patacongo's avatar
patacongo committed
  <li><a href="#DirStructConfigs">2.3 configs/</a></li>
  <ul>
    <li><a href="#configsdirectorystructure">2.3.1 Subdirectory Structure</a></li>
    <li><a href="#summaryofconfigfiles">2.3.2 Summary of Files</a></li>
patacongo's avatar
patacongo committed
    <ul>
      <li><a href="#boardlogic">2.3.2.1 Board Specific Logic</a></li>
patacongo's avatar
patacongo committed
      <li><a href="#boardconfigsubdirs">2.3.2.2 Board Specific Configuration Sub-Directories</a></li>
patacongo's avatar
patacongo committed
    </ul>
    <li><a href="#supportedboards">2.3.3 Supported Boards</a></li>
  </ul>
patacongo's avatar
patacongo committed
  <li><a href="#DirStructDrivers">2.4 drivers/</a></li>
  <li><a href="#DirStructExamples">2.5 examples/</a></li>
  <li><a href="#DirStructFs">2.6 fs/</a></li>
  <li><a href="#DirStructInclude">2.7 include/</a></li>
  <li><a href="#DirStructLib">2.8 lib/</a></li>
  <li><a href="#DirStructMm">2.9 mm/</a></li>
patacongo's avatar
patacongo committed
  <li><a href="#DirStructNet">2.10 net</a></li>
  <li><a href="#DirStructNetUtils">2.11 netutils</a></li>
  <li><a href="#DirStructSched">2.12 sched/</a></li>
  <li><a href="#DirStructTools">2.13 tools/</a></li>
  <li><a href="#topmakefile">2.14 Makefile</a></li>
patacongo's avatar
patacongo committed
</ul>
patacongo's avatar
patacongo committed
<li><a href="#configandbuild">3.0 Configuring and Building</a></li>
patacongo's avatar
patacongo committed
<ul>
  <li><a href="#configuringnuttx">3.1 Configuring NuttX</a></li>
  <li><a href="#buildingnuttx">3.2 Building NuttX</a></li>
patacongo's avatar
patacongo committed
</ul>
patacongo's avatar
patacongo committed
<li><a href="#ArchAPIs">4.0 Architecture APIs</a></li>
patacongo's avatar
patacongo committed
<ul>
  <li><a href="#imports">4.1 APIs Exported by Architecture-Specific Logic to NuttX</a></li>
  <ul>
    <li><a href="#upinitialize">4.1.1 <code>up_initialize()</code></a></li>
    <li><a href="#upidle">4.1.2 <code>up_idle()</code></a></li>
    <li><a href="#upinitialstate">4.1.3 <code>up_initial_state()</code></a></li>
    <li><a href="#upcreatestack">4.1.4 <code>up_create_stack()</code></a></li>
    <li><a href="#upusestack">4.1.5 <code>up_use_stack()</code></a></li>
    <li><a href="#upreleasestack">4.1.6 <code>up_release_stack()</code></a></li>
    <li><a href="#upunblocktask">4.1.7 <code>up_unblock_task()</code></a></li>
    <li><a href="#upblocktask">4.1.8 <code>up_block_task()</code></a></li>
    <li><a href="#upreleasepending">4.1.9 <code>up_release_pending()</code></a></li>
    <li><a href="#upreprioritizertr">4.1.10 <code>up_reprioritize_rtr()</code></a></li>
    <li><a href="#_exit">4.1.11 <code>_exit()</code></a></li>
    <li><a href="#upassert">4.1.12 <code>up_assert()</code></a></li>
    <li><a href="#upschedulesigaction">4.1.13 <code>up_schedule_sigaction()</code></a></li>
    <li><a href="#upallocateheap">4.1.14 <code>up_allocate_heap()</code></a></li>
    <li><a href="#upinterruptcontext">4.1.15 <code>up_interrupt_context()</code></a></li>
    <li><a href="#updisableirq">4.1.16 <code>up_disable_irq()</code></a></li>
    <li><a href="#upenableirq">4.1.17 <code>up_enable_irq()</code></a></li>
    <li><a href="#upputc">4.1.18 <code>up_putc()</code></a></li>
  </ul>
  <li><a href="#exports">4.2 APIs Exported by NuttX to Architecture-Specific Logic</a></li>
  <ul>
    <li><a href="#osstart">4.2.1 <code>os_start()</code></a></li>
    <li><a href="#listmgmt">4.2.2 OS List Management APIs</a></li></li>
    <li><a href="#schedprocesstimer">4.2.3 <code>sched_process_timer()</code></a></li>
    <li><a href="#irqdispatch">4.2.4 <code>irq_dispatch()</code></a></li>
  </ul>
</ul>
patacongo's avatar
patacongo committed
<li><a href="#NxFileSystem">5.0 NuttX File System</a></li>
patacongo's avatar
patacongo committed
<li><a href="#apndxconfigs">Appendix A: NuttX Configuration Settings</a></li>
patacongo's avatar
patacongo committed
<li><a href="#apndxtrademarks">Appendix B:  Trademarks</a></li>
patacongo's avatar
patacongo committed
<hr>
<h1>1.0 <a name="Introduction">Introduction</a></h1>

<p><b>Overview</b>
patacongo's avatar
patacongo committed
  This document provides and overview of the NuttX build and configuration
patacongo's avatar
patacongo committed
  logic and provides hints for the incorporation of new processor/board architectures
patacongo's avatar
patacongo committed
  into the build.
</p>
<p>
patacongo's avatar
patacongo committed
  See also <code>arch/README.txt</code> and <code>configs/README.txt</code>.
patacongo's avatar
patacongo committed
</p>

<p><b>General Philosophy</b>.

<hr>
<h1>2.0 <a name="DirectoryStructure">Directory Structure</a></h1>

patacongo's avatar
patacongo committed
<p>
  <b>Directory Structure</b>.
  The general directly layout for NuttX is very similar to the directory structure
  of the Linux kernel -- at least at the most superficial layers.
  At the top level is the main makefile and a series of sub-directories identified
  below and discussed in the following paragraphs:
</p>
patacongo's avatar
patacongo committed
<ul><pre>
.
patacongo's avatar
patacongo committed
|-- <a href="#topmakefile">Makefile</a>
patacongo's avatar
patacongo committed
|-- <a href="#DirStructDocumentation">Documentation</a>
patacongo's avatar
patacongo committed
|   `-- <i>(documentation files)</i>/
|-- <a href="#DirStructArch">arch</a>/
|   |-- <i>&lt;arch-name&gt;</i>/
|   |   |-- include/
|   |   |   |--<i>&lt;chip-name&gt;</i>/
|   |   |   |  `-- <i>(chip-specific header files)</i>
|   |   |   |--<i>&lt;other-chips&gt;</i>/
|   |   |   `-- <i>(architecture-specific header files)</i>
|   |   `-- src/
|   |       |--<i>&lt;chip-name&gt;</i>/
|   |       |  `-- <i>(chip-specific source files)</i>
|   |       |--<i>&lt;other-chips&gt;</i>/
|   |       `-- <i>(architecture-specific source files)</i>
patacongo's avatar
patacongo committed
|   `-- <i>&lt;other-architecture directories&gt;</i>/
patacongo's avatar
patacongo committed
|-- <a href="#DirStructConfigs">configs</a>/
|   |-- <i>&lt;board-name&gt;</i>/
|   |   |-- include/
|   |   |   `-- <i>(board-specific header files)</i>
|   |   |-- src/
|   |   |   |-- Makefile
|   |   |  `-- <i>(board-specific source files)</i>
patacongo's avatar
patacongo committed
|   |   |---<i>&lt;config1-dir&gt;</i>/
|   |   |   `-- <i>(board-specific/configuration-specific files)</i>
|   |   `---<i>(other board-specific configuration sub-directories)</i>/
|   `-- <i>&lt;(other board directories)&gt;</i>/
patacongo's avatar
patacongo committed
|-- <a href="#DirStructDrivers">drivers</a>/
|   |-- Makefile
patacongo's avatar
patacongo committed
|   `-- <i>(common driver source files)</i>
|-- <a href="#DirStructExamples">examples</a>/
|   `-- <i>(example)</i>/
patacongo's avatar
patacongo committed
|       |-- Makefile
|       `-- <i>(example source files)</i>
patacongo's avatar
patacongo committed
|-- <a href="#DirStructFs">fs</a>/
patacongo's avatar
patacongo committed
|   |-- Makefile
patacongo's avatar
patacongo committed
|   `-- <i>(common file system source files)</i>
patacongo's avatar
patacongo committed
|-- <a href="#DirStructInclude">include</a>/
patacongo's avatar
patacongo committed
|   |-- <i>(standard header files)</i>
patacongo's avatar
patacongo committed
|   |-- arpa/
|   |   `-- <i>(standard header files)</i>
|   |-- net/
|   |   `-- uip/
|   |       `-- <i>(uIP specific header files)</i>
|   |-- netinet/
|   |   `-- <i>(standard header files)</i>
patacongo's avatar
patacongo committed
|   |-- nuttx/
patacongo's avatar
patacongo committed
|   |   `-- <i>(nuttx specific header files)</i>
patacongo's avatar
patacongo committed
|   `- sys/
patacongo's avatar
patacongo committed
|   |   `-- <i>(more standard header files)</i>
patacongo's avatar
patacongo committed
|-- <a href="#DirStructLib">lib</a>/
patacongo's avatar
patacongo committed
|   |-- Makefile
|   `-- <i>(lib source files)</i>
patacongo's avatar
patacongo committed
|-- <a href="#DirStructMm">mm</a>/
patacongo's avatar
patacongo committed
|   |-- Makefile
patacongo's avatar
patacongo committed
|   `-- <i>(memory management source files)</i>
|-- <a href="#DirStructNet">net</a>/
|   |-- Makefile
|   |-- uip/
|   |   `-- <i>(uip source files)</i>
|   `-- <i>(socket source files)</i>
|-- <a href="#DirStructNetUtils">netutils</a>/
|   |-- dhcp/
|   |   `-- <i>(dhcp source files)</i>
|   |-- resolv/
|   |   `-- <i>(resolv source files)</i>
|   |-- smtp/
|   |   `-- <i>(smtp source files)</i>
|   |-- telnetd/
|   |   `-- <i>(telnetd source files)</i>
|   |-- uiplib/
|   |   `-- <i>(uiplib source files)</i>
|   |-- weblclient/
|   |   `-- <i>(webclient source files)</i>
|   |-- webserver/
|   |   `-- <i>(webserver source files)</i>
|   |-- Makefile
|   `-- <i>(fs source files)</i>
patacongo's avatar
patacongo committed
|-- <a href="#DirStructSched">sched</a>/
patacongo's avatar
patacongo committed
|   |-- Makefile
|   `-- <i>(sched source files)</i>
patacongo's avatar
patacongo committed
`-- <a href="#DirStructDrivers">tools</a>/
patacongo's avatar
patacongo committed
    |-- Makefile.mkconfig
    |-- configure.sh
    |-- mkconfig.c
    |-- mkdeps.sh
    `-- zipme
</pre></ul>

patacongo's avatar
patacongo committed
<p>
  <b>Configuration Files</b>.
  The NuttX configuration consists of:
</p>
<ul>
  <li>
    <i>Processor architecture specific files</i>.
    These are the files contained in the <code>arch/</code><i>&lt;arch-name&gt;</i><code>/</code> directory
    and are discussed in a paragraph <a href="#archdirectorystructure">below</a>.
  </li>
  <li>
    <i>Chip/SoC specific files</i>.
    Each processor processor architecture is embedded in chip or <i>System-on-a-Chip</i> (SoC) architecture.
    The full chip architecture includes the processor architecture plus chip-specific interrupt logic,
    clocking logic, general purpose I/O (GIO) logic, and specialized, internal peripherals (such as UARTs, USB, etc.).
    <p>
      These chip-specific files are contained within chip-specific sub-directories in the
      <code>arch/</code><i>&lt;arch-name&gt;</i><code>/</code> directory and are selected via
      the <code>CONFIG_ARCH_name</code> selection.
    </p>
  </li>
  <li>
patacongo's avatar
patacongo committed
    <i>Board specific configurations</i>.
patacongo's avatar
patacongo committed
    In order to be usable, the chip must be contained in a board environment.
    The board configuration defines additional properties of the board including such things as
    peripheral LEDs, external peripherals (such as network, USB, etc.).
    <p>
      These board-specific configuration files can be found in the
      <code>configs/</code><i>&lt;board-name&gt;</i><code>/</code> sub-directories and are discussed
patacongo's avatar
patacongo committed
      in a paragraph <a href="#configsdirectorystructure">below</a>.
patacongo's avatar
patacongo committed
    </p>
  </li>
</ul>

patacongo's avatar
patacongo committed
<h2>2.1 <a name="DirStructDocumentation">Documentation</a></h2>
patacongo's avatar
patacongo committed

<p>
  General documentation for the NuttX OS resides in this directory.
</p>

patacongo's avatar
patacongo committed
<h2>2.2 <a name="DirStructArch">arch</a></h2>
patacongo's avatar
patacongo committed

<h3><a name="archdirectorystructure">2.2.1 Subdirectory Structure</a></h3>
patacongo's avatar
patacongo committed
<p>
  This directory contains several sub-directories, each containing
  architecture-specific logic.
  The task of porting NuttX to a new processor consists of
patacongo's avatar
patacongo committed
  add a new subdirectory under <code>arch/</code> containing logic specific
  to the new architecture.
  The complete board port in is defined by the architecture-specific code in this
  directory (plus the board-specific configurations in the <code>config/</code>
  subdirectory).
patacongo's avatar
patacongo committed
  Each architecture must provide a subdirectory, <i>&lt;arch-name&gt;</i>
  under <code>arch/</code> with the following characteristics:
patacongo's avatar
patacongo committed
</p>
<ul><pre>
patacongo's avatar
patacongo committed
	<i>&lt;arch-name&gt;</i>/
patacongo's avatar
patacongo committed
	|   |--<i>&lt;chip-name&gt;</i>/
	|   |  `-- <i>(chip-specific header files)</i>
	|   |--<i>&lt;other-chips&gt;</i>/
patacongo's avatar
patacongo committed
	|   |-- arch.h
	|   |-- irq.h
	|   |-- types.h
	|   `-- limits.h
patacongo's avatar
patacongo committed
	    |--<i>&lt;chip-name&gt;</i>/
	    |  `-- <i>(chip-specific source files)</i>
	    |--<i>&lt;other-chips&gt;</i>/
patacongo's avatar
patacongo committed
	    |-- Makefile
	    `-- <i>(architecture-specific source files)</i>
patacongo's avatar
patacongo committed
</pre></ul>

<h3><a name="summaryofarchfiles">2.2.2 Summary of Files</a></h3>
patacongo's avatar
patacongo committed
<ul>
patacongo's avatar
patacongo committed
  <li>
    <code>include/</code><i>&lt;chip-name&gt;</i><code>/</code>
    This sub-directory contains chip-specific header files.
  </li>
patacongo's avatar
patacongo committed
  <li>
    <code>include/arch.h</code>:
    This is a hook for any architecture specific definitions that may
    be needed by the system.  It is included by <code>include/nuttx/arch.h</code>.
  </li>
  <li>
    <code>include/types.h</code>:
    This provides architecture/toolchain-specific definitions for
    standard types.  This file should <code>typedef</code>:
    <ul><code>
      sbyte, ubyte, uint8, boolean, sint16, uint16, sint32, uint32
    </code></ul>
    <p>and if the architecture supports 64-bit integers</p>
    <ul><code>
      sint64, uint64
    </code></ul>
    <p>
      and finally
    </p>
    <ul><code>
      irqstate_t
    </code></ul>
    <p>
      Must be defined to the be the size required to hold the interrupt
     enable/disable state.
    </p>
    <p>
      This file will be included by include/sys/types.h and be made
      available to all files.
    </p>
  </li>
  <li>
    <code>include/irq.h</code>:
    This file needs to define some architecture specific functions (usually
    inline if the compiler supports inlining) and structure.  These include:
    <ul>
      <li>
        <code>struct xcptcontext</code>:
        This structures represents the saved context of a thread.
      </li>
      <li>
        <code>irqstate_t irqsave(void)</code>:
        Used to disable all interrupts.
      </li>
      <li>
        <code>void irqrestore(irqstate_t flags)<code>:
        Used to restore interrupt enables to the same state as before <code>irqsave()</code> was called.
      </li>
    </ul>
    <p>
      This file must also define <code>NR_IRQS</code>, the total number of IRQs supported
       by the board.
    </p>
  </li>
patacongo's avatar
patacongo committed
  <li>
    <code>src/</code><i>&lt;chip-name&gt;</i><code>/</code>
    This sub-directory contains chip-specific source files.
  </li>
patacongo's avatar
patacongo committed
  <li>
    <code>src/Makefile</code>:
    This makefile will be executed to build the targets <code>src/libup.a</code> and
    <code>src/up_head.o</code>.  The <code>up_head.o</code> file holds the entry point into the system
    (power-on reset entry point, for example).  It will be used in
    the final link with <code>libup.a</code> and other system archives to generate the
    final executable.
  </li>
  <li>
    <i>(architecture-specific source files)</i>.
    The file <code>include/nuttx/arch.h</code> identifies all of the APIs that must
    be provided by the architecture specific logic.  (It also includes
patacongo's avatar
patacongo committed
    <code>arch/</code><i>&lt;arch-name&gt;</i><code>/arch.h</code> as described above).
patacongo's avatar
patacongo committed
</ul>

<h3><a name="supportedarchitectures">2.2.3 Supported Architectures</a></h3>
<p>
   <b>Archictecture- and Chip-Specific Directories</b>.
   All processor architecture-specific directories are maintained in sub-directories of
   the <code>arch/</code> directory.
   Different chips or SoC's may implement the same processor core.
   Chip-specific logic can be found in sub-directories under the architecture
   directory.
   Current architecture/chip directories are summarized below:
</p>
patacongo's avatar
patacongo committed
<ul>
  <li><code>arch/sim</code>:
    A user-mode port of NuttX to the x86 Linux platform is available.
    The purpose of this port is primarily to support OS feature developement.
    This port does not support interrupts or a real timer (and hence no
    round robin scheduler)  Otherwise, it is complete.
  </li>
patacongo's avatar
patacongo committed
  <p>NOTE: This target will not run on Cygwin probably for many reasons but
    first off because it uses some of the same symbols as does cygwind.dll.
  </p>
  <li><code>arch/arm</code>:
    This directory holds common ARM architectures.  At present, this includes
    the following subdirectories:
    <ul>
patacongo's avatar
patacongo committed
      <li><code>arch/arm/include</code> and <code>arch/arm/src/common</code>:
          Common ARM logic.
      </li>

      <li><code>arch/arm/include/c5471</code> and <code>arch/arm/src/c5471</code>:
        TI TMS320C5471 (also called TMS320DM180 or just C5471).
        NuttX operates on the ARM7 of this dual core processor.
        This port is complete, verified, and included in the NuttX release 0.1.1.
      </li>

      <li><code>arch/arm/include/dm320</code> and <code>arch/arm/src/dm320</code>:
        TI TMS320DM320 (also called just DM320).
        NuttX operates on the ARM9EJS of this dual core processor.
        This port complete, verified, and included in the NuttX release 0.2.1.
      </li>

      <li><code>arch/arm/include/lpc214x</code> and <code>arch/arm/src/lpc214x</code>:
        These directories provide support for NXP LPC214x family of
        processors.
        STATUS: This port is in progress and should be available in the
        nuttx-0.2.5 release.
      </li>

    </ul>
  </li>

  <li><code>configs/mcu123-lpc214x</code>:
    The mcu123.com lpc214x development board.
    This is a work in progress.
  </li>
patacongo's avatar
patacongo committed
    A work in progress.
  </li>
patacongo's avatar
patacongo committed
  <li><code>arch/pjrc-8051</code>:
patacongo's avatar
patacongo committed
    8051 Microcontroller.  This port is not quite ready for prime time.
  </li>
patacongo's avatar
patacongo committed

patacongo's avatar
patacongo committed
  <li><code>arch/z16f</code>:
    Zilog z16f Microcontroller.
    This port uses the Zilog z16f2800100zcog Development Kit.
patacongo's avatar
patacongo committed
    This port was released with nuttx-0.3.7.
patacongo's avatar
patacongo committed
  </li>

    <li><code>arch/z80</code>:
patacongo's avatar
patacongo committed
    This directory holds 8-bit ZiLOG architectures.  At present, this includes the
    Zilog z80 and z8Encore! Microcontrollers.
    <ul>
      <li><code>arch/z80/include</code> and <code>arch/z80/src/common</code>:
          Common logic.
      </li>

      <li><code>arch/z80/include/z80</code> and <code>arch/z80/src/z80</code>:
        The Z80 port was released in nuttx-0.3.6 has been verified using only a
        z80 instruction simulator.
        The set simulator  can be found in the NuttX CVS at
        http://nuttx.cvs.sourceforge.net/nuttx/misc/sims/z80sim.
        This port also uses the SDCC toolchain (http://sdcc.sourceforge.net/")
patacongo's avatar
patacongo committed
        (verified with version 2.6.0 and 2.7.0).
      </li>

      <li><code>arch/z80/include/z8</code> and <code>arch/z80/src/z8</code>:
        The Z8Encore! port use the Zilog z8encore000zco
patacongo's avatar
patacongo committed
        development kit, Z8F6403 part, and the Zilog ZDS-II Windows command line
patacongo's avatar
patacongo committed
        tools.  The development environment is Cygwin under WinXP.
        This port is in progress and will be released in a future NuttX release.
      </li>
    </ul>
    </li>
</ul>

<p>
  <b>Deprecated Architecture Directories</b>.
  The following architecture directories are deprecated.  They have been
  replaced by the logic in <code>arm/arm</code> and will deleted when
  <code>arch/arm</code> is fully verified.
</p>
<ul>
  <li><code>arch/c5471</code>:
    Replaced with <code>arch/arm/include/c5471</code> and
    <code>arch/arm/src/c5471<code>.
  </li>

  <li><code>arch/dm320</code>:
    Replaced with <code>arch/arm/include/dm320</code> and
    <code>arch/arm/src/dm320<code>.
  </li>
patacongo's avatar
patacongo committed
</ul>
<p>
  Other ports for the for the TI TMS320DM270 and for MIPS are in various states
  of progress
</p>

<h2>2.3 <a name="DirStructConfigs">configs</a></h2>
<p>
  The <code>configs/</code> subdirectory contains configuration data for each board.
  These board-specific configurations plus the architecture-specific configurations in
  the <code>arch/</code> subdirectory complete define a customized port of NuttX.
</p>

<h3><a name="configsdirectorystructure">2.3.1 Subdirectory Structure</a></h3>
<p>
  The configs directory contains board specific configuration files.  Each board must
  provide a subdirectory &lt;board-name&gt; under <code>configs/</code> with the following characteristics:
</p>
<ul><pre>
patacongo's avatar
patacongo committed
	|-- Make.defs
	|-- defconfig
	`-- setenv.sh
patacongo's avatar
patacongo committed
	<i>&lt;board-name&gt;</i>
patacongo's avatar
patacongo committed
	|   `-- <i>(board-specific header files)</i>
patacongo's avatar
patacongo committed
	|   |-- Makefile
	|   `-- <i>(board-specific source files)</i>
patacongo's avatar
patacongo committed
        |-- <i>&lt;config1-dir&gt;</i>
	|   |-- Make.defs
	|   |-- defconfig
	|   `-- setenv.sh
        |-- <i>&lt;config2-dir&gt;</i>
	|   |-- Make.defs
	|   |-- defconfig
	|   `-- setenv.sh
	`-- <i>(other board-specific configuration sub-directories)</i>/
patacongo's avatar
patacongo committed
<h3><a name="summaryofconfigfiles">2.3.2 Summary of Files</a></h3>
<h4><a name="boardlogic">2.3.2.1 Board Specific Logic</a></h4>
  <li>
    <code>include/</code>:
    This directory contains board specific header files.
    This directory will be linked as <code>include/arch/board</code> at configuration time
    and can be included via <code>#include &lt;arch/board/header.h&gt;</code>.
patacongo's avatar
patacongo committed
    These header file can only be included by files in <code>arch/</code><i>&lt;arch-name&gt;</i><code>/include/</code>
    and <code>arch/</code><i>&lt;arch-name&gt;</i><code>/src/</code>.
  <li>
    <code>src/</code>:
    This directory contains board specific drivers.
patacongo's avatar
patacongo committed
    This directory will be linked as <config>arch/</code><i>&lt;arch-name&gt;</i><code>/src/board</config> at configuration
    time and will be integrated into the build system.
  </li>
  <li>
    <code>src/Makefile</code>:
    This makefile will be invoked to build the board specific drivers.
    It must support the following targets:  <code>libext$(LIBEXT)</code>, <code>clean</code>, and <code>distclean</code>.
  </li>
patacongo's avatar
patacongo committed
</ul>
patacongo's avatar
patacongo committed
<h4><a name="boardconfigsubdirs">2.3.2.2 Board Specific Configuration Sub-Directories</a></h4>
patacongo's avatar
patacongo committed
<p>
  The <code>configs/</code><i>&lt;board-name&gt;</i><code>/</code> sub-directory holds all of the
  files that are necessary to configure Nuttx for the particular board.
patacongo's avatar
patacongo committed
  A board may have various different configurations using the common source files.
  Each board configuration is described by three files:  <code>Make.defs</code>, <code>defconfig</code>, and <code>setenv.sh</code>.
  Typically, each set of configuration files is retained in a separate configuration sub-directory
  (<i>&lt;config1-dir&gt;</i>, <i>&lt;config2-dir&gt;</i>, .. in the above diagram).

patacongo's avatar
patacongo committed
  The procedure for configuring NuttX is described <a href="#configuringnuttx">below</a>,
  This paragraph will describe the contents of these configuration files.
</p>
<ul>
  <li>
    <code>Make.defs</code>: This makefile fragment provides architecture and
    tool-specific build options.  It will be included by all other
    makefiles in the build (once it is installed).  This make fragment
    should define:
    <ul>
      <li>Tools: CC, LD, AR, NM, OBJCOPY, OBJDUMP</li>
      <li>Tool options: CFLAGS, LDFLAGS</li>
      <li>COMPILE, ASSEMBLE, ARCHIVE, CLEAN, and MKDEP macros</li>
    </ul>
    <p>
      When this makefile fragment runs, it will be passed TOPDIR which
      is the path to the root directory of the build.  This makefile
      fragment may include ${TOPDIR}/.config to perform configuration
      specific settings.  For example, the CFLAGS will most likely be
      different if CONFIG_DEBUG=y.
  </li>
  <li>
    <code>defconfig</code>: This is a configuration file similar to the Linux
patacongo's avatar
patacongo committed
    configuration file.  In contains variable/value pairs like:
    <ul>
      <li><code>CONFIG_VARIABLE</code>=value</li>
    </ul>
    <p>
      This configuration file will be used at build time:
    </p>
    <ol>
      <li>As a makefile fragment included in other makefiles, and</li>
      <li>to generate <code>include/nuttx/config.h</code> which is included by
          most C files in the system.</li>
    </ol>
  </li>
  <li>
    <code>setenv.sh</code>: This is a script that you can include that will be installed at
    the toplevel of the directory structure and can be sourced to set any
    necessary environment variables.
  </li>
</ul>

patacongo's avatar
patacongo committed
<h3><a name="supportedboards">2.3.3 Supported Boards</a></h3>
<p>
  All of the specific boards supported by NuttX are identified below.
  These are the specific <i>&lt;board-name&gt;</i>'s that may be used to configure NuttX
patacongo's avatar
patacongo committed
  as described <a href="#configuringnuttx">below</a>.
</p>
<ul>
  <li><code>configs/sim</code>:
    A user-mode port of NuttX to the x86 Linux platform is available.
    The purpose of this port is primarily to support OS feature developement.
    This port does not support interrupts or a real timer (and hence no
    round robin scheduler)  Otherwise, it is complete.
  </li>

  <li><code>configs/c5471evm</code>:
    This is a port to the Spectrum Digital C5471 evaluation board.  The
    C5471 is a dual core processor from TI with an ARM7TDMI general purpose
    processor and a c54 SDP.  NuttX runs on the ARM core and is built with
patacongo's avatar
patacongo committed
    with a GNU arm-elf toolchain* under Linux or Cygwin.
    This port is complete, verified, and included in the NuttX release.
  <li><code>configs/mcu123-lpc214x</code>:
    This port is for the NXP LPC2148 as provided on the mcu123.com
    lpc214x development board.
patacongo's avatar
patacongo committed
    This OS is also built with the arm-elf toolchain* under Linux or Cygwin.
    STATUS: This port is in progress and should be available in the
    nuttx-0.2.5 release.
  </li>
  <li><code>configs/ntosd-dm320</code>:
patacongo's avatar
patacongo committed
    This port uses the Neuros OSD with a GNU arm-elf toolchain* under Linux or Cygwin.
    See <a href="http://wiki.neurostechnology.com/index.php/Developer_Welcome">Neuros Wiki</a>
    for futher information.
    NuttX operates on the ARM9EJS of this dual core processor.
    STATUS: This port is code complete, verified, and included in the

  <li><code>configs/m68322evb</code>:
    This is a work in progress for the venerable m68322evb board from

  <li><code>configs/pjrc-8051</code>:
    8051 Microcontroller.  This port uses the PJRC 87C52 development system
patacongo's avatar
patacongo committed
    and the <a href="http://sdcc.sourceforge.net/">SDCC</a> toolchain under Linux or Cygwin.
patacongo's avatar
patacongo committed
    This port is not quite ready for prime time.
  </li>

  <li><code>configs/xtrs</code>
    TRS80 Model 3.  This port uses a vintage computer based on the Z80.
    An emulator for this computer is available to run TRS80 programs on a 
    linux platform (http://www.tim-mann.org/xtrs.html).
  </li>

patacongo's avatar
patacongo committed
  <li><code>configs/z16f2800100zcog</code>
    z16f Microcontroller.
patacongo's avatar
patacongo committed
    This port use the Zilog z16f2800100zcog development kit and the
    Zilog ZDS-II Windows command line tools.
    The development environment is Cygwin under WinXP.
patacongo's avatar
patacongo committed
  </li>

  <li><code>configs/z8encore000zco</code>
    z8Encore! Microcontroller.  This port use the Zilog z8encore000zco
patacongo's avatar
patacongo committed
    development kit, Z8F6403 part, and the Zilog ZDS-II Windows command line
patacongo's avatar
patacongo committed
    tools.  The development environment is Cygwin under WinXP.
  </li>
patacongo's avatar
patacongo committed
  <li><code>configs/z80sim</code>:
    z80 Microcontroller.  This port uses a Z80 instruction set simulator.
    That simulator can be found in the NuttX CVS
    <a href="http://nuttx.cvs.sourceforge.net/nuttx/misc/sims/z80sim/">here</a>.
    This port also the <a href="http://sdcc.sourceforge.net/">SDCC</a> toolchain
patacongo's avatar
patacongo committed
    under Linux or Cygwin(verfied with version 2.6.0).
</ul>

<p><small><blockquote>
  * A customized version of the <a href="http://www.buildroot.org">buildroot</a>
patacongo's avatar
patacongo committed
  is available to build these toolchains under Linux or Cygwin.
</blockquote></small></p>

<h2>2.4 <a name="DirStructDrivers">drivers</a></h2>
patacongo's avatar
patacongo committed

<p>
  This directory holds architecture-independent device drivers.
</p>

<h2>2.5 <a name="DirStructExamples">examples</a></h2>
patacongo's avatar
patacongo committed

<p>
  Example and test programs to build against.
</p>

<h2>2.6 <a name="DirStructFs">fs</a></h2>
patacongo's avatar
patacongo committed

<p>
patacongo's avatar
patacongo committed
  This directory contains the NuttX file system.
  This file system is described <a href="#NxFileSystem">below</a>.
patacongo's avatar
patacongo committed
</p>

<h2>2.7 <a name="DirStructInclude">include</a></h2>
patacongo's avatar
patacongo committed
<p>
  This directory holds NuttX header files.
  Standard header files file retained in can be included in the <i>normal</i> fashion:
</p>
<ul>
  <code>include &lt:stdio.h&gt</code><br>
  <code>include &lt;sys/types.h&gt;</code><br>
  etc.
</ul>

<h2>2.8 <a name="DirStructLib">lib</a></h2>
patacongo's avatar
patacongo committed
<p>
  This directory holds a collection of standard libc-like functions with custom
  interfaces into Nuttx.
</p>

<h2>2.9 <a name="DirStructMm">mm</a></h2>
patacongo's avatar
patacongo committed
<p>
  This is the NuttX memory manager.
</p>

patacongo's avatar
patacongo committed
<h2>2.10 <a name="DirStructNet">net</a></h2>
<p>
  This directory contains the implementation of the socket APIs.
  The subdirectory, <code>uip</code> contians the uIP port.
</P>

<h2>2.11 <a name="DirStructNetUtils">netutils</a></h2>
<p>
  This directory contains most of the network applications contained under the uIP-1.0 apps directory.
  As the uIP apps/README says, these applications "are not all heavily tested."
</p>

<h2>2.12 <a name="DirStructSched">sched</a></h2>
patacongo's avatar
patacongo committed
<p>
  The files forming core of the NuttX RTOS reside here.
</p>

patacongo's avatar
patacongo committed
<h2>2.13 <a name="DirStructTools">tools</a></h2>
patacongo's avatar
patacongo committed
<p>
  This directory holds a collection of tools and scripts to simplify
  configuring and building NuttX.
</p>

patacongo's avatar
patacongo committed
<h2>2.14 <a name="topmakefile">Makefile</a></h2>
patacongo's avatar
patacongo committed
<p>
  The top-level <code>Makefile</code> in the <code>${TOPDIR}</code> directory contains all of the top-level control
  logic to build NuttX.
  Use of this <code>Makefile</code> to build NuttX is described <a href="#buildingnuttx">below</a>.
</p>

patacongo's avatar
patacongo committed
<hr>
patacongo's avatar
patacongo committed
<h1>3.0 <a name="configandbuild">Configuring and Building</a></h1>
<h2><a name="configuringnuttx">3.1 Configuring NuttX</a></h2>
<p>
  <b>Manual Configuration</b>.
  Configuring NuttX requires only copying the
patacongo's avatar
patacongo committed
  <a href="#boardconfigsubdirs">board-specific configuration files</a> into the top level directory which appears in the make files as the make variable, <code>${TOPDIR}</code>.
patacongo's avatar
patacongo committed
  This could be done manually as follows:
</p>
<ul>
patacongo's avatar
patacongo committed
  <li>Copy <code>configs/</code><i>&lt;board-name&gt;</i><code>/[</code><i>&lt;config-dir&gt;</i><code>/]Make.def</code> to <code>${TOPDIR}/Make.defs</code>,<li>
  <li>Copy <code>configs/</code><i>&lt;board-name&gt;</i><code>/[</code><i>&lt;config-dir&gt;</i><code>/]setenv.sh</code> to <code>${TOPDIR}/setenv.sh</code>, and</li>
  <li>Copy <code>configs/</code><i>&lt;board-name&gt;</i><code>/[</code><i>&lt;config-dir&gt;</i><code>/]defconfig</code> to <code>${TOPDIR}/.config</code></li>
patacongo's avatar
patacongo committed
</ul>
<p>
  Where <i>&lt;board-name&gt;</i> is the name of one of the sub-directories of the
  NuttX <a href="#DirStructConfigs"><code>configs/</code></a> directory.
  This sub-directory name corresponds to one of the supported boards
  identified <a href="#supportedboards">above</a>.
patacongo's avatar
patacongo committed
  And &lt;config-dir&gt; is the optional, specific configuration directory for the board.
patacongo's avatar
patacongo committed
</p>
<p>
  <b>Automated Configuration</b>.
  There is a script that automates these steps.  The following steps will
  accomplish the same configuration:
</p>
<ul><pre>
  cd tools
patacongo's avatar
patacongo committed
  ./configure.sh <i>&lt;board-name&gt;</i></i><code>[/</code><i>&lt;config-dir&gt;</i><code>]</code>
patacongo's avatar
patacongo committed
</pre></ul>

<p>
  <b>Additional Configuration Steps</b>.
  The remainder of configuration steps will be performed by <a href="#topmakefile"><code>${TOPDIR}/Makefile</code></a>
  the first time the system is built as described below.
</p>

<h2><a name="buildingnuttx">3.2 Building NuttX</a></h2>
<p>
  <b>Building NuttX</b>.
   Once NuttX has been configured as described <a href="#configuringnuttx">above</a>, it may be built as follows:
</p>
<ul><pre>
cd ${TOPDIR}
source ./setenv.sh
make
</pre></ul>
<p>
  The <code>${TOPDIR}</code> directory holds:
</p>
<ul>
  <li>The top level <a href="#topmakefile"><code>Makefile</code></a> that controls the NuttX build.
</ul>
<p>
  That directory also holds:
</p>
<ul>
patacongo's avatar
patacongo committed
  <li>The makefile fragment <a href="#boardconfigsubdirs"><code>.config</code></a> that describes the current configuration.</li>
  <li>The makefile fragment <a href="#boardconfigsubdirs"><code>Make.defs</code></a> that provides customized build targers, and</li>
  <li>The shell script <a href="#boardconfigsubdirs"><code>setenv.sh</code></a> that sets up the configuration environment for the build.</li>
patacongo's avatar
patacongo committed
</ul>
<p>
patacongo's avatar
patacongo committed
The <a href="#boardconfigsubdirs"><code>setenv.sh</code></a> contains Linux/Cygwin environmental settings that are needed for the build.
The specific environmental definitions are unique for each board but should include, as a minimum, updates to the <code>PATH</code> variable to include the full path to the architecture-specific toolchain identified in <a href="#boardconfigsubdirs"><code>Make.defs</code></a>.
The <a href="#boardconfigsubdirs"><code>setenv.sh</code></a> only needs to be source'ed at the beginning of a session.
patacongo's avatar
patacongo committed
The system can be re-made subsequently by just typing <code>make</code>.
</p>
<p>
  <b>First Time Make.</b>
  Additional configuration actions will be taken the first time that system is built.
  These additional steps include:
</p>
<ul>
  <li>Auto-generating the file <code>include/nuttx/config.</code> using the <code>${TOPDIR}/.config</code> file.
  <li>Creating a link to <code>${TOPDIR}/arch/</code><i>&lt;arch-name&gt;</i><code>/include</code> at <code>${TOPDIR}/include/arch</code>.
  <li>Creating a link to <code>${TOPDIR}/configs/</code><i>&lt;board-name&gt;</i><code>/include</code> at <code>${TOPDIR}/include/arch/board</code>.
  <li>Creating a link to <code>${TOPDIR}/configs/</code><i>&lt;board-name&gt;</i><code>/src</code> at <code>${TOPDIR}/arch/</code><i>&lt;arch-name&gt;</i><code>/src/board</code>
  <li>Creating make dependencies.
</ul>
patacongo's avatar
patacongo committed

patacongo's avatar
patacongo committed
<h1>4.0 <a name="ArchAPIs">Architecture APIs</a></h1>

<p>
  The file <code>include/nuttx/arch.h</code> identifies by prototype all of the APIs that must
  be provided by the architecture specific logic.
  The internal OS APIs that architecture-specific logic must
  interface with also also identified in <code>include/nuttx/arch.h</code> or in
  other header files.
</p>

<h2><a name="imports">4.1 APIs Exported by Architecture-Specific Logic to NuttX</a></h2>
<h3><a name="upinitialize">4.1.1 <code>up_initialize()</code></a></h3>

<p><b>Prototype</b>: <code>void up_initialize(void);</code></p>

<p><b>Description</b>.
  <code>up_initialize()</code> will be called once during OS
  initialization after the basic OS services have been
  initialized.  The architecture specific details of
  initializing the OS will be handled here.  Such things as
  setting up interrupt service routines, starting the
  clock, and registering device drivers are some of the
  things that are different for each processor and hardware
  platform.
</p>
<p>
  <code>up_initialize()</code> is called after the OS initialized but
  before the init process has been started and before the
  libraries have been initialized.  OS services and driver
  services are available.
</p>

<h3><a name="upidle">4.1.2 <code>up_idle()</code></a></h3>
<p><b>Prototype</b>: <code>void up_idle(void);</code></p>

<p><b>Description</b>.
  <code>up_idle()</code> is the logic that will be executed
  when their is no other ready-to-run task.  This is processor
  idle time and will continue until some interrupt occurs to
  cause a context switch from the idle task.
</p>
<p>
  Processing in this state may be processor-specific. e.g.,
  this is where power management operations might be performed.
</p>

<h3><a name="upinitialstate">4.1.3 <code>up_initial_state()</code></a></h3>
<p><b>Prototype</b>: <code>void up_initial_state(FAR _TCB *tcb);</code></p>

<p><b>Description</b>.
  A new thread is being started and a new TCB
  has been created. This function is called to initialize
  the processor specific portions of the new TCB.
</p>
<p>
  This function must setup the intial architecture registers
  and/or  stack so that execution will begin at tcb->start
  on the next context switch.
</p>

<h3><a name="upcreatestack">4.1.4 <code>up_create_stack()</code></a></h3>
<p><b>Prototype</b>: <code>STATUS up_create_stack(FAR _TCB *tcb, size_t stack_size);</code></p>

<p><b>Description</b>.
  Allocate a stack for a new thread and setup
  up stack-related information in the TCB.
</p>
<p>
  The following TCB fields must be initialized:
</p>
<ul>
  <li><code>adj_stack_size</code>: Stack size after adjustment for hardware,
    processor, etc.  This value is retained only for debug
    purposes.</li>
  <li><code>stack_alloc_ptr</code>: Pointer to allocated stack</li>
  <li><code>adj_stack_ptr</code>: Adjusted <code>stack_alloc_ptr</code> for HW.  The
    initial value of the stack pointer.
</ul>
<p>
  This API is <i>NOT</i> required if <code>CONFIG_CUSTOM_STACK</code>
  is defined.
</p>

<p><b>Inputs</b>:</p?
<ul>
  <li>
    <code>tcb</code>: The TCB of new task.
  </li>
  <li>
    <code>stack_size</code>:  The requested stack size.  At least this much
    must be allocated.
  </li>
</ul>

<h3><a name="upusestack">4.1.5 <code>up_use_stack()</code></a></h3>
<p><b>Prototype</b>: 
  <code>STATUS up_use_stack(FAR _TCB *tcb, FAR void *stack, size_t stack_size);</code>
</p>

<p><b>Description</b>.
  Setup up stack-related information in the TCB
  using pre-allocated stack memory.
</p>
<p>
  The following TCB fields must be initialized:
</p>
<ul>
  <li><code>adj_stack_size</code>: Stack size after adjustment for hardware,
    processor, etc.  This value is retained only for debug
    purposes.</li>
  <li><code>stack_alloc_ptr</code>: Pointer to allocated stack</li>
  <li><code>adj_stack_ptr</code>: Adjusted <code>stack_alloc_ptr</code> for HW.  The
    initial value of the stack pointer.
</ul>
<p>
  This API is <i>NOT</i> required if <code>CONFIG_CUSTOM_STACK</code>
  is defined.
</p>

<p><b>Inputs:</b></p>
<ul>
  <li>
    <code>tcb</code>: The TCB of new task.
  </li>
  <li>
    <code>stack_size</code>:  The allocated stack size.
  </li>
</ul>

<h3><a name="upreleasestack">4.1.6 <code>up_release_stack()</code></a></h3>
<p><b>Prototype</b>: <code>void up_release_stack(FAR _TCB *dtcb);</code></p>

<p><b>Description</b>.
  A task has been stopped. Free all stack
  related resources retained int the defunct TCB.
</p>
<p>
  This API is <i>NOT</i> required if <code>CONFIG_CUSTOM_STACK</code>
  is defined.
</p>

<h3><a name="upunblocktask">4.1.7 <code>up_unblock_task()</code></a></h3>
<p><b>Prototype</b>: <code>void up_unblock_task(FAR _TCB *tcb);</code></p>

<p><b>Description</b>.
  A task is currently in an inactive task list
  but has been prepped to execute.  Move the TCB to the
  ready-to-run list, restore its context, and start execution.
</p>
<p>
  This function is called only from the NuttX scheduling
  logic.  Interrupts will always be disabled when this
  function is called.
</p>

<p><b>Inputs</b>:
<ul>
  <li><code>tcb</code>: Refers to the tcb to be unblocked.  This tcb is
    in one of the waiting tasks lists.  It must be moved to
    the ready-to-run list and, if it is the highest priority
    ready to run taks, executed.
  </li>
</ul>

<h3><a name="upblocktask">4.1.8 <code>up_block_task()</code></a></h3>
<p><b>Prototype</b>: <code>void up_block_task(FAR _TCB *tcb, tstate_t task_state);</code></p>

<p><b>Description</b>.
  The currently executing task at the head of
  the ready to run list must be stopped.  Save its context
  and move it to the inactive list specified by task_state.

  This function is called only from the NuttX scheduling
  logic.  Interrupts will always be disabled when this
  function is called.

<p><b>Inputs:</b></p>