[Fuego] [PATCH] Docs: .rst files for user interface and test API reference.
Pooja <[email protected]> Mon, 5 Oct 2020 15:24:12 +0530
| Newsgroups | dev.linux.lists.fuego |
|---|---|
| Message-ID | <[email protected]> |
From: Pooja More <[email protected]> Covert the following wiki pages into rst format: Core_interfaces Dashboard_view FUEGO_BUILD_FLAGS FUEGO_DEBUG FUEGO_LOGLEVELS Variables fuego_board_function_lib.sh Signed-off-by: Pooja More <[email protected]> --- docs/rst_src/Core_interfaces.rst | 431 +++++++++++++++++++++++++++ docs/rst_src/Dashboard_view.rst | 104 +++++++ docs/rst_src/FUEGO_BUILD_FLAGS.rst | 27 ++ docs/rst_src/FUEGO_DEBUG.rst | 36 +++ docs/rst_src/FUEGO_LOGLEVELS.rst | 98 ++++++ docs/rst_src/Variables.rst | 418 ++++++++++++++++++++++++++ docs/rst_src/fuego_board_function_lib.sh.rst | 72 +++++ 7 files changed, 1186 insertions(+) create mode 100644 docs/rst_src/Core_interfaces.rst create mode 100644 docs/rst_src/Dashboard_view.rst create mode 100644 docs/rst_src/FUEGO_BUILD_FLAGS.rst create mode 100644 docs/rst_src/FUEGO_DEBUG.rst create mode 100644 docs/rst_src/FUEGO_LOGLEVELS.rst create mode 100644 docs/rst_src/Variables.rst create mode 100644 docs/rst_src/fuego_board_function_lib.sh.rst diff --git a/docs/rst_src/Core_interfaces.rst b/docs/rst_src/Core_interfaces.rst new file mode 100644 index 0000000..5bfcbce --- /dev/null +++ b/docs/rst_src/Core_interfaces.rst @@ -0,0 +1,431 @@ +.. _core_interfaces: + +################ +Core interfaces +################ + + +This page documents the interface between the Jenkins front end and +the Fuego core engine. See also :ref:`Variables <variables>` + +========================== +From Jenkins to Fuego +========================== + +Environment variables passed during a build +================================================ + +Built-in Jenkins variables for shell script jobs +--------------------------------------------------- + +``BUILD_ID`` + The current test run id. As of (at least) Jenkins + version 2.32.1, this is the same as the BUILD_NUMBER. + + +``BUILD_NUMBER`` + The current test run number, such as "153". + This appears to be selected as the next numerical number in + sequence,by the Jenkins system, at the start of a job. + +``BUILD_TAG`` + String of "jenkins-${JOB_NAME}-${BUILD_NUMBER}". + Convenient to put into a resource file, a jar file, etc for + easier identification. + +``BUILD_URL`` + Full URL of this test run, like + `<http://server:port/jenkins/job/foo/15/>`_ + +``EXECUTOR_NUMBER`` + The unique number that identifies the current + executor (among executors of the same machine) that's carrying out + this test run. This is the number you see in the "test executor status", + except that the number starts from 0, not 1. + +``JENKINS_HOME`` + The absolute path of the directory assigned on the + master node for Jenkins to store data. + +``JENKINS_URL`` + Full URL of Jenkins, like `<http://server:port/jenkins/>`_ + +``JOB_NAME:`` + Name of runned test or test suite, such as "foo" or + +``foo/bar`` + In Fuego, this will be something like: ``Functional.foo`` + or ``Benchmark.bar`` + +``JOB_URL`` + Full URL of this test or test suite, like + `<http://server:port/jenkins/job/foo/>`_ + +``NODE_LABELS`` + Whitespace-separated list of labels that the node is + assigned. + +``NODE_NAME`` + Name of the slave if the test run is on a slave, or + "master" if run on master. In the case of Fuego, this is the board + name (e.g. 'beagleboneblack') + +``WORKSPACE`` + The absolute path of the directory assigned to the test + run as a workspace. For Fuego, this is always ``/fuego-rw/buildzone``. + Note that this comes from "custom workspace" setting in the job definition. + +Fuego variables passed from Jenkins system configuration +------------------------------------------------------------ + +The following variables are defined at the system level, and are passed +by Jenkins in the environment of every job that is executed: + +``FUEGO_RO`` + The location where Fuego read-only data (configuration, + boards and toolchains) are located. Currently ``/fuego-ro`` in the + docker container. + +``FUEGO_RW`` + The location where Fuego read-write data is located + (directories for builds, logs (run data), and other workspace and + scratchpad areas). Currently ``/fuego-rw``. + +``FUEGO_CORE`` + The location where the Fuego script system and tests + are located. Currently ``/fuego-core``. + +Fuego variables passed from Jenkins job definition +------------------------------------------------------ + +These variables are defined in the job definition for a test: + +``Device`` + This is the target board to run the test on. + +``Reboot`` + Indicates to reboot the target device before running the test + +``Rebuild`` + Indicates that build instances of the test suite should + be deleted, and the test suite rebuilt from the tarball + +``Target_PreCleanup`` + Indicates to clean up test materials left from + a previous run of the test, before the test begins. + +``Target_PostCleanup`` + Indicates to clean up test materials after the + test ends. + +``TESTPLAN`` + This has the name of the testplan used for this test job. + Note that this selected by the end user from the output of + getTestplans.groovy. (example value: testplan_default) + +``TESTNAME`` + Has the base name of the test (e.g. LTP vs Functional.LTP) + +``TESTSPEC`` + This has the name of the spec used for this test job + +``FUEGO_DEBUG`` + Can have a 1 to indicate verbose shell script output + +======================= +From Fuego to Fuego +======================= + +``DISTRIB`` + Indicates the distribution file for the board. + This comes from the board file. It's primary purpose is to select the + logging features of the distribution on the target (to indicate whether + there's a logger present on target). The value is often + 'distribs/nologread.dist' + +``OF_BOARD_FILE`` + Full path to the board file + +``OF_CLASSDIR`` + full path to the overlay class directory + (usually /home/jenkins/overlays//base) + +``OF_CLASSDIR_ARGS`` + argument specifying the overlay class directory + (usually '--classdir /home/jenkins/overlays//base') + +``OF_DEFAULT_SPECDIR`` + path to directory containing test specs + (usually /home/jenkins/overlays//test_specs) + +``OF_DISTRIB_FILE`` + path to the distribution file for the target + board (often /home/jenkins/overlays//distribs/nologger.dist + +``OF_OVFILES`` + FIXTHIS - document what OF_OVFILES is for + +``OF_OVFILES_ARGS`` + FIXTHIS - document what OF_OVFILES_ARGS is for + +``OF_ROOT`` + root directory for overlay generator + (usually /home/jenkins/overlays/) + +``OF_SPECDIR_ARGS`` + argument to specify the test spec directory + (usually '--specdir /home/jenkins/overlays//test_specs/') + +``OF_TESTPLAN_ARGS`` + +``OF_TESTPLAN`` + full path to the JSON test plan file for this test + (often /home/jenkins/overlays//testplans/testplan_default.json) + +``OF_TESTPLAN_ARGS`` + argument specifying the path to the testplan + (often '--testplan /home/jenkins/overlays//testplans/testplan_default.json') + +``TEST_HOME`` + home directory for the test materials for this test + (example: /home/jenkins/tests/Functional.bc) + +``TESTDIR`` + base directory name of the test (example: Functional.bc) + +``TRIPLET`` + FIXTHIS - document TRIPLET + +Deprecated +============== + +The following variables are no longer used in Fuego: + +``FUEGO_ENGINE_PATH`` + (deprecated in Fuego 1.1 - use '$FUEGO_CORE/engine' now) + +``FUEGO_PARSER_PATH`` + (deprecated in Fuego 1.1) + + +=================== +Example Values +=================== + +Here are the values from a run using the Jenkins front-end with job +bbb.default.Functional.hello_world: + +(these are sorted alphabetically):: + + AR=arm-linux-gnueabihf-ar + ARCH=arm + AS=arm-linux-gnueabihf-as + BUILD_DISPLAY_NAME=#2 + BUILD_ID=2 + BUILD_NUMBER=2 + BUILD_TAG=jenkins-bbb.default.Functional.hello_world-2 + BUILD_TIMESTAMP=2017-04-10_21-55-26 + CC=arm-linux-gnueabihf-gcc + CONFIGURE_FLAGS=--target=arm-linux-gnueabihf --host=arm-linux-gnueabihf --build=x86_64-unknown-linux-gnu + CPP=arm-linux-gnueabihf-gcc -E + CROSS_COMPILE=arm-linux-gnueabihf- + CXX=arm-linux-gnueabihf-g++ + CXXCPP=arm-linux-gnueabihf-g++ -E + EXECUTOR_NUMBER=0 + FUEGO_CORE=/fuego-core + FUEGO_RO=/fuego-ro + FUEGO_RW=/fuego-rw + FUEGO_START_TIME=1491861326786 + HOME=/var/lib/jenkins + HOST=arm-linux-gnueabihf + HUDSON_COOKIE=1b9620a3-d550-4cb1-afb1-9c5a29650c14 + HUDSON_HOME=/var/lib/jenkins + HUDSON_SERVER_COOKIE=2334aa4d37eae7a4 + JENKINS_HOME=/var/lib/jenkins + JENKINS_SERVER_COOKIE=2334aa4d37eae7a4 + JOB_BASE_NAME=bbb.default.Functional.hello_world + JOB_DISPLAY_URL=http://unconfigured-jenkins-location/job/bbb.default.Functional.hello_world/display/redirect + JOB_NAME=bbb.default.Functional.hello_world + LD=arm-linux-gnueabihf-ld + LDFLAGS=--sysroot / -lm + LOGDIR=/fuego-rw/logs/Functional.hello_world/bbb.default.2.2 + LOGNAME=jenkins + MAIL=/var/mail/jenkins + NODE_LABELS=bbb + NODE_NAME=bbb + PATH=/usr/local/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games + PREFIX=arm-linux-gnueabihf + PWD=/fuego-rw/buildzone + RANLIB=arm-linux-gnueabihf-ranlib + Reboot=false + Rebuild=true + RUN_CHANGES_DISPLAY_URL=http://unconfigured-jenkins-location/job/bbb.default.Functional.hello_world/2/display/redirect?page=changes + RUN_DISPLAY_URL=http://unconfigured-jenkins-location/job/bbb.default.Functional.hello_world/2/display/redirect + SDKROOT=/ + SHELL=/bin/bash + SHLVL=3 + Target_PostCleanup=true + Target_PreCleanup=true + TERM=xterm + TESTDIR=Functional.hello_world + TESTNAME=hello_world + TESTSPEC=default + USER=jenkins + WORKSPACE=/fuego-rw/buildzone + +=========================== +From Fuego to Jenkins +=========================== + + * FIXTHIS - add interface to perform Jenkins operations from the scripts + * To abort a job, fuego does: + + * wget -qO- ${BUILD_URL}/stop + * This is called by common.sh: ``abort_job()`` + + * To check if another test instance is running (do a lock check), + fuego does: + + * wget -qO- "$(cat ${LOCKFILE})/api/xml?xpath=*/building/text%28%29" + + * LOCKFILE was previously set to hold the contents: ${BUILD_URL}, + so this resolves to: + + * wget -qO- ${BUILD_URL}/api/xml?xpath=*/building/text() + + * This is called by functions.sh:``concurrent_check()`` + +Jenkins-cli interface +====================== + +You can run jenkins commands from the command line, using the +pre-installed jenkins-cli interface. Note that Fuego does not use +this interface (that I can tell). + +jenkins-cli.jar is located in the Docker container at: :: + + /var/cache/jenkins/war/WEB-INF/jenkins-cli.jar + + +See https://wiki.jenkins-ci.org/display/JENKINS/Jenkins+CLI for +information about using this plugin. + +Here is a list of available commands for this plugin: :: + + build + Runs a test, and optionally waits until its completion. + cancel-quiet-down + Cancel the effect of the "quiet-down" command. + clear-queue + Clears the test run queue + connect-node + Reconnect to a node + console + Retrieves console output of a build + copy-job + Copies a test. + create-job + Creates a new test by reading stdin as a configuration XML file. + delete-builds + Deletes test record(s). + delete-job + Deletes a test + delete-node + Deletes a node + disable-job + Disables a test + disconnect-node + Disconnects from a node + enable-job + Enables a test + get-job + Dumps the test definition XML to stdout + groovy + Executes the specified Groovy script. + groovysh + Runs an interactive groovy shell. + help + Lists all the available commands. + install-plugin + Installs a plugin either from a file, an URL, or from update center. + install-tool + Performs automatic tool installation, and print its location to + stdout. Can be only called from inside a test run. + keep-build + Mark the test run to keep the test run forever. + list-changes + Dumps the changelog for the specified test(s). + list-jobs + Lists all tests in a specific view or item group. + list-plugins + Outputs a list of installed plugins. + login + Saves the current credential to allow future commands to run + without explicit credential information. + logout + Deletes the credential stored with the login command. + mail + Reads stdin and sends that out as an e-mail. + offline-node + Stop using a node for performing test runs temporarily, until the + next "online-node" command. + online-node + Resume using a node for performing test runs, to cancel out the + earlier "offline-node" command. + quiet-down + Quiet down Jenkins, in preparation for a restart. Don't start + any test runs. + reload-configuration + Discard all the loaded data in memory and reload everything from + file system. Useful when you modified config files directly on disk. + restart + Restart Jenkins + safe-restart + Safely restart Jenkins + safe-shutdown + Puts Jenkins into the quiet mode, wait for existing test runs to + be completed, and then shut down Jenkins. + session-id + Outputs the session ID, which changes every time Jenkins restarts + set-build-description + Sets the description of a test run. + set-build-display-name + Sets the displayName of a test run + set-build-result + Sets the result of the current test run. Works only if invoked + from within a test run. + shutdown + Immediately shuts down Jenkins server + update-job + Updates the test definition XML from stdin. + The opposite of the get-job command + version + Outputs the current version. + wait-node-offline + Wait for a node to become offline + wait-node-online + Wait for a node to become online + who-am-i + Reports your credential and permissions + + +Scripts to process Fuego data +============================== + +Benchmark parsing +-------------------- + +In Fuego, Benchmark log parsing is done by a python system consisting +of ``parser.py`` (from each test), ``dataload.py`` and utility functions in +``fuego-core/engine/scripts/parser`` + +See :ref:`Benchmark parser notes <benchmark_parser_notes>`, +:ref:`parser.py <parser.py>`, :ref:`reference.log <reference.log>` and +:ref:`Parser module API <Parser_module_API>`. + +Postbuild action +------------------ + +In Fuego, Jenkins jobs are configured to perfrom a postbuild action, +to set the description of a test with links to the test log +(and possibly plot and other files generated in post-processing) diff --git a/docs/rst_src/Dashboard_view.rst b/docs/rst_src/Dashboard_view.rst new file mode 100644 index 0000000..8ed0d68 --- /dev/null +++ b/docs/rst_src/Dashboard_view.rst @@ -0,0 +1,104 @@ +.. _dashboard_view: + +################ +Dashboard view +################ + + +Here is some information about the main dashboard view in Jenkins, in +Fuego: + +========================= +Main screen elements +========================= + +If you click on "Jenkins" in the upper left +part of any page in the = web interface, you will be taken to a page +with the following parts: + + * Top of screen are some logos and a search bar + * A navigation bar below that (with a context trail) + * A sidebar of the left of the page with: + + * A menu + * A "Build Queue" + * A "Build Executor Status" + * Target status + + * The main job panel, which may consists of several tabs, but + which will have at least the following: + + * All + * ``+`` sign + +Job dashboard +============== + +Each job dashboard shows a list of jobs, with some +information about each one. The information shows the status of the +last execution of the test associated with the job, as well as a +"weather report", indicating the status of the last few runs. There +is also information about the last successful run, the duration of the +last run, and so on. + +============================ +Changing the interface +============================ + +Create a new view +================== + +It is often handyto see just a subset of the jobs +(like those for a particular board, +or those having to do with a specific test area (like filesystems or +networking). + +You can create a new view by clicking on the "+" sign, to add a new +tab to the dashboard. Then entering a name, and selecting the "List +View" button. Then press the "OK" button. + +At this point you can customize the view. The most important thing in +creating a new view is selecting which jobs to show in the view. You +can select specific jobs by name, or use a regular expression to +select the jobs to display. If you wanted to create a view that +showed all the jobs related to your board 'myboard', you could create +a view called 'myboard', and under "Job Filters", check the checkbox +labeled: "User a regular expression to include jobs into the view". +Then add a regular expression like: 'myboard.*" + +Click OK to save your view, and it should show up as a new tab in the +dashboard view. + +Edit an existing view +======================= + +To see the configuration for each view, +select the tab you want to view/edit, and select "Edit View" in the +left sidebar menu. + +For each Dashboard view you can set: + + * Name, Description + * Job Filters + + * You can select individual tests, or use a regular expression to + include tests in the view + + * Columns + + * You can add or remove columns, or reorder the columns + + * Default columns: + + * Status + * Weather + * Name + * Last Success + * Last Failure + * Last Duration + * Build Button + + * To remove a column, press the button labeled "Delete" + * To reorder columns, hover your mouse over the column name, then + click and drag the column to the position you would like it, in + the list of columns. diff --git a/docs/rst_src/FUEGO_BUILD_FLAGS.rst b/docs/rst_src/FUEGO_BUILD_FLAGS.rst new file mode 100644 index 0000000..d8f3ff7 --- /dev/null +++ b/docs/rst_src/FUEGO_BUILD_FLAGS.rst @@ -0,0 +1,27 @@ +.. _feugo_build_flags: + +################## +FUEGO BUILD FLAGS +################## + +This variable may be defined in a board file or in a tools file, and +is used to specify build attributes for test programs built by Fuego +for that board or toolchain (respectively) + +Currently, this can have the value: **no_static** + +Other values may be supported (in a space-separated list) in the +future. + +By default, many Fuego tests will attempt to build static binaries, as +these require less dependencies on the target. However, some +toolchains do not support compiling static binaries. For a board that +uses such a a toolchain, this flag should be used in the board file, +to indicate to the Fuego build system to build dynamic programs +instead. + +Example (put this line your board configuration file, or in your +$PLATFORM-tools.sh file): :: + + FUEGO_BUILD_FLAGS="no_static" + diff --git a/docs/rst_src/FUEGO_DEBUG.rst b/docs/rst_src/FUEGO_DEBUG.rst new file mode 100644 index 0000000..d9a69f5 --- /dev/null +++ b/docs/rst_src/FUEGO_DEBUG.rst @@ -0,0 +1,36 @@ +.. _fuego_debug: + +############### +FUEGO DEBUG +############### + +.. note:: + FUEGO_DEBUG is now deprecated. Please used the newer + :ref:`FUEGO_LOGLEVELS <FUEGO LOGLEVELS>` feature instead of this. + As of Fuego version 1.4, + FUEGO_DEBUG is still supported for backwards compatibility. + +The environment variable FUEGO_DEBUG is used to control debug output +during execution of a Fuego test. + +If this variable is not set, no debugging messages (or less messages) +are produced. + +The variable is a bitmask. If it is defined at all, then the script +system will produce shell trace messages as part of the test log. + +The following bitmask values can be used to turn on debugging for +different parts of the system: + + * 1 = debug the main execution of test phases + * 2 = debug the parser + * 4 = debug the criteria processor + * 8 = debug the chart generator code + +Combinations are allowed, but must be in decimal. + +Example: :: + + export FUEGO_DEBUG=15 + +This would turn on debug messages for all areas. diff --git a/docs/rst_src/FUEGO_LOGLEVELS.rst b/docs/rst_src/FUEGO_LOGLEVELS.rst new file mode 100644 index 0000000..3a747a6 --- /dev/null +++ b/docs/rst_src/FUEGO_LOGLEVELS.rst @@ -0,0 +1,98 @@ +.. _fuego_loglevels: + +###################### +FUEGO LOGLEVELS +###################### + +The environment variable ``FUEGO_LOGLEVELS`` is used to control message +output (including debug messages) during execution of a Fuego test. + +================ +Introduction +================ + +The ``FUEGO_LOGLEVELS`` variable specifies a string containing a list of +areas and log level combinations, separated by commas. The area and +loglevel are joined by a colon. + +Here is an example: :: + + export FUEGO_LOGLEVELS="deploy:verbose,criteria:debug" + + +Note that a sample of this line is provided in the Jenkins job for +every test. It is, by default, commented out. However, you can easily +turn on ``FUEGO_LOGLEVELS`` by uncommenting this line. You can customize +the log level to use for different execution areas by changing the +value of the variable. + +To change this line in a Jenkins job, select the job in the Jenkins +interface, then select "Configure", and edit the line in "Execute +Shell - Command" box, in the "Build" section of the job configuration. + +If the ``FUEGO_LOGLEVELS`` variable is not set, the default logging level +for all areas of test execution is "info". + +=============== +Log levels +=============== + +There are 5 logging levels available, and messages from Fuego are +categorized into these 5 different levels: + + * error + * warning + * info + * verbose + * debug + +Specifying a particular level means that all messages above that level +will be output. Messages at level 'error' are always shown, no matter +what log level is specified. + +================= +Execution areas +================= + +Area names correspond to phases, and to sub-phases of the test +execution stepx. +The following area names are supported: + + * pre_test + * pre_check + * build + * makepkg + * deploy + * snapshot + * run + * post_test + * processing + * parser + * criteria + * charting + +================= +Output functions +================= + +With this feature, 5 new functions have been added to the Fuego core. +These functions may be used in your test shell script (``fuego_test.sh``), so +that your output may be managed the same way that core output is managed. + +The following functions are available: + + * dprint - print output if the message level is 'debug'. + * vprint - print output if the message level is 'debug' or 'verbose'. + * iprint - print output if the message level is 'debug', verbose', + or 'info'. + * wprint - print output if the message level is 'debug', 'verbose', + 'info', or warning'. + * eprint - print output always (message level 'error') + +Deprecated FUEGO_DEBUG +========================= + +``FUEGO_LOGLEVELS`` replaces the earlier :ref:`FUEGO_DEBUG <FUEGO DEBUG>` +variable for controlling debug output of Fuego. However, as of Fuego +version 1.4, both ``FUEGO_DEBUG`` is still supported for backwards +compatibility. diff --git a/docs/rst_src/Variables.rst b/docs/rst_src/Variables.rst new file mode 100644 index 0000000..802513f --- /dev/null +++ b/docs/rst_src/Variables.rst @@ -0,0 +1,418 @@ +.. _variables: + +############### +Variables +############### + +This is an index of all the variables used by Fuego: :: + + + FIXTHIS - I don't have all the fuego variables documented here yet + +See also :ref:`Core interfaces <core_interfaces>` + +== +A +== + + * ``ARCHITECTURE:`` the processor architecture of the target board + + * Defined in the board file for a target + + * Used by toolchain and build scripts for building the tests + + * *NOTE: this appears to only be used by iozone.sh* + + * Sample: arm + + * ``ARCH:`` architecture used by the toolchain + + * Sample: arm + + * Set by :ref:`tools.sh <tools.sh>` based on TOOLCHAIN + + * ``AS:`` name of the assembler + + * Set by :ref:`tools.sh <tools.sh>` based on TOOLCHAIN + * Commonly used during the build phase + (in the function :ref:`test_build <function_test_build>`) + +== +B +== + + * ``BAUD:`` Baud rate to be used with the serialport + + * Defined in the board file for a target + * Used by serial transport + * Sample: "115200" + + * ``BOARD_TESTDIR:`` directory on the target board where test data will + be placed + + * Defined in the board file for a target + * Sample: ``/home/fuego`` + +== +C +== + + * ``CC:`` name of the C compiler + + * Set by :ref:`tools.sh <tools.sh>` based on TOOLCHAIN + * Commonly used during the build phase + (in the function :ref:`test_build <function_test_build>`) + * Sample: arm-linux-gnueabihf-gcc + + * ``CONFIGURE_FLAGS:`` flags used with the 'configure' program + + * Set by :ref:`tools.sh <tools.sh>` based on TOOLCHAIN + * Commonly used during the build phase + (in the function :ref:`test_build <function_test_build>`) + + * ``CROSS_COMPILE:`` cross-compile prefix used for kernel builds + + * Set by :ref:`tools.sh <tools.sh>` based on TOOLCHAIN + * Sample: arm-linux-gnueabihf- + * *NOTE: this is often $PREFIX followed by a single dash* + + * ``CPP:`` name of the C pre-processor + + * Set by :ref:`tools.sh <tools.sh>` based on TOOLCHAIN + + * ``CXX:`` name of the C++ compiler + + * Set by :ref:`tools.sh <tools.sh>` based on TOOLCHAIN + + * ``CXXCPP:`` name of the C++ pre-processor + + * Set by :ref:`tools.sh <tools.sh>` based on TOOLCHAIN + +== +F +== + + * ``FUEGO_BUILD_FLAGS:`` has special flags used to control builds + (for some tests) + + * See :ref:`FUEGO_BUILD_FLAGS <fuego_build_flags>` + + * ``FUEGO_CORE:`` directory for Fuego core scripts and tests + + * This is defined in Jenkins and Fuego system-level configurations + * Set to ``/fuego-core`` inside the Docker container. + + * ``FUEGO_DEBUG:`` controls whether Fuego emits debug information during + test execution + + * See :ref:`FUEGO_DEBUG <feugo_debug>` + + * ``FUEGO_RO:`` directory for Fuego read-only data + + * This is defined in the Jenkins and Fuego system-level + configurations + * Set to ``/fuego-ro`` inside the Docker container. + + * ``FUEGO_RW:`` directory for Fuego read-write data + + * This is defined in Jenkins and Fuego system-level configurations + * Set to ``/fuego-rw`` inside the Docker container. + + * ``FUEGO_TARGET_TMP:`` directory on target to use for syslogs + + * This is defined in the board file for a target board + * This should specify a directory in the board filesystem that is + persistent across reboots. This is to override the default temp + directory (of ``/tmp``), if that directory is erased on a board + reboot. + + * ``FUEGO_TEST_PHASES:`` specifies a list of phases to perform during + test execution + + * This is usually set by 'ftc run-test' based on the '-p' option. + * This is a space-separated list of strings, with the following + possible strings: pre_test pre_check build deploy run post_test + processing + +== +G +== + + * ``GEN_TESTRES_FILE:`` set to the value of TEST_RES, when a + BATCH_TESTPLAN is in effect + +== +I +== + + * ``IO_TIME_SERIAL:`` Time required for echoing the whole command and + response + + * Defined in the board file + * Used by the transport functions + * Sample: 0.1 + + * ``IPADDR:`` IP address of the target board + + * Defined in the board file + * Used by the transport functions + * Sample: 10.0.1.74 + +== +L +== + + * ``LD:`` name of the linker + + * Set by :ref:`tools.sh <tools.sh>` based on TOOLCHAIN + * Sample: arm-linux-gnueabihf-ld + + * ``LOGIN:`` login account name for the target + + * Defined in the board file for the target + * Used by the transport functions + * The account on the target should have sufficient rights to run a + variety of tests and perform a variety of operations on the target + * Sample: root + +== +M +== + + * ``MAX_BOOT_RETRIES:`` Number of times to retry connecting to target + during a :ref:`target_reboot <function_target_reboot>` operation. + + * Defined in the board file + * Sample: 20 + + * ``MMC_DEV:`` device filename for an MMC device on the target + + * Defined in the board file + * Used by filesystem test specs + * Sample: ``/dev/mmcblk0p2`` + + * ``MMC_MP:`` mount point for a filesystem on an MMC device on the target + + * Defined in the board file + * Used by filesystem test specs + * Sample: ``/mnt/mmc`` + + * ``MOUNT_BLOCKDEV:`` device filename for a block device on the target + + * Defined in a filesystem test spec + + * e.g. in (bonnie, fio, ffsb, iozone, synctest, aiostress, + dbench, tiobench).spec + + * Usually references either ``MMC_DEV``, ``SATA_DEV`` or ``USB_DEV``, + depending on what the test spec indicates to test + + * Sample: ``/dev/sda1`` + + * ``MOUNT_POINT:`` mount point for a filesystem to be tested on the target + + * Defined in a filesystem test spec + + * e.g. in (bonnie, fio, ffsb, iozone, synctest, aiostress, + dbench, tiobench).spec + + * Usually references either ``MMC_MP``, ``SATA_MP``, or ``USB_MP``, depending + on what the test spec indicates to test + + * Sample: ``/mnt/sata`` + +== +N +== + + * ``NODE_NAME:`` the name of the board + + * This is set by Jenkins, and is the first part of the + Fuego job name +== +O +== + + * ``OF_ROOT:`` root of overlay system + + * Sample: ``/home/jenkins/overlays/`` + +== +P +== + + * ``PASSWORD:`` password used with to login to the target board + + * Defined in the board file for a target + * Used by the transport functions + * It can be the empty string: "" + * Sample: mypass + + * ``PLATFORM:`` name of the target "platform" This is used to identify + the toolchain used for building tests. This has been deprecated. + Please use 'TOOLCHAIN' instead. + + * ``PREFIX:`` toolchain prefix + + * Set by :ref:`tools.sh <tools.sh>` based on TOOLCHAIN + * Sample: arm-linux-gnueabihf + * *NOTE: see also CROSS_COMPILE* + +== +R +== + + * ``REP_DIR:`` directory where reports are stored + + * Sample: ``/home/jenkins/logs/logruns/`` + + * ``REP_GEN:`` report generator program + + * Sample: ``/home/jenkins/scripts/loggen/gentexml.py`` + + * ``REP_LOGGEN:`` program used to generate report logs? + + * Sample: ``/home/jenkins/scripts/loggen/loggen.py`` + +== +S +== + + * ``SATA_DEV:`` device node filename for a SATA device on the target + + * Defined in the board file + * Used by filesystem tests + * Sample: ``/dev/sda1`` + + * ``SATA_MP:`` mount point for a filesystem on a SATA device on the target + + * Used by filesystem tests + * Sample: ``/mnt/sata`` + + * ``SRV_IP:`` IP address of server machine (host machine where fuego runs) + + * Defined in base-board.fuegoclass + + * Obtained dynamically using the :command:`ip` command + + * Can be defined in a board file for a target, using an :command:`override` + command + * Used by networking tests (NetPIPE, iperf, netperf) + * Sample: 10.0.1.1 + + * ``SSH_PORT:`` port to use for ssh connections on the target + + * Defined in the board file for the target + * The default port for sshd is 22 + * Sample: 22 + + * ``SERIAL:`` port to use for serial connections on the target + + * Defined in the board file for the target + * The device file name as detected in Docker container + * Sample: ttyACM0 + +== +T +== + + * ``TESTLOG:`` full path to log for a particular test + + * Sample: ``/home/jenkins/logs/Functional.bzip2/ + testlogs/bbb.2016-06-24_18-12-53.2.log`` + + * ``TEST_RES:`` full path to JSON results file for a test + + * Sample: ``/home/jenkins/logs/Functional.bzip2/testlogs/ + bbb.2016-06-24_18-12-53.2.res.json`` + * Sample contents: + + * ``TESTDIR:`` name of the directory for a particular test + + * This is just the directory name, not the full path (see $TEST_HOME) + * This is also used as the reference parse log prefix + * Sample: ``Functional.bzip2`` + + * ``TEST_HOME:`` full path to the root of the test directory + + * Sample: ``/home/jenkins/tests/Functional.bzip2`` + + * ``TOOLCHAIN:`` name of the toolchain used to build test programs for a + board. + + * Defined in the board file + * Used in ``tools.sh`` + * Sample: qemu-armv7hf + * *NOTE: this replaced 'PLATFORM', used in earlier versions of Fuego* + + * ``TRANSPORT:`` type of connection between the host system and the target + system + + * Defined in the board file for the target + * possible values: ssh, serial, ttc + + * Others anticipated are: adb, lava + + * Used by the transport functions + * Sample: ssh + + * ``TTC_TARGET:`` target name used with 'ttc' command + + * Defined in the board file for the target + * Used by the transport functions, for the 'ttc' transport only + * Sample: beaglebone + +== +U +== + + * ``USB_DEV:`` device filename for an block device provided by a USB + device on the target + + * Defined in the board file + * Used by filesystem test specs + * Sample: ``/dev/sdb1`` + + * ``USB_MP:`` mount point for a filesystem on an USB device on the target + + * Defined in the board file + * Used by filesystem test specs + * Sample: ``/mnt/usb`` + +==================== +UNDOCUMENTED (YET) +==================== + + * ``TRIPLET`` + * ``LTP_OPEN_POSIX_SUBTEST_COUNT_POS`` + + * Defined in board file for a target + + * ``LTP_OPEN_POSIX_SUBTEST_COUNT_NEG`` + + * Defined in board file for a target + + * ``EXPAT_SUBTEST_COUNT_POS`` + + * Defined in board file for a target + + * ``EXPAT_SUBTEST_COUNT_NEG`` + + * Defined in board file for a target + + * ``OF_ROOT`` + * ``OF_CLASSDIR`` + * ``OF_DEFAULT_SPECDIR`` + * ``OF_OVFILES`` + * ``OF_CLASSDIR_ARGS`` + * ``OF_TESTPLAN_ARGS`` + * ``OF_SPECDIR_ARGS`` + * ``OF_OUTPUT_FILE`` + * ``OF_OUTPUT_FILE_ARGS`` + * ``OF_DISTRIB_FILE`` + * ``OF_OVGEN`` + * ``OF_BOARD_FILE`` + * ``BATCH_TESTPLAN`` + * ``OF_TESTPLAN`` + * ``OF_TESTPLAN_ARGS`` + * ``OF_OVFILES_ARGS`` diff --git a/docs/rst_src/fuego_board_function_lib.sh.rst b/docs/rst_src/fuego_board_function_lib.sh.rst new file mode 100644 index 0000000..62b1937 --- /dev/null +++ b/docs/rst_src/fuego_board_function_lib.sh.rst @@ -0,0 +1,72 @@ +.. _fuego_board_function_lib.sh_: + +############################ +fuego board function lib.sh +############################ + +==================== +Description +==================== + +``fuego_board_function_lib.sh`` is library of shell functions for +performing certain board-side operations in a distribution-independent +way. This set of utility functions is provided so that commonly used +operations can be performed on a variety of distributions (both +desktop and embedded distributions of Linux) without having to write +special-case implementations. + +The library is written purely in POSIX, so it can be used for +board-side testing on almost all Linux platforms. +The library is normally copied to the board during the test's deploy +phase. It resides in found in the host computer in the 'scripts' +directory. This is found at +``/fuego-core/engine/scripts/fuego_board_function_lib.sh`` inside the +Docker container. + +Deploying the library +======================= + +To put the script on board being tested, copy it to the board during +the test's 'deploy' phase (in test_deploy in the test's ``fuego_test.sh`` +file), with a command like so: :: + + put $FUEGO_CORE/engine/scripts/fuego_board_function_lib.sh $BOARD_TESTDIR/fuego.$TESTDIR + +Using the library +===================== + +Once the script is on the board, you can use it in your test's +board-side shell script by sourc'ing it into the script, and calling +its functions. + +Assuming you have a shell script running in the +$BOARD_TESTDIR/fuego.$TESTDIR directory, you could have the following +lines inside your script: :: + + . fuego_board_function_lib.sh + set_init_manager + +This 'sources' the script (function library) into your current shell +environment, and then calls the 'set_init_manager' routine, which is +one of the functions in the library. + +Functionality overview +======================= + +``fuego_board_function_lib.sh`` supports the following operations: + + 1) Detecting the init manager (proc 1) running on the system + 2) Detecting the type of logger service running on the system + 3) Starting and stopping system services in a distribution-neutral + way + +======================= +Function reference +======================= + + * set_init_manager - sets 'init_manager' to either 'systemd' or + 'sysvinit' + * detect_logger_service - sets 'logger_service' to either 'syslog-ng' + or 'syslog' + * exec_service_on_target - is used to start or stop a named service + on the target board -- 2.7.4 -- This message contains confidential information and is intended only for the individual(s) named. If you are not the intended recipient, you are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this mail and attached file/s is strictly prohibited. Please notify the sender immediately and delete this e-mail from your system. E-mail transmission cannot be guaranteed to be secured or error-free as information could be intercepted, corrupted, lost, destroyed, arrive late or incomplete, or contain viruses. The sender therefore does not accept liability for any errors or omissions in the contents of this message, which arise as a result of e-mail transmission.