diff --git a/ChangeLog b/ChangeLog
index 5c0d8369b42ce62fd605c36bc466f27686db3dc5..666c83dae95c5a2e8b8b8b610f93ea486264f880 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -59,5 +59,7 @@
0.1.3 2007-xx-xx Gregory Nutt <spudmonkey@racsa.co.cr>
+ * Fix error in handing signed decimal in vsprintf().
+ * Some Documentation updates
* Added support for the Neuros OSD / DM320
diff --git a/Documentation/NuttX.html b/Documentation/NuttX.html
index 0fbea395766045aa7f040adde3ea1ad457b4b064..62e5702dcbfde02f7df2d645307fd70c6a604fd6 100644
--- a/Documentation/NuttX.html
+++ b/Documentation/NuttX.html
@@ -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>
diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html
index 1065d009778b29a24c6ac5fe37c3901986c4ec9d..dee837cd7b58310fb365f0887e96923508551b11 100644
--- a/Documentation/NuttxPortingGuide.html
+++ b/Documentation/NuttxPortingGuide.html
@@ -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>
diff --git a/arch/README.txt b/arch/README.txt
index 4b03a020e8ae6bc98c9d4a2b42c01db627b2618c..c614013484c8bafe91c2a9b1c0f7574a23368485 100644
--- a/arch/README.txt
+++ b/arch/README.txt
@@ -18,8 +18,8 @@ arch/<arch-name>/arch.h as described below).
Directory Structure
^^^^^^^^^^^^^^^^^^^
-Thie arch directory contains architecture specific logic. Each aructure
-provide a a subdirectory <arch-name>under arch/ with the folling characteristics:
+The arch directory contains architecture specific logic. Each architecture must
+provide a subdirectory <arch-name> under arch/ with the folling characteristics:
<arch-name>
@@ -216,20 +216,30 @@ src/Makefile
Supported Architectures
^^^^^^^^^^^^^^^^^^^^^^^
+arch/sim
+ 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.
+
arch/c5471
- TI TMS320C5471 (also called TMS320DM180).
+ 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 in progress and partially functional (However, my board
- is dead at the moment so it will be awhile before I fix it).
+ This port is complete, verified, and included in the NuttX release.
+
+arch/dm320
+ 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.
arch/pjrc-8051
8051 Microcontroller. This port uses the PJRC 87C52 development system
and the SDCC toolchain. This port is not quite ready for prime time.
-arch/sim
- x86 Linux Simulation</b>. Fully functional.
-
Other ports for the for the TI TMS320DM270 and for MIPS are in various states
of progress