Update README files, Kconfig help comments, and make the network monitor not EXPERIMENTAL

5 files changed, 242 insertions, 75 deletions

diff --git a/nuttx/TODO b/nuttx/TODO
index 50117d83f..df6014ca3 100644
--- a/nuttx/TODO
+++ b/nuttx/TODO
@@ -1,4 +1,4 @@
-NuttX TODO List (Last updated August 11, 2014)
+NuttX TODO List (Last updated August 18, 2014)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This file summarizes known NuttX bugs, limitations, inconsistencies with
@@ -49,7 +49,7 @@ nuttx/
 apps/
 
   (4)  Network Utilities (apps/netutils/)
-  (5)  NuttShell (NSH) (apps/nshlib)
+  (3)  NuttShell (NSH) (apps/nshlib)
   (1)  System libraries apps/system (apps/system)
   (5)  Other Applications & Tests (apps/examples/)
 
@@ -2313,61 +2313,6 @@ o NuttShell (NSH) (apps/nshlib)
   Status:      Open
   Priority:    Low (enhancement)
 
-  Title:       NETWORK BRINGUP
-  Description: If the network is available on reset, then there is really
-               no problem.  Negotiating the link will take only a second or
-               so and the delay to the NSH prompt is normally acceptable.
-
-               But if there is no network connected, then the start-up delay
-               can be very long depending upon things like the PHY, timeout
-               delay times, and numbers of retries.  A failed negotiation
-               can take a very long time, perhaps as much as a minute...
-               Long enough that you would think that the board would never
-               come up.
-
-               The problem is that all of the initialization is sequential:
-               NSH does not run until each sequential initialization step is
-               completed.
-
-               There is an option enabled by CONFIG_NSH_NETINIT_THREAD that
-               will do the network bring-up asynchronously in parallel on
-               a separate thread.  This eliminates the networking delay
-               altogether.  The initial implementation, however, has some
-               limitations:
-
-               - If no network is connected, the network bring-up will fail
-                 and the network initialization thread will simply exit.
-                 There are no retries and no mechanism to know if the network
-                 initialization was successful.
-
-               - Furthermore, there is currently no support for detecting loss
-                 of network connection and recovery of the connection (see the
-                 next issue).
-  Status:      Open
-  Priority:    Medium, but certainly high if you plan to use the generic
-               NSH in a product with a network.
-
-  Title:       LOSS OF CONNECTION
-  Description: There is no logic in place no to detect that the network
-               connection has been lost (if the cable has been unplugged,
-               for example).  And also no logic to bring the network back
-               up when the link can be re-established.
-
-               This is normally done by catching a GPIO interrupt from a
-               PHY.  This is logic outside of the Ethernet MAC driver
-               (although the Ethernet MAC driver would also have to
-               support the PHY operations to determine the link state).
-               Some of the boards provide logic to connect to the PHY
-               interrupt.  Like:
-
-                 xcpt_t arc_phy_irq(FAR const char *intf, xcpt_t irqhandler);
-
-               (prototyped in include/nuttx/arch.h). But that interrupt is
-               not used by anything now.
-  Status:      Open
-  Priority:    Medium.
-
-  Status:      Open
 o System libraries apps/system (apps/system)
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/nuttx/configs/sam4e-ek/README.txt b/nuttx/configs/sam4e-ek/README.txt
index 6704039de..a6b7240e6 100644
--- a/nuttx/configs/sam4e-ek/README.txt
+++ b/nuttx/configs/sam4e-ek/README.txt
@@ -507,6 +507,32 @@ Networking Support
   a network because additional time will be required to fail with timeout
   errors.
 
+  This delay will be especially long if the board is not connected to
+  a network.  On the order of a minute!  You will probably think that
+  NuttX has crashed!  And then, when it finally does come up, the
+  network will not be available.
+
+  Network Initialization Thread
+  -----------------------------
+  There is a configuration option enabled by CONFIG_NSH_NETINIT_THREAD
+  that will do the NSH network bring-up asynchronously in parallel on
+  a separate thread.  This eliminates the (visible) networking delay
+  altogether.  This current implementation, however, has some limitations:
+
+    - If no network is connected, the network bring-up will fail and
+      the network initialization thread will simply exit.  There are no
+      retries and no mechanism to know if the network initialization was
+      successful (it could perform a network Ioctl to see if the link is
+      up and it now, keep trying, but it does not do that now).
+
+    - Furthermore, there is currently no support for detecting loss of
+      network connection and recovery of the connection (similarly, this
+      thread could poll periodically for network status, but does not).
+
+  Both of these shortcomings could be eliminated by enabling the network
+  monitor.  See the SAMA5 configurations for a description of what it would
+  take to incorporate the network monitor feature.
+
 AT25 Serial FLASH
 =================
 
