mirror of
https://github.com/genodelabs/genode.git
synced 2024-12-23 23:42:32 +00:00
c450ddcb3d
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 |
||
---|---|---|
.. | ||
boot_dir | ||
image | ||
load | ||
log | ||
power_off | ||
power_on | ||
amt.inc | ||
iso.inc | ||
load.inc | ||
log.inc | ||
power_netio.inc | ||
qemu.inc | ||
README | ||
run | ||
spike.inc |
=================== 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"]'.