<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: March 22, 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>
<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>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>
<li><a href="#supportedboards">2.3.3 Supported Boards</a></li>
<li><a href="#configuringnuttx">2.3.4 Configuring NuttX</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>
</ul>
<li>3.0 <a href="#DirectoryConfiAndBuild">Configuring and Building</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 arch/README.txt.
</p>
<p><b>General Philosophy</b>.
<hr>
<h1>2.0 <a name="DirectoryStructure">Directory Structure</a></h1>
<p>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>
.
|-- Makefile
|-- <a href="#DirStructDocumentation">Documentation</a>
| `-- <i>(documentation files)</i>
|-- <a href="#DirStructArch">arch</a>
| |-- <i><arch-name></i>
| | |-- include
| | `-- src
| `-- <i><:;other-architectures></i>
|-- <a href="#DirStructConfigs">configs</a>
| |-- <i><board-name></i>
| | |-- Make.defs
| | |-- defconfig
| | `-- setenv.sh
| `-- <i><:;other-architectures></i>
|-- <a href="#DirStructDrivers">drivers</a>
| |-- Makefile
| `-- <i>(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>(fs source files)</i>
|-- <a href="#DirStructInclude">include</a>
| |-- <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>(mm 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>
<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
| |-- arch.h
| |-- irq.h
| `-- types.h
`-- src
|-- 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/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/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/<arch-name>/arch.h</code> as described above).
</li>
</ul>
<h3><a name="supportedarchitectures">2.2.3 Supported Architectures</a></h3>
<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/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><code>arch/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><code>arch/m68322</code>
A work in progress.</li>
<li><code>arch/pjrc-8051</code>:
8051 Microcontroller. This port is not quite ready for prime time.</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>>
|-- Make.defs
|-- defconfig
`-- setenv.sh
</pre></ul>
<h3><a name="#summaryofconfigfiles">2.3.2 Summary of Files</a></h3>
<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>
<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/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>
<h3><a name="configuringnuttx">2.3.4 Configuring NuttX</a></h3>
<p>
Configuring NuttX requires only copying:
</p>
<ul>
<code>configs/<<i>board-name</i>>/Make.def</code> to <code>${TOPDIR}/Make.defs</code>,
<code>configs/<<i>board-name</i>>/setenv.sh</code> to <code>${TOPDIR}/setenv.sh</code>, and
<code>configs/<<i>board-name</i>>/defconfig</code> to ${TOPDIR}/.config</code>
</ul>
<p>
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>
<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="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>
<hr>
<h1>3.0 <a name="DirectoryConfiAndBuild">Configuring and Building</a></h1>
<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>
<ul>
<li><code>CONFIG_ARCH</code>: identifies the arch subdirectory
<li><code>CONFIG_ARCH_name</code>: for use in C code
</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_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_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>,
</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>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>