Re: [Fuego] [PATCH] Docs: Convert the tbwiki pages into .rst files

Pooja,

Thanks for your continued work on this.  This patch has been applied an fixed up.

Some notes are inline below.

> -----Original Message-----
> From: Pooja <[email protected]>
> 
> Following are the files converted:
> Functional.LTP
> Functional.Linaro
> Functional.fuego_release_test
> Functional.template
> Test_Functional.arch_timer
> Test_Functional.cmt
> Test_Functional.crashme
> Test_Functional.expat
> 
> Signed-off-by: Pooja More <[email protected]>
> ---
>  docs/rst_src/Functional.Linaro.rst             | 147 +++++++++++++++++++++++++
>  docs/rst_src/Functional.fuego_release_test.rst |  71 ++++++++++++
>  docs/rst_src/Functional.template.rst           |  39 +++++++
>  docs/rst_src/Test_Functional.arch_timer.rst    |  49 +++++++++
>  docs/rst_src/Test_Functional.cmt.rst           |  49 +++++++++
>  docs/rst_src/Test_Functional.crashme.rst       |  36 ++++++
>  docs/rst_src/Test_Functional.expat.rst         |  37 +++++++

These filenames don't need to be prefixed with "Test_".  I git renamed
these for the rst_src directory.  I don't know if there are more of these
test-specific documentation files,  but if so, please remove the "Test_" prefix
during the conversion to RST format.

>  7 files changed, 428 insertions(+)
>  create mode 100644 docs/rst_src/Functional.Linaro.rst
>  create mode 100644 docs/rst_src/Functional.fuego_release_test.rst
>  create mode 100644 docs/rst_src/Functional.template.rst
>  create mode 100644 docs/rst_src/Test_Functional.arch_timer.rst
>  create mode 100644 docs/rst_src/Test_Functional.cmt.rst
>  create mode 100644 docs/rst_src/Test_Functional.crashme.rst
>  create mode 100644 docs/rst_src/Test_Functional.expat.rst
> 
> diff --git a/docs/rst_src/Functional.Linaro.rst b/docs/rst_src/Functional.Linaro.rst
> new file mode 100644
> index 0000000..05f1bab
> --- /dev/null
> +++ b/docs/rst_src/Functional.Linaro.rst
> @@ -0,0 +1,147 @@
> +#####################
> +Functional.Linaro
> +#####################
> +
> +================
> +Description
> +================
> +
> +This test can be used to run tests from the Linaro test definition
> +suite.
> +
> +As of February, 2019, the test is a proof of concept and only tested
> +with smoke tests. There are FIXTHIS lines to indicate what is left.
> +
> +=============
> +Resources
> +=============
> +
> + * `<https://github.com/Linaro/test-definitions.git>`_
> +
> +===========
> +Results
> +===========
> +
> +
> +========
> +Tags
> +========
> +
> + * first tag
> +
> +================
> +Dependencies
> +================
> +
> +==========
> +Status
> +==========
> +
> + * Experimental
> +
> +=========
> +Notes
> +=========
> +
> +Setup
> +===========
> +
> +Here are some notes on setting up for this test:
> +
> +The test definitions only support running on a board via ssh without
> +using a password.  Therefore, you must provide an SSH_KEY for the
> +board.
> +
> +
> +These instructions use the Fuego board 'bbb' as the board for this
> +s Project source on etup.
I fixed the wording here, which looks like it had some typos

