michallenc commented on code in PR #20578: URL: https://github.com/apache/nuttx/pull/20578#discussion_r4242281071
########## Documentation/applications/netutils/netinit/index.rst: ########## @@ -1,3 +1,623 @@ ================================== -``netinit`` Network initialization +``netinit`` Network Initialization ================================== + +The ``netinit`` utility is the standard network interface bring-up and configuration +subsystem in Apache NuttX (``apps/netutils/netinit``). It serves as the primary bridge +between lower-half network hardware drivers (Ethernet MAC/PHY, IEEE 802.11 Wi-Fi, 6LoWPAN, +SLIP, TUN, Loopback, SocketCAN) and upper-half network application layers (NuttX socket +layer, ``netlib``, and NuttShell). + +``netinit`` coordinates the full boot-up sequence of network interfaces: + +- **MAC Address Assignment**: Configures fixed software MACs, board unique ID (UID) + locally administered addresses (LAA), or device calibration file MACs. +- **Link Layer Configuration**: Identifies and initializes the primary interface + (e.g., ``eth0``, ``wlan0``, ``wpan0``). +- **IP Addressing**: Assigns static IPv4 addresses or coordinates dynamic configuration + via the DHCP client (:rfc:`2131`), static IPv6 addresses or ICMPv6 Stateless Address + Autoconfiguration (SLAAC, :rfc:`4862`), or runtime configuration via ``ipcfg`` files. +- **Wi-Fi Association**: Integrates with Wireless Application Programming Interface + (WAPI) to automatically associate Wi-Fi interfaces with an Access Point (WPA/WPA2-PSK). +- **DNS Registration**: Registers default nameserver addresses with the resolver. +- **Auxiliary Network Services**: Optionally auto-launches background daemons such + as the NTP client (``ntpclient``). +- **Autonomous Link Monitoring**: Runs an optional background event-driven monitor that + detects PHY carrier changes, manages graceful link up/down transitions, and retries + bring-up after disconnection. + +Architecture and Operational Modes +================================== + +``netinit`` supports three primary architectural execution models to accommodate different +embedded memory, real-time, and hardware constraints. + +.. code-block:: text + + +-------------------------------------------------------------------------+ + | System Boot (nsh_init / nxinit) | + +-------------------------------------------------------------------------+ + | + v + netinit_bringup() + | + +----------------------+----------------------+ + | | + v (CONFIG_NETINIT_THREAD=n) v (CONFIG_NETINIT_THREAD=y) + Sequential Foreground Spawn "netinit" Thread + | (Priority 80 / Detached) + +----------------------+----------------------+ + | + v + +-------------------------------------------------------------------------+ + | Phase 1: Local Device Initialization | + | - Select Primary Device (wlan0 / eth0 / wpan0 / bnep0 / sl0 / tun0) | + | - Provision MAC Address (UIDMAC / Device Info / Fixed Software MAC) | + | - Provision Local IP/Mask (Static Kconfig / fsutils ipcfg) | + +-------------------------------------------------------------------------+ + | + +-----> (If CONFIG_NETINIT_NETLOCAL=y: Exit) + | + v + +-------------------------------------------------------------------------+ + | Phase 2: Network Interface Bring-Up | + | - Bring Interface UP (netlib_ifup) | + | - Associate Wi-Fi AP via WAPI (wpa_driver_wext_associate) | + | - Acquire Dynamic IP via DHCPC or ICMPv6 SLAAC | + | - Register Default DNS Nameserver | + | - Start NTP Client Daemon (ntpc_start) | + +-------------------------------------------------------------------------+ + | + +----------------------+----------------------+ + | | + v (CONFIG_NETINIT_MONITOR=n) v (CONFIG_NETINIT_MONITOR=y) + Exit Thread / Persistent MII Monitor + Release Resources (SIOCMIINOTIFY Event Loop) + +Sequential Initialization Mode +------------------------------ + +When ``CONFIG_NETINIT_THREAD`` is disabled (default), ``netinit_bringup()`` executes +synchronously on the calling task's thread (for example, during NSH startup in ``nsh_init()`` +or system startup in ``nxinit``). + +- **Advantages**: Consumes zero additional thread stacks or task management overhead; + ideal for microcontrollers with very limited RAM (e.g., <= 64 KB). +- **Caveats**: If the physical Ethernet cable is unplugged, or if the PHY auto-negotiation + or DHCP acquisition requires several seconds, system boot will block until timeouts + expire. + +Threaded Asynchronous Mode +-------------------------- + +When ``CONFIG_NETINIT_THREAD=y`` is selected, ``netinit_bringup()`` spawns a dedicated +background POSIX thread (named ``"netinit"``) with configurable stack size +(``CONFIG_NETINIT_THREAD_STACKSIZE``) and priority (``CONFIG_NETINIT_THREAD_PRIORITY``, +typically set to low priority, such as 80 or 100). + +- **Advantages**: System boot proceeds immediately. Applications, the NuttShell console, + and local real-time tasks start instantly without blocking on network auto-negotiation. +- **Lifecycle**: The thread configures the network interface, performs DHCP or Wi-Fi + association, and once the network is operational, terminates cleanly to reclaim its + allocated resources (unless the Link State Monitor is enabled). + +Local vs. Network Bringup Split +------------------------------- + +When ``CONFIG_NETINIT_NETLOCAL=y`` is enabled, ``netinit`` performs only local interface +provisioning: + +1. Software MAC address assignment (if hardware requires it). +2. Local IP address and subnet assignment on the network device. + +It explicitly suppresses: + +- Bringing the interface state UP via ``netlib_ifup()``. +- Wi-Fi Access Point association via WAPI. +- Dynamic IP negotiation via the DHCP client. +- Starting the background NTP client daemon. + +This split mode is particularly useful in multi-stage boot environments where wireless +scanning, captive portal redirection, or user credential entry must occur before bringing +the network interface online. + +Link State Monitor Daemon +------------------------- + +When ``CONFIG_NETINIT_MONITOR=y`` is selected (requiring ``CONFIG_NETINIT_THREAD=y``, +``CONFIG_ARCH_PHY_INTERRUPT=y``, ``CONFIG_NETDEV_PHY_IOCTL=y``, and ``CONFIG_NET_UDP=y``), +the ``netinit`` thread persists permanently as an event-driven daemon: + +1. **Signal Attachment**: Registers a signal handler for ``CONFIG_NETINIT_SIGNO`` + (default real-time signal 32) using ``sigaction()``. +2. **PHY Event Registration**: Issues an ``ioctl(sd, SIOCMIINOTIFY, ...)`` command to the + network driver, requesting asynchronous signal delivery upon MII PHY link status + changes. +3. **Carrier Detection**: Reads PHY status registers (``SIOCGMIIPHY`` and ``SIOCGMIIREG`` + at register ``MII_MSR``) to evaluate ``MII_MSR_LINKSTATUS``. +4. **Transition to Up**: When the link transitions from down to up, ``netinit`` marks + the device operational (``IFF_UP``), re-executes ICMPv6 auto-configuration if enabled, + and sleeps until the next interrupt. +5. **Transition to Down**: When cable disconnection is detected, ``netinit`` clears + the ``IFF_UP`` flag and periodically attempts reconnection every + ``CONFIG_NETINIT_RETRYMSEC`` milliseconds (default 2000 ms). + +Device Selection Hierarchy +========================== + +``netinit`` identifies the primary network interface name (``NET_DEVNAME``) at compile +time based on enabled link-layer drivers, adhering to the following selection precedence: + +.. list-table:: + :widths: 25 20 55 + :header-rows: 1 + + * - Interface Name + - Configuration Guard + - Description + * - ``wlan0`` + - ``CONFIG_DRIVERS_IEEE80211`` + - IEEE 802.11 wireless network adapter (Wi-Fi). + * - ``eth0`` + - ``CONFIG_NET_ETHERNET`` + - Standard 10/100/1000 Mbps Ethernet MAC/PHY. + * - ``wpan0`` + - ``CONFIG_NET_6LOWPAN`` or ``CONFIG_NET_IEEE802154`` + - Low-power wireless personal area network (6LoWPAN / Zigbee). + * - ``bnep0`` + - ``CONFIG_NET_BLUETOOTH`` + - Bluetooth Network Encapsulation Protocol interface. + * - ``sl0`` + - ``CONFIG_NET_SLIP`` + - Serial Line Internet Protocol (SLIP) point-to-point interface. + * - ``tun0`` + - ``CONFIG_NET_TUN`` + - Virtual TUN/TAP network tunnel adapter. + * - ``lo`` + - ``CONFIG_NET_LOOPBACK`` + - Local loopback interface (``127.0.0.1``). + * - ``can0`` + - ``CONFIG_NET_CAN`` + - SocketCAN controller interface. + +MAC Address Assignment Strategies +================================= + +Embedded network controllers often lack factory-programmed MAC addresses in non-volatile +hardware registers. When ``CONFIG_NETINIT_NOMAC=y`` is set, ``netinit`` provisions a +valid MAC address before bringing the interface up using one of three strategies: + +Board Unique ID (``CONFIG_NETINIT_UIDMAC``) +------------------------------------------- + +Queries the microcontroller's factory-flashed unique silicon ID (e.g., STM32 96-bit UID, +ESP32 eFuse MAC) by invoking: + +.. code-block:: c + + boardctl(BOARDIOC_UNIQUEID, (uintptr_t)&uid); + +The first byte is adjusted to set the IEEE Locally Administered Address (LAA) bit and +clear the multicast bit: + +.. code-block:: c + + uid[0] = (uid[0] & 0xf0) | 0x02; /* Locally Administered MAC */ + netlib_setmacaddr(NET_DEVNAME, uid); + +This allows boards booted from the same firmware binary to dynamically generate +a unique, UID-derived MAC address on the local network without hardcoding. Note that +because 64-bit or 96-bit MCU hardware UIDs are truncated to 48 bits (6 bytes for Ethernet) +or 64 bits (for 6LoWPAN), collision avoidance depends on the uniqueness of the lower UID +bytes exposed by the hardware platform. + +Device Info File (``CONFIG_NETINIT_MACADDR``) +--------------------------------------------- + +Loads a calibrated, production-programmed MAC address from persistent non-volatile +storage (e.g., ``/etc/device.info`` or EEPROM) via: + +.. code-block:: c + + boardctl(BOARDIOC_MACADDR, (uintptr_t)&req); + +Fixed Software MAC (``CONFIG_NETINIT_SWMAC``) +--------------------------------------------- + +Assigns a static MAC address defined directly in Kconfig: + +- ``CONFIG_NETINIT_MACADDR_1``: Lower 4 bytes (e.g., ``0xdeadbeef``). +- ``CONFIG_NETINIT_MACADDR_2``: Upper 2 bytes (e.g., ``0x00e0`` for Ethernet). + +IP Address Configuration +======================== + +IPv4 Addressing +--------------- + +Dynamic DHCP Client (``CONFIG_NETINIT_DHCPC``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When ``CONFIG_NETINIT_DHCPC=y`` is selected (requires ``CONFIG_NETUTILS_DHCPC=y``), +``netinit`` initializes the device address to ``0.0.0.0``, brings the link up, and +calls: + +.. code-block:: c + + netlib_obtain_ipv4addr(NET_DEVNAME); + +The DHCP client broadcasts a ``DHCPDISCOVER`` packet, negotiates lease terms with the local +DHCP server, and automatically applies the assigned IP address, network mask, default +gateway router, and DNS nameservers. + +Static IPv4 Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^ + +When DHCP is disabled, static addresses are supplied via Kconfig in 32-bit host byte order: + +- ``CONFIG_NETINIT_IPADDR``: Target host IP (e.g., ``0x0a000002`` for ``10.0.0.2``). +- ``CONFIG_NETINIT_DRIPADDR``: Default router IP (e.g., ``0x0a000001`` for ``10.0.0.1``). +- ``CONFIG_NETINIT_NETMASK``: Subnet mask (e.g., ``0xffffff00`` for ``255.255.255.0``). + +Runtime File-Based Configuration (``CONFIG_FSUTILS_IPCFG``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If ``CONFIG_FSUTILS_IPCFG=y`` is enabled, ``netinit`` attempts to read network settings +from an IP configuration file (such as ``/etc/net.cfg``) using ``ipcfg_read()``. Review Comment: I would mention the path to the file is defined by `CONFIG_IPCFG_PATH` and format (ascii vs binary `CONFIG_IPCFG_BINARY`) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
