1 2*__NOTE__: This is still a work in progress project, suitable for:* 3*developers, contributors and testers.* 4*None of the provided tests have been extensively evaluated as of January 2017.* 5 6# Introduction 7 8The LISA project provides a toolkit that supports regression testing and 9interactive analysis of Linux kernel behavior. LISA stands for Linux 10Integrated/Interactive System Analysis. LISA's goal is to help Linux 11kernel developers to measure the impact of modifications in core parts 12of the kernel. The focus is on the scheduler (e.g. EAS), power management and 13thermal frameworks. However LISA is generic and can be used for other purposes 14too. 15 16LISA has a "host"/"target" model. LISA itself runs on a *host* machine, and uses 17the [devlib](https://github.com/ARM-software/lisa) toolkit to interact with the 18*target* via SSH, ADB or telnet. LISA is flexible with regard to the target OS; 19its only expectation is a Linux kernel-based system. Android, GNU/Linux and 20busybox style systems have all been used. 21 22LISA provides features to describe workloads (notably using 23[rt-app](https://github.com/scheduler-tools/rt-app)) and run them on targets. It 24can collect trace files from the target OS (e.g. systrace and ftrace traces), 25parse them via the [TRAPpy](https://github.com/ARM-software/trappy) 26framework. These traces can then be parsed and analysed in order to examine 27detailed target behaviour during the workload's execution. 28 29Some LISA features may require modifying the target OS. For example, in order to 30collect ftrace files the target kernel must have CONFIG_DYNAMIC_FTRACE enabled. 31 32There are two "entry points" for running LISA: 33 34* Via the [Jupyter/IPython notebook framework](http://jupyter.org/). This allows 35 LISA to be used interactively and supports visualisation of trace data. Some 36 notebooks are provided with example and ready-made LISA use-cases. 37 38* Via the automated test framework. This framework allows the development of 39 automated pass/fail regression tests for kernel behaviour. The 40 [BART](https://github.com/ARM-software/trappy) toolkit provides additional 41 domain-specific test assertions for this use-case. LISA provides some 42 ready-made automated tests under the `tests/` directory. 43 44# Motivations 45 46The main goals of LISA are: 47 48* Support study of existing behaviours (i.e. *"how does PELT work?"*) 49* Support analysis of new code being developed (i.e. *"what is the impact on 50 existing code?"*) 51* Get insights on what's not working and possibly chase down why 52* Share reproducible experiments by means of a **common language** that: 53 * is **flexible enough** to reproduce the same experiment on different 54 targets 55 * **simplifies** generation and execution of well defined workloads 56 * **defines** a set of metrics to evaluate kernel behaviours 57 * **enables** kernel developers to easily post process data to produce 58 statistics and plots 59 60# Documentation 61 62* [Wiki Home page](https://github.com/ARM-software/lisa/wiki) 63* [Installation](https://github.com/ARM-software/lisa/wiki/Installation) 64* [Quickstart Tutorial](https://github.com/ARM-software/lisa/wiki/Quickstart-tutorial) 65 66More formal API documentation for LISA is a work in progress, however much of 67the API is currently described in the provided tutorial Jupyter notebooks. 68 69# External Links 70* Linux Integrated System Analysis (LISA) & Friends 71 [Slides](http://events.linuxfoundation.org/sites/events/files/slides/ELC16_LISA_20160326.pdf) 72 and [Video](https://www.youtube.com/watch?v=yXZzzUEngiU) 73 74# License 75 76This project is licensed under Apache-2.0. 77 78This project includes some third-party code under other open source licenses. For more information, see lisa/tools/LICENSE.* 79 80# Contributions / Pull Requests 81 82Contributions are accepted under Apache-2.0. Only submit contributions where you have 83authored all of the code. If you do this on work time make sure your employer 84is cool with this. 85