diff --git a/.gitignore b/.gitignore index e86bc51e47..ed594580ad 100644 --- a/.gitignore +++ b/.gitignore @@ -1,12 +1,14 @@ *~ .* *.pyc +__pycache__ +*.egg-info /results* -*.json *.log /tools/android-sdk-linux -/ipynb/*.pid -/ipynb/server.url +*.pid +server.url /vagrant -/tools/wa_venv /tools/wa_user_directory/dependencies +/src/buildroot +_build diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 44946b19cf..0000000000 --- a/.gitmodules +++ /dev/null @@ -1,15 +0,0 @@ -[submodule "libs/devlib"] - path = libs/devlib - url = https://github.com/ARM-Software/devlib.git -[submodule "libs/trappy"] - path = libs/trappy - url = https://github.com/ARM-Software/trappy.git -[submodule "libs/bart"] - path = libs/bart - url = https://github.com/ARM-Software/bart.git -[submodule "wiki"] - path = wiki - url = https://github.com/ARM-Software/lisa.wiki.git -[submodule "tools/workload-automation"] - path = tools/workload-automation - url = https://github.com/ARM-software/workload-automation.git diff --git a/.travis.yml b/.travis.yml index 7da785246b..792ae8f17f 100644 --- a/.travis.yml +++ b/.travis.yml @@ -15,16 +15,23 @@ # limitations under the License. # +git: + # make sure we have all relevant commits for subtree modif detection + depth: 1000 + sudo: required -language: python +# Use "generic" language to avoid having a virtualenv created for Python by default +language: generic + +# Ubuntu Xenial 16.04 (latest version we can have on Travis) +# https://docs.travis-ci.com/user/reference/overview/ +dist: xenial + install: - - pip install --upgrade trappy bart-py devlib psutil wrapt matplotlib - future jupyter sphinx + - cd "$TRAVIS_BUILD_DIR" + - sudo ./install_base_ubuntu.sh --install-doc-extras + - echo "$(python3 --version)" + script: - - cd $TRAVIS_BUILD_DIR - - 'echo backend : Agg > matplotlibrc' # Otherwise it tries to use tkinter - - export PATH=$TRAVIS_BUILD_DIR/tools/x86_64/:$PATH # For trace-cmd - - source init_env && lisa-test tests/lisa/ - # -W is like -Werror. - # Ideally we should use -n too, which is like -Wall, but we have too many errors for that. - - cd doc/ && sphinx-build -W -b html . _build/html + - cd "$TRAVIS_BUILD_DIR" + - bash ./tools/scripts/travis_tests.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..11b202be9f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,66 @@ +# Contributing to LISA + +First of all, if you're reading this, thanks for thinking about contributing! +This project is maintained by us Arm folks, but we welcome contributions from +anyone. + +## How to reach us + +If you're hitting an error/bug and need help, it's best to raise an issue on github. + +## Coding style + +As a rule of thumb, the code you write should follow the +[PEP-8](https://www.python.org/dev/peps/pep-0008/). + +We strongly recommend using a code checker such as [pylint](https://www.pylint.org/), +as it tracks unused imports/variables, informs you when you can simplify a +statement using Python features, and overall just helps you write better code. + +## Documentation + +Docstring documentation should follow the ReST/Sphinx style. +Classes, class attributes and public methods must be documented. If deemed +necessary, private methods can be documented as well. + +All in all, it should look like this: + +```python +def foo(a, b): + """ + A one liner description + + :param a: A description for param a + :type a: int + + :param b: A description for param b + :type b: str + + Whatever extra description you might over as many lines as you need + (but be reasonable) + """ + pass +``` + +## Tests + +You should strive to validate as much of your code as possible through self-tests. +It’s a nice way to showcase that your code works, and also how it works. On top +of that, it makes sure that later changes won’t break it. + +Have a look at [the doc](https://lisa-linux-integrated-system-analysis.readthedocs.io/en/next/lisa_tests.html) for more info on LISA self-tests. + +## Commits + +As for the shape of the commit, nothing out of the ordinary: just follow the +good old 50/72 rule (it's okay if you bite off a few extra chars). + +The header should highlight the impacted files/classes. The 'lisa' prefix can be omitted - for instance, +if you're modifying the `lisa/wlgen/rta.py` file, we'd expect a header of the shape `wlgen/rta: ...`. + +When that path gets a bit verbose, it's alright to shorten it as long as there +is no confusion as to what you're referencing. In that case, if modifying the +`lisa/tests/kernel/scheduler/load_tracking.py` file, we'd expect a header of +the shape `tests: load_tracking: ...`. + +When in doubt, have a look at the git log. diff --git a/LisaShell.txt b/LisaShell.txt deleted file mode 100644 index 1eb9fa538d..0000000000 --- a/LisaShell.txt +++ /dev/null @@ -1,33 +0,0 @@ - -All LISA Shell commands start with "lisa-", thus using shell completion it is -easy to get a list of all the available commands. - -Here is a list of the main ones, with a short description. -For a longer description type "lisa- help" - -.:: Generic commands --------------------- - -lisa-help - Print this help, or command specific helps -lisa-version - Dump info on the LISA in use - -.:: Maintenance commands ------------------------- - -lisa-update - Update submodules and LISA notebooks/tests - -.:: Notebooks commands ----------------------- - -lisa-ipython - Start/Stop the IPython Notebook server - -.:: Results analysis and Documentation --------------------------------------- - -lisa-report - Pretty format results of last test - -.:: Test commands --------------------------------------- - -lisa-test - Run tests and assert behaviours - diff --git a/README.md b/README.md index 39ac25930a..1c78671040 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,3 @@ -# A word about the future - -A revamped and streamlined version of LISA is available under the 'next' branch -(https://github.com/ARM-software/lisa/tree/next). Active development is moving -towards that branch, so while we'll accept small fixes to LISA/master until we feel -confident it is time to flip the switch, any other kind of pull requests should be -sent against LISA/next. - -In short, this what you should expect to see: -* Complete redo of our test classes (LisaTest & Executor) -* Various clean ups of LISA internals (e.g. TestEnv) -* Migration to Python3 -* Documentation overhaul (as in, not just bare docstrings) - # Introduction The LISA project provides a toolkit that supports regression testing and @@ -48,7 +34,7 @@ There are two "entry points" for running LISA: automated pass/fail regression tests for kernel behaviour. The [BART](https://github.com/ARM-software/trappy) toolkit provides additional domain-specific test assertions for this use-case. LISA provides some - ready-made automated tests under the `tests/` directory. + ready-made automated tests under the `lisa/tests/` directory. # Motivations @@ -66,13 +52,13 @@ The main goals of LISA are: * **enables** kernel developers to easily post process data to produce statistics and plots -# Documentation - -* [Wiki Home page](https://github.com/ARM-software/lisa/wiki) -* [Installation](https://github.com/ARM-software/lisa/wiki/Installation) -* [Quickstart Tutorial](https://github.com/ARM-software/lisa/wiki/Quickstart-tutorial) +# Documentation [![Documentation Status](https://readthedocs.org/projects/lisa-linux-integrated-system-analysis/badge/?version=next)](https://lisa-linux-integrated-system-analysis.readthedocs.io/en/next/?badge=next) -* [API Documentation](http://lisa-linux-integrated-system-analysis.readthedocs.io/en/latest/) +You should find everything on [ReadTheDocs](https://lisa-linux-integrated-system-analysis.readthedocs.io/en/next/). +Here are some noteworthy sections: +* [Installation](https://lisa-linux-integrated-system-analysis.readthedocs.io/en/next/users_guide.html#installation) +* [Self-tests](https://lisa-linux-integrated-system-analysis.readthedocs.io/en/next/lisa_tests.html) +* [Kernel tests](https://lisa-linux-integrated-system-analysis.readthedocs.io/en/next/kernel_tests.html) # External Links * Linux Integrated System Analysis (LISA) & Friends diff --git a/Vagrantfile b/Vagrantfile index 619650c8ce..a5061cbc75 100644 --- a/Vagrantfile +++ b/Vagrantfile @@ -3,7 +3,7 @@ Vagrant.configure(2) do |config| - config.vm.box = "ubuntu/trusty64" + config.vm.box = "ubuntu/bionic64" # Compiling pandas requires 1Gb of memory config.vm.provider "virtualbox" do |v| @@ -21,18 +21,28 @@ Vagrant.configure(2) do |config| fi cd /home/vagrant/lisa + # Install required packages ./install_base_ubuntu.sh --install-android-sdk - chown vagrant.vagrant /home/vagrant/lisa - echo cd /home/vagrant/lisa >> /home/vagrant/.bashrc + chown -R vagrant.vagrant /home/vagrant/lisa + + # Let' use a venv local to vagrant so that we don't pollute the host one. + # This allows to use LISA both from the host and the VM. + export LISA_VENV_PATH=/home/vagrant/venv + + # .bashrc setup + echo "cd /home/vagrant/lisa" >> /home/vagrant/.bashrc for LC in $(locale | cut -d= -f1); do echo unset $LC >> /home/vagrant/.bashrc done - echo "export ANDROID_HOME=/vagrant/tools/android-sdk-linux" >> /home/vagrant/.bashrc - echo 'export PATH=\$ANDROID_HOME/platform-tools:\$ANDROID_HOME/tools:\$PATH' >> /home/vagrant/.bashrc - echo source init_env >> /home/vagrant/.bashrc + echo 'export LISA_VENV_PATH=$LISA_VENV_PATH' >> /home/vagrant/.bashrc + echo 'source init_env' >> /home/vagrant/.bashrc + + # Trigger the creation of a venv + su vagrant bash -c 'source ./init_env' + # We're all done! echo "Virtual Machine Installation completed successfully! " echo " " echo "You can now access and use the virtual machine by running: " @@ -44,5 +54,20 @@ Vagrant.configure(2) do |config| echo " " echo " $ vagrant suspend " echo " " + echo " To destroy it, use: " + echo " " + echo " $ vagrant destroy " + echo " " SHELL + + # TODO: Run self tests to explode sooner rather than later + # config.trigger.after :up do |trigger| + # trigger.info = "Verifying LISA installation" + # trigger.name = "LISA install verification" + # trigger.run_remote = {inline: " + # cd /home/vagrant/lisa + # source init_env + # python3 -m nose + # "} + # end end diff --git a/devmode_requirements.txt b/devmode_requirements.txt new file mode 100644 index 0000000000..647fd5d898 --- /dev/null +++ b/devmode_requirements.txt @@ -0,0 +1,18 @@ +# Must be ordered to satisfy the dependencies without pulling from PyPI. +# Once they are found by pip in editable mode as specified here, they will be +# used and not looked up on PyPI. +-e ./tools/exekall + +# devlib before WA and LISA +-e ./external/devlib/ + +# TRAPpy before BART and LISA +-e ./external/trappy/ +# BART before LISA +-e ./external/bart/ + +# WA before LISA +-e ./external/workload-automation/ +-e ./[notebook,doc,test] + +-e ./tools/bisector[dbus] diff --git a/doc/.gitignore b/doc/.gitignore deleted file mode 100644 index 88f9974bd7..0000000000 --- a/doc/.gitignore +++ /dev/null @@ -1 +0,0 @@ -_build/* diff --git a/doc/Makefile b/doc/Makefile index 7ab1b0ff73..8b64b1e99e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,177 +1,19 @@ -# Makefile for Sphinx documentation +# Minimal makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = +SPHINXBUILD = python3 -m sphinx +SOURCEDIR = . BUILDDIR = _build -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - +# Put it first so that "make" without argument is like "make help". help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/LISA.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/LISA.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/LISA" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/LISA" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." +.PHONY: help Makefile -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/api_separator.rst b/doc/api_separator.rst new file mode 100644 index 0000000000..21bf988654 --- /dev/null +++ b/doc/api_separator.rst @@ -0,0 +1,3 @@ +*************************** +==== API documentation ==== +*************************** diff --git a/doc/bisector b/doc/bisector new file mode 120000 index 0000000000..463efb3266 --- /dev/null +++ b/doc/bisector @@ -0,0 +1 @@ +../tools/bisector/doc \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index a5a97ed2fb..a12c301d8c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -17,15 +17,70 @@ import re import subprocess import sys - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) -lisa_home = os.path.join(os.path.dirname(os.path.abspath(__file__)), '..') -sys.path.insert(0, lisa_home) -for lib in ['utils', 'wlgen', 'trappy', 'bart', 'devlib']: - sys.path.insert(0, os.path.join(lisa_home, 'libs', lib)) +import unittest + +from docutils import nodes +from sphinx.util.docfields import TypedField +from sphinx import addnodes + +# This shouldn't be needed, as using a virtualenv + setup.py should set up the +# sys.path correctly. However that seems to be half broken on ReadTheDocs, so +# manually set it here +sys.path.insert(0, os.path.abspath('../')) + +# Import our packages after modifying sys.path +import lisa +from lisa.doc.helpers import ( + autodoc_process_test_method, autodoc_process_analysis_events +) + +# This ugly hack is required because by default TestCase.__module__ is +# equal to 'case', so sphinx replaces all of our TestCase uses to +# unittest.case.TestCase, which doesn't exist in the doc. +for name, obj in vars(unittest).items(): + try: + m = obj.__module__ + obj.__module__ = 'unittest' if m == 'unittest.case' else m + except Exception: pass + +# This is a hack to prevent :ivar: docs from attempting to create a reference +# Credit goes to https://stackoverflow.com/a/41184353/5096023 +def patched_make_field(self, types, domain, items, env=None): + # type: (List, unicode, Tuple) -> nodes.field + def handle_item(fieldarg, content): + par = nodes.paragraph() + par += addnodes.literal_strong('', fieldarg) # Patch: this line added + #par.extend(self.make_xrefs(self.rolename, domain, fieldarg, + # addnodes.literal_strong)) + if fieldarg in types: + par += nodes.Text(' (') + # NOTE: using .pop() here to prevent a single type node to be + # inserted twice into the doctree, which leads to + # inconsistencies later when references are resolved + fieldtype = types.pop(fieldarg) + if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text): + typename = u''.join(n.astext() for n in fieldtype) + par.extend(self.make_xrefs(self.typerolename, domain, typename, + addnodes.literal_emphasis)) + else: + par += fieldtype + par += nodes.Text(')') + par += nodes.Text(' -- ') + par += content + return par + + fieldname = nodes.field_name('', self.label) + if len(items) == 1 and self.can_collapse: + fieldarg, content = items[0] + bodynode = handle_item(fieldarg, content) + else: + bodynode = self.list_type() + for fieldarg, content in items: + bodynode += nodes.list_item('', handle_item(fieldarg, content)) + fieldbody = nodes.field_body('', bodynode) + return nodes.field('', fieldname, fieldbody) + +TypedField.make_field = patched_make_field # -- General configuration ------------------------------------------------ @@ -43,6 +98,8 @@ 'sphinx.ext.coverage', 'sphinx.ext.imgmath', 'sphinx.ext.viewcode', + 'sphinx.ext.inheritance_diagram', + 'sphinxcontrib.plantuml', ] # Add any paths that contain templates here, relative to this directory. @@ -65,15 +122,16 @@ # |version| and |release|, also used in various other places throughout the # built documents. # - try: git_description = subprocess.check_output( ['git', 'describe', '--tags', '--match=v??.??']) version = re.match('v([0-9][0-9]\.[0-9][0-9]).*', git_description).group(1) - release = version except Exception as e: - logging.error("Couldn't set project version from git: {}".format(e)) - version = release = 'UNKNOWN_VERSION' + logging.info("Couldn't set project version from git: {}".format(e)) + version = lisa.__version__ + +version = str(version) +release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -118,7 +176,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -272,9 +330,17 @@ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} +intersphinx_mapping = { + 'python' : ('https://docs.python.org/3', None), + 'pandas' : ('https://pandas.pydata.org/pandas-docs/stable/', None), + 'matplotlib' : ('https://matplotlib.org', None), + 'numpy': ('http://docs.scipy.org/doc/numpy', None), + # XXX: Doesn't seem to work, might be due to how devlib doc is generated + 'wa' : ('https://devlib.readthedocs.io/en/latest/', None), + 'trappy' : ('https://pythonhosted.org/TRAPpy', None), + 'bart' : ('https://pythonhosted.org/bart-py/', None), + 'wa' : ('https://workload-automation.readthedocs.io/en/latest/', None), +} # # Fix autodoc @@ -283,7 +349,16 @@ # Include __init__ docstrings (obviously) autoclass_content = 'both' -autodoc_default_flags = [ - 'show-inheritance', # Show parent class - 'undoc-members', # Show members even if they don't have docstrings -] +autodoc_member_order = 'bysource' + +autodoc_default_options = { + 'show-inheritance' : '', # Show parent class + 'undoc-members' : '', # Show members even if they don't have docstrings +} +autodoc_inherit_docstrings = True + +def setup(app): + app.connect('autodoc-process-docstring', autodoc_process_test_method) + app.connect('autodoc-process-docstring', autodoc_process_analysis_events) + +# vim :set tabstop=4 shiftwidth=4 textwidth=80 expandtab: diff --git a/doc/contributors_guide.rst b/doc/contributors_guide.rst new file mode 100644 index 0000000000..53774fd999 --- /dev/null +++ b/doc/contributors_guide.rst @@ -0,0 +1,101 @@ +******************* +Contributor's guide +******************* + +Contribution rules +================== + +See `this document `__. + +Subtrees +======== + +are available as subtrees under ``$repo/external``. + +Updating the subtrees ++++++++++++++++++++++ + +If you got a Pull Request merged in e.g. :mod:`devlib` and want to use some of +the features you introduced in LISA, you'll need to update the subtrees. There is +a handy LISA shell command available for that: + + >>> lisa-update-subtrees + +This will update every subtree in the repository with the right incantation, and +the result can be pushed straight away to LISA as a Pull Request (or included in +a broader Pull Request). + +Submitting your subtree changes ++++++++++++++++++++++++++++++++ + +Our changes to subtrees are often developped conjointly with LISA, so we write our +modifications directly in the subtrees. You can commit these changes in the LISA +repository, then shape those modifications into a git history ready to be pushed +using ``git subtree split``. Assuming you want to split a devlib change and have +a devlib remote set up in your repository, you'd have to issue the following:: + + # Ensure refs are up to date + git fetch devlib + # Do the split + git subtree split --prefix=external/devlib -b my-devlib-feature + +This will give you a ``my-devlib-feature`` branch ready to be pushed. To make +things easier, we recommend setting up a remote to your devlib fork:: + + git remote add devlib-me git@github.com:me/devlib.git + +You can then push this branch to your devlib fork like so:: + + git push -u devlib-me my-devlib-feature + +Validating your changes +======================= + +To ensure everything behaves as expected at all times, LISA comes with some +self-tests, which is a mix of unit and behavioural tests. + +From the root of LISA, you can run those tests like so: + +>>> python3 -m nose +>>> # You can also target specific test modules +>>> python3 -m nose tests/test_test_bundle.py +>>> # Or even specific test classes +>>> python3 -m nose tests/test_test_bundle.py:BundleCheck + +Writing self-tests +++++++++++++++++++ + +You should strive to validate as much of your code as possible through +self-tests. It's a nice way to showcase that your code works, and also how it +works. On top of that, it makes sure that later changes won't break it. + +It's possible to write tests that require a live target - see +:meth:`~tests.utils.create_local_target`. However, as these tests +are meant to be run by Travis as part of our pull-request validation, they have +to be designed to work on a target with limited privilege. + +API ++++ + +Utilities +--------- + +.. automodule:: tests.utils + :members: + +Implemented tests +----------------- + +.. TODO:: Make those imports more generic + +.. automodule:: tests.test_test_bundle + :members: + +.. automodule:: tests.test_energy_model + :members: + +.. automodule:: tests.test_trace + :members: + +.. automodule:: tests.test_wlgen_rtapp + :members: diff --git a/doc/doc_requirements.txt b/doc/doc_requirements.txt new file mode 100644 index 0000000000..a93872b8ff --- /dev/null +++ b/doc/doc_requirements.txt @@ -0,0 +1,16 @@ +# A streamlined version of devmode_requirements.txt for doc building +-e ./tools/exekall + +# devlib before WA and LISA +-e ./external/devlib/ + +# TRAPpy before BART and LISA +-e ./external/trappy/ +# BART before LISA +-e ./external/bart/ + +# WA before LISA +-e ./external/workload-automation/ +-e ./[doc] + +-e ./tools/bisector diff --git a/doc/energy_analysis.rst b/doc/energy_analysis.rst new file mode 100644 index 0000000000..e4bfbb6b0b --- /dev/null +++ b/doc/energy_analysis.rst @@ -0,0 +1,218 @@ +*************** +Energy analysis +*************** + +Introduction +============ + +As part of the `EAS +`_ +development efforts, support for CPU energy models and energy probes was added +to LISA. + +Energy model +============ + +The :class:`~lisa.energy_model.EnergyModel` class mimics the energy model used +by EAS, and lets us do some energy analysis. + +.. tip:: + + An :class:`~lisa.energy_model.EnergyModel` instance can be generated from a + live target using :meth:`~lisa.energy_model.EnergyModel.from_target`, + providing this target does have an energy model. + +Its most noteworthy use is in our :meth:`EAS behavioural tests +`, as it lets us +estimate the amount of energy consumed in an execution trace and compare this +to an estimated energy-optimal placement. + +.. seealso:: See :class:`~lisa.energy_model.EnergyModel` for more details. + +Energy meters +============= + +All energy meters inherit from :class:`lisa.energy_meter.EnergyMeter`, and most +of them use one of devlib's :mod:`devlib.instrument` under the hood. + +.. seealso:: See :class:`~lisa.energy_meter.EnergyMeter` for more details. + +HWMON ++++++ + +The ``hwmon`` is a generic Linux kernel subsystem, providing access to hardware +monitoring components like temperature or voltage/current sensors. + +.. TODO:: code snippet + +Arm Energy probe (AEP) +++++++++++++++++++++++ + +ARM Energy Probes are lightweight power measurement tools for software +developers. They can monitor up to three voltage rails simultaneously. + +.. seealso:: Its related class is :class:`~lisa.energy_meter.AEP`. + +Equipment +--------- + +The required equipment is the following: + +* An ARM Energy Probe +* A shunt resistor to be connected between the voltage rail and the probe. The voltage drop + on the resistor must be at most 165 mv. Therefore depending on the maximum current required + by the load, one can properly select the value of the shunt resistor +* Install ``caiman`` required libraries: + + .. code-block:: sh + + sudo apt-get install libudev-dev + +* Clone, compile and install the `caiman `_ tool. + + .. code-block:: sh + + git clone https://github.com/ARM-software/caiman.git + cd caiman/caiman && cmake . && make && cd - + cp caiman/caiman /usr/bin + +.. image:: https://developer.arm.com/-/media/developer/products/software-tools/ds-5-development-studio/images/ARM%20Energy%20Probe/ARM_Energy_Probe_4.png?h=378&w=416&hash=90D98087E80D9178CCC28026C1C8E476A6736D09&hash=90D98087E80D9178CCC28026C1C8E476A6736D09&la=en + :alt: Arm Energy Probe + +Baylibre ACME cape +++++++++++++++++++ + +The ``iiocapture`` instrument exploits the `BayLibre ACME +`_ solution for measuring power. + +To use this instrument you need the following hardware: + +* A `BeagleBone Black `_ +* An `ACME Cape `_ +* Power probes for the ACME Cape + +.. seealso:: Its related class is :class:`~lisa.energy_meter.ACME`. + +Setting up the board +-------------------- + +First step is to get an **IIO version** of the ACME BeagleBone black image. The +recommended way of using ACME is to use the `pre-built image +`_ +provided by BayLibre. + +If you are using a MicroSD card, please ensure that the card is properly +inserted in its slot and to keep pressed the power push-button while connecting +the power (via the miniUSB cable). Here is an image of the configuration we +usually use: + +.. image:: images/ACMECapeBoardConfiguration.png + +To change the IP address and avoid a buggy route to a /8 to be added on your host, +change the address of the board in ``/usr/bin/acme-usbgadget-udhcpd``: + +.. code-block:: sh + + # Use an address that does not clash with your existing networks + #ifconfig usb0 up 10.65.34.1 netmask 255.255.255.0 + ifconfig usb0 up 192.168.50.1 netmask 255.255.255.0 + +Fix the DHCP server config on the ACME board to advertise a small subnet instead +of a whole /8: + +.. code-block:: sh + + #start 10.65.34.20 #default: 192.168.0.20 + #end 10.65.34.254 #default: 192.168.0.254 + + # Advertise a /24 subnet which contains both the + #allocated addresses and the address of the board itself + option subnet 255.255.255.0 + start 192.168.50.20 + end 192.168.50.254 + +Once the board is booted, by default it has its IP address associated with the +``baylibre-acme.local`` hostname. To check for the board being visible in your +network, you can use this command + +.. code-block:: sh + + avahi-browse -a + +which will list all the reachable devices. + +If you do not want to use avahi, you can refer to it by the static IP of the +ethernet-over-USB interface. That has the added benefit of not using the board +of somebody else, since that IP is on the USB interface which can only be +accessed from your local machine. + +Setting up iio-capture +---------------------- + +Install the ``iio-capture`` tool required libraries: + +* If ``libiio-*`` is available from the repositories in your ``apt-get``, then run + ``sudo apt-get install libiio-utils libiio-dev`` +* Otherwise, follow the instructions on the `libiio + wiki `_ + on how to build it +* Clone, compile and install the `iio-capture tool `_ + +.. code-block:: sh + + git clone https://github.com/BayLibre/iio-capture.git + cd iio-capture && make && sudo make install && cd - + +You can now verify your installation and check that the probes are correctly +detected by the ``iio daemon`` running on the BeagleBone with a simple command: + +.. code-block:: sh + + iio_info -n baylibre-acme.local + +If you have any issues, for example if ``iio_info`` hangs, or ``iio-capture`` +reports "Unsupported write attribute 'in_oversampling_ratio'", try rebooting the +ACME by SSH: + +.. code-block:: sh + + # (replace baylibre-acme.local if you changed the hostname) + ssh root@baylibre-acme.local reboot + +Monsoon Power Monitor ++++++++++++++++++++++ + +The ``Monsoon`` energy meter allows collecting data from Monsoon Solutions Inc's +Power Monitor. + +.. seealso:: Its related class is :class:`~lisa.energy_meter.Monsoon`. + +Setup +----- + +This meter depends on the monsoon.py script from AOSP. To set this up, download +that script from `here +`_ +and run ``pip install gflags pyserial``. + +The Power Monitor acts as a power supply as well as an energy meter. LISA +doesn't currently automate setting this up. You'll need to manually run these +commands: + + +API +=== + +Energy model +++++++++++++ + +.. automodule:: lisa.energy_model + :members: + :private-members: _CpuTree + +Energy meters ++++++++++++++ + +.. automodule:: lisa.energy_meter + :members: + :private-members: _DevlibContinuousEnergyMeter diff --git a/doc/exekall b/doc/exekall new file mode 120000 index 0000000000..aa5ea274a9 --- /dev/null +++ b/doc/exekall @@ -0,0 +1 @@ +../tools/exekall/doc/ \ No newline at end of file diff --git a/doc/first_separator.rst b/doc/first_separator.rst new file mode 100644 index 0000000000..d31ac61e74 --- /dev/null +++ b/doc/first_separator.rst @@ -0,0 +1,3 @@ +************************* +==== Getting started ==== +************************* diff --git a/doc/guides_separator.rst b/doc/guides_separator.rst new file mode 100644 index 0000000000..07d8627f95 --- /dev/null +++ b/doc/guides_separator.rst @@ -0,0 +1,3 @@ +**************************** +==== Guides & workflows ==== +**************************** diff --git a/doc/images/ACMECapeBoardConfiguration.png b/doc/images/ACMECapeBoardConfiguration.png new file mode 100644 index 0000000000..7a41cea620 Binary files /dev/null and b/doc/images/ACMECapeBoardConfiguration.png differ diff --git a/doc/images/overview.png b/doc/images/overview.png new file mode 100644 index 0000000000..5ab1351488 Binary files /dev/null and b/doc/images/overview.png differ diff --git a/doc/index.rst b/doc/index.rst index dfe64133ce..e91145c43e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,36 +4,52 @@ contain the root `toctree` directive. LISA API Documentation -============================================== +====================== LISA - "Linux Integrated System Analysis" is a toolkit for interactive analysis -and automated regression testing of Linux kernel behaviour. To get started with LISA: +and automated regression testing of Linux kernel behaviour. - See the README on the project's `Github home page`__ for an overview. -- Check out the project's `Github Wiki`__ for some guides to installation - and setup. - Once you have LISA running, take a look at the tutorial and example notebooks included with the installation. __ https://github.com/ARM-software/lisa -__ https://github.com/ARM-software/lisa/wiki -This site contains documentation for LISA's APIs. For some parts of LISA, API -documentation is a work-in-progress. Where the API documentation is lacking, see -the example/tutorial notebooks provided with LISA, or just dive in and read the -code. Contributions to LISA and its documentation are very welcome, and handled +Contributions to LISA and its documentation are very welcome, and handled via Github pull requests. .. _Readme: Contents: -.. TODO: due to our slightly weird package structure the index here is wildly - nested where it needn't be. - .. toctree:: + :maxdepth: 2 + + first_separator + + overview + setup + lisa_shell + + guides_separator + + transition_guide + contributors_guide + workflows/index + + api_separator + + target + workloads + kernel_tests + trace_analysis + energy_analysis + misc_utilities + + tools_separator - modules + bisector/index + exekall/index Indices and tables ================== @@ -46,5 +62,5 @@ Indices and tables Building this documentation ============================== - Install ``sphinx-doc`` -- From the root of the LISA source tree: ``source init_env && make -C doc/ html`` +- From the root of the LISA source tree: ``cd doc && make html`` - Find the HTML in ``doc/_build/html`` diff --git a/doc/kernel_tests.rst b/doc/kernel_tests.rst new file mode 100644 index 0000000000..c5f659ff32 --- /dev/null +++ b/doc/kernel_tests.rst @@ -0,0 +1,267 @@ +.. _kernel-testing-page: + +************** +Kernel testing +************** + +Introduction +============ + +The LISA kernel tests are mostly meant for regression testing, or for supporting +new submissions to LKML. The existing infrastructure can also be used to hack up +workloads that would allow you to poke specific areas of the kernel. + +Tests do not **have** to target Arm platforms nor the task scheduler. The only +real requirement is to be able to abstract your target through +:mod:`devlib`, and from there you are free to implement tests as you see fit. + +They are commonly split into two steps: + 1) Collect some data by doing work on the target + 2) Post-process the collected data + +In our case, the data usually consists of +`Ftrace `_ traces +that we then postprocess using :mod:`trappy` + +.. seealso:: :ref:`analysis-page` + +Available tests +=============== + +The following tests are available. They can be used as: + + * direct execution using ``lisa-test`` command (``LISA shell``) and ``exekall`` + (see :ref:`automated-testing-page`) + * the individual classes/methods they are composed of can be used in custom + scripts/jupyter notebooks (see ipynb/tests/synthetics_example.ipynb) + +.. run-command:: + :capture-stderr: + + exekall run $LISA_HOME/lisa/tests --rst-list --inject-empty-target-conf + +Running tests +============= + +From the CLI +++++++++++++ + +The shortest path to executing a test from a shell is: + +1. Update the ``target_conf.yml`` file located at the root of the repository + with the credentials to connect to the development board (see + :class:`~lisa.target.TargetConf` keys for more information) +2. Run the following: + + .. code-block:: sh + + # To run all tests + lisa-test + # To list available tests + lisa-test --list + # To run a test matching a pattern + lisa-test '*test_task_placement' + +More advanced workflows are described at :ref:`automated-testing-page`. + +From a python environment ++++++++++++++++++++++++++ + +See the usage example of :class:`~lisa.tests.base.TestBundle` + +Writing tests +============= + +Concepts +++++++++ + +Writing scheduler tests can be difficult, especially when you're +trying to make them work without relying on custom tracepoints (which is +what you should aim for). Sometimes, a good chunk of the test code will be +about trying to get the target in an expected initial state, or preventing some +undesired mechanic from barging in. That's why we rely on the freezer cgroup to +reduce the amount of noise introduced by the userspace, but it's not solving all +of the issues. As such, your tests should be designed to: + +a. minimize the amount of non test-related noise (e.g. freezer) +b. withstand events we can't control (use error margins, averages...) + +Where to start +++++++++++++++ + +The main class of the kernel tests is :class:`~lisa.tests.base.TestBundle`. +Have a look at its documentation for implementation and usage examples. + +.. tip:: + + A simple test implementation worth looking at is + :class:`~lisa.tests.scheduler.sanity.CapacitySanity`. + +The relationship between the test classes has been condensed into this diagram, +although you'll find more details in the API documentation of these classes. + +.. uml:: + + class TestMetric { + + data + + units + } + + + note bottom of TestMetric { + TestMetrics serve to answer + "Why did my test fail/pass ?". + They are free-form, so they can be + error counts, durations, stats... + } + + class Result { + PASSED + FAILED + UNDECIDED + } + + class ResultBundle { + + result : Result + + add_metric() + } + + ResultBundle "1" *- "1" Result + ' This forces a longer arrow ------------v + ResultBundle "1" *- "1..*" TestMetric : " " + + class TestBundle { + # _from_target() : TestBundle + + from_target() : TestBundle + + from_dir() : TestBundle + } + + note right of TestBundle { + Methods returning TestBundle + are alternative constructors + + from_target() does some generic + work, then calls _from_target(). You'll + have to override it depending on what + you want to execute on the target. + } + + class MyTestBundle { + # _from_target() : TestBundle + + test_foo_is_bar() : ResultBundle + } + + note right of MyTestBundle { + Non-abstract TestBundle classes + must define test methods that return + a ResultBundle + } + + TestBundle <|-- MyTestBundle + MyTestBundle .. ResultBundle + +Implementations of :class:`~lisa.tests.base.TestBundle._from_target` can +execute any sort of arbitry Python code. This means that you are free to +manipulate sysfs entries, or to execute arbitray binaries on the target. The +:class:`~lisa.wlgen.workload.Workload` class has been created to +facilitate the execution of commands/binaries on the target. + +An important daughter class of :class:`~lisa.wlgen.workload.Workload` +is :class:`~lisa.wlgen.rta.RTA`, as it facilitates the creation and +execution of `rt-app `_ workloads. +It is very useful for scheduler-related tests, as it makes it easy to create +tasks with a pre-determined utilization. + +API +=== + +Base classes +++++++++++++ + +.. automodule:: lisa.tests.base + :members: + :private-members: _from_target + +.. TODO:: Make those imports more generic + +Scheduler tests ++++++++++++++++ + +EAS tests +--------- + +.. inheritance-diagram:: lisa.tests.scheduler.eas_behaviour + :top-classes: lisa.tests.base.TestBundle + :parts: 1 + +| + +.. automodule:: lisa.tests.scheduler.eas_behaviour + :members: + +Load tracking tests +------------------- + +.. inheritance-diagram:: lisa.tests.scheduler.load_tracking + :top-classes: lisa.tests.base.TestBundle + :parts: 1 + +| + +.. automodule:: lisa.tests.scheduler.load_tracking + :members: + :private-members: _from_target + +Misfit tests +------------ + +.. inheritance-diagram:: lisa.tests.scheduler.misfit + :top-classes: lisa.tests.base.TestBundle + :parts: 1 + +| + +.. automodule:: lisa.tests.scheduler.misfit + :members: + +Sanity tests +------------ + +.. inheritance-diagram:: lisa.tests.scheduler.sanity + :top-classes: lisa.tests.base.TestBundle + :parts: 1 + +| + +.. automodule:: lisa.tests.scheduler.sanity + :members: + +Hotplug tests ++++++++++++++ + +.. inheritance-diagram:: lisa.tests.hotplug.torture + :top-classes: lisa.tests.base.TestBundle + :parts: 1 + +| + +.. automodule:: lisa.tests.hotplug.torture + :members: + +Cpufreq tests ++++++++++++++ + +.. inheritance-diagram:: lisa.tests.cpufreq.sanity + :top-classes: lisa.tests.base.TestBundle + :parts: 1 + +| + +.. automodule:: lisa.tests.cpufreq.sanity + :members: + +Staged tests ++++++++++++++ + +Those are tests that have been merged into LISA but whose behaviour are being +actively evaluated. diff --git a/doc/libs.rst b/doc/libs.rst deleted file mode 100644 index 1af3a1992f..0000000000 --- a/doc/libs.rst +++ /dev/null @@ -1,17 +0,0 @@ -libs package -============ - -Subpackages ------------ - -.. toctree:: - - libs.utils - -Module contents ---------------- - -.. automodule:: libs - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/libs.utils.android.rst b/doc/libs.utils.android.rst deleted file mode 100644 index d49a1a747d..0000000000 --- a/doc/libs.utils.android.rst +++ /dev/null @@ -1,38 +0,0 @@ -libs.utils.android package -========================== - -Submodules ----------- - -libs.utils.android.screen module --------------------------------- - -.. automodule:: libs.utils.android.screen - :members: - :undoc-members: - :show-inheritance: - -libs.utils.android.system module --------------------------------- - -.. automodule:: libs.utils.android.system - :members: - :undoc-members: - :show-inheritance: - -libs.utils.android.workload module ----------------------------------- - -.. automodule:: libs.utils.android.workload - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: libs.utils.android - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/libs.utils.rst b/doc/libs.utils.rst deleted file mode 100644 index 23da13c19f..0000000000 --- a/doc/libs.utils.rst +++ /dev/null @@ -1,117 +0,0 @@ -libs.utils package -================== - -Subpackages ------------ - -.. toctree:: - - libs.utils.android - -Submodules ----------- - -libs.utils.analysis_module module ---------------------------------- - -.. automodule:: libs.utils.analysis_module - :members: - :undoc-members: - :show-inheritance: - -libs.utils.analysis_register module ------------------------------------ - -.. automodule:: libs.utils.analysis_register - :members: - :undoc-members: - :show-inheritance: - -libs.utils.colors module ------------------------- - -.. automodule:: libs.utils.colors - :members: - :undoc-members: - :show-inheritance: - -libs.utils.conf module ----------------------- - -.. automodule:: libs.utils.conf - :members: - :undoc-members: - :show-inheritance: - -libs.utils.energy module ------------------------- - -.. automodule:: libs.utils.energy - :members: - :undoc-members: - :show-inheritance: - -libs.utils.env module ---------------------- - -.. automodule:: libs.utils.env - :members: - :undoc-members: - :show-inheritance: - -libs.utils.executor module --------------------------- - -.. automodule:: libs.utils.executor - :members: - :undoc-members: - :show-inheritance: - -libs.utils.perf_analysis module -------------------------------- - -.. automodule:: libs.utils.perf_analysis - :members: - :undoc-members: - :show-inheritance: - -libs.utils.report module ------------------------- - -.. automodule:: libs.utils.report - :members: - :undoc-members: - :show-inheritance: - -libs.utils.results module -------------------------- - -.. automodule:: libs.utils.results - :members: - :undoc-members: - :show-inheritance: - -libs.utils.test module ----------------------- - -.. automodule:: libs.utils.test - :members: - :undoc-members: - :show-inheritance: - -libs.utils.trace module ------------------------ - -.. automodule:: libs.utils.trace - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: libs.utils - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/lisa_shell.rst b/doc/lisa_shell.rst new file mode 100644 index 0000000000..c5dac3045a --- /dev/null +++ b/doc/lisa_shell.rst @@ -0,0 +1,20 @@ +********** +LISA shell +********** + +.. TODO:: Have the shell manpage here + +Once you have all of the required dependencies installed, you can use the LISA +shell, which provides a convenient set of commands for easy access to many LISA +related functions: + + .. code-block:: sh + + source init_env + +.. note:: + + This is done automatically by vagrant, so you don't have to issue this + command after doing a ``vagrant ssh`` + +.. tip:: Run ``lisa-help`` to see an overview of the provided LISA commands. diff --git a/doc/man1/bisector.1 b/doc/man1/bisector.1 new file mode 100644 index 0000000000..b2550a0198 --- /dev/null +++ b/doc/man1/bisector.1 @@ -0,0 +1,1042 @@ +.\" Man page generated from reStructuredText. +. +.TH "BISECTOR" "1" "2019" "" "bisector" +.SH NAME +bisector \- command sequencer +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH DESCRIPTION +.sp +\fBbisector\fP is a \fBgit bisect run\fP [1] compatible tool used in LISA. Its goal is +to sequence commands to be repeated an arbitrary number of times and generates +a report. +.sp +For example, \fBbisector\fP can be used to compile a kernel, flash a board, +reboot it and run test suite. To achieve that, \fBbisector\fP runs a sequence of +steps, and saves a report file containing the result of each step. This step +sequence is run for a number of iterations, or for a given duration. That +allows tracking fluctuating bugs by repeating a test process many times. +.sp +The steps class can implement any run or report behavior, with the ability to +take parameters. They also decide what data is saved into the report, and +their contribution to the overall \fBgit bisect\fP result: +.INDENT 0.0 +.IP \(bu 2 +\fIgood\fP: the test steps passed +.IP \(bu 2 +\fIbad\fP: the test steps failed +.IP \(bu 2 +\fIuntestable\fP: the build or flash step failed +.IP \(bu 2 +\fIabort\fP: the reboot step failed, and the board is now unusable and requires +manual intervention +.IP \(bu 2 +\fINA\fP: the step will not impact the overall result +.UNINDENT +.sp +It is important to note that \fBbisector\fP step classes usually only invoke a +user\-specified command line tool and will use the return code to decide what +\fBgit bisect\fP result to return. They can also implement more specific result +reporting, and additional run behaviors. +.SH OPTIONS +.SS bisector +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +usage: bisector [\-h] [\-\-cli\-options CLI_OPTIONS] + {step\-help,run,report,edit,monitor\-server,monitor} ... + + Git\-bisect\-compatible command sequencer. + + bisector allows to run commands with timeout handling in predefined + sequences (steps). The output is saved in a report that can be later + analyzed. The exit status of all steps is merged to obtain a git bisect + compatible value which is returned. The error code 254 is used + when bisector itself encounters an error. + + SIGNAL HANDLING + + The script can be stopped with SIGINT (Ctrl\-C) or SIGTERM (kill or timeout + commands) or SIGHUP (when the terminal dies) and will save the completed + iterations to the report. The execution can later be resumed with \-\-resume. + + +optional arguments: + \-h, \-\-help show this help message and exit + \-\-cli\-options CLI_OPTIONS + YAML file containing command line option string in a + "cmd\-line" toplevel key. Therefore, the same file can be used + for \-\-steps. The options are inserted at the location of + \-\-cli\-options in the command line. That can be used to control what + can be overriden by configuration file and what is forced by the + command line + +subcommands: + {step\-help,run,report,edit,monitor\-server,monitor} + +.ft P +.fi +.UNINDENT +.UNINDENT +.SS bisector run +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +usage: bisector run [\-h] [\-\-cli\-options CLI_OPTIONS] [\-o OPTION] [\-\-debug] + [\-\-steps STEPS] [\-\-allowed\-bad ALLOWED_BAD] [\-\-skip SKIP] + [\-\-only ONLY] [\-\-git\-clean] [\-\-inline CLASS NAME] + [\-n ITERATIONS] [\-\-timeout TIMEOUT] [\-\-log LOG] + [\-\-report REPORT] [\-\-overwrite] [\-\-resume] [\-\-desc DESC] + [\-\-early\-bailout] [\-\-upload\-report] [\-\-no\-dbus] + +Run the given steps in a loop and record the result in a report file. The +report file can be inspected using the "report" subcommand. The exit status is +suitable for git bisect. + +optional arguments: + \-h, \-\-help show this help message and exit + \-\-cli\-options CLI_OPTIONS + YAML file containing command line option string in a + "cmd\-line" toplevel key. Therefore, the same file can + be used for \-\-steps. The options are inserted at the + location of \-\-cli\-options in the command line. That + can be used to control what can be overriden by + configuration file and what is forced by the command + line + \-o OPTION, \-\-option OPTION + Step\-specific options. Can be repeated. The format is + .