genode/tool/run
Norman Feske c450ddcb3d Disambiguate kernel-specific file names
This patch removes possible ambiguities with respect to the naming of
kernel-dependent binaries and libraries. It also removes the use of
kernel-specific global side effects from the build system. The reach of
kernel-specific peculiarities has thereby become limited to the actual
users of the respective 'syscall-<kernel>' libraries.

Kernel-specific build artifacts are no longer generated at magic places
within the build directory (like okl4's includes, or the L4 build
directories of L4/Fiasco and Fiasco.OC, or the build directories of
various kernels). Instead, such artifacts have been largely moved to the
libcache. E.g., the former '<build-dir>/l4/' build directory for the L4
build system resides at '<build-dir>/var/libcache/syscall-foc/build/'.
This way, the location is unique to the kernel. Note that various tools
are still generated somewhat arbitrarily under '<build-dir>/tool/' as
there is no proper formalism for building host tools yet.

As the result of this work, it has become possible to use a joint Genode
build directory that is usable with all kernels of a given hardware
platform. E.g., on x86_32, one can now seamlessly switch between linux,
nova, sel4, okl4, fiasco, foc, and pistachio without rebuilding any
components except for core, the kernel, the dynamic linker, and the timer
driver. At the current stage, such a build directory must still be
created manually. A change of the 'create_builddir' tool will follow to
make this feature easily available.

This patch also simplifies various 'run/boot_dir' plugins by removing
the option for an externally hosted kernel. This option remained unused
for many years now.

Issue #2190
2016-12-23 16:51:32 +01:00
..
boot_dir Disambiguate kernel-specific file names 2016-12-23 16:51:32 +01:00
image run: Add image/muen script to support Muen SK build 2016-01-08 14:37:56 +01:00
load run/ipxe: cleanup creation of config file 2016-08-30 17:17:20 +02:00
log amt: Introduce --log-amt-timeout run parameter 2016-08-29 17:29:36 +02:00
power_off run: plugin for Gembird EnerGenie powerplug 2015-09-09 15:14:30 +02:00
power_on tool: remove WSMAN URL parameters 2016-05-26 15:54:16 +02:00
amt.inc run: modularize run tool 2015-01-26 12:28:40 +01:00
iso.inc run: modularize run tool 2015-01-26 12:28:40 +01:00
load.inc run: modularize run tool 2015-01-26 12:28:40 +01:00
log.inc run: modularize run tool 2015-01-26 12:28:40 +01:00
power_netio.inc run: rename powerplug to netio 2015-09-09 15:14:30 +02:00
qemu.inc Introduce 'spec' subdirectories to outline aspects 2015-09-16 13:58:50 +02:00
README run: rename powerplug to netio 2015-09-09 15:14:30 +02:00
run Disambiguate kernel-specific file names 2016-12-23 16:51:32 +01:00
spike.inc riscv: run tool support for spike 2016-02-26 11:36:51 +01:00


                             ===================
                             The Genode run tool
                             ===================

Introduction
############

The run tool is used to configure, build, and execute so-called run scripts.
These run scripts include a scenario or test-case of Genode components and
subsystems. Its core functionality is split into various modules to accommodate
a variety of different execution environments. These modules provide the
implementation of a given step in the sequence of execution of a run script.
These steps are:

* Building the corresponding components
* Wrapping the components in a format suitable for execution
* Preparing the target systems
* Executing the scenario
* Collecting any output

After the run script was executed successfully, the run tool will print the
string 'Run script execution successful.". This message can be used to check
for the successful completion of the run script when doing automated testing.

The categories of modules are formed by existing requirements such as automated
testing on a variety of different hardware platforms and are based
on the above-named steps:

:boot_dir:
  These modules contain the functionality to populate the boot directory
  and are specific to each kernel. It is mandatory to always include the
  module corresponding to the used kernel.

:image modules:
  These modules are used to wrap up all components used by the run script
  in a specific format and thereby to prepare them for execution.
  Depending on the used kernel, there are different formats. With these
  modules, the creation of ISO and disk images is also handled.

