NuttxPortingGuide.html

    <p>
    <b>Examples</b>:
    <code>arch/arm/src/chip/lm3s_serial.c</code>, <code>arch/arm/src/lpc214x/lpc214x_serial.c</code>, <code>arch/z16/src/z16f/z16f_serial.c</code>, etc.
    </p>
  </li>
</ul>

<h3><a name="fbdrivers">6.3.5 Frame Buffer Drivers</a></h3>

<ul>
  <li>
    <p>
      <b><code>include/nuttx/fb.h</code></b>.
      All structures and APIs needed to work with frame buffer drivers are provided in this header file.
    </p>
  </li>
  <li>
    <p>
      <b><code>struct fb_vtable_s</code></b>.
      Each frame buffer device driver must implement an instance of <code>struct fb_vtable_s</code>.
      That structure defines a call table with the following methods:
    </p>
    <p>
      Get information about the video controller configuration and the configuration of each color plane.
    </p>
    <ul>
     <p><code>int (*getvideoinfo)(FAR struct fb_vtable_s *vtable, FAR struct fb_videoinfo_s *vinfo);</code><br>
     <code>int (*getplaneinfo)(FAR struct fb_vtable_s *vtable, int planeno, FAR struct fb_planeinfo_s *pinfo);</code></p>
    </ul>
    <p>
      The following are provided only if the video hardware supports RGB color mapping:
    </p>
    <ul>
     <p><code>int (*getcmap)(FAR struct fb_vtable_s *vtable, FAR struct fb_cmap_s *cmap);</code><br>
     <code>int (*putcmap)(FAR struct fb_vtable_s *vtable, FAR const struct fb_cmap_s *cmap);</code></p>
    </ul>
    <p>
      The following are provided only if the video hardware supports a hardware cursor:
    </p>
    <ul>
     <p><code>int (*getcursor)(FAR struct fb_vtable_s *vtable, FAR struct fb_cursorattrib_s *attrib);</code><br>
     <code>int (*setcursor)(FAR struct fb_vtable_s *vtable, FAR struct fb_setcursor_s *settings);</code></p>
    </ul>
  </li>
  <li>
    <p>
      <b>Binding Frame Buffer Drivers</b>.
      Frame buffer drivers are not normally directly accessed by user code, but are usually bound to another,
      higher level device driver.
      In general, the binding sequence is:
    </p>
    <p>
      <ol>
        <li>Get an instance of <code>struct fb_vtable_s</code> from the hardware-specific frame buffer device driver, and </li>
        <li>Provide that instance to the initialization method of the higher level device driver.</li>
      </ol>
    </p>
  </li>
  <li>
    <p>
      <b>Examples</b>:
      <code>arch/sim/src/up_framebuffer.c</code>.
      See also the usage of the frame buffer driver in the <code>graphics/</code> directory.
    </p>
  </li>
</ul>

<h3><a name="lcddrivers">6.3.6 LCD Drivers</a></h3>

