Skip to content
Snippets Groups Projects
NuttxPortingGuide.html 126 KiB
Newer Older
patacongo's avatar
patacongo committed
<html>
<head>
<title>NuttX Porting Guide</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>
<table width ="100%">
  <tr align="center" bgcolor="#e4e4e4">
    <td>
      <h1><big><font color="#3c34ec">
        <i>NuttX RTOS Porting Guide</i>
      </font></big></h1>
patacongo's avatar
patacongo committed
      <p>Last Updated: December 4, 2010</p>
    </td>
  </tr>
</table>
patacongo's avatar
patacongo committed
<hr><hr>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
    <td>
  <h1>Table of Contents</h1>
    </td>
  </tr>
</table>

patacongo's avatar
patacongo committed
<ul>
  <a href="#Introduction">1.0 Introduction</a><br>
  <a href="#DirectoryStructure">2.0 Directory Structure</a>
    <a href="#DirStructDocumentation">2.1 Documentation</a></br>
    <a href="#DirStructArch">2.2 arch/</a>
patacongo's avatar
patacongo committed
    <ul>
      <a href="#archdirectorystructure">2.2.1 Subdirectory Structure</a><br>
      <a href="#summaryofarchfiles">2.2.2 Summary of Files</a><br>
      <a href="#supportedarchitectures">2.2.3 Supported Architectures</a>
patacongo's avatar
patacongo committed
    </ul>
    <a href="#DirStructBinFmt">2.2 binfmt/</a><br>
    <a href="#DirStructConfigs">2.4 configs/</a>
    <ul>
      <a href="#configsdirectorystructure">2.3.1 Subdirectory Structure</a><br>
      <a href="#summaryofconfigfiles">2.3.2 Summary of Files</a>
      <ul>
        <a href="#boardlogic">2.4.2.1 Board Specific Logic</a><br>
        <a href="#boardconfigsubdirs">2.3.2.2 Board Specific Configuration Sub-Directories</a>
      </ul>
      <a href="#supportedboards">2.4.3 Supported Boards</a>
    </ul>
    <a href="#DirStructDrivers">2.5 drivers/</a><br>
    <a href="#DirStructExamples">2.6 examples/</a><br>
    <a href="#DirStructFs">2.7 fs/</a><br>
    <a href="#DirStructGraphics">2.8 graphics/</a><br>
    <a href="#DirStructInclude">2.9 include/</a><br>
    <a href="#DirStructLib">2.10 lib/</a><br>
    <a href="#DirStructLibXX">2.11 libxx/</a><br>
    <a href="#DirStructMm">2.12 mm/</a><br>
    <a href="#DirStructNet">2.13 net</a><br>
    <a href="#DirStructNetUtils">2.14 netutils</a><br>
    <a href="#DirStructSched">2.15 sched/</a><br>
    <a href="#DirStructTools">2.16 tools/</a><br>
    <a href="#topmakefile">2.17 Makefile</a>
  <a href="#configandbuild">3.0 Configuring and Building</a>
patacongo's avatar
patacongo committed
  <ul>
    <a href="#configuringnuttx">3.1 Configuring NuttX</a><br>
    <a href="#buildingnuttx">3.2 Building NuttX</a>
patacongo's avatar
patacongo committed
  </ul>
  <a href="#ArchAPIs">4.0 Architecture APIs</a>
