From 2c37918140d800f7c2ec7c2e9b8bb4286619ab3f Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Tue, 18 Feb 2020 11:09:00 +1100 Subject: user/tools: Add RTEMS TFTP Proxy command documentation --- user/tools/boot-image.rst | 2 +- user/tools/index.rst | 1 + user/tools/tftp-proxy.rst | 166 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 168 insertions(+), 1 deletion(-) create mode 100644 user/tools/tftp-proxy.rst (limited to 'user/tools') diff --git a/user/tools/boot-image.rst b/user/tools/boot-image.rst index 6e76a2d..8e8f63d 100644 --- a/user/tools/boot-image.rst +++ b/user/tools/boot-image.rst @@ -2,7 +2,7 @@ .. Copyright (C) 2019 Chris Johns -.. _RTEMSExecutableInfomation: +.. _rtems-boot-image: RTEMS Boot Image ================ diff --git a/user/tools/index.rst b/user/tools/index.rst index 2ee619b..03e198d 100644 --- a/user/tools/index.rst +++ b/user/tools/index.rst @@ -23,3 +23,4 @@ developers. bsp-builder tester boot-image + tftp-proxy diff --git a/user/tools/tftp-proxy.rst b/user/tools/tftp-proxy.rst new file mode 100644 index 0000000..7516a0d --- /dev/null +++ b/user/tools/tftp-proxy.rst @@ -0,0 +1,166 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 Chris Johns + +.. _RTEMSTFTPProxy: + +RTEMS TFTP Proxy +================ + +.. index:: Tools, rtems-tftp-proxy + +The RTEMS TFTP Proxy (:program:`rtems-tftp-proxy`) command is an RTEMS +tool to simplify hardware testing using the RTEMS Test and Run +commands. This command lets a test set up support a number of +similarly configured boards running tests at the same time by proxying +the TFTP session requests. The :ref:`tftp-and-uboot` section details +the process to run a test executable on a network connected board. + +The TFTP Proxy approach does not require any special modifications in +a boot loader to work and works with any compliant TFTP boot client. + +An identical SD card boot configuration can be used in similar board +when a test set up has a number of similar boards. There is no need to +specialize boot configurations. The TFTP proxy server identifies each +board by MAC address. + +A configuration file maps a board's MAC address to a TFTP server's IP +address and port number. This provides a centralized means to +partition hardware in a test rack between members of a team, continuous +integration services or any other project demands. + +The TFTP port number a proixed service runs with does not need to be +the privileged TFTP port number removing the need to be root to run +the RTEMS Test or Run commands. Only the TFTP Proxy needs to running +as a privileged user. The RTEMS Test and Run commands lets you +specified the TFTP port to bind too. + +Operation +--------- + +A network connected board with a suitable boot loader such as U-Boot +is configured to boot using TFTP. The boot loader's configured TFTP +server IP address is the address of the host computer running the TFTP +Proxy server or the proxy. The TFTP Proxy runs as root or an +administrator as it binds by default to the default TFTP port of 69. + +A reset board sends a TFTP read request (``RRQ``) packet to the host +machine running the TFTP proxy on the standard TFTP port (69). The +proxy server searches the configuration data for a matching MAC +address. A configuration match creates a session, forwarding the +read request to the proxied IP and port. + +The response from the proxied server identifies the remote session +port number and the proxy server knows the board's client port number +from the initial request. The proxy transfers the TFTP data +transparently between the session's ports until the transfer finishes. + +An example configuration is three different types of boards used for +RTEMS kernel regression testing and application development. + +.. _fig-tftp-proxy-1: + +.. figure:: ../../images/user/tftp-proxy-1.png + :width: 75% + :alt: RTEMS TFTP Proxy Test Lab + :figclass: align-center + + RTEMS TFTP Proxy Test Lab + +The project has a continuous integration (CI) server on address +``10.0.0.100`` and two boards, a BeagleBone Black and Xilinx MicroZed +board, are confgured for testing. A developer on another host machine +is using a RaspberryPi to develop an application. The configuration +file is: + +.. code-block:: none + + ; + ; Project Foo Test network. + ; + [default] + clients = bbb, uzed, rpi2 + + [bbb] + mac = 1c:ba:8c:96:20:bc + host = 10.0.0.100:9001 + + [uzed] + mac = 6e:3a:1c:22:aa:5f, 8a:3d:5f:67:55:cb + host = 10.0.0.100:9002 + + [rpi2] + mac = b8:27:eb:29:6b:bc + host = 10.0.0.110:9001 + +The MicroZed board can be seen by different MAC addresses depending on +how U-Boot starts. As a result both are listed. + +Configuration +------------- + +The boot image tool is configured by an INI file that is passed to the +TFTP proxy on the command line when it starts. + +The ``[default]`` section has to contain a ``clients`` entry that +lists the clients. There needs to be a client section for each listed +client. + +A client section header is a client name listed in the ``clients`` +record in the ``defaults`` section. A client section has to contain a +``mac`` record and a ``host`` record. The MAC record is a comma +separated list of MAC addresses in the standard 6 octet hex format +separated by ``:``. A list of MAC addresses will match for any address +listed. The host record is the IP address and port number of the +proxied TFTP server. + +Command +------- + +The :program:`rtems-tftp-proxy` tool runs a TFTP proxy server using a +user provided configuration file. The command line options are: + +:program:`rtems-tftp-proxy` + +.. option:: -h, --help + + Display the command line help. + +.. option:: -l, --log + + Set the log file name. + +.. option:: -v, --trace + + Enable trace or debug logging. + +.. option:: -c CONFIG, --config CONFIG + + The INI format configuration file. + +.. option:: -B BIND, --bind BIND + + The interface address the proxy binds too. The default is ``all`` + which means the proxy binds to all interfaces. + +.. option:: -P PORT, --port PORT + + The port the proxy server binds too. The default is the TFTP + standard port of 69. This is a privileged port so if using this + port number run the TFTP proxy with root or administrator + privileges. + +Examples +-------- + +The examples show running the TFTP Proxy as a privileged user: + +.. code-block:: none + + $ sudo rtems-tftp-proxy -c foo-test-lab.ini + Password: + RTEMS Tools - TFTP Proxy, 5.1.0 + Command Line: rtems-tftp-proxy -c foo-test-lab.ini + Host: FreeBSD ruru 12.0-RELEASE-p3 FreeBSD 12.0-RELEASE-p3 GENERIC amd64 + Python: 3.6.9 (default, Nov 14 2019, 01:16:50) [GCC 4.2.1 Compatible FreeBSD Clang 6.0.1 (tags/RELEASE_601/final 335540)] + Proxy: all:6 -- cgit v1.2.3