<ul>
  <li>
    <p>
      <b><code>include/nuttx/lcd/lcd.h</code></b>.
      Structures and APIs needed to work with LCD drivers are provided in this header file.
      This header file also depends on some of the same definitions used for the frame buffer driver as privided in <code>include/nuttx/fb.h</code>.
    </p>
  </li>
  <li>
    <p>
      <b><code>struct lcd_dev_s</code></b>.
      Each LCD device driver must implement an instance of <code>struct lcd_dev_s</code>.
      That structure defines a call table with the following methods:
    </p>
    <p>
      Get information about the LCD video controller configuration and the configuration of each LCD color plane.
    </p>
    <ul>
    <p>
       <code>int (*getvideoinfo)(FAR struct lcd_dev_s *dev, FAR struct fb_videoinfo_s *vinfo);</code><br>
       <code>int (*getplaneinfo)(FAR struct lcd_dev_s *dev, unsigned int planeno, FAR struct lcd_planeinfo_s *pinfo);</code>
     </p>
    </ul>
    <p>
      The following are provided only if the video hardware supports RGB color mapping:
    </p>
    <ul>
     <p>
       <code>int (*getcmap)(FAR struct lcd_dev_s *dev, FAR struct fb_cmap_s *cmap);</code><br>
       <code>int (*putcmap)(FAR struct lcd_dev_s *dev, FAR const struct fb_cmap_s *cmap);</code>
     </p>
    </ul>
    <p>
      The following are provided only if the video hardware supports a hardware cursor:
    </p>
    <ul>
     <p>
       <code>int (*getcursor)(FAR struct lcd_dev_s *dev, FAR struct fb_cursorattrib_s *attrib);</code><br>
       <code>int (*setcursor)(FAR struct lcd_dev_s *dev, FAR struct fb_setcursor_s *settings)</code>
     </p>
    </ul>
    <p>
      Get the LCD panel power status (0: full off - <code>CONFIG_LCD_MAXPOWER</code>: full on).
      On backlit LCDs, this setting may correspond to the backlight setting.
    </p>
    <ul>
     <p>
       <code>int (*getpower)(struct lcd_dev_s *dev);</code>
     </p>
    </ul>
    <p>
      Enable/disable LCD panel power (0: full off - <code>CONFIG_LCD_MAXPOWER</code>: full on).
      On backlit LCDs, this setting may correspond to the backlight setting.
    </p>
    <ul>
     <p>
       <code>int (*setpower)(struct lcd_dev_s *dev, int power);</code>
     </p>
    </ul>
    <p>
      Get the current contrast setting (0-CONFIG_LCD_MAXCONTRAST) */
    </p>
    <ul>
     <p>
       <code>int (*getcontrast)(struct lcd_dev_s *dev);</code>
     </p>
    </ul>
    <p>
      Set LCD panel contrast (0-CONFIG_LCD_MAXCONTRAST)
    </p>
    <ul>
     <p>
       <code>int (*setcontrast)(struct lcd_dev_s *dev, unsigned int contrast);</code>
     </p>
    </ul>
  </p>
  <li>
    <p>
      <b>Binding LCD Drivers</b>.
      LCD drivers are not normally directly accessed by user code, but are usually bound to another,
      higher level device driver.
      In general, the binding sequence is:
    </p>
    <p>
      <ol>
        <li>Get an instance of <code>struct lcd_dev_s</code> from the hardware-specific LCD device driver, and </li>
        <li>Provide that instance to the initialization method of the higher level device driver.</li>
      </ol>
    </p>
  </li>
  <li>
    <p>
      <b>Examples</b>:
      <code>drivers/lcd/nokia6100.c</code>, <code>drivers/lcd/p14201.c</code>, <code>configs/sam3u-ek/src/up_lcd.c.</code>
      See also the usage of the LCD driver in the <code>graphics/</code> directory.
    </p>
  </li>
</ul>

<h3><a name="mtddrivers">6.3.7 Memory Technology Device Drivers</a></h3>

