[rtems-docs commit] user/tools: Add RTEMS TFTP Proxy command documentation
Chris Johns
chrisj at rtems.org
Wed Feb 19 03:14:08 UTC 2020
Module: rtems-docs
Branch: master
Commit: 2c37918140d800f7c2ec7c2e9b8bb4286619ab3f
Changeset: http://git.rtems.org/rtems-docs/commit/?id=2c37918140d800f7c2ec7c2e9b8bb4286619ab3f
Author: Chris Johns <chrisj at rtems.org>
Date: Tue Feb 18 11:09:00 2020 +1100
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(-)
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 <chrisj at rtems.org>
+' All rights reserved.
+'
+ at 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)
+
+ at 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 <chrisj at rtems.org>
+.. _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 <chrisj at rtems.org>
-.. _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 <chrisj at rtems.org>
+
+.. _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
More information about the vc
mailing list