patacongo's avatar
patacongo committed
  <ul>
    <a href="#imports">4.1 APIs Exported by Architecture-Specific Logic to NuttX</a>
    <ul>
      <a href="#upinitialize">4.1.1 <code>up_initialize()</code></a><br>
      <a href="#upidle">4.1.2 <code>up_idle()</code></a><br>
      <a href="#upinitialstate">4.1.3 <code>up_initial_state()</code></a><br>
      <a href="#upcreatestack">4.1.4 <code>up_create_stack()</code></a><br>
      <a href="#upusestack">4.1.5 <code>up_use_stack()</code></a><br>
      <a href="#upreleasestack">4.1.6 <code>up_release_stack()</code></a><br>
      <a href="#upunblocktask">4.1.7 <code>up_unblock_task()</code></a><br>
      <a href="#upblocktask">4.1.8 <code>up_block_task()</code></a><br>
      <a href="#upreleasepending">4.1.9 <code>up_release_pending()</code></a><br>
      <a href="#upreprioritizertr">4.1.10 <code>up_reprioritize_rtr()</code></a><br>
      <a href="#_exit">4.1.11 <code>_exit()</code></a><br>
      <a href="#upassert">4.1.12 <code>up_assert()</code></a><br>
      <a href="#upschedulesigaction">4.1.13 <code>up_schedule_sigaction()</code></a><br>
      <a href="#upallocateheap">4.1.14 <code>up_allocate_heap()</code></a><br>
      <a href="#upinterruptcontext">4.1.15 <code>up_interrupt_context()</code></a><br>
      <a href="#updisableirq">4.1.16 <code>up_disable_irq()</code></a><br>
      <a href="#upenableirq">4.1.17 <code>up_enable_irq()</code></a><br>
      <a href="#upprioritizeirq">4.1.18 <code>up_prioritize_irq()</code></a></br>
      <a href="#upputc">4.1.19 <code>up_putc()</code></a>
    </ul>
    <a href="#exports">4.2 APIs Exported by NuttX to Architecture-Specific Logic</a>
    <ul>
      <a href="#osstart">4.2.1 <code>os_start()</code></a><br>
      <a href="#listmgmt">4.2.2 OS List Management APIs</a><br>
      <a href="#schedprocesstimer">4.2.3 <code>sched_process_timer()</code></a><br>
      <a href="#irqdispatch">4.2.4 <code>irq_dispatch()</code></a>
    </ul>
patacongo's avatar
patacongo committed
    <a href="#demandpaging">4.3 On-Demand Paging</a><br>
    <a href="#ledsupport">4.4 LED Support</a>
    <ul>
      <a href="#ledheaders">4.3.1 Header Files</a><br>
      <a href="#leddefinitions">4.3.2 LED Definitions</a><br>
      <a href="#ledapis">4.3.3 Common LED interfaces</a>
    </ul>
patacongo's avatar
patacongo committed
  </ul>
  <a href="#NxFileSystem">5.0 NuttX File System</a><br>
  <a href="#DeviceDrivers">6.0 NuttX Device Drivers</a><br>
  <ul>
    <a href="#chardrivers">6.1 Character Device Drivers</a><br>
    <a href="#blockdrivers">6.2 Block Device Drivers</a><br>
    <a href="#blockdrivers">6.3 Specialized Device Drivers</a>
    <ul>
       <a href="#ethdrivers">6.3.1 Ethernet Device Drivers</a><br>
       <a href="#spidrivers">6.3.2 SPI Device Drivers</a><br>
       <a href="#i2cdrivers">6.3.3 I2C Device Drivers</a><br>
patacongo's avatar
patacongo committed
       <a href="#serialdrivers">6.3.4 Serial Device Drivers</a><br>
       <a href="#fbdrivers">6.3.5 Frame Buffer Drivers</a><br>
patacongo's avatar
patacongo committed
       <a href="#mtddrivers">6.3.6 Memory Technology Device Drivers</a><br>
       <a href="#sdiodrivers">6.3.7 SDIO Device Drivers</a><br>
  <a href="#apndxconfigs">Appendix A: NuttX Configuration Settings</a><br>
  <a href="#apndxtrademarks">Appendix B:  Trademarks</a>
patacongo's avatar
patacongo committed
</ul>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
    <td>
      <h1>1.0 <a name="Introduction">Introduction</a></h1>
    </td>
  </tr>
</table>
patacongo's avatar
patacongo committed

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

<table width ="100%">
  <tr bgcolor="#e4e4e4">
    <td>
      <h1>2.0 <a name="DirectoryStructure">Directory Structure</a></h1>
    </td>
  </tr>
