Newer
Older
<hr>
<center><h1><i>Under Construction</i></h1></center>
<hr>
<p>Porting Guide</p>
</b></big>
<p><small>by</small></p>
<p>Gregory Nutt</p>
<p><small>Last Update: April 30, 2007</small></p>
</center>
<center><h1>Table of Contents</h1></center>
<li>1.0 <a href="#Introduction">1.0 Introduction</a></li>
<li>2.0 <a href="#DirectoryStructure">Directory Structure</a></li>
<ul>
<li>2.1 <a href="#DirStructDocumentation">Documentation</a></li>
<l1>2.2 <a href="#DirStructArch">arch</a></li>
<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>2.3 <a href="#DirStructConfigs">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>2.4 <a href="#DirStructDrivers">drivers</a></li>
<li>2.5 <a href="#DirStructExamples">examples</a></li>
<li>2.6 <a href="#DirStructFs">fs</a></li>
<li>2.7 <a href="#DirStructInclude">include</a></li>
<li>2.8 <a href="#DirStructLib">lib</a></li>
<li>2.9 <a href="#DirStructMm">mm</a></li>
<li>2.10 <a href="#DirStructSched">sched</a></li>
<li>2.11 <a href="#DirStructTools">tools</a></li>
<li>2.12 <a href="#topmakefile">Makefile</a></li>
</ul>
<li>3.0 <a href="#configandbuild">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>
<li>4.0 <a href="#ArchAPIs">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>
<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>
| `-- <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>/
| |-- Makefile/
| `-- <i>(common driver source files)</i>
|-- <a href="#DirStructExamples">examples</a>/
| `-- <i>(example)</i>/
|-- Makefile.mkconfig
|-- configure.sh
|-- mkconfig.c
|-- mkdeps.sh
`-- zipme
</pre></ul>
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
<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>
<p>
General documentation for the NuttX OS resides in this directory.
</p>
<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:
| |--<i><chip-name></i>/
| | `-- <i>(chip-specific header files)</i>
| |--<i><other-chips></i>/
|--<i><chip-name></i>/
| `-- <i>(chip-specific source files)</i>
|--<i><other-chips></i>/
`-- <i>(architecture-specific source files)</i>
<h3><a name="summaryofarchfiles">2.2.2 Summary of Files</a></h3>
<li>
<code>include/</code><i><chip-name></i><code>/</code>
This sub-directory contains chip-specific header files.
</li>
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
<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><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>
patacongo
committed
<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>
<li><code>configs/mcu123-lpc214x</code>:
The mcu123.com lpc214x development board.
This is a work in progress.
<li><code>arch/m68322</code>
A work in progress.</li>
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>
|-- 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>
<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.
</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
patacongo
committed
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
patacongo
committed
included in the NuttX release.
</li>
<li><code>configs/mcu123-lpc214x</code>:
patacongo
committed
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
patacongo
committed
NuttX 0.2.1 release.
</li>
<li><code>configs/m68322evb</code>:
This is a work in progress for the venerable m68322evb board from
patacongo
committed
Motorola.
</li>
<li><code>configs/pjrc-8051</code>:
8051 Microcontroller. This port uses the PJRC 87C52 development system
patacongo
committed
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>
<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>
<h2>2.10 <a name="DirStructSched">sched</a></h2>
<p>
The files forming core of the NuttX RTOS reside here.
</p>
<h2>2.11 <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.12 <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>
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
<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>
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<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