> +
> +
> +Enter the docker container
> +---------------------------
> +
> + * $ fuegosh
> + * (at this point, you will be root)
> + * $ su jenkins
> +
> +SSH_KEY
> +--------------
> +
> + * If not done already, prepare ssh keys for your board
> +
> +   * $ ssh-keygen -t rsa
> +   * (change the filename to include the board name
> +     (from id_rsa to bbb_id_rsa)
> +   * The output should look something like this.
> +
> +     ::
> +
> +      Enter file in which to save the key (/var/lib/jenkins/.ssh/id_rsa): /var/lib/.ssh/bbb_id_rsa
> +      Enter passphrase (empty for no passphrase):
> +      Enter same passphrase again:
> +      Your identification has been saved in bbb_id_rsa.
> +      Your public key has been saved in bbb_id_rsa.pub.
> +      The key fingerprint is:
> +      xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx jenkins@timdesk
> +      The key's randomart image is:
> +      +---[RSA 2048]----+
> +      |.(image omitted).|
> +      +-----------------+
> +
> + * Put the ``bbb_id_rsa.pub`` file on the board, in the .ssh
> +   directory of the account used for testing.
> +
> +    * This can be done using the tool 'ssh-copy-id', as follows:
> +
> +      * $ ssh-copy-id -i bbb_id_rsa.pub [email protected]
> +        (use the correct login account and IP address)
> +      * (this will prompt for the password for the root account)
> +
> +    * You can test this by using ssh, to check that it doesn't
> +      require a password
> +
> +      * $ ssh -i bbb_id_rsa [email protected]
> +      * (you should be logged in without a request for a password)
> +
> +
> + * Install ssh key into the jenkins ssh config file
> +
> +    * (still inside the docker container, as user 'jenkins')
> +    * vi ~/.ssh/config
> +
> +       * Adjust or add a Host section
> +
> +         * Put the Host line:  Host 10.0.1.2 <- replace with your
> +           boards ip address ($IPADDR)
> +         * Put an indented line for the IdentityFile: IdentityFile ``~/.ssh/bbb_id_rsa``
> +
> +
> +When done, the config should have a section that looks like this:
> +
> +::
> +
> + Host 10.0.1.2
> +     IdentityFile ~/.ssh/bbb_id_rsa
> +
> +
> +
> +Jenkins job setup
> +-----------------------
> +
> +Now, add a job for ``Functional.linaro`` to Jenkins
> +
> +  * $ftc add-job -b bbb -t Functional.linaro
> +  * (this should create the job: ``bbb.default.Functional.linaro``)
> +
> +
> +Execute the job
> +-----------------------
> +
> + * Execute the job from jenkins, by finding the job in the Jenkins interface,
> +   and clicking on Build
> +
> +    - Expected results
> +
> +    	- Table with each test case and the results (PASS/FAIL/SKIP)
> +    	- ``run.json``
> +    	- csv

These three lines had a mixture of spaces and tabs for indentation.
I fixed this, but please check for this in the future.

> diff --git a/docs/rst_src/Functional.fuego_release_test.rst b/docs/rst_src/Functional.fuego_release_test.rst
> new file mode 100644
> index 0000000..3695a66
> --- /dev/null
> +++ b/docs/rst_src/Functional.fuego_release_test.rst
> @@ -0,0 +1,71 @@
> +##############################
> +Functional.fuego release test
> +##############################
> +
> +=============
> +Description
> +=============
> +
> +``Functional.fuego_release_test`` is a Fuego selftest, intended to be run
> +immediately before a release to test a ``Fuego/Jenkins`` integration.
> +
> +It builds a separate docker container, with jenkins running on another
> +port, and then runs tests against that other container.
> +
> +=============
> +Resources
> +=============
> +
> + * See the README for this test at:
> +   `<https://bitbucket.org/fuegotest/fuego-core/src/master/tests/Functional.fuego_release_test/README.md>`_
> +
> +
> +===========
> +Results
> +===========
> +
> +As of July 2020, this test has been broken since at least January 2019.
> +
> +
> +See `<http://fuegotest.org/wiki/Issue_0074>`_
> +
> +========
> +Tags
> +========
> +
> + * fuego
> + * selftest
> +
> +================
> +Dependencies
> +================
> +
> +
> +==========
> +Status
> +==========
> +
> + * not OK
> +
> +==========
> +Notes
> +==========
> +
> +How to run
> +================
> +
> +In order to run the test, you need to build your initial container with
> +``Dockerfile.test`` instead of Dockerfile.  Otherwise, you will not have
> +the needed components in the Fuego docker container for the test.
> +
> +
> +The following is a guess as to the correct sequence:
> +
> + * ./fuego-host-scripts/docker-build-image.sh fuego 8090 Dockerfile
> + * ./fuego-host-scripts/docker-build-image.sh fuego-test 8090 Dockerfile.test
> + * ./fuego-host-scripts/docker-create-container.sh fuego-test fuego-test-container
> + * ./start.sh fuego-test-container
> + * ftc add-node -b fuego-test
> + * ftc add-job -b fuego-test -t Functional.fuego_release_test
> + * ftc build-job fuego-test.default.Functional.fuego_release_test
> +
> diff --git a/docs/rst_src/Functional.template.rst b/docs/rst_src/Functional.template.rst
> new file mode 100644
> index 0000000..8ee8ab5
> --- /dev/null
> +++ b/docs/rst_src/Functional.template.rst
> @@ -0,0 +1,39 @@
> +
> +###################
> +Functional.template
> +###################
> +
> +
> +===============
> +Description
> +===============
> +
> +=============
> +Resources
> +=============
> +
> + * First external resource (web site, tutorial, article, etc)
> +
> +===========
> +Results
> +===========
> +
> +========
> +Tags
> +========
> +
> + * first tag
> +
> +================
> +Dependencies
> +================
> +
> +==========
> +Status
> +==========
> +
> + * OK
> +
> +========
> +Notes
> +========
> diff --git a/docs/rst_src/Test_Functional.arch_timer.rst b/docs/rst_src/Test_Functional.arch_timer.rst
> new file mode 100644
> index 0000000..4d891cb
> --- /dev/null
> +++ b/docs/rst_src/Test_Functional.arch_timer.rst
> @@ -0,0 +1,49 @@
> +############################
> +Test Functional.arch timer
> +############################
> +
> +This test appears to check that a target has an interrupt named
> +"arch_timer", and that it is running (``/proc/interrupts`` increments
> +over a 5-second period), and is assigned IRQ number 27.
> +
> +This looks like something very specific to a Renesas lager board.
> +
> +=======
> +Details
> +=======
> +
> +This test unpacks a tarball called: ``dung-3.4.25-m2.tar.gz``
> +It runs the following scripts on target:
> +
> + * ``arch_timer-interrupt-lager.s``
> + * ``dmesg-lager.sh``
> + * ``proc-interrupts-lager.sh``
> +
> +then checks that the log contains "Test passed" exactly
> +$FUNCTIONAL_ARCH_TIMER_RES_LINES_COUNT times
> +
> +This variable is not defined (would have been nice to test it earlier
> +than in test_processing).  I thought maybe the lager board file would
> +have this, but it appears not to.
> +
> +arch_timer-interrupt-lager.sh
> +===================================
> +
> +This script uses ``common/interrupt-count.sh`` to measure the number of
> +occurrences of the arch_timer interrupt over a period of 5 seconds.
> +
> +if the value is increasing, then it emits "Test passed"
> +
> +dmesg-lager.sh
> +===================
> +
> +This script uses ``common/dmesg.sh`` to search for the following
> +string: "ARM arch timer >56 bits at 10000kHz" in the dmesg output
> +
> +proc-interrupts-lager.sh
> +===============================
> +
> +This script uses ``common/proc-interrupts.sh`` to check for the
> +arch_timer interrupt, and see if it matches 27.
> +
> +If the value matches, then it emits "Test passed"
> diff --git a/docs/rst_src/Test_Functional.cmt.rst b/docs/rst_src/Test_Functional.cmt.rst
> new file mode 100644
> index 0000000..44dbc31
> --- /dev/null
> +++ b/docs/rst_src/Test_Functional.cmt.rst
> @@ -0,0 +1,49 @@
> +######################
> +Test Functional.cmt
> +######################
> +
> +This test appears to check that a target has an interrupt named
> +"sh_cmt.0", and that it is running (``/proc/interrupts`` increments over a
> +5-second period), and is assigned IRQ number 174.

I adjusted the wording here for clarity.

> +
> +This looks like something very specific to some Renesas lager board.
> +
> +===========
> +Details
> +===========
> +
> +This test unpacks a tarball called: dung-3.4.25-m2.tar.gz It runs the
> +following scripts on target:
> +
> + * ``cmt/cmt-interrupt.sh``
> + * ``cmt/dmesg.sh``
> + * ``cmt/proc-interrupts.sh``
> +
> +then checks that the log contains "Test passed" exactly
> +$FUNCTIONAL_CMT_LINES_COUNT times
> +
> +This variable is not defined (would have been nice to test it earlier
> +than in test_processing).  I thought maybe another board file would
> +have this, but it appears not to.
> +
> +cmt/cmt-interrupt.sh
> +=========================
> +
> +This script uses ``common/interrupt-count.sh`` to measure the number of
> +occurrences of the 'sh_cmt.0' interrupt over a period of 5 seconds.
> +
> +If the value is increasing, then it emits "Test passed"
> +
> +cmt/dmesg.sh
> +=================
> +
> +This script uses ``common/dmesg.sh`` to search for the following string:
> +"sh_cmt sh_cmt.0: used for clock events" in the dmesg output
> +
> +cmt/proc-interrupts.sh
> +=============================
> +
> +This script uses ``common/proc-interrupts.sh`` to check for the 'sh_cmt.0'
> +interrupt, and see if it matches 174.
> +
> +If the value matches, then it emits "Test passed"
> diff --git a/docs/rst_src/Test_Functional.crashme.rst b/docs/rst_src/Test_Functional.crashme.rst
> new file mode 100644
> index 0000000..900500a
> --- /dev/null
> +++ b/docs/rst_src/Test_Functional.crashme.rst
> @@ -0,0 +1,36 @@
> +#########################
> +Test Functional.crashme
> +#########################
> +
> +This test runs the crashme program.
> +
> +You can find information about crashme here:
> +`<http://www.linuxcertif.com/man/1/crashme/>`_
> +
> +crashme creates some random data, and tries to execute it to see if
> +the system or environment will crash.
> +
> +============
> +Details
> +============
> +
> +This test unpacks a tarball called: crashme_2.4.tar.bz2 and deploys a
> +single binary file (crashme) to the target.
> +
> +The test spec for this defines the following variables:
> +
> + * NBYTES: 1000
> + * INC: 1000
> + * SRAND: 2
> + * NTRYS: 100
> + * NSUB: 3000
> +
> +These are passed to crashme as follows:
> +
> + * crashme NBYTES.INC SRAND NTRYS NSUB 2
> +
> +The final 2 in the command line is the verbosity level.
> +
> +The tests checks for the string "0 ...  3000" occuring once in the log
> +output.
> +
> diff --git a/docs/rst_src/Test_Functional.expat.rst b/docs/rst_src/Test_Functional.expat.rst
> new file mode 100644
> index 0000000..a834815
> --- /dev/null
> +++ b/docs/rst_src/Test_Functional.expat.rst
> @@ -0,0 +1,37 @@
> +######################
> +Test Functional.expat
> +######################
> +
> +This test conducts a test of XML processing performed by the
> +libexpat.so library.  Specifically, it runs the xmlts (XML Test Suite)
> +to test the library.
> +
> +You can find information about crashme here:
> +`<http://www.linuxcertif.com/man/1/crashme/>`_
> +
> +crashme creates some random data, and tries to execute it to see if
> +the system or environment will crash.

I removed these two paragraphs, which look like a copy-paste
bug from the original file.

> +
> +============
> +Details
> +============
> +
> +This test unpacks a tarball called: expat-2.0.0.tar.gz and applies a
> +patch ``xmltest.sh.patch``, which adds pass/fail strings to the test
> +results.
> +
> +The build phase also untars and build the xml test suite (from
> +xmlts20080827.tar.gz)
> +
> +For the deploy phase, the test suite is tarred up, put on the target,
> +and extracted there.  Also the file xmlwf is put on the target.
> +
> +For the actual test, a program called 'runtestspp is run, as well a
> +program called ``xmltest.sh``.
> +
> +
> +The test_processing phase checks for ``EXPAT_SUBTEST_COUNT_POS`` and
> +``EXPAT_SUBTEST_COUNT_NEG``.  The positive test looks for the string
> +"100%%: Checks: 48|passed".  (This is a bit of a weird string to check
> +for multiple times.)
> +
> --
> 2.7.4
> 

Thanks.  These changes have been pushed to master.

 -- Tim