<ul>
  <li>
    <p>
      <b><code>include/nuttx/mtd.h</code></b>.
      All structures and APIs needed to work with MTD drivers are provided in this header file.
    </p>
  </li>
  <li>
    <p>
      <b><code>struct mtd_dev_s</code></b>.
      Each MTD device driver must implement an instance of <code>struct mtd_dev_s</code>.
      That structure defines a call table with the following methods:
    </p>
    <p>
      Erase the specified erase blocks (units are erase blocks):
    </p>
    <ul>
     <p><code>int (*erase)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks);</code></p>
    </ul>
    <p>
      Read/write from the specified read/write blocks:
    </p>
    <ul>
     <p><code>ssize_t (*bread)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks, FAR uint8_t *buffer);</code><br>
     <code>ssize_t (*bwrite)(FAR struct mtd_dev_s *dev, off_t startblock, size_t nblocks, FAR const uint8_t *buffer);</code></p>
    </ul>
    <p>
      Some devices may support byte oriented reads (optional).
      Most MTD devices are inherently block oriented so byte-oriented writing is not supported.
      It is recommended that low-level drivers not support read() if it requires buffering.
    </p>
    <ul>
     <p><code>ssize_t (*read)(FAR struct mtd_dev_s *dev, off_t offset, size_t nbytes, FAR uint8_t *buffer);</code></p>
    </ul>
    <p>
      Support other, less frequently used commands:
    </p>
    <ul>
      <li><code>MTDIOC_GEOMETRY</code>:  Get MTD geometry</li>
      <li><code>MTDIOC_XIPBASE:</code>: Convert block to physical address for eXecute-In-Place</li>
      <li><code>MTDIOC_BULKERASE</code>: Erase the entire device</li>
    </ul>
    <p>
      is provided via a sinble <code>ioctl</code> method (see <code>include/nuttx/ioctl.h</code>):
    </p>
    <ul>
     <p><code>int (*ioctl)(FAR struct mtd_dev_s *dev, int cmd, unsigned long arg);</code></p>
    </ul>
  </li>
  <li>
    <p>
      <b>Binding MTD Drivers</b>.
      MTD drivers are not normally directly accessed by user code, but are usually bound to another,
      higher level device driver.
      In general, the binding sequence is:
    </p>
    <p>
      <ol>
        <li>Get an instance of <code>struct mtd_dev_s</code> from the hardware-specific MTD device driver, and </li>
        <li>Provide that instance to the initialization method of the higher level device driver.</li>
      </ol>
    </p>
  </li>
  <li>
    <p>
      <b>Examples</b>:
      <code>drivers/mtd/m25px.c</code> and <code>drivers/mtd/ftl.c</code>
    </p>
  </li>
</ul>

<h3><a name="sdiodrivers">6.3.8 SDIO Device Drivers</a></h3>

<ul>
  <li>
    <p>
      <b><code>include/nuttx/sdio.h</code></b>.
      All structures and APIs needed to work with SDIO drivers are provided in this header file.
    </p>
  </li>
  <li>
    <p>
      <b><code>struct sdio_dev_s</code></b>.
      Each SDIOI device driver must implement an instance of <code>struct sdio_dev_s</code>.
      That structure defines a call table with the following methods:
    </p>
    <p>
      Initialization/setup:
    </p>
    <ul>
     <p><code>void (*reset)(FAR struct sdio_dev_s *dev);</code><br>
     <code>uint8_t (*status)(FAR struct sdio_dev_s *dev);</code><br>
     <code>void (*widebus)(FAR struct sdio_dev_s *dev, bool enable);</code><br>
     <code>void (*clock)(FAR struct sdio_dev_s *dev, enum sdio_clock_e rate);</code><br>
     <code>int (*attach)(FAR struct sdio_dev_s *dev);</code></p>
    </ul>
    <p>
      Command/Status/Data Transfer:
    </p>
    <ul>
     <p><code>void (*sendcmd)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t arg);</code><br>
     <code>int (*recvsetup)(FAR struct sdio_dev_s *dev, FAR uint8_t *buffer, size_t nbytes);</code><br>
     <code>int (*sendsetup)(FAR struct sdio_dev_s *dev, FAR const uint8_t *buffer, size_t nbytes);</code><br>
     <code>int (*cancel)(FAR struct sdio_dev_s *dev);</code><br>
     <code>int (*waitresponse)(FAR struct sdio_dev_s *dev, uint32_t cmd);</code><br>
     <code>int (*recvR1)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R1);</code><br>
     <code>int (*recvR2)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t R2[4]);</code><br>
     <code>int (*recvR3)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R3);</code><br>
     <code>int (*recvR4)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R4);</code><br>
     <code>int (*recvR5)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R5);</code><br>
     <code>int (*recvR6)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R6);</code><br>
     <code>int (*recvR7)(FAR struct sdio_dev_s *dev, uint32_t cmd, uint32_t *R7);</code></p>
    </ul>
    <p>
      Event/Callback support:
    </p>
    <ul>
     <p><code>void (*waitenable)(FAR struct sdio_dev_s *dev, sdio_eventset_t eventset);</code><br>
     <code>sdio_eventset_t (*eventwait)(FAR struct sdio_dev_s *dev, uint32_t timeout);</code><br>
     <code>void (*callbackenable)(FAR struct sdio_dev_s *dev, sdio_eventset_t eventset);</code><br>
     <code>int (*registercallback)(FAR struct sdio_dev_s *dev, worker_t callback, void *arg);</code></p>
    </ul>
    <p>
      DMA support:
    </p>
    <ul>
     <p><code>bool (*dmasupported)(FAR struct sdio_dev_s *dev);</code><br>
     <code>int (*dmarecvsetup)(FAR struct sdio_dev_s *dev, FAR uint8_t *buffer, size_t buflen);</code><br>
     <code>int (*dmasendsetup)(FAR struct sdio_dev_s *dev, FAR const uint8_t *buffer,  size_t buflen);</code></p>
    </ul>
  </li>
  <li>
    <p>
      <b>Binding SDIO Drivers</b>.
      SDIO drivers are not normally directly accessed by user code, but are usually bound to another,
      higher level device driver.
      In general, the binding sequence is:
    </p>
    <p>
      <ol>
        <li>Get an instance of <code>struct sdio_dev_s</code> from the hardware-specific SDIO device driver, and </li>
        <li>Provide that instance to the initialization method of the higher level device driver.</li>
      </ol>
    </p>
  </li>
  <li>
    <p>
      <b>Examples</b>:
      <code>arch/arm/src/stm32/stm32_sdio.c</code> and <code>drivers/mmcsd/mmcsd_sdio.c</code>
    </p>
  </li>
