Re: [Fuego] [PATCH] Docs: .rst files for user interface and test API reference.

Sorry I missed this e-mail earlier I the week.

> From: Pooja More

> 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]> <mailto:[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``
Was this automatically converted?  This belongs with the JOB_NAME definition,
and not on its own.

> +
> +``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)::

Good call putting this in a colored offset block!  Thanks.

> +
> + 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:
Should be _fuego_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.
> +
``FUEGO_DEBUG``

> +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

Good call putting this fixthis a colored block offset.

> +
> +See also :ref:`Core interfaces <core_interfaces>`
> +
> +==
> +A
> +==
> +
> + * ``ARCHITECTURE:`` the processor architecture of the target board

Colons should be outside the verbatim quote.  They are not part of
the variable name.  True throughout file.

> +
> + * 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

For the "Sample" bullet item, I decided to change the name
to "Example value:", as I think that's clearer.  Also, instead of
using verbatim quotes to refer to items as actual entities, I
switched to bold quoting.  These are means as example strings
not as actual item references.  I did this throughout.


> +
> + * ``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

Looks good.  This patch has been committed, and I did some content
fixup patches on top.  Some of the information was out of date, and
I made some changes to bring it up-to-date.

Thanks,
 -- Tim