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>
<p>
Directory structure:
</p>
<ul><pre>
include/
|-- <i>(standard header files)</i>
|-- arpa/
| `-- <i>(Standard header files)</i>
|-- cxx/
| `-- <i>(C++ standard header files)</i>
|-- netinet/
| `-- <i>(Standard header files)</i>
|-- nuttx/
| |-net/
| | `-- uip/
| | `-- <i>(uIP specific header files)</i>
| `-- <i>(NuttX specific header files)</i>
`- sys/
`-- <i>(More standard header files)</i>
</per></ul>
<h2>2.9 <aname="DirStructLib">nuttx/lib</a></h2>
<p>
This directory holds a collection of standard libc-like functions with custom
interfaces into NuttX.
</p>
<p>
Normally the logic in this file builds to a single library (<code>liblib.a</code>).
However, if NuttX is built as a separately compiled kernel (with <code>CONFIG_NUTTX_KERNEL=y</code>), then the contents of this directory are built as two libraries:
One for use by user programs (<code>libulib.a</code>) and one for use only within the <kernel> space (<code>libklib.a</code>).
</p>
<p>
These user/kernel space libraries (along with the sycalls of <ahref="#DirStructSyscall"><code>nuttx/syscall</code></a>) are needed to support the two differing protection domains.
</p>
<p>
Directory structure:
</p>
<ul><pre>
lib/
|-- libgen/
| `-- <i>(Implementation of functions from libgen.h)</i>
|-- math/
| `-- <i>(Implementation of functions from fixedmath.h)</i>
|-- misc/
| `-- <i>(Implementation of miscellaneous library functions)</i>
|-- mqueue/
| `-- <i>(Implementation of some functions from mqueue.h)</i>
|-- net/
| `-- <i>(Implementation of network-related library functions)</i>
|-- queue/
| `-- <i>(Implementation of functions from queue.h)</i>
|-- sched/
| `-- <i>(Implementation of some functions from sched.h)</i>
|-- semaphore/
| `-- <i>(Implementation of some functions from semaphore.h)</i>
|-- signal/
| `-- <i>(Implementation of some functions from signal.h)</i>
|-- stdio/
| `-- <i>(Implementation of functions from stdio.h)</i>
|-- stdlib/
| `-- <i>(Implementation of functions from stdlib.h)</i>
|-- string/
| `-- <i>(Implementation of functions from string.h)</i>
|-- time/
| `-- <i>(Implementation of some functions from time.h)</i>
`-- unistd/
`-- <i>(Implementation of some functions from unistd.h)</i>
<ahref="#boardconfigsubdirs">board-specific configuration files</a> into the top level directory which appears in the make files as the make variable, <code>${TOPDIR}</code>.
This could be done manually as follows:
</p>
<ul>
<li>Copy <code>configs/</code><i><board-name></i><code>/[</code><i><config-dir></i><code>/]Make.defs</code> to <code>${TOPDIR}/Make.defs</code>,<li>
<li>Copy <code>configs/</code><i><board-name></i><code>/[</code><i><config-dir></i><code>/]setenv.sh</code> to <code>${TOPDIR}/setenv.sh</code>, and</li>
<li>Copy <code>configs/</code><i><board-name></i><code>/[</code><i><config-dir></i><code>/]defconfig</code> to <code>${TOPDIR}/.config</code></li>
</ul>
<p>
And if <code>configs/</code><i><board-name></i><code>/[</code><i><config-dir></i><code>/appconfig</code> exists in the board configuration directory:
</p>
<ul>
<li>Copy <code>configs/</code><i><board-name></i><code>/[</code><i><config-dir></i><code>/appconfig</code> to <app-dir><code>/.config</code></li>
The NuttX version number expressed a major and minor number separated
by a period
<outfile-path>
The full path to the version file to be created
</pre></ul>
<p>
As an example, the following command will generate a version file for version 6.1 using the current SVN revision number:
</p>
<ul><pre>
tools/version.h -v 6.1 .version
</pre></ul>
<p>
The <code>.version</code> file is also used during the build process to create a C header file at <code>include/nuttx/version.h</code> that contains the same version information.
That version file may be used by your C applications for, as an example, reporting version information.
</p>
<p>
<b>Additional Configuration Steps</b>.
The remainder of configuration steps will be performed by <ahref="#topmakefile"><code>${TOPDIR}/Makefile</code></a>
the first time the system is built as described below.
</p>
<h2><aname="buildingnuttx">3.2 Building NuttX</a></h2>
<p>
<b>Building NuttX</b>.
Once NuttX has been configured as described <ahref="#configuringnuttx">above</a>, it may be built as follows:
</p>
<ul><pre>
cd ${TOPDIR}
source ./setenv.sh
make
</pre></ul>
<p>
The <code>${TOPDIR}</code> directory holds:
</p>
<ul>
<li>The top level <ahref="#topmakefile"><code>Makefile</code></a> that controls the NuttX build.
</ul>
<p>
That directory also holds:
</p>
<ul>
<li>The makefile fragment <ahref="#boardconfigsubdirs"><code>.config</code></a> that describes the current configuration.</li>
<li>The makefile fragment <ahref="#boardconfigsubdirs"><code>Make.defs</code></a> that provides customized build targets, and</li>
<li>The shell script <ahref="#boardconfigsubdirs"><code>setenv.sh</code></a> that sets up the configuration environment for the build.</li>
</ul>
<p>
The <ahref="#boardconfigsubdirs"><code>setenv.sh</code></a> contains Linux/Cygwin environmental settings that are needed for the build.
The specific environmental definitions are unique for each board but should include, as a minimum, updates to the <code>PATH</code> variable to include the full path to the architecture-specific toolchain identified in <ahref="#boardconfigsubdirs"><code>Make.defs</code></a>.
The <ahref="#boardconfigsubdirs"><code>setenv.sh</code></a> only needs to be source'ed at the beginning of a session.
The system can be re-made subsequently by just typing <code>make</code>.
</p>
<p>
<b>First Time Make.</b>
Additional configuration actions will be taken the first time that system is built.
These additional steps include:
</p>
<ul>
<li>Auto-generating the file <code>include/nuttx/config.h</code> using the <code>${TOPDIR}/.config</code> file.</li>
<li>Auto-generating the file <code>${TOPDIR}/.version</code> with version 0.0 if one does not exist.</li>
<li>Auto-generating the file <code>include/nuttx/version.h</code> using the <code>${TOPDIR}/.version</code> file.</li>
<li>Creating a link to <code>${TOPDIR}/arch/</code><i><arch-name></i><code>/include</code> at <code>${TOPDIR}/include/arch</code>.</li>
<li>Creating a link to <code>${TOPDIR}/configs/</code><i><board-name></i><code>/include</code> at <code>${TOPDIR}/include/arch/board</code>.</li>
<li>Creating a link to <code>${TOPDIR}/configs/</code><i><board-name></i><code>/src</code> at <code>${TOPDIR}/arch/</code><i><arch-name></i><code>/src/board</code></li>
<li>Creating a link to <code>${APPDIR}/include</code> at <code>${TOPDIR}/include/apps</code></li>
This is a debug interface exported by the architecture-specific logic.
Output one character on the console
</p>
<h3><aname="systemtime">4.1.20 System Time and Clock</a></h3>
<h4>4.1.20.1 Basic System Timer</h4>
<p><b>System Timer</b>
In most implementations, system time is provided by a timer interrupt.
That timer interrupt runs at rate determined by <code>CONFIG_MSEC_PER_TICKS</code> (default 10 or 100Hz).
The timer generates an interrupt each <code>CONFIG_MSEC_PER_TICKS</code> milliseconds and increments a counter called <code>g_system_timer</code>.
<code>g_system_timer</code> then provides a time-base for calculating <i>up-time</i> and elapsed time intervals in units of <code>CONFIG_MSEC_PER_TICKS</code>.
The range of <code>g_system_timer</code> is, by default, 32-bits.
However, if the MCU supports type <code>long long</code> and <code>CONFIG_SYSTEM_TIME16</code> is selected,
a 64-bit system timer will be supported instead.
</p>
<p><b>System Timer Accuracy</b>
On many system, the exact timer interval specified by <code>CONFIG_MSEC_PER_TICKS</code> cannot be achieved due to limitations in frequencies or in dividers.
As a result, the time interval specified by <code>CONFIG_MSEC_PER_TICKS</code> may only be approximate and there may be small errors in the apparent <i>up-time</i> time.
These small errors, however, will accumulate over time and after a long period of time may have an unacceptably large error in the apparent <i>up-time</i> of the MCU.
</p>
If the timer tick period generated by the hardware is not exactly <code>CONFIG_MSEC_PER_TICKS</code><i>and</i> if there you require accurate up-time for the MCU, then there are measures that you can take:
</p>
<ul>
<li>
Perhaps you can adjust <code>CONFIG_MSEC_PER_TICKS</code> to a different value so that an exactly <code>CONFIG_MSEC_PER_TICKS</code> can be accomplished.
</li>
<li>
Or you can use a technique known as <i>Delta-Sigma Modulation</i>. (Suggested by Uros Platise). Consider the example below.
</li>
</ul>
<p><b>Delta-Sigma Modulation Example</b>.
Consider this case: The system timer is a count-up timer driven at 32.768KHz.
There are dividers that can be used, but a divider of one yields the highest accuracy.
This counter counts up until the count equals a match value, then a timer interrupt is generated.
The desire frequency is 100Hz (<code>CONFIG_MSEC_PER_TICKS</code> is 10).
</p>
<p>
This exact frequency of 100Hz cannot be obtained in this case.
In order to obtain that exact frequency a match value of 327.68 would have to be provided.
The closest integer value is 328 but the ideal match value is between 327 and 328.
The closest value, 328, would yield an actual timer frequency of 99.9Hz!
That will may cause significant timing errors in certain usages.
</p>
<p>
Use of Delta-Sigma Modulation can eliminate this error in the long run.
Consider this example implementation:
</p>
<ol>
<li>
Initially an accumulator is zero an the match value is programmed to 328:
<ul><pre>
accumulator = 0;
match = 328;
</pre></ul>
</li>
<li>
On each timer interrupt, accumulator is updated with difference that, in this reflects, 100* the error in interval that just passed.
So on the first timer interrupt, the accumulator would be updated like:
<ul><pre>
if (match == 328)
{
accumulator += 32; // 100*(328 - 327.68)
}
else
{
accumulator -= 68; // (100*(327 - 327.68)
}
</pre></ul>
</li>
<li>
And on that same timer interrupt a new match value would be programmed:
<ul><pre>
if (accumulator <0)
{
match = 328;
}
else
{
match = 327;
}
</pre></ul>
</ol>
<p>
In this way, the timer interval is controlled from interrupt-to-interrupt to produce an average frequency of exactly 100Hz.
</p>
<h4>4.1.20.1 Hardware</h4>
<p>
To enable hardware module use the following configuration options:
<p>
<ul><dl>
<dt><code>CONFIG_RTC</code>
<dd>Enables general support for a hardware RTC.
Specific architectures may require other specific settings.
<dt><code>CONFIG_RTC_DATETIME</code>
<dd>There are two general types of RTC: (1) A simple battery backed counter that keeps the time when power
is down, and (2) A full date / time RTC the provides the date and time information, often in BCD format.
If <code>CONFIG_RTC_DATETIME</code> is selected, it specifies this second kind of RTC.
In this case, the RTC is used to "seed"" the normal NuttX timer and the NuttX system timer
provides for higher resoution time.
<dt><code>CONFIG_RTC_HIRES</code>
<dd>If <code>CONFIG_RTC_DATETIME</code> not selected, then the simple, battery backed counter is used.
There are two different implementations of such simple counters based on the time resolution of the counter:
The typical RTC keeps time to resolution of 1 second, usually supporting a 32-bit <code>time_t</code> value.
In this case, the RTC is used to "seed" the normal NuttX timer and the NuttX timer provides for higher resoution time.
If <code>CONFIG_RTC_HIRES</code> is enabled in the NuttX configuration, then the RTC provides higher resolution time and completely replaces the system timer for purpose of date and time.
<dt><code>CONFIG_RTC_FREQUENCY</code>
<dd>If <code>CONFIG_RTC_HIRES</code> is defined, then the frequency of the high resolution RTC must be provided.
If <code>CONFIG_RTC_HIRES</code> is not defined, <code>CONFIG_RTC_FREQUENCY</code> is assumed to be one.
<dt><code>CONFIG_RTC_ALARM</code>
<dd>Enable if the RTC hardware supports setting of an alarm.
A callback function will be executed when the alarm goes off
</dl></ul>
<p>
which requires the following base functions to read and set time:
</p>
<ul>
<li><code>up_rtcinitialize()</code>.
Initialize the hardware RTC per the selected configuration.
This function is called once during the OS initialization sequence
</li>
<li><code>up_rtc_time()</code>.
Get the current time in seconds. This is similar to the standard <code>time()</code> function.
This interface is only required if the low-resolution RTC/counter hardware implementation selected.
It is only used by the RTOS during intialization to set up the system time when <code>CONFIG_RTC</code> is set
but neither <code>CONFIG_RTC_HIRES</code> nor <code>CONFIG_RTC_DATETIME</code> are set.
</li>
<li><code>up_rtc_gettime()</code>.
Get the current time from the high resolution RTC clock/counter.
This interface is only supported by the hight-resolution RTC/counter hardware implementation.
It is used to replace the system timer (<code>g_system_tick</code>).
</li>
<li><code>up_rtc_settime()</code>.
Set the RTC to the provided time.
All RTC implementations must be able to set their time based on a standard timespec.
</li>
<li><code>up_rtc_setalarm()</code>.
Set up an alarm.
</li>
</ul>
<h4>4.1.20.2 System Tick and Time</h4>
<p>
The system tick is represented by::
</p>
<ul>
<li><code>g_system_timer</code></li>
</ul>
<p>
Running at rate of system base timer, used for time-slicing, and so forth.
</p>
<p>
If hardware RTC is present (<code>CONFIG_RTC</code>) and and high-resolution timing
is enabled (<code>CONFIG_RTC_HIRES</code>), then after successful
initiliazation variables are overriden by calls to <code>up_rtc_gettime()</code> which is
running continously even in power-down modes.
</p>
<p>
In the case of <code>CONFIG_RTC_HIRES</code> is set the <code>g_system_timer</code>
keeps counting at rate of a system timer, which however, is disabled in power-down mode.
By comparing this time and RTC (actual time) one may determine the actual system active time.
To retrieve that variable use:
</p>
<h2><aname="exports">4.2 APIs Exported by NuttX to Architecture-Specific Logic</a></h2>
<p>
These are standard interfaces that are exported by the OS
LED-related definitions are provided in two header files:
<ul>
<li>
LED definitions are provided for each board in the <code>board.h</code> that resides
in the <code><i><board-name></i>/include/board.h</code> file (which is also
linked to <code>include/arch/board/board.h</code> when the RTOS is configured).
Those definitions are discussed <ahref="#leddefinitions">below</a>.
</li>
<li>
The board-specific logic provides unique instances of the LED interfaces.
This is because the implementation of LED support may be very different
on different boards.
Prototypes for these board-specific implementations are, however, provided
in architecture-common header files.
That header file is usually at <code><i><arch-name></i>/src/common/up_internal.h</code>,
but could be at other locations in particular architectures.
These prototypes are discussed <ahref="#ledapis">below</a>.
</li>
</ul>
</p>
<h3><aname="leddefinitions">4.3.2 LED Definitions</a></h3>
<p>
The implementation of LED support is very specific to a board architecture.
Some boards have several LEDS, others have only one or two.
Some have none.
Others LED matrices and show alphanumeric data, etc.
The NuttX logic does not refer to specific LEDS, rather, it refers to an event to be shown on the LEDS
in whatever manner is appropriate for the board;
the way that this event is presented depends upon the hardware available on the board.
</p>
<p>
The model used by NuttX is that the board can show 8 events defined as follows in <code><i><board-name></i>/include/board.h</code>:
</p>
<ul><pre>
#define LED_STARTED ??
#define LED_HEAPALLOCATE ??
#define LED_IRQSENABLED ??
#define LED_STACKCREATED ??
#define LED_INIRQ ??
#define LED_SIGNAL ??
#define LED_ASSERTION ??
#define LED_PANIC ??
</pre></ul>
<p>
The specific value assigned to each pre-processor variable can be whatever makes the implementation easiest for the board logic.
The <i>meaning</i> associated with each definition is as follows:
</p>
<ul>
<li>
<code>LED_STARTED</code> is the value that describes the setting of the LEDs when the LED logic is first initialized.
This LED value is set but never cleared.
</li>
<li>
<code>LED_HEAPALLOCATE</code> indicates that the NuttX heap has been configured.
This is an important place in the boot sequence because if the memory is configured wrong, it will probably crash leaving this LED setting.
This LED value is set but never cleared.
</li>
<li>
<code>LED_IRQSENABLED</code> indicates that interrupts have been enabled.
Again, during bring-up (or if there are hardware problems), it is very likely that the system may crash just when interrupts are enabled, leaving this setting on the LEDs.
This LED value is set but never cleared.
</li>
<li>
<code>LED_STACKCREATED</code> is set each time a new stack is created.
If set, it means that the system attempted to start at least one new thread.
This LED value is set but never cleared.
</li>
<li>
<code>LED_INIRQ</code> is set and cleared on entry and exit from each interrupt.
If interrupts are working okay, this LED will have a dull glow.
</li>
<li>
<code>LED_SIGNAL</code> is set and cleared on entry and exit from a signal handler.
Signal handlers are tricky so this is especially useful during bring-up or a new architecture.
</li>
<li>
<code>LED_ASSERTION</code> is set if an assertion occurs.
</li>
<li>
<code>LED_PANIC</code> will blink at around 1Hz if the system panics and hangs.
</li>
</ul>
<h3><aname="ledapis">4.3.3 Common LED interfaces</a></h3>
<p>
The <code><i><arch-name></i>/src/common/up_internal.h</code> probably has definitions
like:
</p>
<ul><pre>
/* Defined in board/up_leds.c */
#ifdef CONFIG_ARCH_LEDS
extern void up_ledinit(void);
extern void up_ledon(int led);
extern void up_ledoff(int led);
#else
# define up_ledinit()
# define up_ledon(led)
# define up_ledoff(led)
#endif
</pre></ul>
<p>
Where:
<p>
<ul>
<li>
<code>void up_ledinit(void)</code> is called early in power-up initialization to initialize the LED hardware.
</li>
<li>
<code>up_ledon(int led)</code> is called to instantiate the LED presentation of the event.
The <code>led</code> argument is one of the definitions provided in <code><i><board-name></i>/include/board.h</code>.
</li>
<li>
<code>up_ledoff(int led</code>is called to terminate the LED presentation of the event.
The <code>led</code> argument is one of the definitions provided in <code><i><board-name></i>/include/board.h</code>.
Note that only <code>LED_INIRQ</code>, <code>LED_SIGNAL</code>, <code>LED_ASSERTION</code>, and <code>LED_PANIC</code>
Each USB host class driver must implement an instance of <code>struct usbhost_class_s</code>.
This structure is also defined in <code>include/nuttx/usb/usbhost.h</code>.
</p>
<p>
<b>Examples</b>:
<code>drivers/usbhost/usbhost_storage.c</code>
</p>
</li>
<li>
<p>
<b>USB Host Class Driver Registry</b>.
The NuttX USB host infrastructure includes a <i>registry</i>.
During its initialization, each USB host class driver must call the interface, <code>usbhost_registerclass()</code>
in order add its interface to the registery.
Later, when a USB device is connected, the USB host controller will look up the USB host class driver that is needed to support the connected device in this registry.
</p>
<p>
<b>Examples</b>:
<code>drivers/usbhost/usbhost_registry.c</code>, <code>drivers/usbhost/usbhost_registerclass.c</code>, and <code>drivers/usbhost/usbhost_findclass.c</code>,
</p>
</li>
<li>
<p>
<b>Detection and Enumeration of Connected Devices</b>.
Each USB host device controller supports two methods that are used to detect and enumeration newly connected devices
As part of this enumeration process, the driver will
(1) get the device's configuration descriptor,
(2) extract the class ID info from the configuration descriptor,
(3) call <code>usbhost_findclass(</code>) to find the class that supports this device,
(4) call the <code>create()</code> method on the <code>struct usbhost_registry_s interface</code> to get a class instance, and
finally (5) call the <code>connect()</code> method of the <code>struct usbhost_class_s</code> interface.
After that, the class is in charge of the sequence of operations.
</p>
</ul>
</p>
</li>
<li>
<p>
<b>Binding USB Host-Side Drivers</b>.
USB host-side controller drivers are not normally directly accessed by user code,
but are usually bound to another, higher level USB host class driver.
The class driver exports the standard NuttX device interface so that the connected USB device can be accessed just as with other, similar, on-board devices.
For example, the USB host mass storage class driver (<code>drivers/usbhost/usbhost_storage.c</code>) will register a standard, NuttX block driver interface (like <code>/dev/sda</code>)
that can be used to mount a file system just as with any other other block driver instance.
In general, the binding sequence is:
</p>
<p>
<ol>
<li>
<p>
Each USB host class driver includes an intialization entry point that is called from the
application at initialization time.
This driver calls <code>usbhost_registerclass()</code> during this initialization in order to makes itself available in the event the the device that it supports is connected.
</p>
<p>
<b>Examples</b>:
The function <code>usbhost_storageinit()</code> in the file <code>drivers/usbhost/usbhost_storage.c</code>
</p>
</li>
<li>
<p>
Each application must include a <i>waiter</i> thread thread that (1) calls the USB host controller driver's <code>wait()</code> to detect the connection of a device, and then
(2) call the USB host controller driver's <code>enumerate</code> method to bind the registered USB host class driver to the USB host controller driver.
</p>
<p>
<b>Examples</b>:
The function <code>nsh_waiter()</code> in the file <code>configs/nucleus2g/src/up_nsh.c</code> and
the function <code>nsh_waiter()</code> in the file <code>configs/olimex-lpc1766stk/src/up_nsh.c</code>.
</p>
</li>
<li>
<p>
As part of its operation during the binding operation, the USB host class driver will register an instances of a standard NuttX driver under the <code>/dev</code> directory.
To repeat the above example, the USB host mass storage class driver (<code>drivers/usbhost/usbhost_storage.c</code>) will register a standard, NuttX block driver interface (like <code>/dev/sda</code>)
that can be used to mount a file system just as with any other other block driver instance.
</p>
<p>
<b>Examples</b>:
See the call to <code>register_blockdriver()</code> in the function <code>usbhost_initvolume()</code> in the file <code>drivers/usbhost/usbhost_storage.c</code>.
</p>
</li>
</ol>
</p>
</li>
</ul>
<h3><aname="usbdevdrivers">6.3.10 USB Device-Side Drivers</a></h3>
<ul>
<li>
<p>
<b><code>include/nuttx/usb/usbdev.h</code></b>.
All structures and APIs needed to work with USB device-side drivers are provided in this header file.
<code>arch/arm/src/lpc214x/lpc214x_usbdev.c</code>, <code>arch/arm/src/lpc313x/lpc313x_usbdev.c</code>, and
<code>arch/arm/src/stm32/stm32_usbdev.c</code>.
</p>
</li>
<li>
<p>
<b><code>struct usbdevclass_driver_s</code></b>.
Each USB device class driver must implement an instance of <code>struct usbdevclass_driver_s</code>.
This structure is also defined in <code>include/nuttx/usb/usbdev.h</code>.
</p>
<p>
<b>Examples</b>:
<code>drivers/usbdev/pl2303.c</code> and <code>drivers/usbdev/usbmsc.c</code>
</p>
</li>
<li>
<p>
<b>Binding USB Device-Side Drivers</b>.
USB device-side controller drivers are not normally directly accessed by user code,
but are usually bound to another, higher level USB device class driver.
The class driver is then configured to export the USB device functionality.
In general, the binding sequence is:
</p>
<p>
<ol>
<li>
<p>
Each USB device class driver includes an intialization entry point that is called from the
application at initialization time.
</p>
<p>
<b>Examples</b>:
The function <code>usbdev_serialinitialize()</code> in the file <code>drivers/usbdev/pl2303.c</code> and
the function <code></code> in the file <code>drivers/usbdev/usbmsc.c</code>
</p>
</li>
<li>
<p>
These initialization functions called the driver API, <code>usbdev_register()</code>.
This driver function will <i>bind</i> the USB class driver to the USB device controller driver,
completing the initialization.
</p>
</li>
</ol>
</p>
</li>
</ul>
<h3><aname="analogdrivers">6.3.11 Analog (ADC/DAC) Drivers</a></h3>
<p>
The NuttX PWM driver is split into two parts:
</p>
<ol>
<li>
An "upper half", generic driver that provides the comman PWM interface to application level code, and
</li>
<li>
A "lower half", platform-specific driver that implements the low-level timer controls to implement the PWM functionality.
</li>
</ol>
<ul>
<li>
General header files for the NuttX analog drivers reside in <code>include/nuttx/analog/</code>.
These header files includes both the application level interface to the analog driver as well as the interface between the "upper half" and "lower half" drivers.
</li>
<li>
Common analog logic and share-able analog drivers reside in the <code>drivers/analog/</code>.
</li>
<li>
Platform-specific drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> analog peripheral devices.
For the purposes of this driver, a PWM device is any device that generates periodic output pulses of controlled frequency and pulse width.
Such a device might be used, for example, to perform pulse-width modulated output or frequency/pulse-count modulated output
(such as might be needed to control a stepper motor).
</p>
<p>
The NuttX PWM driver is split into two parts:
</p>
<ol>
<li>
An "upper half", generic driver that provides the comman PWM interface to application level code, and
</li>
<li>
A "lower half", platform-specific driver that implements the low-level timer controls to implement the PWM functionality.
</li>
</ol>
<p>
Files supporting PWM can be found in the following locations:
</p>
<ul>
<li><b>Interface Definition</b>.
The header file for the NuttX PWM driver reside at <code>include/nuttx/pwm.h</code>.
This header file includes both the application level interface to the PWM driver as well as the interface between the "upper half" and "lower half" drivers.
The PWM module uses a standard character driver framework.
However, since the PWM driver is a devices control interface and not a data transfer interface,
the majority of the functionality available to the application is implemented in driver ioctl calls.
</li>
<li><b>"Upper Half" Driver</b>.
The generic, "upper half" PWM driver resides at <code>drivers/pwm.c</code>.
</li>
<li><b>"Lower Half" Drivers</b>.
Platform-specific PWM drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> PWM peripheral devices.
</li>
</ul>
<h3><aname="candrivers">6.3.13 CAN Drivers</a></h3>
<p>
NuttX supports only a very low-level CAN driver.
This driver supports only the data exchange and does not include any high-level CAN protocol.
The NuttX CAN driver is split into two parts:
</p>
<ol>
<li>
An "upper half", generic driver that provides the comman CAN interface to application level code, and
</li>
<li>
A "lower half", platform-specific driver that implements the low-level timer controls to implement the CAN functionality.
</li>
</ol>
<p>
Files supporting CAN can be found in the following locations:
</p>
<ul>
<li><b>Interface Definition</b>.
The header file for the NuttX CAN driver reside at <code>include/nuttx/can.h</code>.
This header file includes both the application level interface to the CAN driver as well as the interface between the "upper half" and "lower half" drivers.
The CAN module uses a standard character driver framework.
</li>
<li><b>"Upper Half" Driver</b>.
The generic, "upper half" CAN driver resides at <code>drivers/can.c</code>.
</li>
<li><b>"Lower Half" Drivers</b>.
Platform-specific CAN drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> CAN peripheral devices.
NuttX supports a low-level, two-part Quadrature Encoder driver.
</p>
<ol>
<li>
An "upper half", generic driver that provides the comman Quadrature Encoder interface to application level code, and
</li>
<li>
A "lower half", platform-specific driver that implements the low-level timer controls to implement the Quadrature Encoder functionality.
</li>
</ol>
<p>
Files supporting the Quadrature Encoder can be found in the following locations:
</p>
<ul>
<li><b>Interface Definition</b>.
The header file for the NuttX Quadrature Encoder driver reside at <code>include/nuttx/sensors/qencoder.h</code>.
This header file includes both the application level interface to the Quadrature Encoder driver as well as the interface between the "upper half" and "lower half" drivers.
The Quadrature Encoder module uses a standard character driver framework.
</li>
<li><b>"Upper Half" Driver</b>.
The generic, "upper half" Quadrature Encoder driver resides at <code>drivers/sensors/qencoder.c</code>.
</li>
<li><b>"Lower Half" Drivers</b>.
Platform-specific Quadrature Encoder drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> Quadrature Encoder peripheral devices.
NuttX supports a low-level, two-part watchdog timer driver.
</p>
<ol>
<li>
An "upper half", generic driver that provides the comman watchdog timer interface to application level code, and
</li>
<li>
A "lower half", platform-specific driver that implements the low-level timer controls to implement the watchdog timer functionality.
</li>
</ol>
<p>
Files supporting the watchdog timer can be found in the following locations:
</p>
<ul>
<li><b>Interface Definition</b>.
The header file for the NuttX watchdog timer driver reside at <code>include/nuttx/watchdog.h</code>.
This header file includes both the application level interface to the watchdog timer driver as well as the interface between the "upper half" and "lower half" drivers.
The watchdog timer driver uses a standard character driver framework.
</li>
<li><b>"Upper Half" Driver</b>.
The generic, "upper half" watchdog timer driver resides at <code>drivers/watchdog.c</code>.
</li>
<li><b>"Lower Half" Drivers</b>.
Platform-specific watchdog timer drivers reside in <code>arch/</code><i><architecture></i><code>/src/</code><i><chip></i> directory for the specific processor <i><architecture></i> and for the specific <i><chip></i> watchdog timer peripheral devices.
</li>
</ul>
<h2><aname="pwrmgmt">6.4 Power Management</a></h2>
<h3><aname="pmoverview">6.4.1 Overview</a></h3>
<p>
NuttX supports a simple power managment (PM) sub-system. This sub-system:
</p>
<ul>
<li>
<p>
Monitors driver activity, and
</p>
</li>
<li>
<p>
Provides hooks to place drivers (and the whole system) into reduce power
modes of operation.
</p>
</li>
</ul>
<p>
<center><imgsrc="pm.png"></center>
</p>
<p>
The PM sub-system integrates the MCU idle loop with a collection of device drivers to support:
</p>
<ul>
<li>
<p>
Reports of relevant driver or other system activity.
</p>
</li>
<li>
<p>
Registration and callback mechanism to interface with individual device drivers.
</p>
</li>
<li>
<p>
IDLE time polling of overall driver activity.
</p>
</li>
<li>
<p>
Coordinated, global, system-wide transitions to lower power usage states.
</p>
</li>
</ul>
<p>
Various "sleep" and low power consumption states have various names and are sometimes used in conflicting ways.
In the NuttX PM logic, we will use the following terminology:
</p>
<dl>
<dt><code>NORMAL</code>
<dd>The normal, full power operating mode.
<dt><code>IDLE</code>
<dd>This is still basically normal operational mode, the system is,
however, <code>IDLE</code> and some simple simple steps to reduce power
consumption provided that they do not interfere with normal
Operation. Simply dimming the a backlight might be an example
somethat that would be done when the system is idle.
<dt><code>STANDBY</code>
<dd>Standby is a lower power consumption mode that may involve more
extensive power management steps such has disabling clocking or
setting the processor into reduced power consumption modes. In
this state, the system should still be able to resume normal
activity almost immediately.
<dt><code>SLEEP</code>
<dd>The lowest power consumption mode. The most drastic power
reduction measures possible should be taken in this state. It
may require some time to get back to normal operation from
<code>SLEEP</code> (some MCUs may even require going through reset).
</dl>
<p>
These various states are represented with type <code>enum pm_state_e</code> in <code>include/nuttx/power/pm.h</code>.
This function is called by MCU-specific one-time at power on reset in order to initialize the power management capabilities.
This function must be called <i>very</i> early in the intialization sequence <i>before</i> any other device drivers are initialize (since they may attempt to register with the power management subsystem).
This function is called from the MCU-specific IDLE loop to monitor the the power management conditions.
This function returns the "recommended" power management state based on the PM configuration and activity reported in the last sampling periods.
The power management state is not automatically changed, however.
The IDLE loop must call <code>pm_changestate()</code> in order to make the state change.
</p>
<p>
These two steps are separated because the plaform-specific IDLE loop may have additional situational information that is not available to the the PM sub-system.
For example, the IDLE loop may know that the battery charge level is very low and may force lower power states even if there is activity.
</p>
<p>
NOTE: That these two steps are separated in time and, hence, the IDLE loop could be suspended for a long period of time between calling <code>pm_checkstate()</code> and <code>pm_changestate()</code>.
The IDLE loop may need to make these calls atomic by either disabling interrupts until the state change is completed.
This function is used by platform-specific power management logic.
It will announce the power management power management state change to all drivers that have registered for power management event callbacks.
</p>
<p><b>Input Parameters:</b>
<dl>
<dt><code>newstate</code>
<dd>Identifies the new PM state
</dl>
</p>
<p><b>Returned Value:</b>
0 (<code>OK</code>) means that the callback function for all registered drivers returned <code>OK</code> (meaning that they accept the state change).
Non-zero means that one of the drivers refused the state change.
In this case, the system will revert to the preceding state.
</p>
<p><b>Assumptions:</b>
It is assumed that interrupts are disabled when this function is called.
This function is probably called from the IDLE loop... the lowest priority task in the system.
Changing driver power management states may result in renewed system activity and, as a result, can
suspend the IDLE thread before it completes the entire state change unless interrupts are disabled throughout the state change.
</p>
<h3><aname="pmcallbacks">6.4.3 Callbacks</a></h3>
<p>
The <code>struct pm_callback_s</code> includes the pointers to the driver callback functions.
This structure is defined <code>include/nuttx/power/pm.h</code>.
These callback functions can be used to provide power management information to the driver.
</p>
<h4><aname="pmprepare">6.4.3.1 prepare()</a></h4>
<p><b>Function Prototype:</b></p>
<ul><pre>
int (*prepare)(FAR struct pm_callback_s *cb, enum pm_state_e pmstate);
</pre></ul>
<p><b>Description:</b>
Request the driver to prepare for a new power state.
This is a warning that the system is about to enter into a new power state.
The driver should begin whatever operations that may be required to enter power state.
The driver may abort the state change mode by returning a non-zero value from the callback function.
</p>
<p><b>Input Parameters:</b>
<dl>
<dt><code>cb</code>
<dd>Returned to the driver.
The driver version of the callback strucure may include additional, driver-specific state data at the end of the structure.
<dt><code>pmstate</code>
<dd>Identifies the new PM state
</dl>
</p>
<p><b>Returned Value:</b>
Zero (<code>OK</code>) means the event was successfully processed and that the driver is prepared for the PM state change.
Non-zero means that the driver is not prepared to perform the tasks needed achieve this power setting and will cause the state change to be aborted.
NOTE: The <code>prepare()</code> method will also be called when reverting from lower back to higher power consumption modes (say because another driver refused a lower power state change).
Drivers are not permitted to return non-zero values when reverting back to higher power
The following variables are recognized by the build (you may
also include architecture-specific settings).
</p>
<h2>Architecture selection</h2>
<p>
The following configuration items 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>
<li><code>CONFIG_ARCH_NOINTC</code>:
Define if the architecture does not support an interrupt controller
or otherwise cannot support APIs like up_enable_irq() and up_disable_irq().</li>
<li><code>CONFIG_ARCH_VECNOTIRQ</code>:
Usually the interrupt vector number provided to interfaces like <code>irq_attach()</code>
and <code>irq_detach</code> are the same as IRQ numbers that are provied to IRQ
management functions like <code>up_enable_irq()</code> and <code>up_disable_irq()</code>.
But that is not true for all interrupt controller implementations. For example, the
PIC32MX interrupt controller manages interrupt sources that have a many-to-one
relationship to interrupt vectors.
In such cases, <code>CONFIG_ARCH_VECNOTIRQ</code> must defined so that the OS logic
will know not to assume it can use a vector number to enable or disable interrupts.
<li><code>CONFIG_ARCH_IRQPRIO</code>:
Define if the architecture supports prioritization of interrupts and the
up_prioritize_irq() API.</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>
<h2>Build Options</h2>
<p>
General build options:
</p>
<ul>
<li><code>CONFIG_RRLOAD_BINARY</code>:
Make the rrload binary format used with BSPs from <ahref="www.ridgerun.com">ridgerun.com</a>
using the <code>tools/mkimage.sh</code> script.
</li>
<li><code>CONFIG_INTELHEX_BINARY</code>:
Make the Intel HEX binary format used with many different loaders using the GNU objcopy program
This option should not be selected if you are not using the GNU toolchain.
</li>
<li><code>CONFIG_MOTOROLA_SREC</code>:
Make the Motorola S-Record binary format used with many different loaders using the GNU objcopy program
Should not be selected if you are not using the GNU toolchain.
</li>
<li><code>CONFIG_RAW_BINARY</code>:
Make a raw binary format file used with many different loaders using the GNU objcopy program.
This option should not be selected if you are not using the GNU toolchain.
</li>
<li><code>CONFIG_HAVE_LIBM</code>:
Toolchain supports libm.a
</li>
<li><code>CONFIG_HAVE_CXX</code>:
Toolchain supports C++ and <code>CXX</code>, <code>CXXFLAGS</code>, and <code>COMPILEXX</code>
have been defined in the configurations <code>Make.defs</code> file.
</li>
<li><code>CONFIG_HAVE_CXXINITIALIZE</code>:
The platform-specific logic includes support for initialization of static C++ instances for this architecture and for the selected toolchain (via <code>up_cxxinitialize()</code>).
</li>
</ul>
<p>
Building application code:
</p>
<ul>
<li>
<p>
<code>CONFIG_APPS_DIR</code>: Identifies the directory that builds the application to link with NuttX.
This symbol must be assigned to the path of the application build directory <i>relative</i> to the NuttX top build directory.
If the application resides in the top-level <code>../apps/</code> directory, it is not necessary to define <code>CONFIG_APPS_DIR</code>.
If you have an application directory and the NuttX directory each in separate directories such as this:
<ul><pre>
build
|-nuttx
| |
| `- Makefile
`-application
|
`- Makefile
</pre></ul>
Then you would set <code>CONFIG_APPS_DIR=../application</code>.
The default value of <code>CONFIG_APPS_DIR</code> is <code>../apps/</code>.
</p>
<p>
The application direction must contain <code>Makefile</code> and this make file must support the following targets:
<code>libapps.a</code> is a static library ( an archive) that contains all of application object files.
</li>
<li>
<code>clean</code>.
Do whatever is appropriate to clean the application directories for a fresh build.
</li>
<li>
<code>distclean</code>.
Clean everthing -- auto-generated files, symbolic links etc. -- so that the directory contents are the same as the contents in your configuration management system.
This is only done when you change the NuttX configuration.
</li>
<li>
<code>context</code>.
Perform one-time configuration-related setup.
This might includes such things as creating auto-generated files or symbolic links for directory configurations.
</li>
<li>
<code>depend</code>.
Make or update the application build dependencies.
</li>
</ul>
</p>
<p>
When this application is invoked it will receive the setting <code>TOPDIR</code> like:
<code>TOPDIR</code> is the full path to the NuttX directory.
It can be used, for example, to include makefile fragments (e.g., <code>.config</code> or <code>Make.defs</code>) or to set up include file paths.
</p>
</li>
</ul>
<p>
Two-pass Build Options.
If the 2 pass build option is selected, then these options configure the make system build a extra link object.
This link object is assumed to be an incremental (relative) link object, but could be a static library (archive)
(some modification to this Makefile would be required if CONFIG_PASS1_TARGET generates an archive).
Pass 1 1ncremental (relative) link objects should be put into the processor-specific source directory
where other link objects will be created - ff the pass1 obect is an archive, it could go anywhere.
</p>
<ul>
<li>
<code>CONFIG_BUILD_2PASS</code>:
Enables the two pass build options.
</li>
</ul>
<p>
When the two pass build option is enabled, the following also apply:
</p>
<ul>
<li>
<p>
<code>CONFIG_PASS1_TARGET</code>: The name of the first pass build target.
</p>
</li>
<li><code>CONFIG_PASS1_BUILDIR</code>:
<p>
The path, relative to the top NuttX build directory to directory that contains the Makefile to build the first pass object.
The Makefile must support the following targets:
</p>
<p>
<ul>
<li>The special target <code>CONFIG_PASS1_TARGET</code> (if defined), and</li>
<li>The usual depend, clean, and distclean targets.</li>
</ul>
</p>
</li>
<li>
<code>CONFIG_PASS1_OBJECT</code>: May be used to include an extra, pass1 object into the final link.
This would probably be the object generated from the <code>CONFIG_PASS1_TARGET</code>.
It may be available at link time in the <code>arch/<architecture>/src</code> directory.
</li>
</ul>
<h2>Debug Options</h2>
<p>
General Debug setup options are provided to (1) enable and control debug console output, (2) to build NuttX for use with a debugger, and (3) to enable specific debug features:
This includes more extensive parameter checking, debug assertions, and other debug logic.
This option is also necessary (but not sufficient) to enable debug console output;
Debug console output must also be enabled on a subsystem-by-subsystem basis as described below.
</li>
<li>
<code>CONFIG_DEBUG_VERBOSE</code>: If debug console output is enabled, the option enables more verbose debug output.
Ignored if <code>CONFIG_DEBUG</code> is not defined.
If only <code>CONFIG_DEBUG</code> then the only output will be errors, warnings, and critical information.
If <code>CONFIG_DEBUG_VERBOSE</code> is defined in addition, then general debug comments will also be included in the console output.
</li>
<li>
<code>CONFIG_DEBUG_ENABLE</code>: Support an interface to enable or disable debug output.
</li>
<li>
<code>CONFIG_DEBUG_SYMBOLS</code>: build without optimization and with debug symbols (needed for use with a debugger).
This option has nothing to do with debug output.
</li>
<li>
<code>CONFIG_DEBUG_STACK</code>: a few ports include logic to monitor stack usage.
If the NuttX port supports this option, it would be enabled with this option.
This option also requires <code>CONFIG_DEBUG</code> to enable general debug features.
</li>
</ul>
<p>
If debug features are enabled with <code>CONFIG_DEBUG</code> (and possibly <code>CONFIG_DEBUG_VERBOSE</code>), then debug console output can also be enabled on a subsystem-by-subsystem basis.
Below are debug subsystems that are generally available on all platforms:
<ul>
<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 (disabled by default)
</li>
<li>
<code>CONFIG_DEBUG_NET</code>: enable network debug output (disabled by default)
</li>
<li>
<code>CONFIG_DEBUG_USB</code>: enable USB 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_DEBUG_BINFMT</code>: enable binary loader debug output (disabled by default)
</li>
<li>
<code>CONFIG_DEBUG_GRAPHICS</code>: enable NX graphics debug output (disabled by default)
</li>
</ul>
<p>
The following debug options may also be used with certain ports that support these features:
</p>
<ul>
<li>
<code>CONFIG_DEBUG_DMA</code>: enable DMA controller debug output (disabled by default)
</li>
<li>
<code>CONFIG_DEBUG_GPIO</code>: enable detail GPIO usage debug output (disabled by default)
</li>
<li>
<code>CONFIG_DEBUG_PAGING</code>: enable on-demand paging debug output (disabled by default)
</li>
</ul>
<h2>Memory Management</h2>
<ul>
<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_MM_SMALL</code>: Each memory allocation has a small allocation
overhead. The size of that overhead is normally determined by
the "width" of the address support by the MCU. MCUs that support
16-bit addressability have smaller overhead than devices that
support 32-bit addressability. However, there are many MCUs
that support 32-bit addressability <i>but</i> have internal SRAM
of size less than or equal to 64K. In this case, CONFIG_MM_SMALL
can be defined so that those MCUs will also benefit from the
smaller, 16-bit-based allocation overhead.
</li>
<li>
<code>CONFIG_HEAP2_BASE</code> and <code>CONFIG_HEAP2_SIZE</code>:
Some architectures use these settings to specify the size of
a second heap region.
</li>
<li>
<code>CONFIG_GRAN</code>:
Enable granual allocator support. Allocations will be aligned to the
granule size; allocations will be in units of the granule size.
Larger granules will give better performance and less overhead but
more losses of memory due to alignment and quantization waste.
NOTE: The current implementation also restricts the maximum
allocation size to 32 granaules. That restriction could be
eliminated with some additional coding effort.
</li>
<li>
<code>CONFIG_GRAN_SINGLE</code>:
Select if there is only one instance of the granule allocator (i.e.,
gran_initialize will be called only once. In this case, (1) there
are a few optimizations that can can be done and (2) the GRAN_HANDLE
is not needed.
</li>
<li>
<code>CONFIG_GRAN_INTR</code>:
Normally mutual exclusive access to granule allocator data is assured using a semaphore.
If this option is set then, instead, mutual exclusion logic will disable interrupts.
While this options is more invasive to system performance, it will also support use of the
granule allocator from interrupt level logic.
</li>
<li>
<code>CONFIG_DEBUG_GRAM</code>:
Just like <code>CONFIG_DEBUG_MM</code>, but only generates ouput from the gran
<code>CONFIG_SEM_PREALLOCHOLDERS</code>: This setting is only used
if priority inheritance is enabled.
It defines the maximum number of different threads (minus one) that
can take counts on a semaphore with priority inheritance support.
This may be set to zero if priority inheritance is disabled OR if you
are only using semaphores as mutexes (only one holder) OR if no more
than two threads participate using a counting semaphore.
If defined, then this should be a relatively large number because this
is the total number of counts on the total number of semaphores (like
64 or 100).
</li>
<li>
<code>CONFIG_SEM_NNESTPRIO</code>: If priority inheritance is enabled,
then this setting is the maximum number of higher priority threads (minus
1) than can be waiting for another thread to release a count on a semaphore.
This value may be set to zero if no more than one thread is expected to
wait for a semaphore.
If defined, then this should be a relatively small number because this the
number of maximumum of waiters on one semaphore (like 4 or 8).
</li>
<li>
<code>CONFIG_FDCLONE_DISABLE</code>: Disable cloning of all file descriptors
by task_create() when a new task is started.
If set, all files/drivers will appear to be closed in the new task.
</li>
<li>
<code>CONFIG_FDCLONE_STDIO</code>: Disable cloning of all but the first
three file descriptors (stdin, stdout, stderr) by task_create()
when a new task is started.
If set, all files/drivers will appear to be closed in the new task except
for stdin, stdout, and stderr.
</li>
<li>
<code>CONFIG_SDCLONE_DISABLE</code>: Disable cloning of all socket
desciptors by task_create() when a new task is started.
If set, all sockets will appear to be closed in the new task.
</li>
<li>
<code>CONFIG_NXFLAT</code>: Enable support for the NXFLAT binary format.
This format will support execution of NuttX binaries located
in a ROMFS file system (see <code>apps/examples/nxflat</code>).
</li>
<li>
<code>CONFIG_SCHED_WORKQUEUE</code>: Create a dedicated "worker" thread to
handle delayed processing from interrupt handlers. This feature
is required for some drivers but, if there are not complaints,
can be safely disabled. The worker thread also performs
garbage collection -- completing any delayed memory deallocations
from interrupt handlers. If the worker thread is disabled,
then that clean will be performed by the IDLE thread instead
(which runs at the lowest of priority and may not be appropriate
if memory reclamation is of high priority). If CONFIG_SCHED_WORKQUEUE
is enabled, then the following options can also be used:
</li>
<li>
<code>CONFIG_SCHED_WORKPRIORITY</code>: The execution priority of the worker
thread. Default: 50
</li>
<li>
<code>CONFIG_SCHED_WORKPERIOD</code>: How often the worker thread checks for
work in units of microseconds. Default: 50*1000 (50 MS).
</li>
<li>
<code>CONFIG_SCHED_WORKSTACKSIZE</code>: The stack size allocated for the worker
thread. Default: CONFIG_IDLETHREAD_STACKSIZE.
</li>
<li>
<code>CONFIG_SIG_SIGWORK</code>: The signal number that will be used to wake-up
the worker thread. Default: 4
</li>
<li>
<code>CONFIG_SCHED_LPWORK</code>: If CONFIG_SCHED_WORKQUEUE</code> is defined, then a single work queue is created by default.
If <code>CONFIG_SCHED_LPWORK</code> is also defined then an additional, lower-priority work queue will also be created.
This lower priority work queue is better suited for more extended processing (such as file system clean-up operations)
</li>
<li>
<code>CONFIG_SCHED_LPWORKPRIORITY</code>: The execution priority of the lower priority worker thread. Default: 50
</li>
<li>
<code>CONFIG_SCHED_LPWORKPERIOD</code>: How often the lower priority worker thread checks for work in units of microseconds. Default: 50*1000 (50 MS).
</li>
<li>
<code>CONFIG_SCHED_LPWORKSTACKSIZE - The stack size allocated for the lower priority worker thread. Default: CONFIG_IDLETHREAD_STACKSIZE.
</li>
<li>
<code>CONFIG_SCHED_WAITPID</code>: Enables the <ahref="NuttxUserGuide.html#waitpid"><code>waitpid()</code><a> API
</li>
<li>
<code>CONFIG_SCHED_ATEXIT</code>: Enables the <ahref="NuttxUserGuide.html#atexit">atexit()</code><a> API
</li>
<li>
<code>CONFIG_SCHED_ATEXIT_MAX</code>: By default if <code>CONFIG_SCHED_ATEXIT</code> is selected, only a single <code>atexit()</code> function is supported.
That number can be increased by defined this setting to the number that you require.
</li>
<li>
<code>CONFIG_SCHED_ONEXIT</code>: Enables the <ahref="NuttxUserGuide.html#onexit">on_exit()</code><a> API
</li>
<li>
<code>CONFIG_SCHED_ONEXIT_MAX</code>: By default if <code>CONFIG_SCHED_ONEXIT</code> is selected, only a single <code>on_exit()</code> function is supported.
That number can be increased by defined this setting to the number that you require.
</li>
<li>
<code>CONFIG_USER_ENTRYPOINT</code>: The name of the entry point for user
applications.
For the example applications this is of the form <code>app_main</code>
where <code>app</code> is the application name.
If not defined, <code>CONFIG_USER_ENTRYPOINT</code> defaults to
<code>user_start</code>.
</li>
</ul>
<p>
System Logging:
</p>
<ul>
<li>
<code>CONFIG_SYSLOG</code>: Enables general system logging support.
</li>
<code>CONFIG_SYSLOG_DEVPATH</code>: The full path to the system logging device.
Default <code>"/dev/ramlog"</code> (RAMLOG) or <code>"dev/ttyS1;</code> (CHARDEV).
<p>
At present, there are two system loggins devices available.
If <code>CONFIG_SYSLOG</code> is selected, then these options are also available.
</p>
<p>
First, any a generic character device that may be used as the SYSLOG.
</p>
<li>
<code>CONFIG_SYSLOG_CHAR</code>:
Enable the generic character device for the SYSLOG.
A disadvantage of using the generic character device for the SYSLOG is that it cannot handle debug output generated from interrupt level handlers.
NOTE: No more than one SYSLOG device should be configured.
<p>
Alternatively, a circular buffer in RAM can be used as the SYSLOGing device.
The contents of this RAM buffer can be dumped using the NSH dmesg command.
</p>
<li>
<code>CONFIG_RAMLOG</code>: Enables the RAM logging feature
</li>
<li>
<code>CONFIG_RAMLOG_CONSOLE</code>: Use the RAM logging device as a system console.
If this feature is enabled (along with <code>CONFIG_DEV_CONSOLE</code>), then all
console output will be re-directed to a circular buffer in RAM. This
is useful, for example, if the only console is a Telnet console. Then
in that case, console output from non-Telnet threads will go to the
circular buffer and can be viewed using the NSH 'dmesg' command.
</li>
<li>
<code>CONFIG_RAMLOG_SYSLOG</code>:
Use the RAM logging device for the syslogging interface.
If this feature is enabled (along with <code>CONFIG_SYSLOG</code>), then all debug output (only) will be re-directed to the circular buffer in RAM.
This RAM log can be view from NSH using the <code>dmesg</code> command.
NOTE: Unlike the limited, generic character driver SYSLOG device, the RAMLOG <i>can</i> be used to generate debug output from interrupt level handlers.
</li>
<li>
<code>CONFIG_RAMLOG_NPOLLWAITERS</code>: The number of threads than can be waiting
for this driver on poll(). Default: 4
</li>
<p>
If <code>CONFIG_RAMLOG_CONSOLE</code> or <code>CONFIG_RAMLOG_SYSLOG</code> is selected, then the
following may also be provided:
</p>
</li>
<li>
<code>CONFIG_RAMLOG_CONSOLE_BUFSIZE</code>: Size of the console RAM log. Default: 1024
</li>
</ul>
<p>
Kernel build options:
</p>
<ul>
<li>
<code>CONFIG_NUTTX_KERNEL</code>: Builds NuttX as a separately compiled kernel.
</li>
<code>CONFIG_SYS_RESERVED</code>: Reserved system call values for use by architecture-specific logic.
</li>
</ul>
<p>
OS setup related to on-demand paging:
</p>
<ul>
<li>
<code>CONFIG_PAGING</code>: If set =y in your configation file, this setting will
enable the on-demand paging feature as described in
This actual size of the paged text region (in pages).
This is also the number of virtual pages required to support the entire paged region.
The on-demand paging feature is intended to support only the case where the virtual paged text
area is much larger the available physical pages.
Otherwise, why would you enable on-demand paging?
</li>
<li>
<code>CONFIG_PAGING_NDATA</code>:
This is the number of data pages in the memory map.
The data region will extend to the end of RAM unless overridden by a setting in the configuration file.
<b>NOTE</b>:
In some architectures, it may be necessary to take some memory from the end of RAM for page tables
or other system usage.
The configuration settings and linker directives must be cognizant of that:
<code>CONFIG_PAGING_NDATA</code> should be defined to prevent the data region from extending all the way to the end of memory.
</li>
<li>
<code>CONFIG_PAGING_DEFPRIO</code>:
The default, minimum priority of the page fill worker thread.
The priority of the page fill work thread will be boosted boosted dynmically so that it matches the
priority of the task on behalf of which it peforms the fill.
This defines the minimum priority that will be used. Default: 50.
</li>
<li>
<code>CONFIG_PAGING_STACKSIZE</code>:
Defines the size of the allocated stack for the page fill worker thread. Default: 1024.
</li>
<li>
<code>CONFIG_PAGING_BLOCKINGFILL</code>:
The architecture specific <code>up_fillpage()</code> function may be blocking or non-blocking.
If defined, this setting indicates that the <code>up_fillpage()</code> implementation will block until the
transfer is completed. Default: Undefined (non-blocking).
</li>
<li>
<code>CONFIG_PAGING_WORKPERIOD</code>:
The page fill worker thread will wake periodically even if there is no mapping to do.
This selection controls that wake-up period (in microseconds).
This wake-up a failsafe that will handle any cases where a single is lost (that would
really be a bug and shouldn't happen!)
and also supports timeouts for case of non-blocking, asynchronous fills (see <code>CONFIG_PAGING_TIMEOUT_TICKS</code>).
</li>
<li>
<code>CONFIG_PAGING_TIMEOUT_TICKS</code>:
If defined, the implementation will monitor the (asynchronous) page fill logic.
If the fill takes longer than this number if microseconds, then a fatal error will be declared.
Default: No timeouts monitored.
</li>
<p>
Some architecture-specific settings.
Defaults are architecture specific.
If you don't know what you are doing, it is best to leave these undefined and try the system defaults:
</p>
<li>
<code>CONFIG_PAGING_VECPPAGE</code>:
This the physical address of the page in memory to be mapped to the vector address.
</li>
<li>
<code>CONFIG_PAGING_VECL2PADDR</code>:
This is the physical address of the L2 page table entry to use for the vector mapping.
</li>
<li>
<code>CONFIG_PAGING_VECL2VADDR</code>:
This is the virtual address of the L2 page table entry to use for the vector mapping.
</li>
<li>
<code>CONFIG_PAGING_BINPATH</code>:
If <code>CONFIG_PAGING_BINPATH</code> is defined, then it is the full path to a file on a mounted file system that contains a binary image of the NuttX executable.
Pages will be filled by reading from offsets into this file that correspond to virtual fault addresses.
</li>
<li>
<code>CONFIG_PAGING_MOUNTPT</code>:
If <code>CONFIG_PAGING_BINPATH</code> is defined, additional options may be provided to control the initialization of underlying devices.
<code>CONFIG_PAGING_MOUNTPT</code> identifies the mountpoint to be used if a device is mounted.
</li>
<li>
<code>CONFIG_PAGING_MINOR</code>:
Some mount operations require a "minor" number to identify the specific device instance.
Default: 0
</li>
<li>
<code>CONFIG_PAGING_SDSLOT</code>:
If <code>CONFIG_PAGING_BINPATH</code> is defined, additional options may be provided to control the initialization of underlying devices.
<code>CONFIG_PAGING_SDSLOT</code> identifies the slot number of the SD device to initialize.
This must be undefined if SD is not being used.
This should be defined to be zero for the typical device that has only a single slot (See <code>CONFIG_MMCSD_NSLOTS</code>).
If defined, <code>CONFIG_PAGING_SDSLOT</code> will instruct certain board-specific logic to initialize the media in this SD slot.
</li>
<li>
<code>CONFIG_PAGING_M25PX</code>:
Use the m25px.c FLASH driver.
If this is selected, then the MTD interface to the M25Px device will be used to support paging.
</li>
<li>
<code>CONFIG_PAGING_AT45DB</code>:
Use the at45db.c FLASH driver.
If this is selected, then the MTD interface to the Atmel AT45DB device will be used to support paging.
</li>
<li>
<code>CONFIG_PAGING_BINOFFSET</code>:
If CONFIG_PAGING_M25PX or CONFIG_PAGING_AT45DB is defined then CONFIG_PAGING_BINOFFSET will be used to specify the offset in bytes into the FLASH device where the NuttX binary image is located.
Default: 0
</li>
<li>
<code>CONFIG_PAGING_SPIPORT</code>:
If CONFIG_PAGING_M25PX or CONFIG_PAGING_AT45DB is defined and the device has multiple SPI busses (ports), then this configuration should be set to indicate which SPI port the device is connected.
Default: 0
</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
<code>CONFIG_NOPRINTF_FIELDWIDTH</code>: <code>sprintf</code>-related logic is a
little smaller if we do not support fieldwidthes
</li>
<li>
<code>CONFIG_LIBC_FLOATINGPOINT</code>: By default, floating point
support in <code>printf</code>, <code>sscanf</code>, etc. is disabled.
</li>
<li>
<code>CONFIG_LIBC_STRERROR</code>:
<code>strerror()</code> is useful because it decodes <code>errno</code> values into a human readable strings.
But it can also require a lot of memory to store the strings.
If this option is selected, <code>strerror()</code> will still exist in the build but it will not decode error values.
This option should be used by other logic to decide if it should use <code>strerror()</code> or not.
For example, the NSH application will not use <code>strerror()</code> if this option is not selected;
<code>perror(</code>) will not use strerror() is this option is not selected (see also <code>CONFIG_NSH_STRERROR</code>).
</li>
<li>
<code>CONFIG_LIBC_STRERROR_SHORT</code>:
If this option is selected, then <code>strerror()</code> will use a shortened string when it decodes the error.
Specifically, <code>strerror()</code> is simply use the string that is the common name for the error.
For example, the <code>errno</code> value of 2 will produce the string "No such file or directory" if <code>CONFIG_LIBC_STRERROR_SHORT</code> is not defined but the string "ENOENT" if <code>CONFIG_LIBC_STRERROR_SHORT</code> is defined.
</li>
<li>
<code>CONFIG_LIBC_PERROR_STDOUT</code>:
POSIX requires that <code>perror()</code> provide its output on <code>stderr</code>.
This option may be defined, however, to provide <code>perror()</code> output that is serialized with other <code>stdout</code> messages.
</li>
</ul>
<h2>Allow for architecture optimized implementations</h2>
<ul>
<li>
The architecture can provide optimized versions of the following to improve system performance.
The architecture may provide custom versions of certain standard header files:
</p>
<ul>
<li><b><code>CONFIG_ARCH_STDBOOL_H</code></b>.
<p>
The <code>stdbool.h</code> header file can be found at <code>nuttx/include/stdbool.h</code>.
However, that header includes logic to redirect the inclusion of an architecture specific header file like:
</p>
<ul><pre>
#ifdef CONFIG_ARCH_STDBOOL_H
# include <arch/stdbool.h>
#else
...
#endif
</pre></ul>
<p>
Recall that that include path, <code>include/arch</code>, is a symbolic link and will refer to a version of <code>stdbool.h</code> at <code>nuttx/arch/<architecture>/include/stdbool.h</code>.
</p>
</li>
<li><b><code>CONFIG_ARCH_STDINT_H</code></b>.
<p>
Similar logic exists for the <code>stdint.h</code> header file can also be found at <code>nuttx/include/stdint.h</code>.
<ul><pre>
#ifdef CONFIG_ARCH_STDBOOL_H
# include <arch/stdinit.h>
#else
...
#endif
</pre></ul>
</p>
</li>
<li><b><code>CONFIG_ARCH_MATH_H</code></b>.
<p>
There is also a re-directing version of <code>math.h</code> in the source tree. However, it resides out-of-the-way at <code>include/nuttx/math.h</code> because it conflicts too often with the system <code>math.h</code>.
If <code>CONFIG_ARCH_MATH_H=y</code> is defined, however, the top-level makefile will copy the redirecting <code>math.h</code> header file from <code>include/nuttx/math.h</code> to <code>include/math.h</code>.
<code>math.h</code> will then include the architecture-specific version of <code>math.h</code> that you must provide at <code>nuttx/arch/<architecture>/include/math.h</code>.
</p>
<ul><pre>
#ifdef CONFIG_ARCH_MATH_H
# include <arch/math.h>
#endif
</pre></ul>
<p>
So for the architectures that define <code>CONFIG_ARCH_MATH_H=y</code>, <code>include/math.h</code> will be the redirecting <code>math.h</code> header file; for the architectures that don't select <code>CONFIG_ARCH_MATH_H</code>, the redirecting <code>math.h</code> header file will stay out-of-the-way in <code>include/nuttx/</code>.
</p>
</li>
<li><b><code>CONFIG_ARCH_STDARG_H</code></b>.
<p>
There is also a redirecting version of <code>stdarg.h</code> in the source tree as well.
It also resides out-of-the-way at <code>include/nuttx/stdarg.h</code>.
This is because you should normally use your toolchain's <code>stdarg.h</code> file.
But sometimes, your toolchain's <code>stdarg.h</code> file may have other header file dependencies and so may not be usable in the NuttX build environment.
In those cases, you may have to create a architecture-specific <code>stdarg.h</code> header file at <code>nuttx/arch/<architecture>/include/stdarg.h</code>
</p>
<p>
If <code>CONFIG_ARCH_STDARG_H=y</code> is defined, the top-level makefile will copy the re-directing <code>stdarg.h</code> header file from <code>include/nuttx/stdarg.h</code> to <code>include/stdarg.h</code>.
So for the architectures that cannot use their toolchain's <code>stdarg.h</code> file, they can use this alternative by defining <code>CONFIG_ARCH_STDARG_H=y</code> and providing.
If <code>CONFIG_ARCH_STDARG_H</code>, is not defined, then the <code>stdarg.h</code> header file will stay out-of-the-way in <code>include/nuttx/.</code>
</p>
</li>
</ul>
</li>
<li>
<p><code>CONFIG_ARCH_ROMGETC</code>:
There are cases where string data cannot be cannot be accessed by simply de-referencing a string pointer.
As examples:
</p>
<ul>
<li>
In Harvard architectures, data accesses and instruction accesses occur on different busses, perhaps concurrently.
All data accesses are performed on the data bus unless special machine instructions are used to read data from the instruction address space.
Also, in the typical MCU, the available SRAM data memory is much smaller that the non-volatile FLASH instruction memory.
So if the application requires many constant strings, the only practical solution may be to store those constant strings in FLASH memory where they can only be accessed using architecture-specific machine instructions.
</li>
<li>
A similar case is where strings are retained in "external" memory such as EEPROM or serial FLASH.
This case is similar only in that again special operations are required to obtain the string data;
it cannot be accessed directly from a string pointer.
</li>
</ul>
<p>
If <code>CONFIG_ARCH_ROMGETC</code> is defined, then the architecture-specific logic must export the function <code>up_romgetc()</code>.
<code>up_romgetc()</code> will simply read one byte of data from the instruction space.
</p>
<p>
If <code>CONFIG_ARCH_ROMGETC</code>, certain C stdio functions are effected:
(1) All format strings in <code>printf</code>, <code>fprintf</code>, <code>sprintf</code>, etc. are assumed to lie in FLASH
(string arguments for <code>%s</code> are still assumed to reside in SRAM).
And (2), the string argument to <code>puts</code> and <code>fputs</code> is assumed to reside in FLASH.
Clearly, these assumptions may have to modified for the particular needs of your environment.
There is no "one-size-fits-all" solution for this problem.
</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>: Maximum number of bytes in a filename (not including terminating null).
Default: 32
</li>
<li>
<code>CONFIG_PATH_MAX</code>: Maximum number of bytes in a pathname, including the terminating null character.
<code>CONFIG_STDIO_BUFFER_SIZE</code>: Size of the buffer to allocate
on fopen. (Only if CONFIG_NFILE_STREAMS > 0)
</li>
<li>
<code>CONFIG_STDIO_LINEBUFFER</code>:
If standard C buffered I/O is enabled (<code>CONFIG_STDIO_BUFFER_SIZE</code> > 0),
then this option may be added to force automatic, line-oriented flushing the output buffer
for <code>putc()</code>, <code>fputc()</code>, <code>putchar()</code>, <code>puts()</code>, <code>fputs()</code>,
<code>printf()</code>, <code>fprintf()</code>, and <code>vfprintf()</code>.
When a newline character is encountered in the output string, the output buffer will be flushed.
This (slightly) increases the NuttX footprint but supports the kind of behavior that people expect for <code>printf()</code>.
<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 setting (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>
<li>
<code>CONFIG_PREALLOC_IGMPGROUPS</code>: Pre-allocated IGMP groups are used
Only if needed from interrupt level group created (by the IGMP server).
Default: 4
</li>
<li>
<code>CONFIG_DEV_PIPE_SIZE</code>: Size, in bytes, of the buffer to allocated
for pipe and FIFO support (default is 1024).
</li>
</ul>
<h2>File Systems</h2>
<ul>
<li>
<code>CONFIG_FS_FAT</code>: Enable FAT file system support.
</li>
<li>
<code>CONFIG_FAT_LCNAMES</code>: Enable use of the NT-style upper/lower case 8.3 file name support.
</li>
<li>
<code>CONFIG_FAT_LFN</code>: Enable FAT long file names.
NOTE: Microsoft claims patents on FAT long file name technology.
Please read the disclaimer in the top-level COPYING file and only enable this feature if you understand these issues.
</li>
<li>
<code>CONFIG_FAT_MAXFNAME</code>: If <code>CONFIG_FAT_LFN</code> is defined, then the default, maximum long file name is 255 bytes.
This can eat up a lot of memory (especially stack space).
If you are willing to live with some non-standard, short long file names, then define this value.
A good choice would be the same value as selected for CONFIG_NAME_MAX which will limit the visibility of longer file names anyway.
</li>
<li>
<code>CONFIG_FS_FATTIME</code>: Support FAT date and time.
NOTE: There is not much sense in supporting FAT date and time unless you have a hardware RTC
or other way to get the time and date.
</li>
<li>
<code>CONFIG_FS_NXFFS</code>: Enable NuttX FLASH file system (NXFF) support.
</li>
<li>
<code>CONFIG_NXFFS_ERASEDSTATE</code>: The erased state of FLASH.
This must have one of the values of <code>0xff</code> or <code>0x00</code>.
Default: <code>0xff</code>.
</li>
<li>
<code>CONFIG_NXFFS_PACKTHRESHOLD</code>: When packing flash file data,
don't both with file chunks smaller than this number of data bytes.
Default: 32.
</li>
<li>
<code>CONFIG_NXFFS_MAXNAMLEN</code>: The maximum size of an NXFFS file name.
Default: 255.
</li>
<li>
<code>CONFIG_NXFFS_PACKTHRESHOLD</code>: When packing flash file data,
don't both with file chunks smaller than this number of data bytes.
Default: 32.
</li>
<li>
<code>CONFIG_NXFFS_TAILTHRESHOLD</code>: clean-up can either mean
packing files together toward the end of the file or, if file are
deleted at the end of the file, clean up can simply mean erasing
the end of FLASH memory so that it can be re-used again. However,
doing this can also harm the life of the FLASH part because it can
mean that the tail end of the FLASH is re-used too often. This
threshold determines if/when it is worth erased the tail end of FLASH
and making it available for re-use (and possible over-wear).
Default: 8192.
</li>
<li>
<code>CONFIG_FS_ROMFS</code>: Enable ROMFS file system support
</li>
<li>
<code>CONFIG_NFS</code>: Enable Network File System (NFS) client file system support.
Provided support is version 3 using UDP.
In addition to common prerequisites for mount-able file systems in general,
this option requires UDP networking support;
this would include <code>CONFIG_NET</code> and <code>CONFIG_NET_UDP</code> at a minimum.
</li>
<li>
<code>CONFIG_FS_RAMMAP</code>: For file systems that do not support
XIP, this option will enable a limited form of memory mapping that is
implemented by copying whole files into memory.
</li>
</ul>
<h2>Device Drivers</h2>
<h3>RTC</h3>
<ul>
<li>
<code>CONFIG_RTC</code>:
Enables general support for a hardware RTC.
Specific architectures may require other specific settings.
</li>
<li>
<code>CONFIG_RTC_DATETIME</code>:
There are two general types of RTC: (1) A simple battery backed counter that keeps the time when power
is down, and (2) A full date / time RTC the provides the date and time information, often in BCD format.
If <code>CONFIG_RTC_DATETIME</code> is selected, it specifies this second kind of RTC.
In this case, the RTC is used to "seed"" the normal NuttX timer and the NuttX system timer
provides for higher resoution time.
</li>
<li>
<code>CONFIG_RTC_HIRES</code>:
If <code>CONFIG_RTC_DATETIME</code> not selected, then the simple, battery backed counter is used.
There are two different implementations of such simple counters based on the time resolution of the counter:
The typical RTC keeps time to resolution of 1 second, usually supporting a 32-bit <code>time_t</code> value.
In this case, the RTC is used to "seed" the normal NuttX timer and the NuttX timer provides for higher resoution time.
If <code>CONFIG_RTC_HIRES</code> is enabled in the NuttX configuration, then the RTC provides higher resolution time and completely replaces the system timer for purpose of date and time.
</li>
<li>
<code>CONFIG_RTC_FREQUENCY</code>:
If <code>CONFIG_RTC_HIRES</code> is defined, then the frequency of the high resolution RTC must be provided.
If <code>CONFIG_RTC_HIRES</code> is not defined, <code>CONFIG_RTC_FREQUENCY</code> is assumed to be one.
</li>
<li>
<code>CONFIG_RTC_ALARM</code>:
Enable if the RTC hardware supports setting of an alarm.
A callback function will be executed when the alarm goes off
</li>
</ul>
<h3>CAN driver</h3>
<ul>
<li>
<code>CONFIG_CAN</code>: Enables CAN support
</li>
<li>
<code>CONFIG_CAN_FIFOSIZE</code>: The size of the circular buffer of CAN messages. Default: 8
</li>
<li>
<code>CONFIG_CAN_NPENDINGRTR</code>: The size of the list of pending RTR requests. Default: 4
</li>
<li>
<code>CONFIG_CAN_LOOPBACK</code>: A CAN driver may or may not support a loopback mode for testing.
If the driver does support loopback mode, the setting will enable it.
(If the driver does not, this setting will have no effect).
</li>
</ul>
<h3>SPI driver</h3>
<ul>
<li>
<code>CONFIG_SPI_OWNBUS</code>: Set if there is only one active device
on the SPI bus. No locking or SPI configuration will be performed.
It is not necessary for clients to lock, re-configure, etc..
</li>
<li>
<code>CONFIG_SPI_EXCHANGE</code>: Driver supports a single exchange method
(vs a recvblock() and sndblock ()methods)
</li>
</ul>
<h3>SPI-based MMC/SD driver</h3>
<ul>
<li>
<code>CONFIG_MMCSD_NSLOTS</code>: Number of MMC/SD slots supported by the driver. Default is one.
</li>
<li>
<code>CONFIG_MMCSD_READONLY</code>: Provide read-only access. Default is Read/Write
</li>
<li>
<code>CONFIG_MMCSD_SPICLOCK</code>: Maximum SPI clock to drive MMC/SD card. Default is 20MHz.
<code>CONFIG_ENC28J60_HALFDUPPLEX</code>: Default is full duplex
</li>
</ul>
<h2>Network Support</h2>
<h3>TCP/IP and UDP support via uIP</h3>
<ul>
<li>
<code>CONFIG_NET</code>: Enable or disable all network features
</li>
<li>
<code>CONFIG_NET_SLIP</code>: Selects the Serial Line Internet Protocol (SLIP) data link layer.
(This selection is discussed further <ahref="#slipdriver">below</a>).
</li>
<li>
<code>CONFIG_NET_NOINTS</code>: <code>CONFIG_NET_NOINT</code> indicates that uIP not called from the interrupt level.
If <code>CONFIG_NET_NOINTS</code> is defined, critical sections will be managed with semaphores;
Otherwise, it assumed that uIP will be called from interrupt level handling and critical sections will be managed by enabling and disabling interrupts.
</li>
<li>
<code>CONFIG_NET_MULTIBUFFER</code>: Traditionally, uIP has used a single buffer for all incoming and outgoing traffic.
If this configuration is selected, then the driver can manage multiple I/O buffers and can, for example, be filling one input buffer while sending another output buffer.
Or, as another example, the driver may support queuing of concurrent input/ouput and output transfers for better performance.
</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_NACTIVESOCKETS</code>: Maximum number of concurrent socket operations (recv, send, etc.).
<code>CONFIG_PREALLOC_IGMPGROUPS</code>: Pre-allocated IGMP groups are used
Only if needed from interrupt level group created (by the IGMP server).
Default: 4
</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_ARP_IPIN</code>: Harvest IP/MAC address mappings for the ARP table from incoming IP packets.
</li>
<li>
<code>CONFIG_NET_BROADCAST</code>: Incoming UDP broadcast support
</li>
<li>
<code>CONFIG_NET_MULTICAST</code>: Outgoing multi-cast address support
</li>
</ul>
<h3><aname="slipdriver">SLIP</a></h3>
<p>
The NuttX SLIP driver supports point-to-point IP communications over a serial port.
The default data link layer for uIP is Ethernet.
If <code>CONFIG_NET_SLIP</code> is defined in the NuttX configuration file, then SLIP will be supported.
The basic differences between the SLIP and Ethernet configurations is that when SLIP is selected:
<ul>
<li>The link level header (that comes before the IP header) is omitted.</li>
<li>All MAC address processing is suppressed.</li>
<li>ARP is disabled.</li>
</ul>
If <code>CONFIG_NET_SLIP</code> is not selected, then Ethernet will be used
(there is no need to define anything special in the configuration file to use Ethernet -- it is the default).
</p>
<ul>
<li>
<code>CONFIG_NET_SLIP</code>: Enables building of the SLIP driver.
SLIP requires at least one IP protocols selected and the following additional network settings: <code>CONFIG_NET_NOINTS</code> and <code>CONFIG_NET_MULTIBUFFER</code>.
<code>CONFIG_NET_BUFSIZE</code><i>must</i> be set to 296.
Other optional configuration settings that affect the SLIP driver: <code>CONFIG_NET_STATISTICS</code>.
Default: Ethernet.
</li>
<p>
If SLIP is selected, then the following SLIP options are available:
</p>
<li>
<code>CONFIG_CLIP_NINTERFACES</code>: Selects the number of physical SLIP interfaces to support. Default: 1
</li>
<li>
<code>CONFIG_SLIP_STACKSIZE</code>: Select the stack size of the SLIP RX and TX tasks. Default: 2048
</li>
<li>
<code>CONFIG_SLIP_DEFPRIO</code>: The priority of the SLIP RX and TX tasks. Default: 128
</li>
</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
<code>CONFIG_THTTPD_PATH</code>: Server working directory. Default: <code>/mnt/www</code>.
</li>
<li>
<code>CONFIG_THTTPD_CGI_PATH</code>: Path to CGI executables. Default: <code>/mnt/www/cgi-bin</code>.
</li>
<li>
<code>CONFIG_THTTPD_CGI_PATTERN</code>: Only CGI programs whose expanded paths
match this pattern will be executed. In fact, if this value is not defined
then no CGI logic will be built. Default: <code>/mnt/www/cgi-bin/*</code>.
</li>
<li>
<code>CONFIG_THTTPD_CGI_PRIORITY</code>: Provides the priority of CGI child tasks
</li>
<li>
<code>CONFIG_THTTPD_CGI_STACKSIZE</code>: Provides the initial stack size of
CGI child task (will be overridden by the stack size in the NXFLAT
header)
</li>
<li>
<code>CONFIG_THTTPD_CGI_BYTECOUNT</code>: Byte output limit for CGI tasks.
</li>
<li>
<code>CONFIG_THTTPD_CGI_TIMELIMIT</code>: How many seconds to allow CGI programs
to run before killing them.
</li>
<li>
<code>CONFIG_THTTPD_CHARSET</code>: The default character set name to use with
text MIME types.
</li>
<li>
<code>CONFIG_THTTPD_IOBUFFERSIZE</code>:
</li>
<li>
<code>CONFIG_THTTPD_INDEX_NAMES</code>: A list of index filenames to check. The
files are searched for in this order.
</li>
<li>
<code>CONFIG_AUTH_FILE</code>: The file to use for authentication. If this is
defined then thttpd checks for this file in the local directory
before every fetch. If the file exists then authentication is done,
otherwise the fetch proceeds as usual. If you leave this undefined
then thttpd will not implement authentication at all and will not
check for auth files, which saves a bit of CPU time. A typical
value is ".htpasswd&quout;
</li>
<li>
<code>CONFIG_THTTPD_LISTEN_BACKLOG</code>: The listen() backlog queue length.
</li>
<li>
<code>CONFIG_THTTPD_LINGER_MSEC</code>: How many milliseconds to leave a connection
open while doing a lingering close.
</li>
<li>
<code>CONFIG_THTTPD_OCCASIONAL_MSEC</code>: How often to run the occasional
cleanup job.
</li>
<li>
<code>CONFIG_THTTPD_IDLE_READ_LIMIT_SEC</code>: How many seconds to allow for
reading the initial request on a new connection.
</li>
<li>
<code>CONFIG_THTTPD_IDLE_SEND_LIMIT_SEC</code>: How many seconds before an
idle connection gets closed.
</li>
<li>
<code>CONFIG_THTTPD_TILDE_MAP1 and CONFIG_THTTPD_TILDE_MAP2</code>: Tilde mapping.
Many URLs use ~username to indicate a user's home directory. thttpd
provides two options for mapping this construct to an actual filename.
<ol>
<li>
Map ~username to <prefix>/username. This is the recommended choice.
Each user gets a subdirectory in the main web tree, and the tilde
construct points there. The prefix could be something like "users",
or it could be empty.
</li>
<li>
Map ~username to <user's homedir>/<postfix>. The postfix would be
the name of a subdirectory off of the user's actual home dir,
something like "public_html".
</li>
</ol>
You can also leave both options undefined, and thttpd will not do
anything special about tildes. Enabling both options is an error.
Typical values, if they're defined, are "users" for
CONFIG_THTTPD_TILDE_MAP1 and "public_html" forCONFIG_THTTPD_TILDE_MAP2.
</li>
<li>
<code>CONFIG_THTTPD_GENERATE_INDICES</code>:
</li>
<li>
<code>CONFIG_THTTPD_URLPATTERN</code>: If defined, then it will be used to match
and verify referrers.
</li>
</ul>
<h3>FTP Server</h3>
<ul>
<li>
<code>CONFIG_FTPD_VENDORID</code>: The vendor name to use in FTP communications. Default: "NuttX"
</li>
<li>
<code>CONFIG_FTPD_SERVERID</code>: The server name to use in FTP communications. Default: "NuttX FTP Server"
</li>
<li>
<code>CONFIG_FTPD_CMDBUFFERSIZE</code>: The maximum size of one command. Default: 128 bytes.
</li>
<li>
<code>CONFIG_FTPD_DATABUFFERSIZE</code>: The size of the I/O buffer for data transfers. Default: 512 bytes.
</li>
<li>
<code>CONFIG_FTPD_WORKERSTACKSIZE</code>: The stacksize to allocate for each FTP daemon worker thread. Default: 2048 bytes.
</li>
</ul>
<p>
Other required FTPD configuration settings: Of course TCP networking support is required. But here are a couple that are less obvious:
</p>
<ul>
<li>
<code>CONFIG_DISABLE_PTHREAD=n</code>: pthread support is required
</li>
<li>
<code>CONFIG_DISABLE_POLL=n</code>: poll() support is required
</li>
</ul>
<h2>USB Device-Side Support</h2>
<h3>USB Device Controller Driver</h3>
<ul>
<li>
<code>CONFIG_USBDEV</code>: Enables USB device support
</li>
<li>
<code>CONFIG_USBDEV_COMPOSITE</code>: Enables USB composite device support
</li>
<li>
<code>CONFIG_USBDEV_ISOCHRONOUS</code>: Build in extra support for isochronous endpoints
</li>
<li>
<code>CONFIG_USBDEV_DUALSPEED</code>: Hardware handles high and full speed operation (USB 2.0)
</li>
<li>
<code>CONFIG_USBDEV_SELFPOWERED</code>: Will cause USB features to indicate that the device is self-powered
</li>
<li>
<code>CONFIG_USBDEV_MAXPOWER</code>: Maximum power consumption in mA
</li>
<li>
<code>CONFIG_USBDEV_TRACE</code>: Enables USB tracing for debug
</li>
<li>
<code>CONFIG_USBDEV_TRACE_NRECORDS</code>: Number of trace entries to remember
</li>
</ul>
<h3>USB Serial Device Class Driver (Prolific PL2303 Emulation)</h3>
<ul>
<li>
<code>CONFIG_PL2303</code>: Enable compilation of the USB serial driver
</li>
<li>
<code>CONFIG_PL2303_EPINTIN</code>: The logical 7-bit address of a hardware endpoint that supports interrupt IN operation
</li>
<li>
<code>CONFIG_PL2303_EPBULKOUT</code>: The logical 7-bit address of a hardware endpoint that supports bulk OUT operation
</li>
<li>
<code>CONFIG_PL2303_EPBULKIN</code>: The logical 7-bit address of a hardware endpoint that supports bulk IN operation
</li>
<li>
<code>CONFIG_PL2303_NWRREQS</code> and <code>CONFIG_PL2303_NRDREQS</code>: The number of write/read requests that can be in flight
</li>
<li>
<code>CONFIG_PL2303_VENDORID</code> and <code>CONFIG_PL2303_VENDORSTR</code>: The vendor ID code/string
</li>
<li>
<code>CONFIG_PL2303_PRODUCTID</code> and <code>CONFIG_PL2303_PRODUCTSTR</code>: The product ID code/string
</li>
<li>
<code>CONFIG_PL2303_RXBUFSIZE</code> and <code>CONFIG_PL2303_TXBUFSIZE</code>: Size of the serial receive/transmit buffers
</li>
</ul>
<h3>USB serial device class driver (Standard CDC ACM class)</h3>
<ul>
<li>
<code>CONFIG_CDCACM</code>: Enable compilation of the USB serial driver
</li>
<li>
<code>CONFIG_CDCACM_COMPOSITE</code>:
Configure the CDC serial driver as part of a composite driver
(only if <code>CONFIG_USBDEV_COMPOSITE</code> is also defined)
</li>
<li>
<code>CONFIG_CDCACM_IFNOBASE</code>:
If the CDC driver is part of a composite device, then this may need to
be defined to offset the CDC/ACM interface numbers so that they are
unique and contiguous. When used with the Mass Storage driver, the
correct value for this offset is zero.
</li>
<li>
<code>CONFIG_CDCACM_STRBASE</code>:
If the CDC driver is part of a composite device, then this may need to
be defined to offset the CDC/ACM string numbers so that they are
unique and contiguous. When used with the Mass Storage driver, the
correct value for this offset is four (this value actuallly only needs
to be defined if names are provided for the Notification interface,
<code>CONFIG_CDCACM_NOTIFSTR</code>, or the data interface, <code>CONFIG_CDCACM_DATAIFSTR</code>).
</li>
<li>
<code>CONFIG_CDCACM_EP0MAXPACKET</code>: Endpoint 0 max packet size. Default 64.
</li>
<li>
<code>CONFIG_CDCACM_EPINTIN</code>: The logical 7-bit address of a hardware endpoint that supports
interrupt IN operation. Default 2.
</li>
<li>
<code>CONFIG_CDCACM_EPINTIN_FSSIZE</code>: Max package size for the interrupt IN endpoint if full speed mode. Default 64.
</li>
<li>
<code>CONFIG_CDCACM_EPINTIN_HSSIZE</code>: Max package size for the interrupt IN endpoint if high speed mode. Default 64.
</li>
<li>
<code>CONFIG_CDCACM_EPBULKOUT</code>: The logical 7-bit address of a hardware endpoint that supports
bulk OUT operation.
</li>
<li>
<code>CONFIG_CDCACM_EPBULKOUT_FSSIZE</code>: Max package size for the bulk OUT endpoint if full speed mode. Default 64.
</li>
<li>
<code>CONFIG_CDCACM_EPBULKOUT_HSSIZE</code>: Max package size for the bulk OUT endpoint if high speed mode. Default 512.
</li>
<li>
<code>CONFIG_CDCACM_EPBULKIN</code>: The logical 7-bit address of a hardware endpoint that supports
bulk IN operation
</li>
<li>
<code>CONFIG_CDCACM_EPBULKIN_FSSIZE</code>: Max package size for the bulk IN endpoint if full speed mode. Default 64.
</li>
<li>
<code>CONFIG_CDCACM_EPBULKIN_HSSIZE</code>: Max package size for the bulk IN endpoint if high speed mode. Default 512.
</li>
<li>
<code>CONFIG_CDCACM_NWRREQS</code> and <code>CONFIG_CDCACM_NRDREQS</code>: The number of write/read requests that can be in flight.
<code>CONFIG_CDCACM_NWRREQS</code> includes write requests used for both the interrupt and bulk IN endpoints.
Default 4.
</li>
<li>
<code>CONFIG_CDCACM_VENDORID</code> and <code>CONFIG_CDCACM_VENDORSTR</code>: The vendor ID code/string. Default 0x0525 and "NuttX,"
0x0525 is the Netchip vendor and should not be used in any products.
This default VID was selected for compatibility with the Linux CDC ACM default VID.
</li>
<li>
<code>CONFIG_CDCACM_PRODUCTID</code> and <code>CONFIG_CDCACM_PRODUCTSTR</code>: The product ID code/string. Default 0xa4a7 and "CDC/ACM Serial"
0xa4a7 was selected for compatibility with the Linux CDC ACM default PID.
</li>
<li>
<code>CONFIG_CDCACM_RXBUFSIZE</code> and <code>CONFIG_CDCACM_TXBUFSIZE</code>: Size of the serial receive/transmit buffers. Default 256.
</ul>
<h3>USB Storage Device Configuration</h3>
<ul>
<li>
<code>CONFIG_USBMSC</code>:
Enable compilation of the USB storage driver
</li>
<li>
<code>CONFIG_USBMSC_COMPOSITE</code>:
Configure the mass storage driver as part of a composite driver
(only if <code>CONFIG_USBDEV_COMPOSITE</code> is also defined)
</li>
<li>
<code>CONFIG_USBMSC_IFNOBASE</code>:
If the CDC driver is part of a composite device, then this may need to
be defined to offset the mass storage interface number so that it is
unique and contiguous. When used with the CDC/ACM driver, the
correct value for this offset is two (because of the two CDC/ACM
interfaces that will precede it).
</li>
<li>
<code>CONFIG_USBMSC_STRBASE</code>:
If the CDC driver is part of a composite device, then this may need to
be defined to offset the mass storage string numbers so that they are
unique and contiguous. When used with the CDC/ACM driver, the
correct value for this offset is four (or perhaps 5 or 6, depending
on if <code>CONFIG_CDCACM_NOTIFSTR</code> or <code>CONFIG_CDCACM_DATAIFSTR</code> are defined).
</li>
<li>
<code>CONFIG_USBMSC_EP0MAXPACKET</code>:
Max packet size for endpoint 0
</li>
<li>
<code>CONFIG_USBMSCEPBULKOUT</code> and <code>CONFIG_USBMSC_EPBULKIN</code>:
The logical 7-bit address of a hardware endpoints that support bulk OUT and IN operations
</li>
<li>
<code>CONFIG_USBMSC_NWRREQS</code> and <code>CONFIG_USBMSC_NRDREQS</code>:
The number of write/read requests that can be in flight
</li>
<li>
<code>CONFIG_USBMSC_BULKINREQLEN</code> and <code>CONFIG_USBMSC_BULKOUTREQLEN</code>:
The size of the buffer in each write/read request.
This value needs to be at least as large as the endpoint maxpacket and
ideally as large as a block device sector.
</li>
<li>
<code>CONFIG_USBMSC_VENDORID</code> and <code>CONFIG_USBMSC_VENDORSTR</code>:
The vendor ID code/string
</li>
<li>
<code>CONFIG_USBMSC_PRODUCTID</code> and <code>CONFIG_USBMSC_PRODUCTSTR</code>:
The product ID code/string
</li>
<li>
<code>CONFIG_USBMSC_REMOVABLE</code>:
Select if the media is removable
</li>
</ul>
<h3>USB Composite Device Configuration</h3>
<ul>
<li>
<code>CONFIG_USBDEV_COMPOSITE</code>:
Enables USB composite device support
</li>
<li>
<code>CONFIG_CDCACM_COMPOSITE</code>:
Configure the CDC serial driver as part of a composite driver
(only if CONFIG_USBDEV_COMPOSITE is also defined)
</li>
<li>
<code>CONFIG_UBMSC_COMPOSITE</code>:
Configure the mass storage driver as part of a composite driver
(only if CONFIG_USBDEV_COMPOSITE is also defined)
</li>
<li>
<code>CONFIG_COMPOSITE_IAD</code>:
If one of the members of the composite has multiple interfaces
(such as CDC/ACM), then an Interface Association Descriptor (IAD)
will be necessary. Default: IAD will be used automatically if
needed. It should not be necessary to set this.
</li>
<li>
<code>CONFIG_COMPOSITE_EP0MAXPACKET</code>:
Max packet size for endpoint 0
</li>
<li>
<code>CONFIG_COMPOSITE_VENDORID</code> and <code>CONFIG_COMPOSITE_VENDORSTR</code>:
The vendor ID code/string
</li>
<li>
<code>CONFIG_COMPOSITE_PRODUCTID</code> and <code>CONFIG_COMPOSITE_PRODUCTSTR</code>:
The product ID code/string
</li>
<li>
<code>CONFIG_COMPOSITE_SERIALSTR</code>:
Device serial number string
</li>
<li>
<code>CONFIG_COMPOSITE_CONFIGSTR</code>:
Configuration string
</li>
<li>
<code>CONFIG_COMPOSITE_VERSIONNO</code>:
Interface version number.
</li>
</ul>
<h2>USB Host-Side Support</h2>
<h3>USB Host Controller Driver</h3>
<ul>
<li>
<code>CONFIG_USBHOST</code>: Enables USB host support
</li>
<li>
<code>CONFIG_USBHOST_NPREALLOC</code>: Number of pre-allocated class instances
</li>
<li>
<code>CONFIG_USBHOST_BULK_DISABLE</code>: On some architectures, selecting this setting will reduce driver size by disabling bulk endpoint support
</li>
<li>
<code>CONFIG_USBHOST_INT_DISABLE</code>: On some architectures, selecting this setting will reduce driver size by disabling interrupt endpoint support
</li>
<li>
<code>CONFIG_USBHOST_ISOC_DISABLE</code>: On some architectures, selecting this setting will reduce driver size by disabling isochronous endpoint support
<code>CONFIG_HIDKBD_NPOLLWAITERS</code>: If the poll() method is enabled, this defines the maximum number of threads that can be waiting for keyboard events. Default: 2.
</li>
<li>
<code>CONFIG_HIDKBD_RAWSCANCODES</code>: If set to <code>y</code> no conversion will be made on the raw keyboard scan codes. Default: ASCII conversion.
</li>
<li>
<code>CONFIG_HIDKBD_ALLSCANCODES</code>: If set to <code>y</code> all 231 possible scancodes will be converted to something. Default: 104 key US keyboard.
</li>
<li>
<code>CONFIG_HIDKBD_NODEBOUNCE</code>: If set to <code>y</code> normal debouncing is disabled. Default: Debounce/No repeat keys.