diff --git a/nuttx/configs/sama5d3-xplained/README.txt b/nuttx/configs/sama5d3-xplained/README.txt
index 570821c81..589f307b1 100644
--- a/nuttx/configs/sama5d3-xplained/README.txt
+++ b/nuttx/configs/sama5d3-xplained/README.txt
@@ -908,7 +908,77 @@ Networking
   so that access to the NSH prompt is not delayed.
 
   This delay will be especially long if the board is not connected to
-  a network.
+  a network.  On the order of a minute!  You will probably think that
+  NuttX has crashed!  And then, when it finally does come up, the
+  network will not be available.
+
+  Network Initialization Thread
+  -----------------------------
+  There is a configuration option enabled by CONFIG_NSH_NETINIT_THREAD
+  that will do the NSH network bring-up asynchronously in parallel on
+  a separate thread.  This eliminates the (visible) networking delay
+  altogether.  This networking initialization feature by itself has
+  some limitations:
+
+    - If no network is connected, the network bring-up will fail and
+      the network initialization thread will simply exit.  There are no
+      retries and no mechanism to know if the network initialization was
+      successful.
+
+    - Furthermore, there is no support for detecting loss of the network
+      connection and recovery of networking when the connection is restored.
+
+  Both of these shortcomings can be eliminated by enabling the network
+  monitor:
+
+  Network Monitor
+  ---------------
+  By default the network initialization thread will bring-up the network
+  then exit, freeing all of the resources that it required.  This is a
+  good behavior for systems with limited memory.
+
+  If the CONFIG_NSH_NETINIT_MONITOR option is selected, however, then the
+  network initialization thread will persist forever; it will monitor the
+  network status.  In the event that the network goes down (for example, if
+  a cable is removed), then the thread will monitor the link status and
+  attempt to bring the network back up.  In this case the resources
+  required for network initialization are never released.
+
+  Pre-requisites:
+
+    - CONFIG_NSH_NETINIT_THREAD as described above.
+
+    - CONFIG_NETDEV_PHY_IOCTL. Enable PHY IOCTL commands in the Ethernet
+      device driver. Special IOCTL commands must be provided by the Ethernet
+      driver to support certain PHY operations that will be needed for link
+      management. There operations are not complex and are implemented for
+      the Atmel SAMA5 family.
+
+    - CONFIG_ARCH_PHY_INTERRUPT. This is not a user selectable option.
+      Rather, it is set when you select a board that supports PHY interrupts.
+      In most architectures, the PHY interrupt is not associated with the
+      Ethernet driver at all. Rather, the PHY interrupt is provided via some
+      board-specific GPIO and the board-specific logic must provide support
+      for that GPIO interrupt. To do this, the board logic must do two things:
+      (1) It must provide the function arch_phy_irq() as described and
+      prototyped in the nuttx/include/nuttx/arch.h, and (2) it must select
+      CONFIG_ARCH_PHY_INTERRUPT in the board configuration file to advertise
+      that it supports arch_phy_irq().  This logic can be found at
+      nuttx/configs/sama5d3-xplained/src/sam_ethernet.c.
+
+    - And a few other things: UDP support is required (CONFIG_NET_UDP) and
+      signals must not be disabled (CONFIG_DISABLE_SIGNALS).
+
+  Given those prerequisites, the newtork monitor can be selected with these additional settings.
+
+    Networking Support -> Networking Device Support
+      CONFIG_NETDEV_PHY_IOCTL=y             : Enable PHY ioctl support
+
+    Application Configuration -> NSH Library -> Networking Configuration
+      CONFIG_NSH_NETINIT_THREAD             : Enable the network initialization thread
+      CONFIG_NSH_NETINIT_MONITOR=y          : Enable the network monitor
+      CONFIG_NSH_NETINIT_RETRYMSEC=2000     : Configure the network monitor as you like
+      CONFIG_NSH_NETINIT_SIGNO=18
 
 AT25 Serial FLASH
 =================
diff --git a/nuttx/configs/sama5d3x-ek/README.txt b/nuttx/configs/sama5d3x-ek/README.txt
index 8f1978b67..c881be148 100644
--- a/nuttx/configs/sama5d3x-ek/README.txt
+++ b/nuttx/configs/sama5d3x-ek/README.txt
@@ -1069,7 +1069,77 @@ Networking
   so that access to the NSH prompt is not delayed.
 
   This delay will be especially long if the board is not connected to
