Visitar URL original
Documentation/netutils: add comprehensive guide for tftpc by Swatantra-66 · Pull Request #20493 · apache/nuttx · GitHub
Skip to content

Documentation/netutils: add comprehensive guide for tftpc - #20493

Merged
acassis merged 1 commit into
apache:masterfrom
Swatantra-66:doc/tftpc-guide
Oct 8, 2026
Merged

acassis merged 1 commit into
apache:masterfrom
Swatantra-66:doc/tftpc-guide

Conversation

@Swatantra-66

Copy link
Copy Markdown
Contributor

Summary

This PR replaces the 5-line placeholder stub in Documentation/applications/netutils/tftpc/index.rst with a comprehensive, production-grade guide for the tftpc (TFTP client) network utility.

Addresses #11081

Key Additions:

  • Architecture Overview: Documents tftpc's dual role as both the interactive NSH get and put shell commands engine and a standalone programmatic C API.
  • Core Capabilities: Covers RFC 1350 compliance, binary (octet) and text (netascii) transfer modes, streaming callback architecture, dynamic TID port negotiation, and automatic retransmission timeouts.
  • Security Considerations: Details caveats for firmware transfers over TFTP, emphasizing isolated network environments and the necessity of independent cryptographic verification (verified digital signatures or out-of-band digests).
  • Kconfig Options & Dependencies: Outlines prerequisite networking subsystems (CONFIG_NET_UDP, CONFIG_NET_IPv4) and all tuneable options (CONFIG_NETUTILS_TFTPC, CONFIG_NETUTILS_TFTP_PORT, CONFIG_NETUTILS_TFTP_TIMEOUT, CONFIG_NETUTILS_TFTP_DUMPBUFFERS).
  • NSH CLI Guide: Full command synopses, option flags (-b, -n, -f, -h), and practical shell examples for both get and put.
  • C API Reference: Detailed coverage of filesystem helpers (tftpget(), tftpput()) and streaming callback APIs (tftpget_cb(), tftpput_cb()).
  • Production C Application Example: Provides a runnable embedded file-download helper demonstrating memory sink callbacks with buffer boundary checks and proper errno returns.

Impact

  • Documentation: Fills another critical unwritten documentation page tracked in Documentation: blank pages in documentation #11081.
  • User Experience: Provides clear, secure patterns for embedded firmware transfer and shell usage in NuttX.
  • Code/Build: Documentation-only change. No functional code or ABI alterations.

Testing

  • Validated Sphinx reStructuredText syntax, formatting, and header underline lengths.
  • Verified NSH CLI flags against apps/nshlib/nsh_command.c and nsh_netcmds.c.
  • Verified C API definitions and callback signatures against apps/include/netutils/tftp.h.

Provide a complete documentation guide for the tftpc (TFTP client) network
utility in Documentation/applications/netutils/tftpc/index.rst, replacing
the previous 5-line placeholder stub.

Includes:
- Architecture overview (NSH get/put engine + programmatic C APIs)
- Key features (RFC 1350, octet/netascii modes, streaming callbacks, dynamic TID port negotiation)
- Configuration options table and networking prerequisites
- NSH get and put command synopses, option flags, and terminal examples
- C API reference for filesystem helpers (tftpget, tftpput) and streaming callbacks (tftpget_cb, tftpput_cb)
- Complete, runnable C application example demonstrating callback-based streaming downloads

Addresses apache#11081

Signed-off-by: Swatantra Yadav <maverickswatantra@gmail.com>
@github-actions github-actions Bot added Area: Documentation Improvements or additions to documentation Size: M The size of the change in this PR is medium labels Oct 7, 2026
@acassis
acassis merged commit 5b59766 into apache:master Oct 8, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Area: Documentation Improvements or additions to documentation Size: M The size of the change in this PR is medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants