From 7069502991eb8c0835bab67601650ddde42a3c65 Mon Sep 17 00:00:00 2001 From: Valentin Schneider Date: Wed, 20 Mar 2019 13:28:27 +0000 Subject: [PATCH 1/4] lisa/tests: TestBundle: Cleanup some docstrings --- lisa/tests/base.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lisa/tests/base.py b/lisa/tests/base.py index f16a219d6..0e3110ced 100644 --- a/lisa/tests/base.py +++ b/lisa/tests/base.py @@ -194,10 +194,10 @@ class TestBundle(Serializable, abc.ABC): a :class:`TestBundle`. * :attr:`VERIFY_SERIALIZATION` is there to ensure both above methods remain operationnal at all times. - * `res_dir` parameter of `__init__` must be stored as an attribute + * ``res_dir`` parameter of ``__init__`` must be stored as an attribute without further processing, in order to support result directory relocation. - * Test methodes should have a return annotation for the + * Test methods should have a return annotation for the :class:`ResultBundle` to be picked up by the test runners. **Implementation example**:: -- GitLab From 39749098990deadda4aa0b20ffbdcc5fc61165ed Mon Sep 17 00:00:00 2001 From: Valentin Schneider Date: Wed, 20 Mar 2019 13:45:33 +0000 Subject: [PATCH 2/4] lisa/tests: Remove superfluous abc.ABC inheritance --- lisa/tests/base.py | 2 +- lisa/tests/hotplug/torture.py | 2 +- lisa/tests/scheduler/eas_behaviour.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/lisa/tests/base.py b/lisa/tests/base.py index 0e3110ced..5d8e10033 100644 --- a/lisa/tests/base.py +++ b/lisa/tests/base.py @@ -348,7 +348,7 @@ class TestBundle(Serializable, abc.ABC): """ super().to_path(self._filepath(res_dir)) -class RTATestBundle(TestBundle, abc.ABC): +class RTATestBundle(TestBundle): """ "Abstract" class for :class:`lisa.wlgen.rta.RTA`-powered TestBundles diff --git a/lisa/tests/hotplug/torture.py b/lisa/tests/hotplug/torture.py index 74f096632..e8bb6e7b1 100644 --- a/lisa/tests/hotplug/torture.py +++ b/lisa/tests/hotplug/torture.py @@ -33,7 +33,7 @@ from lisa.utils import ArtifactPath class CPUHPSequenceError(Exception): pass -class HotplugBase(TestBundle, abc.ABC): +class HotplugBase(TestBundle): def __init__(self, plat_info, target_alive, hotpluggable_cpus, live_cpus): res_dir = None super().__init__(res_dir, plat_info) diff --git a/lisa/tests/scheduler/eas_behaviour.py b/lisa/tests/scheduler/eas_behaviour.py index 00241183c..3970ddcbc 100644 --- a/lisa/tests/scheduler/eas_behaviour.py +++ b/lisa/tests/scheduler/eas_behaviour.py @@ -36,7 +36,7 @@ from lisa.trace import requires_events from lisa.target import Target from lisa.trace import FtraceCollector -class EASBehaviour(RTATestBundle, abc.ABC): +class EASBehaviour(RTATestBundle): """ Abstract class for EAS behavioural testing. -- GitLab From 6cc4f4b7c4af0546dfa3f9196346874b296c551c Mon Sep 17 00:00:00 2001 From: Valentin Schneider Date: Wed, 20 Mar 2019 14:14:42 +0000 Subject: [PATCH 3/4] doc/kernel_tests: Generate inheritance diagrams --- doc/conf.py | 1 + doc/kernel_tests.rst | 43 +++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 42 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index ba697c068..efff70d56 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -98,6 +98,7 @@ extensions = [ 'sphinx.ext.coverage', 'sphinx.ext.imgmath', 'sphinx.ext.viewcode', + 'sphinx.ext.inheritance_diagram', ] # Add any paths that contain templates here, relative to this directory. diff --git a/doc/kernel_tests.rst b/doc/kernel_tests.rst index 8f8e636bc..3f8f79238 100644 --- a/doc/kernel_tests.rst +++ b/doc/kernel_tests.rst @@ -109,8 +109,8 @@ tasks with a pre-determined utilization. API === -Base API -++++++++ +Base classes +++++++++++++ .. automodule:: lisa.tests.base :members: @@ -123,11 +123,25 @@ 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 @@ -135,23 +149,48 @@ Load tracking tests 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: -- GitLab From 58182d149b577b51401318e34e52423976cd60fe Mon Sep 17 00:00:00 2001 From: Valentin Schneider Date: Tue, 19 Mar 2019 17:22:58 +0000 Subject: [PATCH 4/4] doc/kernel_tests: Add a class diagram for TestBundle & friends --- .travis.yml | 2 +- doc/conf.py | 1 + doc/kernel_tests.rst | 69 ++++++++++++++++++++++++++++++++++++++++-- install_base_ubuntu.sh | 15 +++++++-- setup.py | 3 +- 5 files changed, 83 insertions(+), 7 deletions(-) diff --git a/.travis.yml b/.travis.yml index 466e7046e..792ae8f17 100644 --- a/.travis.yml +++ b/.travis.yml @@ -29,7 +29,7 @@ dist: xenial install: - cd "$TRAVIS_BUILD_DIR" - - sudo ./install_base_ubuntu.sh + - sudo ./install_base_ubuntu.sh --install-doc-extras - echo "$(python3 --version)" script: diff --git a/doc/conf.py b/doc/conf.py index efff70d56..2af97de94 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -99,6 +99,7 @@ extensions = [ 'sphinx.ext.imgmath', 'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram', + 'sphinxcontrib.plantuml', ] # Add any paths that contain templates here, relative to this directory. diff --git a/doc/kernel_tests.rst b/doc/kernel_tests.rst index 3f8f79238..c7ed538c1 100644 --- a/doc/kernel_tests.rst +++ b/doc/kernel_tests.rst @@ -69,8 +69,8 @@ See the usage example of :class:`~lisa.tests.base.TestBundle` Writing tests ============= -Basics -++++++ +Concepts +++++++++ Writing scheduler tests can be difficult, especially when you're trying to make them work without relying on custom tracepoints (which is @@ -94,7 +94,70 @@ Have a look at its documentation for implementation and usage examples. A simple test implementation worth looking at is :class:`~lisa.tests.scheduler.sanity.CapacitySanity`. -Implementations of :class:`~lisa.tests.base.TestBundle` can +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 diff --git a/install_base_ubuntu.sh b/install_base_ubuntu.sh index 637789bd3..6fcdda47a 100755 --- a/install_base_ubuntu.sh +++ b/install_base_ubuntu.sh @@ -10,7 +10,7 @@ SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}") cd "$SCRIPT_DIR" usage() { - echo Usage: "$0" [--install-android-sdk] + echo Usage: "$0" [--install-android-sdk] [--install-doc-extras] } latest_version() { @@ -59,13 +59,20 @@ install_nodejs() { apt-get install -y nodejs npm } +install_doc_extras() { + apt-get -y install plantuml graphviz +} + set -eu install_android_sdk=n +install_doc_extras=n for arg in "$@"; do if [ "$arg" == "--install-android-sdk" ]; then - install_android_sdk=y + install_android_sdk=y + elif [ "$arg" == "--install-doc-extras" ]; then + install_doc_extras=y else echo "Unrecognised argument: $arg" usage @@ -87,6 +94,10 @@ if [ "$install_android_sdk" == y ]; then install_sdk fi +if [ "$install_doc_extras" == y ]; then + install_doc_extras +fi + # Make sure we exit with no errors, so we can start making use of that # if we introduce some meaningful error handling. Since some packages are not # needed for some tasks and since we don't have mechanisms in place to group diff --git a/setup.py b/setup.py index cb1178d30..b9c67637d 100755 --- a/setup.py +++ b/setup.py @@ -114,7 +114,8 @@ setup( "doc": [ "sphinx >= 1.8", - "sphinx_rtd_theme" + "sphinx_rtd_theme", + "sphinxcontrib-plantuml", ], "test": [ -- GitLab