0d8a9ffae2
git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@105 42af7a65-404d-4744-a932-0658087f49c3
977 lines
32 KiB
HTML
977 lines
32 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: March 20, 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="#sudirectorystructure">2.2.1 Subdirectory Structure</a></li>
|
|
<li><a href="#summaryoffiles">2.2.2 Summary of Files</a></li>
|
|
<li><a href="#supportedarchitectures">2.2.3 Supported Architectures</a></li>
|
|
<li><a href="#configuringnuttx">2.2.4 Configuring NuttX</a></li>
|
|
</ul>
|
|
<li>2.3 <a href="#DirStructDrivers">drivers</a></li>
|
|
<li>2.4 <a href="#DirStructExamples">examples</a></li>
|
|
<li>2.5 <a href="#DirStructFs">fs</a></li>
|
|
<li>2.6 <a href="#DirStructInclude">include</a></li>
|
|
<li>2.7 <a href="#DirStructLib">lib</a></li>
|
|
<li>2.8 <a href="#DirStructMm">mm</a></li>
|
|
<li>2.9 <a href="#DirStructSched">sched</a></li>
|
|
<li>2.10 <a href="#DirStructDrivers">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>(architecture)</i>
|
|
| | |-- Make.defs
|
|
| | |-- defconfig
|
|
| | |-- include
|
|
| | |-- setenv.sh
|
|
| | `-- src
|
|
| `-- <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="sudirectorystructure">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 or board consists of
|
|
add a new sudirectory under <code>arch/</code> containing logic specific
|
|
to the new architecuture.
|
|
Each architecture must provide a subdirectory, <<i>arch-name</i>>
|
|
under <code>arch/</code> with the folling characteristics:
|
|
</p>
|
|
<ul><pre>
|
|
<<i>arch-name</i>>
|
|
|-- Make.defs
|
|
|-- defconfig
|
|
|-- setenv.sh
|
|
|-- include
|
|
| |-- arch.h
|
|
| |-- irq.h
|
|
| `-- types.h
|
|
`-- src
|
|
|-- Makefile
|
|
`-- (architecture-specific source files)
|
|
</pre></ul>
|
|
|
|
<h3><a name="summaryoffiles">2.2.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>
|
|
<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>
|
|
</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
|
|
uses the Spectrum Digital evaluation board with a GNU arm-elf toolchain*.
|
|
This port is complete, verified, and included in the NuttX release.
|
|
<li><code>arch/dm320</code>:
|
|
TI TMS320DM320 (also called just DM320).
|
|
NuttX operates on the ARM9EJS of this dual core processor.
|
|
This port uses the Neuros OSD with a GNU arm-elf toolchain*:
|
|
see http://wiki.neurostechnology.com/index.php/Developer_Welcome .
|
|
STATUS: This port is code complete but totally untested due to
|
|
hardware issues with my OSD.
|
|
<li><code>arch/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.
|
|
</ul>
|
|
<p>
|
|
Other ports for the for the TI TMS320DM270 and for MIPS are in various states
|
|
of progress
|
|
</p>
|
|
|
|
<h3><a name="configuringnuttx">2.2.4 Configuring NuttX</a></h3>
|
|
<p>
|
|
Configuring NuttX requires only copying:
|
|
</p>
|
|
<ul>
|
|
<code>arch/<<i>arch-name</i>>/Make.def</code> to <code>${TOPDIR}/Make.defs</code>,
|
|
<code>arch/<<i>arch-name</i>>/setenv.sh</code> to <code>${TOPDIR}/setenv.sh</code>, and
|
|
<code.arch/<<i>arch-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>arch-name</i>>
|
|
</pre></ul>
|
|
|
|
<h2>2.3 <a name="DirStructDrivers">drivers</a></h2>
|
|
|
|
<p>
|
|
This directory holds architecture-independent device drivers.
|
|
</p>
|
|
|
|
<h2>2.4 <a name="DirStructExamples">examples</a></h2>
|
|
|
|
<p>
|
|
Example and test programs to build against.
|
|
</p>
|
|
|
|
<h2>2.5 <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.6 <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.7 <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.8 <a name="DirStructMm">mm</a></h2>
|
|
|
|
<p>
|
|
This is the NuttX memory manager.
|
|
</p>
|
|
|
|
<h2>2.9 <a name="DirStructSched">sched</a></h2>
|
|
|
|
<p>
|
|
The files forming core of the NuttX RTOS reside here.
|
|
</p>
|
|
|
|
<h2>2.10 <a name="DirStructDrivers">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>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>
|
|
|
|
|