-  a network.
+  a network.  On the order of a minute!  You will probably think that
+  NuttX has crashed!  And then, when it finally does come up, the
+  network will not be available.
+
+  Network Initialization Thread
+  -----------------------------
+  There is a configuration option enabled by CONFIG_NSH_NETINIT_THREAD
+  that will do the NSH network bring-up asynchronously in parallel on
+  a separate thread.  This eliminates the (visible) networking delay
+  altogether.  This networking initialization feature by itself has
+  some limitations:
+
+    - If no network is connected, the network bring-up will fail and
+      the network initialization thread will simply exit.  There are no
+      retries and no mechanism to know if the network initialization was
+      successful.
+
+    - Furthermore, there is no support for detecting loss of the network
+      connection and recovery of networking when the connection is restored.
+
+  Both of these shortcomings can be eliminated by enabling the network
+  monitor:
+
+  Network Monitor
+  ---------------
+  By default the network initialization thread will bring-up the network
+  then exit, freeing all of the resources that it required.  This is a
+  good behavior for systems with limited memory.
+
+  If the CONFIG_NSH_NETINIT_MONITOR option is selected, however, then the
+  network initialization thread will persist forever; it will monitor the
+  network status.  In the event that the network goes down (for example, if
+  a cable is removed), then the thread will monitor the link status and
+  attempt to bring the network back up.  In this case the resources
+  required for network initialization are never released.
+
+  Pre-requisites:
+
+    - CONFIG_NSH_NETINIT_THREAD as described above.
+
+    - CONFIG_NETDEV_PHY_IOCTL. Enable PHY IOCTL commands in the Ethernet
+      device driver. Special IOCTL commands must be provided by the Ethernet
+      driver to support certain PHY operations that will be needed for link
+      management. There operations are not complex and are implemented for
+      the Atmel SAMA5 family.
+
+    - CONFIG_ARCH_PHY_INTERRUPT. This is not a user selectable option.
+      Rather, it is set when you select a board that supports PHY interrupts.
+      In most architectures, the PHY interrupt is not associated with the
+      Ethernet driver at all. Rather, the PHY interrupt is provided via some
+      board-specific GPIO and the board-specific logic must provide support
+      for that GPIO interrupt. To do this, the board logic must do two things:
+      (1) It must provide the function arch_phy_irq() as described and
+      prototyped in the nuttx/include/nuttx/arch.h, and (2) it must select
+      CONFIG_ARCH_PHY_INTERRUPT in the board configuration file to advertise
+      that it supports arch_phy_irq().  This logic can be found at
+      nuttx/configs/sama5d3x-ek/src/sam_ethernet.c.
+
+    - And a few other things: UDP support is required (CONFIG_NET_UDP) and
+      signals must not be disabled (CONFIG_DISABLE_SIGNALS).
+
+  Given those prerequisites, the newtork monitor can be selected with these additional settings.
+
+    Networking Support -> Networking Device Support
+      CONFIG_NETDEV_PHY_IOCTL=y             : Enable PHY ioctl support
+
+    Application Configuration -> NSH Library -> Networking Configuration
+      CONFIG_NSH_NETINIT_THREAD             : Enable the network initialization thread
+      CONFIG_NSH_NETINIT_MONITOR=y          : Enable the network monitor
+      CONFIG_NSH_NETINIT_RETRYMSEC=2000     : Configure the network monitor as you like
+      CONFIG_NSH_NETINIT_SIGNO=18
 
 AT25 Serial FLASH
 =================
diff --git a/nuttx/configs/sama5d4-ek/README.txt b/nuttx/configs/sama5d4-ek/README.txt
index 94371e09f..b992c0cd6 100644
--- a/nuttx/configs/sama5d4-ek/README.txt
+++ b/nuttx/configs/sama5d4-ek/README.txt
@@ -1385,22 +1385,76 @@ Networking
 
   This delay will be especially long if the board is not connected to
   a network.  On the order of a minute!  You will probably think that
-  NuttX has crashed!
+  NuttX has crashed!  And then, when it finally does come up, the
+  network will not be available.
 
+  Network Initialization Thread
+  -----------------------------
   There is a configuration option enabled by CONFIG_NSH_NETINIT_THREAD
   that will do the NSH network bring-up asynchronously in parallel on
   a separate thread.  This eliminates the (visible) networking delay
-  altogether.  This current implementation, however, has some limitations:
+  altogether.  This networking initialization feature by itself has
+  some limitations:
 
     - If no network is connected, the network bring-up will fail and
       the network initialization thread will simply exit.  There are no
       retries and no mechanism to know if the network initialization was
