nuttx/configs/sim/README.txt

README
^^^^^^

Contents
^^^^^^^^
  o Overview
    - Description
    - Fake Interrupts
    - Timing Fidelity
  o Debugging
  o Issues
    - 64-bit Issues
    - Stack Size Issues
    - Buffered I/O Issues
    - Networking Issues
    - X11 Issues
  o Configurations

Overview
^^^^^^^^

Description
-----------
This README file describes the contents of the build configurations available
for the NuttX "sim" target.  The sim target is a NuttX port that runs as a
user-space program under Linux or Cygwin.  It is a very "low fidelity" embedded
system simulation: This environment does not support any kind of asynchonous
events -- there are nothing like interrupts in this context.  Therefore, there
can be no pre-empting events.

Fake Interrupts
---------------
In order to get timed behavior, the system timer "interrupt handler" is called
from the sim target's IDLE loop.  The IDLE runs whenever there is no other task
running.  So, for example, if a task calls sleep(), then that task will suspend
wanting for the time to elapse.  If nothing else is available to run, then the
IDLE loop runs and the timer increments, eventually re-awakening the sleeping task.

Context switching is based on logic similar to setjmp() and longjmp().

The sim target is used primarily as a development and test platform for new
RTOS features.  It is also of academic interest.  But it has no real-world
application that I know of.

Timing Fidelity
---------------
NOTE:  In order to facility fast testing, the sim target's IDLE loop, by default,
calls the system "interrupt handler" as fast as possible.  As a result, there
really are no noticeable delays when a task sleeps.  However, the task really does
sleep -- but the time scale is wrong.  If you want behavior that is closer to
normal timing, then you can define CONFIG_SIM_WALLTIME=y in your configuration
file.  This configuration setting will cause the sim target's IDLE loop to delay
on each call so that the system "timer interrupt" is called at a rate approximately
correct for the system timer tick rate.  With this definition in the configuration,
sleep() behavior is more or less normal.

Debugging
^^^^^^^^^
One of the best reasons to use the simulation is that is supports great, Linux-
based debugging.  Here are the steps that I following to use the Linux ddd
graphical front-end to GDB:

1. Modify the top-level configuration file.  Enable debug symbols by defining
   the following.

   cd <NuttX-Directory>
   CONFIG_DEBUG_SYMBOLS=y

2. Re-build:

   cd <NuttX-Directory>
   make clean
   make

3. Then start the debugging:

   ddd nuttx &
   gdb> b user_start
   gdb> r

NOTE:  This above steps work fine on both Linux and Cygwin.  On Cygwin, you
will need to start the Cywin-X server before running ddd.

Issues
^^^^^^

64-Bit Issues
-------------
As mentioned above, context switching is based on logic like setjmp and longjmp.
This context switching is only available for 32-bit targets.  On 64-bit machines,
this context switching will fail.

There are other 64-bit issues as well.  For example, addresses are retained in
32-bit unsigned integer types in a few places.  On a 64-bit machine, the 32-bit
address storage may correcupt 64-bit addressing.  NOTE:  This is really a bug --
addresses should not be retained in uint32_t types but rather in uintptr_t types
to avoid issues just like this.

The workaround on 64-bit machines for now is to build for a 32-bit target on the
64-bit machine.  The workaround for this issue has been included in NuttX 6.15 and
beyond.  For thoses versions, you must add CONFIG_SIM_M32=y to the .config file in
order to enable building a 32-bit image on a 64-bit platform.

For older versions of NuttX, a patch also exists.  The patch the Make.defs file in the
appropriate places so that -m32 is included in the CFLAGS and -m32 and -melf_386
are included in the LDFLAGS. See the patch
0001-Quick-hacks-to-build-sim-nsh-ostest-on-x86_64-as-32-.patch that can be found at
http://tech.groups.yahoo.com/group/nuttx/files.

Stack Size Issues
-----------------
When you run the NuttX simulation, it uses stacks allocated by NuttX from the
NuttX heap.  The memory management model is exactly the same in the simulation
as it is real, target system.  This is good because this produces a higher
fidelity simulation.

However, when the simulation calls into Linux/Cygwin libraries, it will still
use these small simulation stacks.  This happens, for example, when you call
into the system to get and put characters to the console window or when you
make x11 calls into the system.  The programming model within those libraries
will assume a Linux/Cygwin environment where the stack size grows dynamically
and not the small, limited stacks of a deeply embedded system.