</ul>

<h3><a name="usbhostdrivers">6.3.9 USB Host-Side Drivers</a></h3>

<ul>
  <li>
    <p>
      <b><code>include/nuttx/usb/usbhost.h</code></b>.
      All structures and APIs needed to work with USB host-side drivers are provided in this header file.
    </p>
  </li>
  <li>
    <p>
      <b><code>struct usbhost_driver_s</code></b>.
      Each USB host controller driver must implement an instance of <code>struct usbhost_driver_s</code>.
      This structure is defined in <code>include/nuttx/usb/usbhost.h</code>.
    </p>
    <p>
      <b>Examples</b>:
      <code>arch/arm/src/lpc17xx/lpc17_usbhost.c</code>.
    </p>
  </li>
  <li>
    <p>
      <b><code>struct usbhost_class_s</code></b>.
      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
      (and also detect disconnected devices):
    </p>
    <p>
      <ul>
        <li>
          <p>
            <code>int (*wait)(FAR struct usbhost_driver_s *drvr, bool connected);</code>
          </p>
          <p>
            Wait for a device to be connected or disconnected.
          </p>
        </li>
        <li>
          <p>
            <code>int (*enumerate)(FAR struct usbhost_driver_s *drvr);</code>
          </p>
          <p>
            Enumerate the connected device.
            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><a name="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.
    </p>
  </li>
  <li>
    <p>
      <b><code>struct usbdev_s</code></b>.
      Each USB device controller driver must implement an instance of <code>struct usbdev_s</code>.
      This structure is defined in <code>include/nuttx/usb/usbdev.h</code>.
    </p>
    <p>
      <b>Examples</b>:
      <code>arch/arm/src/dm320/dm320_usbdev.c</code>, <code>arch/arm/src/lpc17xx/lpc17_usbdev.c</code>, 
      <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/usbdev_serial.c</code> and <code>drivers/usbdev/usbdev_storage.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/usbdev_serial.c</code> and
            the function <code></code> in the file <code>drivers/usbdev/usbdev_storage.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>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
    <td>
      <h1><a name="apndxconfigs">Appendix A:  NuttX Configuration Settings</a></h1>
    </td>
  </tr>
</table>

