Swatantra-66 opened a new pull request, #20578:
URL: https://github.com/apache/nuttx/pull/20578
## Summary
Provide a comprehensive documentation guide for the `netinit` (Network
Initialization) subsystem in
`Documentation/applications/netutils/netinit/index.rst`, replacing the previous
4-line placeholder stub.
Addresses #11081.
### Key Additions:
1. **Architecture & Execution Models**:
- Details synchronous foreground bring-up (`!CONFIG_NETINIT_THREAD`) vs.
asynchronous background thread execution (`CONFIG_NETINIT_THREAD`, priority 80,
stack sizing), preventing boot freezes during PHY auto-negotiation or DHCP
delays.
- Documents split local-only configuration (`CONFIG_NETINIT_NETLOCAL`)
for staged multi-phase boot, captive portals, and interactive Wi-Fi onboarding.
- Comprehensive ASCII architectural lifecycle diagram depicting Phase 1
(Local Device Setup) and Phase 2 (Network Bring-Up).
2. **Autonomous Link State Monitor Daemon**:
- Documents `CONFIG_NETINIT_MONITOR` event-driven lifecycle: signal
registration (`CONFIG_NETINIT_SIGNO`), MII PHY carrier interrupt notifications
(`SIOCMIINOTIFY`), register status evaluation (`MII_MSR_LINKSTATUS`), automatic
link down / UP state toggling, and configurable retry periods
(`CONFIG_NETINIT_RETRYMSEC`).
3. **Primary Device Selection Precedence**:
- Complete reference table mapping link-layer configuration flags to
compile-time interface names (`wlan0` → `eth0` → `wpan0` → `bnep0` → `sl0` →
`tun0` → `lo` → `can0`).
4. **MAC Address Provisioning Strategies**:
- Documents `CONFIG_NETINIT_NOMAC` options: board silicon unique ID
(`CONFIG_NETINIT_UIDMAC`) derived as an IEEE Locally Administered Address (LAA)
with truncation caveats noted, device calibration files
(`CONFIG_NETINIT_MACADDR` via `BOARDIOC_MACADDR`), and fixed software MACs
(`CONFIG_NETINIT_SWMAC`).
5. **IP Addressing & Protocols**:
- IPv4: Dynamic DHCP client (:rfc:`2131`), static IP configuration, and
dynamic runtime file configuration (`CONFIG_FSUTILS_IPCFG` via `/etc/net.cfg`)
with filesystem mount retry delays (`CONFIG_NETINIT_RETRY_MOUNTPATH`).
- IPv6: Stateless Address Autoconfiguration (SLAAC, :rfc:`4862`) vs.
static IPv6 addressing, accurately documenting the effective Kconfig default
netmask (`ffff:ffff:ffff:ffff:ffff:ffff:ffff:0`, `/112`).
- Default DNS nameserver registration via `netlib_set_ipv4dnsaddr()`.
6. **Wi-Fi Association (WAPI Integration)**:
- Walkthrough of `netinit_associate()` using Wireless Extensions (WEXT)
ioctls, covering station modes (Infrastructure, Ad-hoc, Mesh),
WPA/WPA2-Personal, CCMP/AES and TKIP ciphers, and SSID/passphrase credentials.
7. **Auxiliary Daemons (NTP Client)**:
- Automated startup of Network Time Protocol synchronization via
`ntpc_start()` as soon as interface link state transitions to UP.
8. **Configuration & Public C API Reference**:
- Comprehensive Kconfig table detailing 23 major configuration symbols.
- Complete C API signatures, parameter lists, and return semantics for
`netinit_bringup()` and `netinit_associate()`.
9. **Practical Integration Scenarios & Troubleshooting**:
- Ready-to-use configuration and code walkthroughs: Standard Ethernet
with DHCP, Industrial static IP node with UID MAC, and Wi-Fi IoT
auto-association.
- Dedicated unit debug tracing via `CONFIG_NETINIT_DEBUG=y` to prevent
system-wide `DEBUG_NET` console flooding.
- Troubleshooting guide resolving boot freezes, MAC collisions, missing
PHY interrupts, and Wi-Fi association mismatches.
## Impact
- **Documentation**: Fills a core network blank documentation page
identified in #11081.
- **Architecture**: Explains the critical distinction between foreground
blocking bring-up and background threaded initialization, preventing boot
lockups on disconnected embedded targets.
- **Developer Experience**: Eliminates confusion surrounding hardware MAC
provisioning from silicon UIDs, effective IPv6 subnet masks, and Wi-Fi WAPI
auto-association parameters.
- **Build / ABI**: Documentation-only change. No functional code or ABI
alterations to existing NuttX libraries or apps.
## Testing
- Verified reStructuredText syntax, section underline lengths, and directive
syntax with `docutils` and Sphinx parsers (0 errors, 0 warnings).
- Verified pure LF line endings and 0 trailing whitespaces (`git diff
--check`).
- Cross-referenced all public C API signatures and headers against
`apps/include/netutils/netinit.h`.
- Cross-referenced all operational logic, ioctls, and defaults against
`apps/netutils/netinit/netinit.c`, `netinit_associate.c`, and
`apps/netutils/netinit/Kconfig`.
--
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]
