[PATCH rtems-docs 1/1] TFTPFS: New documentation

[Chris Johns]

Hi Frank,

Thanks for the documentation and the TFTP file system update.

On 4/6/2022 1:22 am, Frank Kuehndel wrote:
> From: Frank Kühndel <frank.kuehndel at embedded-brains.de>
> 
> ---
>  filesystem/index.rst       |   1 +
>  filesystem/trivial_ftp.rst | 638 ++++++++++++++++++++++++++++++++++++-
>  2 files changed, 636 insertions(+), 3 deletions(-)
> 
> diff --git a/filesystem/index.rst b/filesystem/index.rst
> index f4e2ed6..64a2f1d 100644
> --- a/filesystem/index.rst
> +++ b/filesystem/index.rst
> @@ -9,6 +9,7 @@ RTEMS Filesystem Design Guide (|version|).
>  .. topic:: Copyrights and License
>  
>      | |copy| 1988, 2015 On-Line Applications Research Corporation (OAR)
> +    | |copy| 2022 embedded brains GmbH (http://www.embedded-brains.de)
>  
>      .. include:: ../common/license.rst
>  
> diff --git a/filesystem/trivial_ftp.rst b/filesystem/trivial_ftp.rst
> index e43c036..f5940c6 100644
> --- a/filesystem/trivial_ftp.rst
> +++ b/filesystem/trivial_ftp.rst
> @@ -3,7 +3,639 @@
>  Trivial FTP Client Filesystem
>  *****************************
>  
> -This chapter describes the Trivial FTP (TFTP) Client Filesystem.
> +This chapter describes the Trivial File Transfer Protocol (TFTP) Client
> +Filesystem.  TFTP is designed to be an especially simple protocol which
> +uses the User Datagram Protocol (UDP) for data transfer over the Internet.
> +Its purpose is to send a single file between to network nodes (client and
> +server).  A file can be sent in both directions, i.e. a client can either
> +read a file from a server or write a file to the server.
>  
> -This chapter should be written after the IMFS chapter is completed and describe
> -the implementation of the TFTP.
> +Besides reading or writing a file no other operations are supported.  That
> +is, one cannot seek the file, not append to the end of a file, not open
> +the file for reading and writing at the same time, not list directories,
> +not move files and so on.
> +
> +TFTP is inherent insecure as it does not provide any means for
> +authentication or encryption.  Therefore, it cannot be used over the public
> +Internet.  

Recommended or highly recommended to not be used on public networks?

> Nevertheless, it is still widely used to load software and
> +configuration data during early boot stages over a Local Area Network
> +(LAN).

With regard to security the TFTP port is secure and so the server runs as root.
In rtems-tools there is a TFTP proxy to provide a central instance that can
proxy sessions out to other machines on a network at any port, ie ones that a
user can connect with. This works with the rtems-tftp-server also included in
rtems-tools. The rtems-tftp-server (and proxy) and in Python so should be portable.

> +
> +RTEMS TFTP Filesystem Implementation
> +====================================
> +
> +The RTEMS TFTP filesystem implements a TFTP client which can be used
> +through the file system.  With other words, one needs to mount the
> +TFTP filesystem and can afterwards open a file for reading or writing
> +below that mount point.  The content of that file is then effectively
> +read from or written to the remote server.  The RTEMS implementation
> +implements the following features:
> +
> +* RFC 1350 *The TFTP Protocol (Revision 2)*
> +* RFC 2347 *TFTP Option Extension*
> +* RFC 2348 *TFTP Blocksize Option*
> +* RFC 7440 *TFTP Windowsize Option*
> +
> +Many simple TFTP server do not support options (RFC 2347). Therefore, in
> +case the server rejects the first request with options, the RTEMS client
> +makes automatically a second attempt using only the "classical" RFC 1350.
> +
> +The implementation has the following shortcomings:
> +
> +* IPv6 is not supported (yet).
> +
> +* No congestion control is implemented.
> +
> +  (Congestion is simply expressed a network traffic jam which involves
> +  package loss.)  This implementation would worsen a congestion situation
> +  and squeeze out TCP connections.  If that is a concern in your setup,
> +  it can be prevented by using value `1` as `windowsize`.

Where is this set, the server or the client?

> +
> +* One must call ``open()``, ``read()``, ``write()`` and ``close()``
> +  at a good pace.
> +
> +  TFTP uses timeouts (of unspecified length). 

What about the option (RFC2437) to allow a timeout to be exchanged? The
rtems-tools supports proxing of this option.

> It does not know keep-alive
> +  messages.  If the client does not respond to the server in due time,
> +  the server sets the connection faulty and drops it.  To avoid this,
> +  the user must read or write enough data fast enough.

Servers can retry by sending the same packet again?

> +  "Enough data" means at least so much data which fills a single data
> +  package or all packages of a window if windows are used.  The data
> +  can be read or written in anything from one single large chunk to
> +  byte-by-byte pieces.  The point is, one cannot pause the reading
> +  or writing for longer periods of time.

Can packets vary the data size in a sequence of packets? I thought doing that
signalled the end of the transmission? May be I am not understanding this paragraph?

> +
> +* The transfer mode is always ``octet``.  The only alternative
> +  ``netascii`` cannot be selected.
> +
> +* Block number roll-over is currently not supported.  Therefore,
> +  the maximum file size is limited to max-block-number times blocksize.
> +  For RFC 1350 blocksize is would be 65535 * 512 = 32 MB.  For the
> +  default blocksize is would be 65535 * 1456 = 90 MB.
> +
> +* The inherent insecurity of the protocol has already be mentioned but
> +  it is worth repeating.
> +
> +Prerequisites
> +=============
> +
> +To use the RTEMS TFTP filesystem one needs:
> +
> +* The RTEMS tools (cross-compiler, linker, debugger etc.) compiled
> +  for the target architecture and installed at a prefix
> +* The RTEMS Board Support Package (BSP) compiled for the
> +  target board and installed at the same prefix
> +* The RTEMS libbsd compiled to match the BSP and installed at the same
> +  prefix

A prefix can vary. These items are already detailed in the user manual so would
it make more sense to mention looking there rather than detailing it again here?

> +
> +Note, this text does not cover RTEMS legacy networking because it is
> +outdated.

Depreciated for new works?

> +
> +As an example the ARM architecture and a xilinx_zynq_a9 BSP is used below.
> +The instructions are tested with RTEMS version 6.  It is
> +recommended to actually use ``arm/xilinx_zynq_a9_qemu`` for the first
> +experiments as other BSPs tend to require different configuration values
> +and/or command line options.
> +
> +Moreover, it is recommended to first execute any code using QEMU as
> +simulator so that no hardware is needed.  Therefore, ``qemu-system-arm``
> +must be installed.  In Linux distributions this executable is usually
> +available in the repositories as package ``qemu-arm``.
> +
> +RTEMS Tools
> +-----------
> +
> +Instructions on how to obtain, compile and install the RTEMS tools can
> +be found in the *RTEMS User Manual* chapter `2. Quick Start
> +<https://docs.rtems.org/branches/master/user/start/index.html>`_.  

Sorry, no links like this in the documentation. It breaks release branches.

> To
> +follow the suggested example ``6/rtems-arm`` should be used as
> +target architecture argument of the ``../source-builder/sb-set-builder``
> +command.
> +
> +RTEMS Board Support Package
> +---------------------------
> +
> +Instructions on how to obtain, compile and install a BSP can be found
> +in the *RTEMS User Manual* section `Build a Board Support Package (BSP)
> +<https://docs.rtems.org/branches/master/user/start/bsp-build.html>`_.

Same here.

> +The bsp-option should have the following value to match the example BSP:
> +
> +.. code-block:: none
> +
> +  --rtems-bsps=arm/xilinx_zynq_a9_qemu
> +
> +The POSIX API must be enabled, e.g. in ``config.ini``:
> +``RTEMS_POSIX_API = True``.  Enabling tests and debug is recommended:
> +``BUILD_TESTS = True`` and ``RTEMS_DEBUG = True``.  It is mandatory that
> +RTEMS legacy networking is disabled when use of libbsd is intended
> +(``RTEMS_NETWORKING`` must be ``False``).

I see this as out of scope for the TFTP file system.

> +
> +RTEMS libbsd
> +------------
> +
> +Instructions on how to obtain, compile and install RTEMS libbsd can be
> +found in the `README.rst
> +<https://git.rtems.org/rtems-libbsd/tree/README.rst>`_

Not sure about this link as well.

> +of the ``rtems-libbsd`` GIT repository:
> +``git://git.rtems.org/rtems-libbsd.git``.
> +Make sure to compile and install libbsd for the correct RTEMS version
> +(here ``6``).  The default build set (``--buildset=buildset/default.ini``)
> +does suffice and as BSP ``--rtems-bsp=arm/xilinx_zynq_a9_qemu`` is
> +to be used in the ``waf configure`` command.
> +
> +RTEMS Configuration
> +-------------------
> +
> +To make the TFTP filesystem available to the application and have it
> +initialized, the macro ``CONFIGURE_FILESYSTEM_TFTPFS`` must be defined
> +when configuring RTEMS (typically in the ``init.c`` file).  In addition
> +the value for ``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS`` must be increased:
> +
> +.. code-block:: c
> +
> +  #define CONFIGURE_FILESYSTEM_TFTPFS
> +  #define CONFIGURE_MAXIMUM_FILE_DESCRIPTORS 64
> +
> +Moreover, libbsd and RTEMS must be configured appropriately as well.
> +For orientation, the code below is from an application using TFTP FS
> +(file ``tftp_init.c``).
> +
> +.. code-block:: c
> +
> +  /* Configure libbsd. */
> +  #define RTEMS_BSD_CONFIG_NET_PF_UNIX
> +  #define RTEMS_BSD_CONFIG_NET_IF_BRIDGE
> +  #define RTEMS_BSD_CONFIG_NET_IF_LAGG
> +  #define RTEMS_BSD_CONFIG_NET_IF_VLAN
> +  #define RTEMS_BSD_CONFIG_BSP_CONFIG
> +  #define RTEMS_BSD_CONFIG_INIT
> +
> +  #include <machine/rtems-bsd-config.h>
> +
> +  /* RTEMS configuration for libbsd */
> +  #define CONFIGURE_MAXIMUM_USER_EXTENSIONS 1
> +  #define CONFIGURE_INIT_TASK_STACK_SIZE (32 * 1024)
> +  #define CONFIGURE_INIT_TASK_INITIAL_MODES RTEMS_DEFAULT_MODES
> +  #define CONFIGURE_INIT_TASK_ATTRIBUTES RTEMS_FLOATING_POINT
> +  #define CONFIGURE_APPLICATION_NEEDS_LIBBLOCK
> +
> +  /* RTEMS configuration for tftp */
> +  #define CONFIGURE_FILESYSTEM_TFTPFS
> +  #define CONFIGURE_MAXIMUM_FILE_DESCRIPTORS 64
> +
> +  /* Simple RTEMS configuration */
> +  #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
> +  #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
> +  #define CONFIGURE_UNLIMITED_OBJECTS
> +  #define CONFIGURE_UNIFIED_WORK_AREAS
> +  #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
> +  #define CONFIGURE_INIT
> +
> +  #include <rtems/confdefs.h>
> +
> +Application Linkage
> +-------------------
> +
> +The TFTP filesystem is compiled and linked into ``libtftpfs``.  After
> +installation it should be in a place like:
> +
> +.. code-block:: none
> +
> +  <PREFIX>/arm-rtems6/xilinx_zynq_a9_qemu/lib/libtftpfs.a
> +
> +An RTEMS application which wants to use the TFTP filesystem must be linked
> +with the libraries ``libtftpfs``, ``libbsd``, and ``libm`` --- in this order.
> +An example build target in a ``wscript`` for use with the RTEMS WAF build
> +system could be:
> +
> +.. code-block:: python
> +
> +  def build(ctx):
> +      rtems.build(ctx)
> +      ctx(features = 'c cprogram',
> +          target = 'tftp_app.exe',
> +          cflags = '-g -O2',
> +          source = ['tftp_app.c', 'tftp_init.c'],
> +          lib    = ['tftpfs', 'bsd', 'm'])
> +
> +Network Configuration and TFTP Server
> +-------------------------------------
> +
> +QEMU has a simple build-in TFTP server which can serve files for reading
> +only.  By default it is reachable from the application executed by QEMU
> +at IP address ``10.0.2.2`` if SLIRP networking is used.  For the
> +example ``arm/xilinx_zynq_a9_qemu`` BSP, the QEMU option
> +
> +.. code-block:: none
> +
> +  -nic user,model=cadence_gem,tftp=/tmp
> +
> +will cause this TFTP server to deliver files found below directory
> +``/tmp``.  Note that SLIRP requires that the application uses DHCP.
> +
> +Alternatively, it is of course possible to use other kinds of QEMU
> +networking (as for example the TAP virtual Ethernet interface described
> +in the above mentioned
> +`README.rst <https://git.rtems.org/rtems-libbsd/tree/README.rst>`_
> +in section *Qemu and Networking*).  

Thanks for the references here. It is hard to document how to use qemu and then
remain generic for all the hosts we support. For example I use vdewsitch with qemu.

I am not sure about the the link to libbsd's README because a release needs that
documentation not vary in time but I do not have a better solution.

Can the following be sectioned as a specific example for Linux on OpenSUSE so it
is clear there can be differences?

> Also an external TFTP
> +server can be used.  The code was tested with ``atftp`` compiled
> +from the `sources <https://sourceforge.net/projects/atftp/>`_.  On
> +an OpenSUSE 15.3 machine, the following commands sets up ``atftp``
> +for use with the mentioned TAP interface (these commands must be executed
> +as root; ``<APP-USER>`` must be replaced by the name of the "normal"
> +user starting the RTEMS application in QEMU later on; for other
> +distributions the ``firewall-cmd`` commands must be
> +replaced by the equivalent of that distribution):
> +
> +.. code-block:: shell
> +
> +  # Create and configure TAP interface
> +  ip tuntap add qtap mode tap user <APP-USER>
> +  ip link set dev qtap up
> +  ip addr add 169.254.1.1/16 dev qtap
> +
> +  # Open firewalld as non-permanent configuration
> +  firewall-cmd --zone=home --add-service=tftp
> +  firewall-cmd --zone=home --add-interface=qtap
> +
> +  # Start TFTP daemon
> +  touch /var/log/atftpd/atftp.log
> +  chown tftp.tftp /var/log/atftpd/atftp.log
> +  atftpd --user tftp --group tftp --daemon --verbose \
> +      --logfile /var/log/atftpd/atftp.log /srv/tftpboot
> +
> +The ``atftp`` server will then be reachable from an application executed
> +by QEMU at the address of the TAP interface which is in this case
> +``169.254.1.1``.  Note, the IP address in the example code below must
> +be changed to the one at which the TFTP server is actually reachable
> +from the application running in QEMU.  When used with this TAP interface,
> +the QEMU network option must be changed to (replacing the ``-net`` options
> +in the examples found in the already mentioned `README.rst
> +<https://git.rtems.org/rtems-libbsd/tree/README.rst>`_):

Links!

> +
> +.. code-block:: none
> +
> +   -nic tap,model=cadence_gem,ifname=qtap,script=no,downscript=no
> +
> +Usage
> +=====
> +
> +The following diagram shows how the TFTP filesystem is used by an
> +application.  The mount point can be any directory.  The name ``/tftp``
> +used in the figure serves only as an example.  The final unmounting and
> +remove directory steps are optional.
> +
> +.. figure:: ../images/filesystem/tftpfs_usage.png
> +  :width: 90%
> +  :align: center
> +  :alt: TFTP Usage Diagram
> +
> +Mounting the TFTP Filesystem
> +----------------------------
> +
> +When mounting the TFTP filesystem, the argument ``filesystemtype`` must
> +be ``RTEMS_FILESYSTEM_TYPE_TFTPFS`` (``#include <rtems/libio.h>``).
> +
> +The argument ``data`` can either be
> +
> +* a 0-terminated C string of comma separated mount options or
> +* ``NULL`` for mounting with default values.
> +
> +The mount options are case sensitive.  Spaces are not allowed in the string.
> +If conflicting options are specified, the ones more to the right (i.e. end
> +of the string) take precedence.  These mount options are supported:
> +
> +``blocksize=N``
> +  where ``N`` is a decimal integer number.
> +
> +  The TFTP blocksize option is introduced in RFC 2348.  It defines the
> +  number of octets in the data packages transferred.  Valid values
> +  range between 8 and 65464 octets, inclusive.  Values larger
> +  than 1468 may cause package fragmentation over standard Ethernet.
> +  A value of 512 will prevent this option from being sent to
> +  the server.
> +
> +  The default value is 1456.
> +
> +``windowsize=N``
> +  where ``N`` is a decimal integer number.
> +
> +  The TFTP windowsize option is introduced in RFC 7440.  It defines the
> +  number of data packages send before the receiver must send an
> +  acknowledgment package.  Valid values range between 1 and 65535
> +  packages, inclusive.  Simple TFTP servers usually do not support this
> +  option.  This option may negatively contribute to network
> +  congestion.  This can be avoided by using a window size of 1.
> +  A value of 1 will prevent this option from being sent to
> +  the server.
> +
> +  The default value is 8.
> +
> +``rfc1350``
> +  The TFTP client should strictly follow RFC 1350 and not send any
> +  options to the server.  Many simple TFTP server do still not support
> +  the option extension defined in RFC 2347.  The TFTP filesystem will
> +  always make a second option-less connection attempt to the TFTP server
> +  in case a first attempt with options was rejected with an error message.
> +
> +  This option is equivalent to ``blocksize=512,windowsize=1``.
> +
> +``verbose``
> +  During operation, print messages to ``stdout``.  This option has
> +  currently little effect.  It is kept to be compatible to older
> +  implementations.
> +
> +Opening a File
> +--------------
> +
> +Files must be opened by using either ``O_RDONLY`` or ``O_WRONLY``
> +as flags but not both.  Other flags are not supported.
> +
> +The ``pathname`` argument to ``open()`` has the following format:
> +
> +.. code-block:: none
> +
> +  <PREFIX>/<server-address>:<path-on-server>
> +
> +``<PREFIX>``
> +  The path to the point where the TFTP filesystem is mounted.  This can
> +  be a relative path from the current working directory or an absolute
> +  path.
> +
> +``<server-address>``
> +  The network address for the TFTP server from which to download the
> +  file or to which the file should be sent.  This is either
> +
> +    * an IPv4 address (like `127.0.0.1`) or
> +    * the (full-qualified) name of an IPv4 host (acceptable to
> +      ``gethostbyname()``)
> +
> +  The port number cannot be specified and will always be the one reserved
> +  for TFTP: 69.
> +
> +``<path-on-server>``
> +  The path and file name at which the TFTP server will find or create the
> +  file.  Any directories in this path must already exist.  It is not
> +  possible to create or read directories with TFTP.  RFC 1350 specifies
> +  that this ``<path-on-server>`` must be in *netascii*:
> +
> +      This is ascii as defined in "USA Standard Code for Information
> +      Interchange" [1] with the modifications specified in "Telnet
> +      Protocol Specification" [3].
> +
> +      [1] USA Standard Code for Information Interchange, USASI X3.4-1968.
> +
> +      [3] Postel, J., "Telnet Protocol Specification," RFC 764,
> +      USC/Information Sciences Institute, June, 1980.
> +
> +Example pathnames:
> +
> +.. code-block:: c
> +
> +  "/tftp/169.254.1.1:file.txt"
> +  "/TFTPFS/tftp-server.sample.org:bootfiles/image"
> +
> +In the above examples, ``/tftp`` and ``/TFTPFS`` are the directory at which
> +the TFTP filesystem is mounted.  ``169.254.1.1`` and
> +``tftp-server.sample.org`` are the network address of the TFTP server to
> +contact.  ``file.txt`` and ``bootfiles/image`` are the file name and
> +the path at the server side.
> +
> +Closing a File
> +--------------
> +
> +Especially, when writing a file to the server, the return
> +code of ``close()`` should be checked.  Invoking ``close()`` triggers
> +the sending of the last -- not completely filled -- data block.  This
> +may fail the same way as any ``write()`` may fail.  Therefore, an error
> +returned by ``close()`` likely indicates that the file was not completely
> +transferred.
> +
> +Use From Shell
> +==============
> +
> +It is possible to use the RTEMS shell through test ``media01`` of
> +libbsd to exercise the TFTP filesystem.  This text assumes that libbsd
> +has already been setup, configured, compiled and installed as described
> +in the `README.rst <https://git.rtems.org/rtems-libbsd/tree/README.rst>`_.
> +How the test ``media01.exe`` can be executed is described in
> +section *Qemu and Networking* of that file.
> +
> +A TFTP server must be setup and run.  The instructions to setup the TAP
> +device and the ``atftp`` server found above in section *Network
> +Configuration and TFTP Server* could be followed for this purpose.
> +It may be useful to create a sample file for later download in the
> +directory served by the TFTP server.  For ``atftp`` "root" could create
> +a file with these instructions:
> +
> +.. code-block:: shell
> +
> +  # echo "Hello World!" >/srv/tftpboot/hello.txt
> +  # chown tftp.tftp /srv/tftpboot/hello.txt
> +
> +Start the ``media01`` test in one terminal --- as "normal" user:
> +
> +.. code-block:: shell
> +
> +  $ qemu-system-arm -serial null -serial mon:stdio -nographic \
> +    -M xilinx-zynq-a9 -m 256M \
> +    -nic tap,model=cadence_gem,mac=0e:b0:ba:5e:00:01,ifname=qtap,script=no,downscript=no \
> +    -kernel build/arm-rtems6-xilinx_zynq_a9_qemu-default/media01.exe
> +
> +Wait till a line like the following is printed in the terminal:
> +
> +.. code-block:: none
> +
> +  info: cgem0: using IPv4LL address 169.254.191.13
> +
> +Next use the displayed IP address to open a telnet connection in a second terminal:
> +
> +.. code-block:: shell
> +
> +  $ telnet 169.254.191.13
> +
> +At the telnet prompt, enter this command to list the filesystems
> +available for mounting:
> +
> +.. code-block:: none
> +
> +  TLNT [/] # mount -L
> +  File systems: / dosfs tftpfs
> +
> +``tftpfs`` should be among them.  Create a directory and mount the TFTP
> +filesystem:
> +
> +.. code-block:: none
> +
> +  TLNT [/] # mkdir /tftp
> +  TLNT [/] # mount -t tftpfs -o verbose "" /tftp
> +  mounted  -> /tftp
> +
> +Now, files can be sent to and read from the TFTP server using the usual
> +shell commands:
> +
> +.. code-block:: none
> +
> +  TLNT [/] # cp /etc/dhcpcd.duid /tftp/169.254.1.1:dhcpcd.duid
> +  TFTPFS: /169.254.1.1:dhcpcd.duid
> +  TLNT [/] # cat /tftp/169.254.1.1:hello.txt
> +  TFTPFS: /169.254.1.1:hello.txt
> +  Hello World!
> +
> +The terminal session can be terminated with key combination "CTRL-]"
> +followed by a ``quit`` command; the
> +QEMU simulation with "CTRL-a x" and ``tail -f`` with "CTRL-c".
> +
> +TFTP Client API
> +===============
> +
> +The TFTP filesystem has a TFTP client which is responsible to handle all
> +network traffic.  It permits the use of TFTP without filesystem.
> +Essentially, one saves the mounting of the filesystem.  Otherwise the
> +usage is similar to the one of the filesystem.  The equivalent of the
> +``open()``, ``read()``, ``write()``, and ``close()`` functions are:
> +
> +.. code-block:: c
> +
> +  int tftp_open(
> +    const char *hostname,
> +    const char *path,
> +    bool is_for_reading,
> +    const tftp_net_config *config,
> +    void **tftp_handle
> +  );
> +
> +  ssize_t tftp_read( void *tftp_handle, void *buffer, size_t count );
> +
> +  ssize_t tftp_write( void *tftp_handle, const void *buffer, size_t count );
> +
> +  int tftp_close( void *tftp_handle );
> +
> +``tftp_open()`` accepts as input a data structure of type
> +``tftp_net_config``.  It can be used to specify certain values governing
> +the file transfer such as the already described options.  Data of
> +``tftp_net_config`` type can be initialized using function
> +
> +.. code-block:: c
> +
> +  void tftp_initialize_net_config( tftp_net_config *config );
> +
> +The full description can be found in the file ``cpukit/include/rtems/tftp.h``.
> +The function ``rtems_tftpfs_initialize()`` found there is only for RTEMS
> +internal use by the ``mount()`` function.
> +
> +Software Design
> +===============
> +
> +The original source code contained only the files
> +``cpukit/include/rtems/tftp.h`` and ``cpukit/libfs/src/ftpfs/tftpDriver.c``.
> +There was no test suite nor any documentation.
> +
> +When the code was extended to support options (RFC 2347 and others),
> +the code in ``tftpDriver.c`` was split.  The new file ``tftpfs.c`` is
> +responsible to handle all filesystem related issues while ``tftpDriver.c``
> +provides the network related functions.  In effect ``tftpDriver.c`` is
> +a TFTP client library which can be used independently of the filesystem.
> +``tftpfs.c`` calls the functions of ``tftpDriver.c`` to do the actual
> +TFTP file transfer.
> +
> +At this occasion a test suite and this documentation in the *RTEMS
> +Filesystem Design Guide* was added.
> +
> +Test Suite
> +----------
> +
> +The TFTP filesystem comes with an extensive test suite.
> +
> +``libtftpfs`` source code is situated in the RTEMS repository.  For
> +testing it, either ``libbsd`` or RTEMS legacy networking would have been
> +required.  This implies that the tests for ``libtftpfs`` would have
> +needed to be placed in the ``libbsd`` repository --- a different one
> +than the ``libtftpfs`` source code.
> +
> +Yet, ``libtftpfs`` uses only a handful of networking functions.  The
> +test suite provides fake implementations of those functions.  These fake
> +functions permit to simulate the exchange of UDP packages
> +with the ``libtftpfs`` code and thus permits testing the TFTP filesystem
> +without the need of a full network stack.
> +
> +Consequently, the test suite is placed in the RTEMS repository together
> +with the TFTP filesystem source code.  Neither ``libbsd`` nor RTEMS
> +legacy networking is required to run the tests.
> +
> +The test suite can be executed using the ``rtems-test`` tool:
> +
> +.. code-block:: shell
> +
> +  $ cd <path-to-rtems-git-worktree>
> +  $ rtems-test --log-mode=all --rtems-bsp=xilinx_zynq_a9_qemu \
> +    build/arm/xilinx_zynq_a9_qemu/testsuites/fstests/tftpfs.exe
> +
> +TFTP Files in the ``rtems-docs`` GIT
> +------------------------------------
> +
> +``filesystem/trivial_ftp.rst``
> +  The file contains the text of chapter *Trivial FTP Client Filesystem*
> +  in the *RTEMS Filesystem Design Guide*.
> +
> +``images/filesystem/*``
> +  These graphic files contain the diagrams used in chapter *Trivial FTP
> +  Client Filesystem* in the *RTEMS Filesystem Design Guide*.
> +
> +TFTP Files in the ``rtems`` GIT
> +-------------------------------

Is this something want here? Would this be better in a README in the source repo?

Again thanks
Chris

> +
> +``cpukit/include/rtems/tftp.h``
> +  This file declares the public constants, structures, and functions of
> +  the Trivial File Transfer Protocol (TFTP) file system.
> +
> +``cpukit/libfs/src/ftpfs/tftpDriver.c``
> +  This source file contains the implementation of a Trivial File Transfer
> +  Protocol (TFTP) client library --- the network related part of the code.
> +
> +``cpukit/libfs/src/ftpfs/tftp_driver.h``
> +  This file declares private functions of the Trivial File Transfer
> +  Protocol (TFTP) client library.
> +
> +``cpukit/libfs/src/ftpfs/tftpfs.c``
> +  This source file contains the implementation of the Trivial File Transfer
> +  Protocol (TFTP) filesystem.  The code in this file handles the file system
> +  operations (such as ``mount()``, ``open()``, ``read()``, ``write()``,
> +  ``close()`` etc.).
> +
> +``spec/build/cpukit/libtftpfs.yml``
> +  This file specifies how the RTEMS WAF build system has to compile, link
> +  and install ``libtftpfs``.
> +
> +``spec/build/testsuites/fstests/grp.yml``
> +  This file specifies how the RTEMS WAF build system has to compile, link
> +  and install all filesystem test suites.  The TFTP test suite must
> +  be mentioned in this file to be build.
> +
> +``spec/build/testsuites/fstests/tftpfs.yml``
> +  This file specifies how the RTEMS WAF build system has to compile, link
> +  and install the TFTP test suite.
> +
> +``testsuites/fstests/tftpfs/init.c``
> +  This source file contains the test suite with all tests for ``libtftpfs``.
> +  The test suite uses functions from files ``tftpfs_interactions.c`` and ``tftpfs_udp_network_fake.c`` as private helpers.
> +
> +``testsuites/fstests/tftpfs/tftpfs_interactions.h``
> +  This header file provides definitions and declarations of data structures
> +  and functions used to implement network interactions of the UDP network
> +  fake for ``libtftpfs`` tests.
> +
> +``testsuites/fstests/tftpfs/tftpfs_interactions.c``
> +  This source file contains the implementation of network interaction
> +  functions related to the UDP network fake for ``libtftpfs`` tests.
> +
> +``testsuites/fstests/tftpfs/tftpfs_udp_network_fake.h``
> +  This header file provides definitions and declarations of data structures
> +  and functions used to implement the UDP network fake for ``libtftpfs``
> +  tests.
> +
> +``testsuites/fstests/tftpfs/tftpfs_udp_network_fake.c``
> +  This source file contains the implementation of UDP network fake
> +  functions related to ``libtftpfs`` testing.  This code provides fake
> +  implementations for functions like ``socket()``, ``bind()``, ``sendto()``,
> +  ``recvfrom()``, etc. which would normally be provided by libbsd.