As a consequence, those system libraries may allocate large data structures
on the stack and overflow the small NuttX stacks.  X11, in particular,
requires large stacks.  If you are using X11 in the simulation, make sure
that you set aside a "lot" of stack for the X11 system calls (maybe 8 or 16Kb).
The stack size for the thread that begins with user start is controlled
by the configuration setting CONFIG_USERMAIN_STACKSIZE; you may need to
increase this value to larger number to survive the X11 system calls.

If you are running X11 applications as NSH add-on programs, then the stack
size of the add-on program is controlled in another way.  Here are the
steps for increasing the stack size in that case:

  cd ../apps/namedapps  # Go to the namedapps directory
  vi namedapps_list.h   # Edit this file and increase the stack size of the add-on
  rm .built *.o         # This will force the namedapps logic to rebuild

Buffered I/O Issues
-------------------
The simulated serial driver has some odd behavior.  It will stall for a long time
on reads when the C stdio buffers are being refilled. This only effects the behavior
of things like fgetc().  Workaround: Set CONFIG_STDIO_BUFFER_SIZE=0, suppressing
all C buffered I/O.

Networking Issues
-----------------
I never did get networking to work on the sim target.  It tries to use the tap device
(/dev/net/tun) to emulate an Ethernet NIC, but I never got it correctly integrated
with the NuttX networking (I probably should try using raw sockets instead).

X11 Issues
----------
There is an X11-based framebuffer driver that you can use exercise the NuttX graphics
subsystem on the simulator (see the sim/nx11 configuration below).  This may require a
lot of tinkering to get working, depending upon where your X11 installation stores
libraries and header files and how it names libraries.

For example, on UBuntu 9.09, I had to do the following to get a clean build:

    cd /usr/lib/
    sudo ln -s libXext.so.6.4.0 libXext.so

(I also get a segmentation fault at the conclusion of the NX test -- that will need
to get looked into as well).

The X11 examples builds on Cygwin, but does not run.  The last time I tried it,
XOpenDisplay() aborted the program.  UPDATE:  This was caused by the small stack
size and can be fixed by increasing the size of the NuttX stack that calls into
X11.  See the discussion "Stack Size Issues" above.

Configurations
^^^^^^^^^^^^^^

mount

  Description
  -----------
  Configures to use examples/mount.  This configuration may be
  selected as follows:

    cd <nuttx-directory>/tools
    ./configure.sh sim/mount

nettest

  Description
  -----------
  Configures to use examples/nettest.  This configuration
  enables networking using the network TAP device.  It may
  be selected via:

    cd <nuttx-directory>/tools
    ./configure.sh sim/nettest

  NOTES:
  - The NuttX network is not, however, functional on the Linux TAP
    device yet.

  - As of NuttX-5.18, when built on Windows, this test does not try
    to use the TAP device (which is not available on Cygwin anyway), 
    but inside will try to use the Cygwin WPCAP library.  Only the
    most preliminary testing has been performed with the Cygwin WPCAP
    library, however.

    NOTE that the IP address is hard-coded in arch/sim/src/up_wpcap.c.
    You will either need to edit your configuration files to use 10.0.0.1
    on the "target" (CONFIG_EXAMPLE_NETTEST_*) or edit up_wpcap.c to
    select the IP address that you want to use.

nsh

  Description
  -----------
  Configures to use the NuttShell at examples/nsh.  This configuration
  may be selected as follows:

    cd <nuttx-directory>/tools
    ./configure.sh sim/nsh

nsh2

  Description
  -----------
  This is another example that configures to use the NuttShell at examples/nsh.
  Unlike nsh, this version uses NSH built-in functions.  The nx, nxhello, and
  nxlines examples are included as built-in functions.

  X11 Configuration
  -----------------
  This configuration uses an X11-based framebuffer driver.  Of course, this
  configuration can only be used in environments that support X11!  (And it
  may not even be usable in all of those environments without some "tweaking"
  See discussion below under the nx11 configuration).

  Configuring
  -----------
  This configuration may be selected as follows:

    cd <nuttx-directory>/tools
    ./configure.sh sim/nsh2

nx

  Description
  -----------
  Configures to use examples/nx.  This configuration may be
  selected as follows:

    cd <nuttx-directory>/tools
    ./configure.sh sim/nx

  Special Framebuffer Configuration
  ---------------------------------
  Special simulated framebuffer configuration options:

    CONFIG_SIM_FBHEIGHT - Height of the framebuffer in pixels
    CONFIG_SIM_FBWIDTH  - Width of the framebuffer in pixels.
    CONFIG_SIM_FBBPP    - Pixel depth in bits

  No Display!
  -----------
  This version has NO DISPLAY and is only useful for debugging NX
  internals in environments where X11 is not supported.  There is
  and additonal configuration that may be added to include an X11-
  based simulated framebuffer driver:
  
    CONFIG_SIM_X11FB    - Use X11 window for framebuffer

  See the "nx11" configuration below for more information.

  Multi- and Single-User Modes
  ----------------------------
  The default is the single-user NX implementation.  To select
  the multi-user NX implementation:

    CONFG_NX_MULTIUSER=y
    CONFIG_DISABLE_MQUEUE=n

