NuttxPortingGuide.html

  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 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="NxFileSystem">5.0 NuttX File System</a></h1>

<p><b>Overview</b>.
  NuttX includes an optional, scalable file system.
  This file-system may be omitted altogther; NuttX does not depend on the presence
  of any file system.
</p>

<p><b>Pseudo Root File System</b>.
  Or, a simple <i>in-memory</i>, <i>psuedo</i> file system can be enabled.
  This simple file system can be enabled setting the CONFIG_NFILE_DESCRIPTORS
  option to a non-zero value (see <a href="#apndxconfigs">Appendix A</a>).
  This is an <i>in-memory</i> file system because it does not require any
  storage medium or block driver support.
  Rather, file system contents are generated on-the-fly as referenced via
  standard file system operations (open, close, read, write, etc.).
  In this sense, the file system is <i>psuedo</i> file system (in the
  same sense that the Linux <code>/proc</code> file system is also
  referred to as a psuedo file system).
</p>

<p>
  Any user supplied data or logic can be accessed via the psuedo-file system.
  Built in support is provided for character and block drivers in the
  <code>/dev</code> psuedo file system directory.
</p>

<p><b>Mounted File Systems</b>
  The simple in-memory file system can be extended my mounting block
  devices that provide access to true file systems backed up via some
  mass storage device.
  NuttX supports the standard <code>mount()</code> command that allows
  a block driver to be bound to a mountpoint within the psuedo file system
  and to a a file system.
  At present, NuttX supports only the VFAT file system.
</p>

<p><b>Comparison to Linux</b>
  From a programming perspective, the NuttX file system appears very similar
  to a Linux file system.
  However, there is a fundamental difference:
  The NuttX root file system is a psuedo file system and true file systems may be
  mounted in the psuedo file system.
  In the typical Linux installation by comparison, the Linux root file system
  is a true file system and psuedo file systems may be mounted in the true,
  root file system.
  The approach selected by NuttX is intended to support greater scalability
  from the very tiny platform to the moderate platform.
</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>
<p>
  The following configuration itemes select the architecture, chip, and
  board configuration for the build.
