update
git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@105 42af7a65-404d-4744-a932-0658087f49c3
This commit is contained in:
patacongo
parent
7a82bf1afc
commit
369c723ff6
@ -180,7 +180,7 @@
|
||||
</table>
|
||||
|
||||
<p>
|
||||
The second release of NuttX (nuttx-0.1.2) is avalable for download
|
||||
The third release of NuttX (nuttx-0.1.2) is avalable for download
|
||||
from the <a href="http://sourceforge.net/project/showfiles.php?group_id=189573">SourceForge</a>
|
||||
website.
|
||||
</p>
|
||||
|
||||
@ -11,12 +11,12 @@
|
||||
<hr>
|
||||
<center>
|
||||
<big><b>
|
||||
<p>Nuttx Operating System</p>
|
||||
<p>NuttX Operating System</p>
|
||||
<p>Porting Guide</p>
|
||||
</b></big>
|
||||
<p><small>by</small></p>
|
||||
<p>Gregory Nutt</p>
|
||||
<p><small>Last Update: February 8, 2007</small></p>
|
||||
<p><small>Last Update: March 20, 2007</small></p>
|
||||
</center>
|
||||
|
||||
<center><h1>Table of Contents</h1></center>
|
||||
@ -25,6 +25,12 @@
|
||||
<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>
|
||||
@ -35,12 +41,43 @@
|
||||
<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
|
||||
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>
|
||||
@ -53,7 +90,7 @@
|
||||
<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
|
||||
<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>
|
||||
@ -105,19 +142,834 @@ below and discussed in the following paragraphs:</p>
|
||||
</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>
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user