</table>
patacongo's avatar
patacongo committed

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>/
|-- <a href="#DirStructBinFmt">binfmt</a>/
|   |-- Makefile
|   |-- <i>(binfmt-specific sub-directories)</i>/
|   |   `-- <i>(binfmt-specific source files)</i>
|   `-- <i>(common binfmt source files)</i>
patacongo's avatar
patacongo committed
|-- <a href="#DirStructConfigs">configs</a>/
|   |-- <i>&lt;board-name&gt;</i>/
|   |   |-- include/
|   |   |   `-- <i>(other board-specific header files)</i>
patacongo's avatar
patacongo committed
|   |   |-- src/
|   |   |   `-- <i>(board-specific source files)</i>
|   |   |---<i>&lt;config-name&gt;</i>/
|   |   |   `-- <i>(board configuration-specific source files)</i>
|   |   `---<i>(other configuration sub-directories for this board)</i>/
patacongo's avatar
patacongo committed
|   `-- <i>&lt;(other board directories)&gt;</i>/
patacongo's avatar
patacongo committed
|-- <a href="#DirStructDrivers">drivers</a>/
|   |-- Makefile
|   |-- <i>(driver-specific sub-directories)/</i>
|   |   `-- <i>(driver-specific source files)</i>
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
|   |-- <i>(file system-specific sub-directories)</i>/
|   |   `-- <i>(file system-specific source files)</i>
patacongo's avatar
patacongo committed
|   `-- <i>(common file system source files)</i>
|-- <a href="#DirStructGraphics">graphics</a>/
|   |-- Makefile
|   |-- <i>(feature-specific sub-directories)</i>/
|   |   `-- <i>(feature-specific source files library source files)</i>
|   `-- <i>(common graphics-related source files)</i>
patacongo's avatar
patacongo committed
|-- <a href="#DirStructInclude">include</a>/
patacongo's avatar
patacongo committed
|   |-- <i>(standard header files)</i>
|   |-- <i>(standard include sub-directories)</i>
patacongo's avatar
patacongo committed
|   |   `-- <i>(more standard header files)</i>
|   |-- <i>(non-standard include sub-directories)</i>
|       `-- <i>(non-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>
|-- <a href="#DirStructLibXX">libxx</a>/
|   |-- Makefile
|   `-- <i>(libxx management 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>(BSD socket source files)</i>
patacongo's avatar
patacongo committed
|-- <a href="#DirStructNetUtils">netutils</a>/
|   |-- Makefile
|   |-- <i>(network feature sub-directories)</i>/
|   |   `-- <i>(network feature source files)</i>
|   `-- <i>(netutils common files)</i>
patacongo's avatar
patacongo committed
|-- <a href="#DirStructSched">sched</a>/
patacongo's avatar
patacongo committed
|   |-- Makefile
|   `-- <i>(sched source files)</i>
`-- <a href="#DirStructTools">tools</a>/
    `-- <i>(miscellaneous scripts and programs)</i>
patacongo's avatar
patacongo committed
</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>
<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>/
|   |-- arch.h
|   |-- irq.h
|   |-- types.h
|   `-- limits.h
`-- src/
    |--<i>&lt;chip-name&gt;</i>/
    |  `-- <i>(chip-specific source files)</i>
    |--<i>&lt;other-chips&gt;</i>/
    |-- 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>
      _int8_t, _uint8_t, _int16_t, _uint16_t, _int32_t, _uint32_t_t
patacongo's avatar
patacongo committed
    </code></ul>
    <p>and if the architecture supports 24- or 64-bit integers</p>
patacongo's avatar
patacongo committed
    <ul><code>
patacongo's avatar
patacongo committed
    </code></ul>
    <p>
      NOTE that these type names have a leading underscore character.  This
      file will be included(indirectly) by include/stdint.h and typedef'ed to
      the final name without the underscore character.  This roundabout way of
      doings things allows the stdint.h to be removed from the include/
      directory in the event that the user prefers to use the definitions
      provided by their toolchain header files
    </p>
    <p>
      And finally
patacongo's avatar
patacongo committed
    </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>
patacongo's avatar
patacongo committed
        <code>void irqrestore(irqstate_t flags)</code>:
patacongo's avatar
patacongo committed
        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>
patacongo's avatar
patacongo committed
   <b>Architecture- 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.
patacongo's avatar
patacongo committed
    The purpose of this port is primarily to support OS feature development.
patacongo's avatar
patacongo committed
    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 boots and passes the OS test (examples/ostest).
        The port is complete and verified.  As of NuttX 0.3.17, the port includes:
        timer interrupts, serial console, USB driver, and SPI-based MMC/SD card
        support.  A verified NuttShell configuration is also available.
    </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, ez80Acclaim! and z8Encore! Microcontrollers.
patacongo's avatar
patacongo committed
    <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/ez80</code> and <code>arch/z80/src/ez80</code>:
        The ez80Acclaim! port uses the ZiLOG ez80f0910200kitg development kit, eZ80F091 part,
        with the Zilog ZDS-II Windows command line tools.
        The development environment is Cygwin under WinXP.
        This is a work in progress.  Verified ez80 support will be announced in a future NuttX release.
      </li>

patacongo's avatar
patacongo committed
      <li><code>arch/z80/include/z8</code> and <code>arch/z80/src/z8</code>:
        The Z8Encore! port uses either the ZiLOG z8encore000zco development kit, Z8F6403 part,
        or the z8f64200100kit development kit, Z8F6423 part with the Zilog ZDS-II Windows command line
patacongo's avatar
patacongo committed
        tools.  The development environment is Cygwin under WinXP.
        The initial release, verified only on the ZDS-II ez8 simulator, was released in nuttx-0.3.9.
patacongo's avatar
patacongo committed
      </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
patacongo's avatar
patacongo committed
    <code>arch/arm/src/c5471</code>.
  </li>

  <li><code>arch/dm320</code>:
    Replaced with <code>arch/arm/include/dm320</code> and
patacongo's avatar
patacongo committed
    <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="DirStructBinFmt">binfmt</a></h2>

<p>
  The <code>binfmt/</code> subdirectory contains logic for loading binaries in the file
  system into memory in a form that can be used to execute them.
</p>

<h2>2.4 <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>
<i>&lt;board-name&gt;</i>
|-- include/
|   |-- board.h
|   `-- <i>(board-specific header files)</i>
|-- src/
|   |-- Makefile
|   `-- <i>(board-specific source files)</i>
|-- <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</code> 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
patacongo's avatar
patacongo committed
  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
patacongo's avatar
patacongo committed
    the top level of the directory structure and can be sourced to set any
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/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/ez80f0910200kitg</code>
    ez80Acclaim! Microcontroller.  This port use the Zilog ez80f0910200kitg
    development kit, eZ80F091 part, and the Zilog ZDS-II Windows command line
    tools.  The development environment is Cygwin under WinXP.
  </li>

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

  <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.
    The port supports serial, timer0, spi, and usb.
  <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>
patacongo's avatar
patacongo committed
    for further 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/olimex-strp711</code>:
    This port uses the Olimex STR-P711 board arm-elf toolchain* under Linux or Cygwin.
    See the <a href="http://www.olimex.com/dev/str-p711.html">Olimex</a> web site
patacongo's avatar
patacongo committed
    for further information.
    STATUS: Coding for the basic port -- serial console and system timer -- is complete
    but untested to problems I am having using OpenOCD with a wiggler clone JTAG.

  <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/sim</code>:
    A user-mode port of NuttX to the x86 Linux platform is available.
patacongo's avatar
patacongo committed
    The purpose of this port is primarily to support OS feature development.
    This port does not support interrupts or a real timer (and hence no
    round robin scheduler)  Otherwise, it is complete.
  </li>

  <li><code>configs/us7032evb1</code>:
    This is a port of the Hitachi SH-1 on the Hitachi SH-1/US7032EVB1 board.
    STATUS:  This port is available as of release 0.3.18 of NuttX.  The port is basically
    complete and many examples run correctly.  However, there are remaining instabilities
    that make the port un-usable.  The nature of these is not understood; the behavior is
    that certain SH-1 instructions stop working as advertised.  This could be a silicon
    problem, some pipeline issue that is not handled properly by the gcc 3.4.5 toolchain
    (which has very limited SH-1 support to begin with), or perhaps with the CMON debugger.
    At any rate, I have exhausted all of the energy that I am willing to put into this cool
    old processor for the time being.
  </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 
patacongo's avatar
patacongo committed
    Linux platform (http://www.tim-mann.org/xtrs.html).
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/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(verified with version 2.6.0).
patacongo's avatar
patacongo committed
  <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>
  <li><code>configs/z8encore000zco</code>
    z8Encore! Microcontroller.  This port use the Zilog z8f64200100kit
    development kit, Z8F6423 part, and the Zilog ZDS-II Windows command line
    tools.  The development environment is Cygwin under WinXP.
  </li>
</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.
<h2>2.5 <a name="DirStructDrivers">drivers</a></h2>
patacongo's avatar
patacongo committed

<p>
  This directory holds architecture-independent device drivers.
</p>
<ul><pre>
drivers/
|-- Makefile
|-- bch/
|   |-- Make.defs
|   `-- <i>(bch driver source files)</i>
|-- mmcsd/
|   |-- Make.defs
|   `-- <i>(mmcsd driver source files)</i>
|-- net/
|   |-- Make.defs
|   `-- <i>(net driver source files)</i>
|-- usbdev/
|   |-- Make.defs
|   `-- <i>(usbdev driver source files)</i>
`-- <i>(common driver source files)</i>
</pre></ul>
patacongo's avatar
patacongo committed

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

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

<h2>2.7 <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>
<ul><pre>
fs/
|-- Makefile
|-- fat/
|   |-- Make.defs
|   `-- <i>(fat file system source files)</i>
|-- romfs/
|   |-- Make.defs
|   `-- <i>(romfs file system source files)</i>
 `-- <i>(common file system source files)</i>
</pre></ul>

<h2>2.8 <a name="DirStructGraphics">graphics</a></h2>

<p>
  This directory contains files for graphics/video support under NuttX.
</p>
<ul><pre>
graphics/
|-- Makefile
|-- nxglib/
|   |-- Make.defs
|   `-- <i>(NuttX graphics library source files)</i>
|-- nx/
|   |-- Make.defs
patacongo's avatar
patacongo committed
|   `-- <i>(NuttX X-server source files)</i>
`-- <i>(common file system source files)</i>
</pre></ul>
patacongo's avatar
patacongo committed

<h2>2.9 <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>
patacongo's avatar
patacongo committed
  <code>include &lt;sys/types.h&gt;</code><br>
  etc.
</ul>
<p>
  Directory structure:
</p>
<ul><pre>
include/
|-- <i>(standard header files)</i>
|-- arpa/
|   `-- <i>(standard header files)</i>
|-- net/
|   `-- uip/
|       `-- <i>(uIP specific header files)</i>
|-- netinet/
|   `-- <i>(standard header files)</i>
|-- nuttx/
|   `-- <i>(nuttx specific header files)</i>
`- sys/
    `-- <i>(more standard header files)</i>
</per></ul>

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

<h2>2.11 <a name="DirStructLibXX">libxx</a></h2>
<p>
  This directory holds a tiny, minimal standard std C++ that can be used to
  build some, simple C++ applications in NuttX.
</p>

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

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

<h2>2.14 <a name="DirStructNetUtils">netutils</a></h2>
patacongo's avatar
patacongo committed
<p>
  This directory contains most of the network applications.
patacongo's avatar
patacongo committed
  Some of these are original with NuttX (like tftpc and dhcpd) and others were leveraged from the uIP-1.0 apps directory.
  As the uIP apps/README says, these applications &quot;are not all heavily tested.&quot;
patacongo's avatar
patacongo committed
</p>
<ul><pre>
netutils/
|-- Makefile
|-- dhcp/
|   |-- Make.defs
|   `-- <i>(dhcp source files)</i>
|-- dhcpd/
|   |-- Make.defs
|   `-- <i>(dhcpd source files)</i>
|-- resolv/
|   |-- Make.defs
|   `-- <i>(resolv source files)</i>
|-- smtp/
|   |-- Make.defs
|   `-- <i>(smtp source files)</i>
|-- telnetd/
|   |-- Make.defs
|   `-- <i>(telnetd source files)</i>
|-- tftpc/
|   |-- Make.defs
|   `-- <i>(tftpc source files)</i>
|-- uiplib/
|   |-- Make.defs
|   `-- <i>(uiplib source files)</i>
|-- weblclient/
|   |-- Make.defs
|   `-- <i>(webclient source files)</i>
|-- webserver/
|   |-- Make.defs
|   `-- <i>(webserver source files)</i>
`-- <i>(netutils common files)</i>
</pre></ul>
patacongo's avatar
patacongo committed

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

<h2>2.16 <a name="DirStructTools">tools</a></h2>
patacongo's avatar
patacongo committed
<p>
  This directory holds a collection of tools and scripts to simplify
  configuring, building and maintaining NuttX.
patacongo's avatar
patacongo committed
</p>
<ul><pre>
tools/
|-- Makefile.mkconfig
|-- configure.sh
|-- incdir.sh
|-- indent.sh
|-- link.sh
|-- mkconfig.c
|-- mkdeps.sh
|-- mkimage.sh
|-- mknulldeps.sh
|-- unlink.sh
|-- winlink.sh
`-- zipme
</pre></ul>
patacongo's avatar
patacongo committed

<h2>2.17 <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>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
    <td>
      <h1>3.0 <a name="configandbuild">Configuring and Building</a></h1>
    </td>
  </tr>
</table>

patacongo's avatar
patacongo committed
<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}