-      successful (it could perform a network Ioctl to see if the link is
-      up and it now, keep trying, but it does not do that now).
+      successful.
+
+    - Furthermore, there is no support for detecting loss of the network
+      connection and recovery of networking when the connection is restored.
 
-    - Furthermore, there is currently no support for detecting loss of
-      network connection and recovery of the connection (similarly, this
-      thread could poll periodically for network status, but does not).
+  Both of these shortcomings can be eliminated by enabling the network
+  monitor:
+
+  Network Monitor
+  ---------------
+  By default the network initialization thread will bring-up the network
+  then exit, freeing all of the resources that it required.  This is a
+  good behavior for systems with limited memory.
+
+  If the CONFIG_NSH_NETINIT_MONITOR option is selected, however, then the
+  network initialization thread will persist forever; it will monitor the
+  network status.  In the event that the network goes down (for example, if
+  a cable is removed), then the thread will monitor the link status and
+  attempt to bring the network back up.  In this case the resources
+  required for network initialization are never released.
+
+  Pre-requisites:
+
+    - CONFIG_NSH_NETINIT_THREAD as described above.
+
+    - CONFIG_NETDEV_PHY_IOCTL. Enable PHY IOCTL commands in the Ethernet
+      device driver. Special IOCTL commands must be provided by the Ethernet
+      driver to support certain PHY operations that will be needed for link
+      management. There operations are not complex and are implemented for
+      the Atmel SAMA5 family.
+
+    - CONFIG_ARCH_PHY_INTERRUPT. This is not a user selectable option.
+      Rather, it is set when you select a board that supports PHY interrupts.
+      In most architectures, the PHY interrupt is not associated with the
+      Ethernet driver at all. Rather, the PHY interrupt is provided via some
+      board-specific GPIO and the board-specific logic must provide support
+      for that GPIO interrupt. To do this, the board logic must do two things:
+      (1) It must provide the function arch_phy_irq() as described and
+      prototyped in the nuttx/include/nuttx/arch.h, and (2) it must select
+      CONFIG_ARCH_PHY_INTERRUPT in the board configuration file to advertise
+      that it supports arch_phy_irq().  This logic can be found at
+      nuttx/configs/sama5d4-ek/src/sam_ethernet.c.
+
+    - And a few other things: UDP support is required (CONFIG_NET_UDP) and
+      signals must not be disabled (CONFIG_DISABLE_SIGNALS).
+
+  Given those prerequisites, the newtork monitor can be selected with these additional settings.
+
+    Networking Support -> Networking Device Support
+      CONFIG_NETDEV_PHY_IOCTL=y             : Enable PHY ioctl support
+
+    Application Configuration -> NSH Library -> Networking Configuration
+      CONFIG_NSH_NETINIT_THREAD             : Enable the network initialization thread
+      CONFIG_NSH_NETINIT_MONITOR=y          : Enable the network monitor
+      CONFIG_NSH_NETINIT_RETRYMSEC=2000     : Configure the network monitor as you like
+      CONFIG_NSH_NETINIT_SIGNO=18
 
 AT25 Serial FLASH
 =================
@@ -3925,17 +3979,19 @@ Configurations
        The configuration option CONFIG_NSH_NETINIT_THREAD is enabled so
        that NSH network bring-up asynchronously and in parallel on a
        separate thread.  This eliminates the (visible) networking bring-up
-       delay.  This current implementation, however, has some limitations:
+       delay.    This networking initialization feature by itself has
+       some limitations:
+
+         - If no network is connected, the network bring-up will fail and
+           the network initialization thread will simply exit.  There are no
+           retries and no mechanism to know if the network initialization was
+           successful.
 
-        - If no network is connected, the network bring-up will fail and
-          the network initialization thread will simply exit.  There are no
-          retries and no mechanism to know if the network initialization was
-          successful (it could perform a network Ioctl to see if the link is
-          up and it now, keep trying, but it does not do that now).
+         - Furthermore, there is no support for detecting loss of the network
+           connection and recovery of networking when the connection is restored.
 
-        - Furthermore, there is currently no support for detecting loss of
-          network connection and recovery of the connection (similarly, this
-          thread could poll periodically for network status, but does not).
+       Both of these shortcomings can be eliminated by enabling the network
+       monitor as described above in the "Network Monitor" paragraph.
 
    14. I2C Tool. This configuration enables TWI0 (only) as an I2C master
        device.  This configuration also supports the I2C tool at