</p>
<ul>
  <li><code>CONFIG_ARCH</code>:
    Identifies the arch subdirectory</li>
  <li><code>CONFIG_ARCH_name</code>:
    For use in C code</li>
  <li><code>CONFIG_ARCH_CHIP</code>:
    Identifies the arch/*/chip subdirectory</li>
  <li><code>CONFIG_ARCH_CHIP_name</code>:
    For use in C code</li>
  <li><code>CONFIG_ARCH_BOARD</code>:
     Identifies the configs subdirectory and hence, the board that supports
     the particular chip or SoC.</li>
  <li><code>CONFIG_ARCH_BOARD_name</code>:
     For use in C code</li>
  <li><code>CONFIG_ENDIAN_BIG</code>:
     Define if big endian (default is little endian).</li>
</ul>

<p>
  Some architectures require a description of the RAM configuration:
</p>
<ul>
  <li><code>CONFIG_DRAM_SIZE</code>:
    Describes the installed DRAM.</li>
  <li><code>CONFIG_DRAM_START</code>:
    The start address of DRAM (physical)</li>
  <li><code>CONFIG_DRAM_VSTART</code>:
    The start address of DRAM (virtual)</li>
</ul>

<p>
  General build options:
</p>
<ul>
  <li><code>CONFIG_RRLOAD_BINARY</code>:
    Make the rrload binary format used with BSPs from <a href="www.ridgerun.com">ridgerun.com</a>.</li>
  <li><code>CONFIG_HAVE_LIBM</code>:
    Toolchain supports libm.a</li>
</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_DEBUG_SCHED</code>: enable OS debug output (disabled by default)
  </li>
  <li>
    <code>CONFIG_DEBUG_MM</code>: enable memory management debug output (disabld by default)
  </li>
  <li>
    <code>CONFIG_DEBUG_NET</code>: enable network debug output (disabled by default)
  </li>
  <li>
    <code>CONFIG_DEBUG_FS</code>: enable file system debug output (disabled by default)
  </li>
  <li>
    <code>CONFIG_DEBUG_LIB</code>: enable C library debug output (disabled by default)
  </li>
  <li>
    <code>CONFIG_ARCH_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_TICKS_PER_MSEC</code>: The default system timer is 100Hz
    or <code>TICKS_PER_MSEC</code>=10.  This setting may be defined to inform NuttX
    that the processor hardware is providing system timer interrupts at some interrupt
    interval other than 10 msec.
  </li>
  <li>
    <code>CONFIG_RR_INTERVAL</code>: The round robin timeslice will be set
    this number of milliseconds;  Round robin scheduling can
    be disabled by setting this value to zero.
  </li>
  <li>
    <code>CONFIG_SCHED_INSTRUMENTATION</code>: enables instrumentation in 
    scheduler to monitor system performance
  </li>
  <li>
    <code>CONFIG_TASK_NAME_SIZE</code>: Spcifies that maximum size of a
    task name to save in the TCB.  Useful if scheduler
    instrumentation is selected.  Set to zero to disable.
  </li>
  <li>
    <code>CONFIG_START_YEAR, CONFIG_START_MONTH, CONFIG_START_DAY -
    Used to initialize the internal time logic.
  </li>
  <li>
    <code>CONFIG_JULIAN_TIME</code>: Enables Julian time conversions
  </li>
  <li>
    <code>CONFIG_DEV_CONSOLE</code>: Set if architecture-specific logic
    provides /dev/console.  Enables stdout, stderr, stdin.
  </li>
</ul>

<p>
  The following can be used to disable categories of APIs supported
  by the OS.  If the compiler supports weak functions, then it
  should not be necessary to disable functions unless you want to
  restrict usage of those APIs.
</p>
<p>
  There are certain dependency relationships in these features.
</p>
<ul>
  <li>
    <code>mq_notify()</code> logic depends on signals to awaken tasks
    waiting for queues to become full or empty.
  </li>
  <li>
    <code>pthread_condtimedwait()</code> depends on signals to wake
    up waiting tasks.
  </li>
</ul>

<ul>
    <code>CONFIG_DISABLE_CLOCK</code>, <code>CONFI_DISABLE_POSIX_TIMERS</code>,
    <code>CONFIG_DISABLE_PTHREAD</code>, <code>CONFIG_DISABLE_SIGNALS</code>,
    <code>CONFIG_DISABLE_MQUEUE</code>, <code>CONFIG_DISABLE_MOUNTPOUNT</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>Network Support</h2>
<h3>TCP/IP and UDP support via uIP</h2>
<ul>
  <li>
    <code>CONFIG_NET</code>: Enable or disable all network features
  </li>
  <li>
    <code>CONFIG_NET_IPv6</code>: Build in support for IPv6
  </li>
  <li>
    <code>CONFIG_NSOCKET_DESCRIPTORS</code>: Maximum number of socket descriptors per task/thread.
  </li>
  <li>
    <code>CONFIG_NET_SOCKOPTS</code>: Enable or disable support for socket options.
  </li>
  <li>
    <code>CONFIG_NET_BUFSIZE</code>: uIP buffer size
  </li>
  <li>
    <code>CONFIG_NET_TCP</code>: TCP support on or off
  </li>
  <li>
    <code>CONFIG_NET_TCP_CONNS</code>: Maximum number of TCP connections (all tasks).
  </li>
  <li>
    <code>CONFIG_NET_TCP_READAHEAD_BUFSIZE</code>: Size of TCP read-ahead buffers
  </li>
  <li>
    <code>CONFIG_NET_NTCP_READAHEAD_BUFFERS</code>: Number of TCP read-ahead buffers (may be zero)
  </li>
  <li>
    <code>CONFIG_NET_MAX_LISTENPORTS</code>: Maximum number of listening TCP ports (all tasks).
  </li>
  <li>
    <code>CONFIG_NET_TCPURGDATA</code>: Determines if support for TCP urgent data
    notification should be compiled in. Urgent data (out-of-band data)
    is a rarely used TCP feature that is very seldom would be required.
  </li>
  <li>
    <code>CONFIG_NET_UDP</code>: UDP support on or off
  </li>
  <li>
    <code>CONFIG_NET_UDP_CHECKSUMS</code>: UDP checksums on or off
  </li>
  <li>
    <code>CONFIG_NET_UDP_CONNS</code>: The maximum amount of concurrent UDP connections
  </li>
  <li>
    <code>CONFIG_NET_ICMP</code>: ICMP ping support on or off
  </li>
  <li>
    <code>CONFIG_NET_PINGADDRCONF</code>: Use "ping" packet for setting IP address
  </li>
  <li>
    <code>CONFIG_NET_STATISTICS</code>: uIP statistics on or off
  </li>
  <li>
    <code>CONFIG_NET_RECEIVE_WINDOW</code>: The size of the advertised receiver's window
  </li>
  <li>
    <code>CONFIG_NET_ARPTAB_SIZE</code>: The size of the ARP table
  </li>
  <li>
    <code>CONFIG_NET_BROADCAST</code>: Broadcast support
  </li>
  <li>
    <code>CONFIG_NET_LLH_LEN</code>: The link level header length
  </li>
  <li>
    <code>CONFIG_NET_FWCACHE_SIZE</code>: number of packets to remember when looking for duplicates
  </li>
</ul>

<h3>UIP Network Utilities</h3>
<ul>
  <li>
    <code>CONFIG_NET_DHCP_LIGHT</code>: Reduces size of DHCP
  </li>
  <li>
    <code>CONFIG_NET_RESOLV_ENTRIES</code>: Number of resolver entries
  </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>

<h1><a name="apndxtrademarks">Appendix B:  Trademarks</a></h1>

  <li>ARM, ARM7 ARM7TDMI, ARM9, ARM926EJS are trademarks of Advanced RISC Machines, Limited.</li>
  <li>Cygwin is a trademark of Red Hat, Incorporated.</li>
  <li>Linux is a registered trademark of Linus Torvalds.</li>
  <li>LPC2148 is a trademark of NXP Semiconductors.</li>
  <li>TI is a tradename of Texas Instruments Incorporated.</li>
  <li>UNIX is a registered trademark of The Open Group.</li>
  <li>VxWorks is a registered trademark of Wind River Systems, Incorporated.</li>
  <li>ZDS, ZNEO, Z16F, Z80, and Zilog are a registered trademark of Zilog, Inc.</li>

<p>
  NOTE: NuttX is <i>not</i> licensed to use the POSIX trademark.  NuttX uses the POSIX
  standard as a development guideline only.
</p>

</body>
</html>