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 --- images/user/tftp-proxy-1.png | Bin 0 -> 15339 bytes images/user/tftp-proxy-1.puml | 34 +++++++++ user/testing/tftp.rst | 2 + user/tools/boot-image.rst | 2 +- user/tools/index.rst | 1 + user/tools/tftp-proxy.rst | 166 ++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 204 insertions(+), 1 deletion(-) create mode 100644 images/user/tftp-proxy-1.png create mode 100644 images/user/tftp-proxy-1.puml create mode 100644 user/tools/tftp-proxy.rst diff --git a/images/user/tftp-proxy-1.png b/images/user/tftp-proxy-1.png new file mode 100644 index 0000000..e6f4b55 Binary files /dev/null and b/images/user/tftp-proxy-1.png differ diff --git a/images/user/tftp-proxy-1.puml b/images/user/tftp-proxy-1.puml new file mode 100644 index 0000000..7f27c73 --- /dev/null +++ b/images/user/tftp-proxy-1.puml @@ -0,0 +1,34 @@ +' +' TFTP Proxy 1: +' +' Copyright (c) 2020 Chris Johns +' All rights reserved. +' +@startuml + + agent Beaglebone as bbb + agent MicroZed as uzed + agent RPi2 as rpi2 + + rectangle Proxy { + agent "TFTP Proxy" as proxy + } + + rectangle "CI Tester" as tester { + agent "Beaglebone Black" as bbb_proxy + agent "MicroZed (ARM Zynq)" as uzed_proxy + } + + rectangle "Developer" as devel { + agent "RasberryPi 2" as rpi2_proxy + } + + bbb -- proxy : "(10.0.0.10:69)" + uzed -- proxy : "(10.0.0.10:69)" + rpi2 -- proxy : "(10.0.0.10:69)" + + proxy .. bbb_proxy : (10.0.0.100:9001) + proxy .. uzed_proxy : (10.0.0.100:9002) + proxy .. rpi2_proxy : (10.0.0.110:9001) + +@enduml diff --git a/user/testing/tftp.rst b/user/testing/tftp.rst index 1abf469..ade8f9a 100644 --- a/user/testing/tftp.rst +++ b/user/testing/tftp.rst @@ -2,6 +2,8 @@ .. Copyright (C) 2018 Chris Johns +.. _tftp-and-uboot: + TFTP and U-Boot --------------- 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