<p>
  The following variables are recognized by the build (you may
  also include architecture-specific settings).
</p>

<h2>Architecture selection</h2>
<p>
  The following configuration 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_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 <a href="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>
</ul>
<p>
  Building application code:
</p>
<ul>
  <li>
    <p>
      <code>CONFIG_APP_DIR</code>: Ldentifies the directory that builds the application to link with NuttX.
      This symbol must be assigned to the path to the application build directory <i>relative</i> to the NuttX top build direcory.
      As an an example, there are several example applicatins in the NuttX <code>examples/</code> sub-directory.
      To use one of these example applications, say <code>nsh</code>, you would set <code>CONFIG_APP_DIR=examples/nsh</code>.
      If you had an application directory and the NuttX directory both within another directory like this:
<ul><pre>
build
 |-nuttx
 |  |
 |  `- Makefile
 `-application
    |
    `- Makefile
</pre></ul>
      Then you would set <code>CONFIG_APP_DIR=../application</code>.
    </p>
    <p>
      The application direction must contain <code>Makefile</code> and this make file must support the following targets:
      <ul>
        <li>
          <code>libapp$(LIBEXT)</code> (usually <code>libapp.a</code>).
          <code>libapp.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>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:
      <ul>
        <code>$(MAKE) -C $(CONFIG_APP_DIR) TOPDIR=&quot;$(TOPDIR)&quot;</code> &lt;target&gt;
      </ul>
    </p>
    <p>
      <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_OBJECT is 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>
    <code>CONFIG_PASS1_OBJECT</code>: The name of the first pass object.
  </li>
  <li><code>CONFIG_PASS1_BUILDIR</code>:
  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:
  <ul>
    <li>The special target <code>arch/$(CONFIG_ARCH)/src/$(CONFIG_PASS1_OBJECT)</code>, and</li>
    <li>The usual depend, clean, and distclean targets.</li>
  </ul>
</ul>

<h2>General OS setup</h2>
<ul>
  <li>
    <code>CONFIG_DEBUG</code>: enables built-in debug options
  </li>
  <li>
    <code>CONFIG_DEBUG_VERBOSE</code>: enables verbose debug output
  </li>
  <li>
    <code>CONFIG_DEBUG_SYMBOLS</code>: build without optimization and with debug symbols (needed for use with a debugger).
  </li>
  <li>
    <code>CONFIG_DEBUG_SCHED</code>: enable OS debug output (disabled by default)
  </li>
  <li>
    <code>CONFIG_DEBUG_MM</code>: enable memory management debug output (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>
  <li>
    <code>CONFIG_ARCH_LOWPUTC</code>: architecture supports low-level, boot
    time console output
  </li>
  <li>
    <code>CONFIG_MM_REGIONS</code>: If the architecture includes multiple
    regions of memory to allocate from, this specifies the
    number of memory regions that the memory manager must
    handle and enables the API mm_addregion(start, end);
  </li>
  <li>
    <code>CONFIG_TICKS_PER_MSEC</code>: The default system timer is 100Hz
    or <code>TICKS_PER_MSEC</code>=10.  This setting may be defined to inform NuttX
    that the processor hardware is providing system timer interrupts at some interrupt
    interval other than 10 msec.
  </li>
  <li>
    <code>CONFIG_RR_INTERVAL</code>: The round robin time slice will be set
    this number of milliseconds;  Round robin scheduling can
    be disabled by setting this value to zero.
  </li>
  <li>
    <code>CONFIG_SCHED_INSTRUMENTATION</code>: enables instrumentation in 
    scheduler to monitor system performance
  </li>
  <li>
    <code>CONFIG_TASK_NAME_SIZE</code>: Specifies that maximum size of a
    task name to save in the TCB.  Useful if scheduler
    instrumentation is selected.  Set to zero to disable.
  </li>
  <li>
    <code>CONFIG_START_YEAR</code>, <code>CONFIG_START_MONTH</code>, <code>CONFIG_START_DAY</code> -
    Used to initialize the internal time logic.
  </li>
  <li>
    <code>CONFIG_GREGORIAN_TIME</code>: Enables Gregorian time conversions.
    You would only need this if you are concerned about accurate time conversions in
    the recent past or in the distant future.
  </li>
  <li>
    <code>CONFIG_JULIAN_TIME</code>: Enables Julian time conversions.
    You would only need this if you are concerned about accurate time conversion in the distand past.
    You must also define <code>CONFIG_GREGORIAN_TIME</code> in order to use Julian time.
  </li>
  <li>
    <code>CONFIG_DEV_CONSOLE</code>: Set if architecture-specific logic
    provides /dev/console.  Enables stdout, stderr, stdin.
  </li>
  <li>
    <code>CONFIG_MUTEX_TYPES</code>: Set to enable support for recursive and
    errorcheck mutexes.  Enables <code>pthread_mutexattr_settype()</code>.
  </li>
  <li>
    <code>CONFIG_PRIORITY_INHERITANCE</code>: Set to enable support for
    priority inheritance on mutexes and semaphores.
    Priority inheritance is a strategy of addressing
    <a href="NuttxUserGuide.html#priorityinversion"><i>priority inversion</i></a>.
    Details of the NuttX implementation of priority inheritance is
    discussed <a href="NuttxUserGuide.html#priorityinheritance">elsewhere</a>.
  </li>
  <li>
    <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.
  </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.
  </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 filesystem (see <code>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>
</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
          <a href="http://www.nuttx.org/NuttXDemandPaging.html">http://www.nuttx.org/NuttXDemandPaging.html</a>.
  </li>
</ul>

<p>
  If CONFIG_PAGING is selected, then you will probabaly need <code>CONFIG_BUILD_2PASS</code> to correctly position
  the code and the following configuration options also apply:
</p>
<ul>
  <li>
    <code>CONFIG_PAGING_PAGESIZE</code>:
    The size of one managed page.
    This must be a value supported by the processor's memory management unit.
  </li>
  <li>
    <code>CONFIG_PAGING_NLOCKED</code>:
    This is the number of locked pages in the memory map.
    The locked address region will then be from <code>CONFIG_DRAM_VSTART</code> through
    (<code>CONFIG_DRAM_VSTART</code> + <code>CONFIG_PAGING_PAGESIZE</code>*<code>CONFIG_PAGING_NLOCKED</code>)
  </li>
  <li>
    <code>CONFIG_PAGING_LOCKED_PBASE</code> and <code>CONFIG_PAGING_LOCKED_VBASE</code>:
    These may be defined to determine the base address of the locked page regions.
    If neither are defined, the logic will be set the bases to <code>CONFIG_DRAM_START</code>
    and <code>CONFIG_DRAM_VSTART</code> (i.e., it assumes that the base address of the locked
    region is at the beginning of RAM).
    <b>NOTE</b>:
    In some architectures, it may be necessary to take some memory from the beginning
    of this region for vectors or for a page table.
    In such cases, <code>CONFIG_PAGING_LOCKED_P/VBASE</code> should take that into consideration
    to prevent overlapping the locked memory region and the system data at the beginning of SRAM.
  </li>
  <li>
    <code>CONFIG_PAGING_NPPAGED</code>:
    This is the number of physical pages available to support the paged text region.
    This paged region begins at
    (<code>CONFIG_PAGING_LOCKED_PBASE</code> + <code>CONFIG_PAGING_PAGESIZE</code>*<code>CONFIG_PAGING_NPPAGED</code>)
    and continues until
    (<code>CONFIG_PAGING_LOCKED_PBASE</code> + <code>CONFIG_PAGING_PAGESIZE</code>*(<code>CONFIG_PAGING_NLOCKED</code> +
    <code>CONFIG_PAGING_NPPAGED</code>)
  </li>
  <li>
    <code>CONFIG_PAGING_NVPAGED</code>:
    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 &quot;minor&quot; 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>