:load modules:
  These modules handle the way the components are transfered to the
  target system. Depending on the used kernel there are various options
  to pass on the components. Loading from TFTP or via JTAG is handled
  by the modules of this category.

:log modules:
  These modules handle how the output of a currently executed run script
  is captured.

:power_on modules:
  These modules are used for bringing the target system into an defined
  state, e.g., by starting or rebooting the system.

:power_off modules:
  These modules are used for turning the target system off after the
  execution of a run script.

When executing a run script, only one module of each category must be used.


Usage
#####

To execute a run script a combination of modules may be used. The combination
is controlled via the RUN_OPT variable used by the build framework. Here are a
few common exemplary combinations:

Executing NOVA in Qemu:

!RUN_OPT = --include boot_dir/nova \
!          --include power_on/qemu --include log/qemu --include image/iso

Executing NOVA on a real x86 machine using AMT for resetting the target system
and for capturing the serial output while loading the files via TFTP:

!RUN_OPT = --include boot_dir/nova \
!          --include power_on/amt --power-on-amt-host 10.23.42.13 \
!                                 --power-on-amt-password 'foo!' \
!          --include load/tftp --load-tftp-base-dir /var/lib/tftpboot \
!                              --load-tftp-offset-dir /x86 \
!          --include log/amt --log-amt-host 10.23.42.13 \
!                            --log-amt-password 'foo!'

Executing fiasco.OC on a real x86 machine using AMT for resetting, USB serial
for output while loading the files via TFTP:

!RUN_OPT = --include boot_dir/foc \
!          --include power_on/amt --amt-host 10.23.42.13 --amt-password 'foo!' \
!          --include load/tftp --tftp-base-dir /var/lib/tftpboot \
!                              --tftp-offset-dir /x86 \
!          --include log/serial --log-serial-cmd 'picocom -b 115200 /dev/ttyUSB0'

Executing hw on a rpi using NETIO powerplug to reset the hardware, JTAG to load
the image and USB serial to capture the output:

!RUN_OPT = --include boot_dir/hw \
!          --include power_on/netio --power-on-netio-host 10.23.42.5 \
!                                   --power-on-netio-user admin \
!                                   --power-on-netio-password secret \
!                                   --power-on-netio-port 1
!          --include power_off/netio --power-off-netio-host 10.23.42.5 \
!                                    --power-off-netio-user admin \
!                                    --power-off-netio-password secret \
!                                    --power-off-netio-port 1
!          --include load/jtag \
!          --load-jtag-debugger /usr/share/openocd/scripts/interface/flyswatter2.cfg \
!          --load-jtag-board /usr/share/openocd/scripts/interface/raspberrypi.cfg \
!          --include log/serial --log-serial-cmd 'picocom -b 115200 /dev/ttyUSB0'


Module overview
###############

A module consist of a expect/TCL source file located in one of the existing
directories of a category. It is named implicitly by its location and the
name of the source file, e.g. 'image/iso' is the name of the image module
that creates an ISO image.

The source file contains one mandatory procedure:

* run_<module> { <module-args> }
  The procedure is called if the step at hand is executed by the
  run tool. If its execution was successful, it returns true and
  otherwise false. Certain modules may also call exit on failure.

A module may have arguments, which are by convention prefixed with the name
of the source file, e.g. 'power_on/amt' may have an argument called
'--power-on-amt-host'. If the argument passes on a value the value must be
made accessible by calling an equally named procedure, e.g.
'--power-on-amt-host' becomes 'proc amt_host { }'.
Thereby a run script or a run environment can access the value of the argument
in a defined way without the use of a global variable by using
'[power_on_amt_host]'. Also arguments without a value may be queried in this
way. '--image-uboot-gzip' becomes '[image_uboot_use_gzip]'.
In addition to these procedures, a module may have any number of public
procedures. They may be used after the presence of the particular module that
contains them is verified. For this reason the run tool provides a procedure
called 'have_include', that performs this check. For example the presence of
the 'load/tftp' module is checked by calling '[have_include "load/tftp"]'.