nx11

  Description
  -----------
  Configures to use examples/nx.  This configuration is similar
  to the nx configuration except that it adds support for an X11-
  based framebuffer driver.  Of course, this configuration can only
  be used in environments that support X11!  (And it may not even
  be usable in all of those environments without some "tweaking").
  
  This configuration may be selected as follows:

    cd <nuttx-directory>/tools
    ./configure.sh sim/nx11

  Special Framebuffer Configuration
  ---------------------------------
  This configuration uses the same special simulated framebuffer
  configuration options as the nx configuration:

    CONFIG_SIM_X11FB    - Use X11 window for framebuffer
    CONFIG_SIM_FBHEIGHT - Height of the framebuffer in pixels
    CONFIG_SIM_FBWIDTH  - Width of the framebuffer in pixels.
    CONFIG_SIM_FBBPP    - Pixel depth in bits

  X11 Configuration
  -----------------
  But now, since CONFIG_SIM_X11FB is also selected the following
  definitions are needed

    CONFIG_SIM_FBBPP (must match the resolution of the display).
    CONFIG_FB_CMAP=y

  My system has 24-bit color, but packed into 32-bit words so
  the correct seeting of CONFIG_SIM_FBBPP is 32.

  For whatever value of CONFIG_SIM_FBBPP is selected, the
  corresponidng CONFIG_NX_DISABLE_*BPP setting must not be
  disabled.

  Touchscreen Support
  -------------------
  A X11 mouse-based touchscreen simulation can also be enabled
  by setting:

    CONFIG_INPUT=y
    CONFIG_SIM_TOUCHSCREEN=y

  Then you must also have some application logic that will call
  sim_tcinitialize(0) to register the touchscreen driver.  See
  also configuration "touchscreen"

  NOTES:

  1. If you do not have the call to sim_tcinitializE(0), the build
     will mysteriously fail claiming that is can't find up_tcenter()
     and up_tcleave().  That is a consequence of the crazy way that
     the simulation is built and can only be eliminated by calling
     up_simtouchscreen(0) from your application.

  2. You must first up_fbinitialize() before calling up_simtouchscreen()
     or you will get a crash.

  3. Call sim_tcuninintialize() when you are finished with the
     simulated touchscreen.

  4. Enable CONFIG_DEBUG_INPUT=y for touchscreen debug output.

  X11 Build Issues
  ----------------
  To get the system to compile under various X11 installations
  you may have to modify a few things.  For example, in order
  to find libXext, I had to make the following change under
  Ubuntu 9.09:

    cd /usr/lib/
    sudo ln -s libXext.so.6.4.0 libXext.so

  Multi- and Single-User Modes
  ----------------------------
  The default is the single-user NX implementation.  To select
  the multi-user NX implementation:

    CONFG_NX_MULTIUSER=y
    CONFIG_DISABLE_MQUEUE=n

  examples/nxconsole
  ------------------
  This configuration is also set up to use the examples/nxconsole
  test instead of examples/nx.  Simply comment out the following
  in the appconfig file:

    -CONFIGURED_APPS += examples/nx
    +#CONFIGURED_APPS += examples/nx

  And uncomment the following:

    -#CONFIGURED_APPS += examples/nxconsole
    +CONFIGURED_APPS += examples/nxconsole

ostest

  Description
  -----------
  The "standard" NuttX examples/ostest configuration.  This
  configuration may be selected as follows:

    cd <nuttx-directory>/tools
    ./configure.sh sim/ostest

pashello

  Description
  -----------
  Configures to use examples/pashello.  This configuration may
  by selected as follows:

    cd <nuttx-directory>/tools
    ./configure.sh sim/pashello

touchscreen

  Description
  -----------
  This configuration uses the simple touchscreen test at
  apps/examples/touchscreen.  This test will create an empty X11 window
  and will print the touchscreen output as it is received from the 
  simulated touchscreen driver.  This configuration may
  by selected as follows:

    cd <nuttx-directory>/tools
    ./configure.sh sim/touchscreen

  Since this example uses the simulated frame buffer driver, the
  most of the configuration settings discussed for the "nx11"
  configuration also apply here.  See that discussion above.

  See apps/examples/README.txt for further information about build
  requirements and configuration settings.