18e3cfd272
git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@406 42af7a65-404d-4744-a932-0658087f49c3
1472 lines
50 KiB
HTML
1472 lines
50 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<title>NuttX Porting Manual</title>
|
|
<meta name="author" content="Gregory Nutt">
|
|
</head>
|
|
|
|
<body background="backgd.gif">
|
|
<hr>
|
|
<center><h1><i>Under Construction</i></h1></center>
|
|
<hr>
|
|
<center>
|
|
<big><b>
|
|
<p>NuttX Operating System</p>
|
|
<p>Porting Guide</p>
|
|
</b></big>
|
|
<p><small>by</small></p>
|
|
<p>Gregory Nutt</p>
|
|
<p><small>Last Update: September 8, 2007</small></p>
|
|
</center>
|
|
|
|
<center><h1>Table of Contents</h1></center>
|
|
<li><a href="#Introduction">1.0 Introduction</a></li>
|
|
<li><a href="#DirectoryStructure">2.0 Directory Structure</a></li>
|
|
<ul>
|
|
<li><a href="#DirStructDocumentation">2.1 Documentation</a></li>
|
|
<l1><a href="#DirStructArch">2.2 arch/</a></li>
|
|
<ul>
|
|
<li><a href="#archdirectorystructure">2.2.1 Subdirectory Structure</a></li>
|
|
<li><a href="#summaryofarchfiles">2.2.2 Summary of Files</a></li>
|
|
<li><a href="#supportedarchitectures">2.2.3 Supported Architectures</a></li>
|
|
</ul>
|
|
<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>
|
|
<ul>
|
|
<li><a href="#boardlogic">2.3.2.1 Board Specific Logic</a></li>
|
|
<li><a href="#boardconfigfiles">2.3.2.2 Board Specific Configuration Files</a></li>
|
|
</ul>
|
|
<li><a href="#supportedboards">2.3.3 Supported Boards</a></li>
|
|
</ul>
|
|
<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>
|
|
<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>
|
|
</ul>
|
|
<li><a href="#configandbuild">3.0 Configuring and Building</a></li>
|
|
<ul>
|
|
<li><a href="#configuringnuttx">3.1 Configuring NuttX</a></li>
|
|
<li><a href="#buildingnuttx">3.2 Building NuttX</a></li>
|
|
</ul>
|
|
<li><a href="#ArchAPIs">4.0 Architecture APIs</a></li>
|
|
<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>
|
|
<li><a href="#apndxconfigs">Appendix A: NuttX Configuration Settings</a></li>
|
|
|
|
<hr>
|
|
<h1>1.0 <a name="Introduction">Introduction</a></h1>
|
|
|
|
<p><b>Overview</b>
|
|
This document provides and overview of the NuttX build and configuration
|
|
logic and provides hints for the incorporation of new processor/board archectures
|
|
into the build.
|
|
</p>
|
|
<p>
|
|
See also <code>arch/README.txt</code> and <code>configs/README.txt</code>.
|
|
</p>
|
|
|
|
<p><b>General Philosophy</b>.
|
|
|
|
<hr>
|
|
<h1>2.0 <a name="DirectoryStructure">Directory Structure</a></h1>
|
|
|
|
<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>
|
|
<ul><pre>
|
|
.
|
|
|-- <a href="#topmakefile">Makefile</a>
|
|
|-- <a href="#DirStructDocumentation">Documentation</a>
|
|
| `-- <i>(documentation files)</i>/
|
|
|-- <a href="#DirStructArch">arch</a>/
|
|
| |-- <i><arch-name></i>/
|
|
| | |-- include/
|
|
| | | |--<i><chip-name></i>/
|
|
| | | | `-- <i>(chip-specific header files)</i>
|
|
| | | |--<i><other-chips></i>/
|
|
| | | `-- <i>(architecture-specific header files)</i>
|
|
| | `-- src/
|
|
| | |--<i><chip-name></i>/
|
|
| | | `-- <i>(chip-specific source files)</i>
|
|
| | |--<i><other-chips></i>/
|
|
| | `-- <i>(architecture-specific source files)</i>
|
|
| `-- <i><other-architectures></i>/
|
|
|-- <a href="#DirStructConfigs">configs</a>/
|
|
| |-- <i><board-name></i>/
|
|
| | |-- include/
|
|
| | | `-- <i>(board-specific header files)</i>
|
|
| | |-- src/
|
|
| | | |-- Makefile
|
|
| | | `-- <i>(board-specific source files)</i>
|
|
| | `-- <i>(board-specific configuration files)</i>
|
|
| `-- <i><other-boards></i>/
|
|
|-- <a href="#DirStructDrivers">drivers</a>/
|
|
| |-- Makefile
|
|
| `-- <i>(common driver source files)</i>
|
|
|-- <a href="#DirStructExamples">examples</a>/
|
|
| `-- <i>(example)</i>/
|
|
| |-- Makefile
|
|
| `-- <i>(example source files)</i>
|
|
|-- <a href="#DirStructFs">fs</a>/
|
|
| |-- Makefile
|
|
| `-- <i>(common file system source files)</i>
|
|
|-- <a href="#DirStructInclude">include</a>/
|
|
| |-- <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>
|
|
|-- <a href="#DirStructLib">lib</a>/
|
|
| |-- Makefile
|
|
| `-- <i>(lib source files)</i>
|
|
|-- <a href="#DirStructMm">mm</a>/
|
|
| |-- Makefile
|
|
| `-- <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>
|
|
|-- <a href="#DirStructSched">sched</a>/
|
|
| |-- Makefile
|
|
| `-- <i>(sched source files)</i>
|
|
`-- <a href="#DirStructDrivers">tools</a>/
|
|
|-- Makefile.mkconfig
|
|
|-- configure.sh
|
|
|-- mkconfig.c
|
|
|-- mkdeps.sh
|
|
`-- zipme
|
|
</pre></ul>
|
|
|
|
<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><arch-name></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><arch-name></i><code>/</code> directory and are selected via
|
|
the <code>CONFIG_ARCH_name</code> selection.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Board specific files</i>.
|
|
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><board-name></i><code>/</code> sub-directories and are discussed
|
|
in a a paragraph <a href="#configsdirectorystructure">below</a>.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h2>2.1 <a name="DirStructDocumentation">Documentation</a></h2>
|
|
|
|
<p>
|
|
General documentation for the NuttX OS resides in this directory.
|
|
</p>
|
|
|
|
<h2>2.2 <a name="DirStructArch">arch</a></h2>
|
|
|
|
<h3><a name="archdirectorystructure">2.2.1 Subdirectory Structure</a></h3>
|
|
<p>
|
|
This directory contains several sub-directories, each containing
|
|
architecture-specific logic.
|
|
The task of porting NuttX to a new processor consists of
|
|
add a new sudirectory under <code>arch/</code> containing logic specific
|
|
to the new architecuture.
|
|
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).
|
|
Each architecture must provide a subdirectory, <i><arch-name></i>
|
|
under <code>arch/</code> with the following characteristics:
|
|
</p>
|
|
<ul><pre>
|
|
<i><arch-name></i>/
|
|
|-- include/
|
|
| |--<i><chip-name></i>/
|
|
| | `-- <i>(chip-specific header files)</i>
|
|
| |--<i><other-chips></i>/
|
|
| |-- arch.h
|
|
| |-- irq.h
|
|
| |-- types.h
|
|
| `-- limits.h
|
|
`-- src/
|
|
|--<i><chip-name></i>/
|
|
| `-- <i>(chip-specific source files)</i>
|
|
|--<i><other-chips></i>/
|
|
|-- Makefile
|
|
`-- <i>(architecture-specific source files)</i>
|
|
</pre></ul>
|
|
|
|
<h3><a name="summaryofarchfiles">2.2.2 Summary of Files</a></h3>
|
|
<ul>
|
|
<li>
|
|
<code>include/</code><i><chip-name></i><code>/</code>
|
|
This sub-directory contains chip-specific header files.
|
|
</li>
|
|
<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>
|
|
<li>
|
|
<code>src/</code><i><chip-name></i><code>/</code>
|
|
This sub-directory contains chip-specific source files.
|
|
</li>
|
|
<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
|
|
<code>arch/</code><i><arch-name></i><code>/arch.h</code> as described above).
|
|
</li>
|
|
</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>
|
|
<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>
|
|
<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>
|
|
<li><code>arch/arm/include</code> and <code>arch/arm/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>
|
|
|
|
<li><code>arch/m68322</code>
|
|
A work in progress.</li>
|
|
</li>
|
|
|
|
<li><code>arch/pjrc-8051</code>:
|
|
8051 Microcontroller. This port is not quite ready for prime time.</li>
|
|
</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>
|
|
</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 <board-name> under <code>configs/</code> with the following characteristics:
|
|
</p>
|
|
<ul><pre>
|
|
<i><board-name></i>
|
|
|-- include/
|
|
| `-- <i>(board-specific header files)</i>
|
|
|-- src/
|
|
| |-- Makefile
|
|
| `-- <i>(board-specific source files)</i>
|
|
|-- Make.defs
|
|
|-- defconfig
|
|
`-- setenv.sh
|
|
</pre></ul>
|
|
|
|
<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>
|
|
<ul>
|
|
<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 <arch/board/header.h></code>.
|
|
These header file can only be included by files in <code>arch/</code><i><arch-name></i><code>/include/</code>
|
|
and <code>arch/</code><i><arch-name></i><code>/src/</code>.
|
|
</li>
|
|
<li>
|
|
<code>src/</code>:
|
|
This directory contains board specific drivers.
|
|
This directory will be linked as <config>arch/</code><i><arch-name></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>
|
|
</ul>
|
|
<h4><a name="boardconfigfiles">2.3.2.2 Board Specific Configuration Files</a></h4>
|
|
<p>
|
|
The <code>configs/</code><i><board-name></i><code>/</code> sub-directory holds all of the
|
|
files that are necessary to configure Nuttx for the particular board.
|
|
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>
|
|
</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.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<code>defconfig</code>: This is a configuration file similar to the Linux
|
|
configuration file. In contains varialble/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>
|
|
|
|
<h3><a name="supportedboards">2.3.3 Supported Boards</a></h3>
|
|
<p>
|
|
All of the specific boards supported by NuttX are identified below.
|
|
These the the specific <i><board-name></i>'s that may be used to configure NuttX
|
|
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
|
|
with a GNU arm-elf toolchain*. This port is complete, verified, and
|
|
included in the NuttX release.
|
|
</li>
|
|
|
|
<li><code>configs/mcu123-lpc214x</code>:
|
|
This port is for the NXP LPC2148 as provided on the mcu123.com
|
|
lpc214x development board.
|
|
This OS is also built with the arm-elf toolchain*.
|
|
STATUS: This port is in progress and should be available in the
|
|
nuttx-0.2.5 release.
|
|
</li>
|
|
|
|
<li><code>configs/ntosd-dm320</code>:
|
|
This port uses the Neuros OSD with a GNU arm-elf toolchain*.
|
|
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
|
|
NuttX 0.2.1 release.
|
|
</li>
|
|
|
|
<li><code>configs/m68322evb</code>:
|
|
This is a work in progress for the venerable m68322evb board from
|
|
Motorola.
|
|
</li>
|
|
|
|
<li><code>configs/pjrc-8051</code>:
|
|
8051 Microcontroller. This port uses the PJRC 87C52 development system
|
|
and the SDCC toolchain. This port is not quite ready for prime time.
|
|
</li>
|
|
</ul>
|
|
|
|
<p><small><blockquote>
|
|
* A customized version of the <a href="http://www.buildroot.org">buildroot</a>
|
|
is available to build these toolchains.
|
|
</blockquote></small></p>
|
|
|
|
<h2>2.4 <a name="DirStructDrivers">drivers</a></h2>
|
|
|
|
<p>
|
|
This directory holds architecture-independent device drivers.
|
|
</p>
|
|
|
|
<h2>2.5 <a name="DirStructExamples">examples</a></h2>
|
|
|
|
<p>
|
|
Example and test programs to build against.
|
|
</p>
|
|
|
|
<h2>2.6 <a name="DirStructFs">fs</a></h2>
|
|
|
|
<p>
|
|
This directory contains the NuttX filesystem.
|
|
The NuttX filesystem is very simple; it does not involve any block drivers or
|
|
particular filesystem (like FAT or EXT2 etc.).
|
|
The NuttX filesystem simply supports a set a filesystem APIs
|
|
(<code>open()</code>, <code>close()</code>, <code>read()</code>, <code>write</code>, etc.)
|
|
and a registration mechanism that allows devices drivers to a associated with <i>nodes</i>
|
|
in a file-system-like name space.
|
|
</p>
|
|
|
|
<h2>2.7 <a name="DirStructInclude">include</a></h2>
|
|
<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 <:stdio.h></code><br>
|
|
<code>include <sys/types.h></code><br>
|
|
etc.
|
|
</ul>
|
|
|
|
<h2>2.8 <a name="DirStructLib">lib</a></h2>
|
|
<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>
|
|
<p>
|
|
This is the NuttX memory manager.
|
|
</p>
|
|
|
|
<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>
|
|
<p>
|
|
The files forming core of the NuttX RTOS reside here.
|
|
</p>
|
|
|
|
<h2>2.13 <a name="DirStructTools">tools</a></h2>
|
|
<p>
|
|
This directory holds a collection of tools and scripts to simplify
|
|
configuring and building NuttX.
|
|
</p>
|
|
|
|
<h2>2.14 <a name="topmakefile">Makefile</a></h2>
|
|
<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>
|
|
|
|
<hr>
|
|
<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
|
|
<a href="#boardconfigfiles">board-specific configuration files</a> into the top level directory which appears in the make files as the make variable, <code>${TOPDIR}</code>.
|
|
This could be done manually as follows:
|
|
</p>
|
|
<ul>
|
|
<li>Copy <code>configs/</code><i><board-name></i></code>/Make.def</code> to <code>${TOPDIR}/Make.defs</code>,<li>
|
|
<li>Copy <code>configs/</code><i><board-name></i></code>/setenv.sh</code> to <code>${TOPDIR}/setenv.sh</code>, and</li>
|
|
<li>Copy <code>configs/</code><i><board-name></i></code>/defconfig</code> to <code>${TOPDIR}/.config</code></li>
|
|
</ul>
|
|
<p>
|
|
Where <i><board-name></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>.
|
|
</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
|
|
./configure.sh <i><board-name></i>
|
|
</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>
|
|
<li>The makefile fragment <a href="#boardconfigfiles"><code>.config</code></a> that describes the current configuration.</li>
|
|
<li>The makefile fragment <a href="#boardconfigfiles"><code>Make.defs</code></a> that provides customized build targers, and</li>
|
|
<li>The shell script <a href="#boardconfigfiles"><code>setenv.sh</code></a> that sets up the configuration environment for the build.</li>
|
|
</ul>
|
|
<p>
|
|
The <a href="#boardconfigfiles"><code>setenv.sh</code></a> contains Linux 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="#boardconfigfiles"><code>Make.defs</code></a>.
|
|
The <a href="#boardconfigfiles"><code>setenv.sh</code></a> only needs to be source'ed at the beginning of a session.
|
|
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><arch-name></i><code>/include</code> at <code>${TOPDIR}/include/arch</code>.
|
|
<li>Creating a link to <code>${TOPDIR}/configs/</code><i><board-name></i><code>/include</code> at <code>${TOPDIR}/include/arch/board</code>.
|
|
<li>Creating a link to <code>${TOPDIR}/configs/</code><i><board-name></i><code>/src</code> at <code>${TOPDIR}/arch/</code><i><arch-name></i><code>/src/board</code>
|
|
<li>Creating make dependencies.
|
|
</ul>
|
|
|
|
<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>
|
|
<ul>
|
|
<li><code>tcb</code>: Refers to a task in the ready-to-run list (normally
|
|
the task at the the head of the list). It most be
|
|
stopped, its context saved and moved into one of the
|
|
waiting task lists. It it was the task at the head
|
|
of the ready-to-run list, then a context to the new
|
|
ready to run task must be performed.
|
|
</li>
|
|
<li><code>task_state</code>: Specifies which waiting task list should be
|
|
hold the blocked task TCB.
|
|
</li>
|
|
</ul>
|
|
|
|
<h3><a name="upreleasepending">4.1.9 <code>up_release_pending()</code></a></h3>
|
|
<p><b>Prototype</b>: <code>void up_release_pending(void);</code></p>
|
|
|
|
<p><b>Description</b>.
|
|
When tasks become ready-to-run but cannot run because pre-emption
|
|
is disabled, they are placed into a pending task list.
|
|
This function releases and makes ready-to-run all of the tasks that have
|
|
collected in the pending task list. This can cause a
|
|
context switch if a new task is placed at the head of
|
|
the ready to run list.
|
|
</p>
|
|
<p>
|
|
This function is called only from the NuttX scheduling logic when
|
|
pre-emption is re-enabled. Interrupts will always be disabled when this
|
|
function is called.
|
|
</p>
|
|
|
|
<h3><a name="upreprioritizertr">4.1.10 <code>up_reprioritize_rtr()</code></a></h3>
|
|
<p><b>Prototype</b>: <code>void up_reprioritize_rtr(FAR _TCB *tcb, ubyte priority);</code></p>
|
|
|
|
<p><b>Description</b>.
|
|
Called when the priority of a running or
|
|
ready-to-run task changes and the reprioritization will
|
|
cause a context switch. Two cases:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
The priority of the currently running task drops and the next
|
|
task in the ready to run list has priority.
|
|
</li>
|
|
<li>
|
|
An idle, ready to run task's priority has been raised above the
|
|
the priority of the current, running task and it now has the
|
|
priority.
|
|
</li>
|
|
</ol>
|
|
<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></p>
|
|
<ul>
|
|
<li>
|
|
<code>tcb</code>: The TCB of the task that has been reprioritized
|
|
</li>
|
|
<li>
|
|
<code>priority</code>: The new task priority
|
|
</li>
|
|
</ul>
|
|
|
|
<h3><a name="_exit">4.1.11 <code>_exit()</code></a></h3>
|
|
<p><b>Prototype</b>: <code>void _exit(int status) noreturn_function;</code></p>
|
|
|
|
<p><b>Description</b>.
|
|
This function causes the currently executing task to cease
|
|
to exist. This is a special case of task_delete().
|
|
</p>
|
|
<p>
|
|
Unlike other UP APIs, this function may be called
|
|
directly from user programs in various states. The
|
|
implementation of this function should diable interrupts
|
|
before performing scheduling operations.
|
|
</p>
|
|
|
|
<h3><a name="upassert">4.1.12 <code>up_assert()</code></a></h3>
|
|
<p><b>Prototype</b>:<br>
|
|
<code>void up_assert(FAR const ubyte *filename, int linenum);</code></br>
|
|
<code>void up_assert_code(FAR const ubyte *filename, int linenum, int error_code);</code></br>
|
|
</p>
|
|
|
|
<p><b>Description</b>.
|
|
Assertions may be handled in an architecture-specific
|
|
way.
|
|
</p>
|
|
|
|
<h3><a name="upschedulesigaction">4.1.13 <code>up_schedule_sigaction()</code></a></h3>
|
|
<p><b>Prototype</b>:
|
|
<code>void up_schedule_sigaction(FAR _TCB *tcb, sig_deliver_t sigdeliver);</code>
|
|
</p>
|
|
|
|
<p><b>Description</b>.
|
|
This function is called by the OS when one or more
|
|
signal handling actions have been queued for execution.
|
|
The architecture specific code must configure things so
|
|
that the 'igdeliver' callback is executed on the thread
|
|
specified by 'tcb' as soon as possible.
|
|
</p>
|
|
<p>
|
|
This function may be called from interrupt handling logic.
|
|
</p>
|
|
<p>
|
|
This operation should not cause the task to be unblocked
|
|
nor should it cause any immediate execution of sigdeliver.
|
|
Typically, a few cases need to be considered:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
This function may be called from an interrupt handler
|
|
During interrupt processing, all xcptcontext structures
|
|
should be valid for all tasks. That structure should
|
|
be modified to invoke sigdeliver() either on return
|
|
from (this) interrupt or on some subsequent context
|
|
switch to the recipient task.
|
|
</li>
|
|
<li>
|
|
If not in an interrupt handler and the tcb is NOT
|
|
the currently executing task, then again just modify
|
|
the saved xcptcontext structure for the recipient
|
|
task so it will invoke sigdeliver when that task is
|
|
later resumed.
|
|
</li>
|
|
<li>
|
|
If not in an interrupt handler and the tcb IS the
|
|
currently executing task -- just call the signal
|
|
handler now.
|
|
</li>
|
|
</ol>
|
|
<p>
|
|
This API is <i>NOT</i> required if <code>CONFIG_DISABLE_SIGNALS</code>
|
|
is defined.
|
|
</p>
|
|
|
|
<h3><a name="upallocateheap">4.1.14 <code>up_allocate_heap()</code></a></h3>
|
|
<p><b>Prototype</b>: <code>void up_allocate_heap(FAR void **heap_start, size_t *heap_size);</code></p>
|
|
|
|
<p><b>Description</b>.
|
|
The heap may be statically allocated by
|
|
defining CONFIG_HEAP_BASE and CONFIG_HEAP_SIZE. If these
|
|
are not defined, then this function will be called to
|
|
dynamically set aside the heap region.
|
|
</p>
|
|
<p>
|
|
This API is <i>NOT</i> required if <code>CONFIG_HEAP_BASE</code>
|
|
is defined.
|
|
</p>
|
|
|
|
<h3><a name="upinterruptcontext">4.1.15 <code>up_interrupt_context()</code></a></h3>
|
|
<p><b>Prototype</b>: <code>boolean up_interrupt_context(void)</code></p>
|
|
|
|
<p><b>Description</b>.
|
|
Return TRUE is we are currently executing in
|
|
the interrupt handler context.
|
|
</p>
|
|
|
|
<h3><a name="updisableirq">4.1.16 <code>up_disable_irq()</code></a></h3>
|
|
<p><b>Prototype</b>: <code>void up_disable_irq(int irq);</code></p>
|
|
|
|
<p><b>Description</b>.
|
|
Disable the IRQ specified by 'irq'
|
|
</p>
|
|
|
|
<h3><a name="upenableirq">4.1.17 <code>up_enable_irq()</code></a></h3>
|
|
<p><b>Prototype</b>: <code>void up_enable_irq(int irq);</code></p>
|
|
|
|
<p><b>Description</b>.
|
|
Enable the IRQ specified by 'irq'
|
|
</p>
|
|
|
|
<h3><a name="upputc">4.1.18 <code>up_putc()</code></a></h3>
|
|
|
|
<p><b>Prototype</b>: <code>int up_putc(int ch);</code></p>
|
|
<p><b>Description</b>.
|
|
This is a debug interface exported by the architecture-specific logic.
|
|
Output one character on the console
|
|
<p>
|
|
This API is <i>NOT</i> required if <code>CONFIG_HEAP_BASE</code>
|
|
is defined.
|
|
</p>
|
|
|
|
<h2><a name="exports">4.2 APIs Exported by NuttX to Architecture-Specific Logic</a></h2>
|
|
<p>
|
|
These are standard interfaces that are exported by the OS
|
|
for use by the architecture specific logic.
|
|
</p>
|
|
|
|
<h3><a name="osstart">4.2.1 <code>os_start()</code></a></h3>
|
|
<p>
|
|
<b><i>To be provided</i></b>
|
|
</p>
|
|
|
|
<h3><a name="listmgmt">4.2.2 OS List Management APIs</a></h3></h3>
|
|
<p>
|
|
<b><i>To be provided</i></b>
|
|
</p>
|
|
|
|
<h3><a name="schedprocesstimer">4.2.3 <code>sched_process_timer()</code></a></h3>
|
|
<p><b>Prototype</b>: <code>void sched_process_timer(void);</code></p>
|
|
|
|
<p><b>Description</b>.
|
|
This function handles system timer events.
|
|
The timer interrupt logic itself is implemented in the
|
|
architecture specific code, but must call the following OS
|
|
function periodically -- the calling interval must be
|
|
<code>MSEC_PER_TICK</code>.
|
|
</p>
|
|
|
|
<h3><a name="irqdispatch">4.2.4 <code>irq_dispatch()</code></a></h3>
|
|
<p><b>Prototype</b>: <code>void irq_dispatch(int irq, FAR void *context);</code></p>
|
|
|
|
<p><b>Description</b>.
|
|
This function must be called from the achitecture-
|
|
specific logic in order to dispaly an interrupt to
|
|
the appropriate, registered handling logic.
|
|
</p>
|
|
|
|
<h1><a name="apndxconfigs">Appendix A: NuttX Configuration Settings</a></h1>
|
|
|
|
<p>
|
|
The following variables are recognized by the build (you may
|
|
also include architecture-specific settings).
|
|
</p>
|
|
|
|
<h2>Architecture selection</h2>
|
|
<p>
|
|
The following configuration itemes select the architecture, chip, and
|
|
board configuration for the build.
|
|
</p>
|
|
<ul>
|
|
<li><code>CONFIG_ARCH</code>:
|
|
Identifies the arch subdirectory</li>
|
|
<li><code>CONFIG_ARCH_name</code>:
|
|
For use in C code</li>
|
|
<li><code>CONFIG_ARCH_CHIP</code>:
|
|
Identifies the arch/*/chip subdirectory</li>
|
|
<li><code>CONFIG_ARCH_CHIP_name</code>:
|
|
For use in C code</li>
|
|
<li><code>CONFIG_ARCH_BOARD</code>:
|
|
Identifies the configs subdirectory and hence, the board that supports
|
|
the particular chip or SoC.</li>
|
|
<li><code>CONFIG_ARCH_BOARD_name</code>:
|
|
For use in C code</li>
|
|
<li><code>CONFIG_ENDIAN_BIG</code>:
|
|
Define if big endian (default is little endian).</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Some architectures require a description of the the RAM configuration:
|
|
</p>
|
|
<ul>
|
|
<li><code>CONFIG_DRAM_SIZE</code>:
|
|
Describes the installed DRAM.</li>
|
|
<li><code>CONFIG_DRAM_START</code>:
|
|
The start address of DRAM (physical)</li>
|
|
<li><code>CONFIG_DRAM_VSTART</code>:
|
|
The startaddress of DRAM (virtual)</li>
|
|
</ul>
|
|
|
|
<h2>General OS setup</h2>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>CONFIG_EXAMPLE</code>: identifies the subdirectory in examples
|
|
that will be used in the build.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_DEBUG</code>: enables built-in debug options
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_DEBUG_VERBOSE</code>: enables verbose debug output
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_DEBUG_SCHED</code>: enable OS debug output (disabled by default)
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_DEBUG_MM</code>: enable memory management debug output (disabld by default)
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_DEBUG_NET</code>: enable network debug output (disabled by default)
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_DEBUG_FS</code>: enable filesystem debug output (disabled by default)
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_DEBUG_LIB</code>: enable C library debug output (disabled by default)
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_HAVE_LOWPUTC</code>: architecture supports low-level, boot
|
|
time console output
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_MM_REGIONS</code>: If the architecture includes multiple
|
|
regions of memory to allocate from, this specifies the
|
|
number of memory regions that the memory manager must
|
|
handle and enables the API mm_addregion(start, end);
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_TICKS_PER_MSEC</code>: The default system timer is 100Hz
|
|
or <code>TICKS_PER_MSEC</code>=10. This setting may be defined to inform NuttX
|
|
that the processor hardware is providing system timer interrupts at some interrupt
|
|
interval other than 10 msec.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_RR_INTERVAL</code>: The round robin timeslice will be set
|
|
this number of milliseconds; Round robin scheduling can
|
|
be disabled by setting this value to zero.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_SCHED_INSTRUMENTATION</code>: enables instrumentation in
|
|
scheduler to monitor system performance
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_TASK_NAME_SIZE</code>: Spcifies that maximum size of a
|
|
task name to save in the TCB. Useful if scheduler
|
|
instrumentation is selected. Set to zero to disable.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_START_YEAR, CONFIG_START_MONTH, CONFIG_START_DAY -
|
|
Used to initialize the internal time logic.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_JULIAN_TIME</code>: Enables Julian time conversions
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_DEV_CONSOLE</code>: Set if architecture-specific logic
|
|
provides /dev/console. Enables stdout, stderr, stdin.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
The following can be used to disable categories of APIs supported
|
|
by the OS. If the compiler supports weak functions, then it
|
|
should not be necessary to disable functions unless you want to
|
|
restrict usage of those APIs.
|
|
</p>
|
|
<p>
|
|
There are certain dependency relationships in these features.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<code>mq_notify()</code> logic depends on signals to awaken tasks
|
|
waiting for queues to become full or empty.
|
|
</li>
|
|
<li>
|
|
<code>pthread_condtimedwait()</code> depends on signals to wake
|
|
up waiting tasks.
|
|
</li>
|
|
</ul>
|
|
|
|
<ul>
|
|
<code>CONFIG_DISABLE_CLOCK</code>, <code>CONFI_DISABLE_POSIX_TIMERS</code>,
|
|
<code>CONFIG_DISABLE_PTHREAD</code>, <code>CONFIG_DISABLE_SIGNALS</code>,
|
|
<code>CONFIG_DISABLE_MQUEUE</code>, <code>CONFIG_DISABLE_MOUNTPOUNT</code>
|
|
</ul>
|
|
|
|
<h2>Miscellaneous libc settings</h2>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>CONFIG_NOPRINTF_FIELDWIDTH</code>: sprintf-related logic is a
|
|
little smaller if we do not support fieldwidthes
|
|
</li>
|
|
</ul>
|
|
|
|
<h2>Allow for architecture optimized implementations</h2>
|
|
|
|
<p>
|
|
The architecture can provide optimized versions of the
|
|
following to improve sysem performance.
|
|
</p>
|
|
|
|
<ul>
|
|
<p>
|
|
<code>CONFIG_ARCH_MEMCPY</code>, <code>CONFIG_ARCH_MEMCMP</code>, <code>CONFIG_ARCH_MEMMOVE</code>,
|
|
<code>CONFIG_ARCH_MEMSET</code>, <code>CONFIG_ARCH_STRCMP</code>, <code>CONFIG_ARCH_STRCPY</code>,
|
|
<code>CONFIG_ARCH_STRNCPY</code>, <code>CONFIG_ARCH_STRLEN</code>, <code>CONFIG_ARCH_BZERO</code>,
|
|
<code>CONFIG_ARCH_KMALLOC</code>, <code>CONFIG_ARCH_KZMALLOC</code>, <code>ONFIG_ARCH_KFREE</code>,
|
|
</p>
|
|
</ul>
|
|
|
|
<h2>Sizes of configurable things (0 disables)</h2>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>CONFIG_MAX_TASKS</code>: The maximum number of simultaneously
|
|
active tasks. This value must be a power of two.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NPTHREAD_KEYS</code>: The number of items of thread-
|
|
specific data that can be retained
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NFILE_DESCRIPTORS</code>: The maximum number of file
|
|
descriptors (one for each open)
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NFILE_STREAMS</code>: The maximum number of streams that
|
|
can be fopen'ed
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NAME_MAX</code>: The maximum size of a file name.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_STDIO_BUFFER_SIZE</code>: Size of the buffer to allocate
|
|
on fopen. (Only if CONFIG_NFILE_STREAMS > 0)
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NUNGET_CHARS</code>: Number of characters that can be
|
|
buffered by ungetc() (Only if CONFIG_NFILE_STREAMS > 0)
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_PREALLOC_MQ_MSGS</code>: The number of pre-allocated message
|
|
structures. The system manages a pool of preallocated
|
|
message structures to minimize dynamic allocations
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_MQ_MAXMSGSIZE</code>: Message structures are allocated with
|
|
a fixed payload size given by this settin (does not include
|
|
other message structure overhead.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_PREALLOC_WDOGS</code>: The number of pre-allocated watchdog
|
|
structures. The system manages a pool of preallocated
|
|
watchdog structures to minimize dynamic allocations
|
|
</li>
|
|
</ul>
|
|
|
|
<h2>Network Support</h2>
|
|
<h3>TCP/IP and UDP support via uIP</h2>
|
|
<ul>
|
|
<li>
|
|
<code>CONFIG_NET</code>: Enable or disable all network features
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_IPv6</code>: Build in support for IPv6
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NSOCKET_DESCRIPTORS</code>: Maximum number of socket descriptors per task/thread.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_SOCKOPTS</code>: Enable or disable support for socket options.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_BUFSIZE</code>: uIP buffer size
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_TCP</code>: TCP support on or off
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_TCP_CONNS</code>: Maximum number of TCP connections (all tasks).
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_TCP_READAHEAD_BUFSIZE</code>: Size of TCP read-ahead buffers
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_NTCP_READAHEAD_BUFFERS</code>: Number of TCP read-ahead buffers (may be zero)
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_MAX_LISTENPORTS</code>: Maximum number of listening TCP ports (all tasks).
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_TCPURGDATA</code>: Determines if support for TCP urgent data
|
|
notification should be compiled in. Urgent data (out-of-band data)
|
|
is a rarely used TCP feature that is very seldom would be required.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_UDP</code>: UDP support on or off
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_UDP_CHECKSUMS</code>: UDP checksums on or off
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_UDP_CONNS</code>: The maximum amount of concurrent UDP connections
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_ICMP</code>: ICMP ping support on or off
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_PINGADDRCONF</code>: Use "ping" packet for setting IP address
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_STATISTICS</code>: uIP statistics on or off
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_RECEIVE_WINDOW</code>: The size of the advertised receiver's window
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_ARPTAB_SIZE</code>: The size of the ARP table
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_BROADCAST</code>: Broadcast support
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_LLH_LEN</code>: The link level header length
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_FWCACHE_SIZE</code>: number of packets to remember when looking for duplicates
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>UIP Network Utilities</h3>
|
|
<ul>
|
|
<li>
|
|
<code>CONFIG_NET_DHCP_LIGHT</code>: Reduces size of DHCP
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_NET_RESOLV_ENTRIES</code>: Number of resolver entries
|
|
</li>
|
|
</ul>
|
|
|
|
<h2>Stack and heap information</h2>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>CONFIG_BOOT_FROM_FLASH</code>: Some configurations support XIP
|
|
operation from FLASH.
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_STACK_POINTER</code>: The initial stack pointer
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_PROC_STACK_SIZE</code>: The size of the initial stack
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_PTHREAD_STACK_MIN</code>: Minimum pthread stack size
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_PTHREAD_STACK_DEFAULT</code>: Default pthread stack size
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_HEAP_BASE</code>: The beginning of the heap
|
|
</li>
|
|
<li>
|
|
<code>CONFIG_HEAP_SIZE</code>: The size of the heap
|
|
</li>
|
|
</ul>
|
|
|
|
</body>
|
|
</html>
|
|
|
|
|