Add definitions to stdlib.h; update README

git-svn-id: https://nuttx.svn.sourceforge.net/svnroot/nuttx/trunk@4071 7fd9a85b-ad96-42d3-883c-3090e2eb8679

1 files changed, 93 insertions, 39 deletions

diff --git a/apps/README.txt b/apps/README.txt
index af3d073040..f6d888adc5 100644
--- a/apps/README.txt
+++ b/apps/README.txt
@@ -1,70 +1,124 @@
 Application Folder
 ==================
 
-This folder provides various applications found in sub-directories.
-
-Application entry points with their requirements are gathered together in 
-in two files:
-
-	- namedapp/namedapp_proto.h	Entry points, prototype function
-	- namedapp/namedapp_list.h	Application specific information and requirements
+Contents
+--------
+
+  General
+  Directory Location
+  Named Applications
+  Named Startup main() function
+  NuttShell (NSH) Built-In Commands
+  Application Configuration File
+  Example Named Application
+
+General
+-------
+This folder provides various applications found in sub-directories.  These
+applications are not inherently a part of NuttX but are provided you help
+you develop your own applications.  The apps/ directory is a "break away"
+part of the configuration that you may chose to use or not.
+
+Directory Location
+------------------
+The default application directory used by the NuttX build should be named
+apps/ (or apps-x.y/ where x.y is the NuttX version number).  This apps/
+directoy should appear in the directory tree at the same level as the
+NuttX directory.  Like:
+
+ .
+ |- nuttx
+ |
+ `- apps
+
+If all of the above conditions are TRUE, then NuttX will be able to
+find the application directory.  If your application directory has a 
+different name or is location at a different position, then you will
+have to inform the NuttX build system of that location.  There are several
+ways to do that:
+
+1) You can define CONFIG_APPS_DIR to be the full path to your application
+   directory in the NuttX configuration file.
+2) You can provide the path to the application directory on the command line
+   like:  make APPDIR=<path> or make CONFIG_APPS_DIR=<path>
+3) When you configure NuttX using tools/configure.sh, you can provide that
+   path to the application directory on the configuration command line
+   like: ./configure.sh -a <app-dir> <board-name>/<config-name>
+
+Named Applications
+------------------
+NuttX also supports applications that can be started using a name string.
+In this case, zpplication entry points with their requirements are gathered
+together in two files:
+
+  - namedapp/namedapp_proto.h  Entry points, prototype function
+  - namedapp/namedapp_list.h  Application specific information and requirements
 
 The build occurs in several phases as different build targets are executed:
-(1) contex, (2) depend, and (3) default (all). Application information is
+(1) context, (2) depend, and (3) default (all). Application information is
 collected during the make context build phase.
 
 To execute an application function:
 
-	exec_namedapp() is defined in the nuttx/include/apps/apps.h 
-	
-NuttShell provides transparent method of invoking the command, when the
-following option is enabled:
+  exec_namedapp() is defined in the nuttx/include/apps/apps.h 
 
-	CONFIG_NSH_BUILTIN_APPS=y
+NuttShell (NSH) Built-In Commands
+---------------------------------
+One use of named applications is to provide a way of invoking your custom
+application through the NuttShell (NSH) command line.  NSH will support
+a seamless method invoking the applications, when the following option is
+enabled in the NuttX configuration file:
 
-in the NuttX configuration.
+  CONFIG_NSH_BUILTIN_APPS=y
 
+Application Configuration File
+------------------------------
 A special configuration file is used to configure which applications
-are to be included in the build.  This file is configs/<board>/<configuration>/appconfig.
-The existence of the appconfig file in the board configuration directory
-is sufficient to enable building of applications.
+are to be included in the build.  The source for this file is 
+configs/<board>/<configuration>/appconfig.  The existence of the appconfig
+file in the board configuration directory is sufficient to enable building
+of applications.
 
 The appconfig file is copied into the apps/ directory as .config when
 NuttX is configured.  .config is included in the toplevel apps/Makefile.
 As a minimum, this configuration file must define files to add to the
 CONFIGURED_APPS list like:
 
-  CONFIGURED_APPS  += hello poweroff jvm
-
-The form of each entry is <dir>=<dependency> when:
-
-  <dir> is the name of a subdirectory in the apps directory, and
+  CONFIGURED_APPS  += vsn/hello vsn/poweroff vsn/jvm
 
-  <dependency> is a make dependency.  This will be "touch"-ed each time
-  that the sub-directory is rebuilt.
+Named Start-Up main() function
+------------------------------
+A named application can even be used as the main, start-up entry point
+into your embedded software.  When the user defines this option in
+the NuttX configuration file:
 
-When the user defines an option:
-	CONFIG_BUILTIN_APP_START=<application name>
-	
-that application shall be invoked immediately after system starts.
-Note that application name must be provided in ".." as: "hello", 
+  CONFIG_BUILTIN_APP_START=<application name>
+  
+that application shall be invoked immediately after system starts
+*instead* of the normal, default "user_start" entry point.
+Note that <application name> must be provided as: "hello", 
 will call:
-	int hello_main(int argc, char *argv[])
 
-Application skeleton can be found under the hello sub-directory,
-which shows how an application can be added to the project. One must
-define:
+  int hello_main(int argc, char *argv[])
+
+Example Named Application
+-------------------------
+An example application skeleton can be found under the vsn/hello
+sub-directory.  This example shows how a named application can be added
+to the project. One must define:
 
  1. create sub-directory as: appname
  2. provide entry point: appname_main()
  3. set the requirements in the file: Makefile, specially the lines:
-	APPNAME		= appname
-	PRIORITY	= SCHED_PRIORITY_DEFAULT
-	STACKSIZE	= 768
-	ASRCS		= asm source file list as a.asm b.asm ...
-	CSRCS		= C source file list as foo1.c foo2.c ..
 
- 4. add application in the apps/Makefile
+  APPNAME    = appname
+  PRIORITY  = SCHED_PRIORITY_DEFAULT
+  STACKSIZE  = 768
+  ASRCS    = asm source file list as a.asm b.asm ...
+  CSRCS    = C source file list as foo1.c foo2.c ..
+
+ 4. add application in the apps/.config
+