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

1 files changed, 72 insertions, 16 deletions

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