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

2026-05-31 23:40:19 +08:00 · 2014-08-18 07:24:47 -06:00
parent 3b07378b38
commit a8d7772ad6
5 changed files with 242 additions and 75 deletions
@@ -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)
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -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
 =================
@@ -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
 =================
@@ -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
 =================
@@ -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
+      successful.
      up and it now, keep trying, but it does not do that now).
-    - Furthermore, there is currently no support for detecting loss of
+    - Furthermore, there is no support for detecting loss of the network
-      network connection and recovery of the connection (similarly, this
+      connection and recovery of networking when the connection is restored.
-      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
+         - If no network is connected, the network bring-up will fail and
-          the network initialization thread will simply exit.  There are no
+           the network initialization thread will simply exit.  There are no
-          retries and no mechanism to know if the network initialization was
+           retries and no mechanism to know if the network initialization was
-          successful (it could perform a network Ioctl to see if the link is
+           successful.
          up and it now, keep trying, but it does not do that now).
-        - Furthermore, there is currently no support for detecting loss of
+         - Furthermore, there is no support for detecting loss of the network
-          network connection and recovery of the connection (similarly, this
+           connection and recovery of networking when the connection is restored.
-          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