Setup#

Installation#

Host installation#

From PyPI#

LISA is available on PyPI:

pip install lisa-linux

Note

Some dependencies cannot be fulfilled by PyPI, such as adb when working with Android devices. It is the user’s responsability to install them. Alternatively, the installation from the git repository allows setting up a full environment.

From GitLab#

LISA is hosted on GitLab. The following references are available:

  • main branch: Main development branch where pull requests are merged as they come.

  • release branch: Branch updated upon release of the lisa-linux package on PyPI.

  • vX.Y.Z tags: One tag per release of lisa-linux PyPI package.

LISA has a minimum Python version requirement of:

Python >= 3.9

If your distribution does not natively ship with a high-enough version, you can install it manually and provide the name of the Python binary before doing any other action:

export LISA_PYTHON=<name of Python 3 binary>

On Ubuntu, the deadsnakes PPA provides alternative versions of Python. Note that Ubuntu splits the Python distribution into multiple packages, which must all be installed. The list is available inside install_base.sh and is more or less:

  • python3

  • python3-pip

  • python3-venv

  • python3-tk

You might also find a python3.X-full package that contains everything you need.

git clone https://gitlab.arm.com/tooling/lisa
# Jump into the cloned repo directory
cd lisa
# This will provide a more accurate changelog when building the doc
git fetch origin refs/notes/changelog
# A few packages need to be installed, like python3 or kernelshark. Python
# modules will be installed in a venv at the next step, without touching
# any system-wide install location.
./install_base.sh --install-all
# On the first run, it will take care of creating a Python venv and populating it
source init_env

Attention

If you use this installation procedure, make sure to always run source init_env before anything else in order to activate the venv. Otherwise, importing lisa will fail, commands will not be available etc.

Attention

Only Bash and ZSH are officially supported by source init_env. Mileage may vary for other shells, up to and including failure from the first line.

In case the venv becomes unusable for some reason, the lisa-install shell command available after sourcing init_env will allow to create a new clean venv from scratch.

Additional Python packages#

lisa-install will also install the content of $LISA_HOME/custom_requirements.txt if the file exists. That allows re-installing a custom set of packages automatically when the venv needs to regenerated.

Without automatic venv#

Sometimes, LISA needs to operate in an environment setup for multiple tools. In that case, it may be easier to manage manually a venv/virtualenv instead of letting LISA create one for its shell.

Setting export LISA_USE_VENV=0 prior to source init_env will avoid the creation and usage of the LISA-managed venv. lisa-install command can still be used to install the necessary Python packages, which will honor any venv-like system manually setup.

Alternatively, lisa package is packaged according to the usual Python practices, which includes a setup.py script, and a devmode_requirements.txt file that will install all the shipped packages in editable mode (including those that are not developped in that repository, but still included for convenience).

Target installation#

LISA’s “device under test” is called target. In order to be able to run e.g. tests on a target, you will need the provide a minimal environment composed of:

  • An adb or ssh server

  • For some tests, a working Python 3 installation

This can be provided by a a regular GNU/Linux or Android distribution, but can also be done with a minimal buildroot environment. The benefits are:

  • Almost no background task that can create issues when testing the Linux kernel scheduler

  • Can be used as a in-memory initramfs, thereby avoiding activity of USB or NFS-related kthreads, as it has been the source of issues on some boards with wonky USB support.

  • Using initramfs has the added advantages of ease of deployment (can be integrated in the kernel image, reducing the amount of assets to flash) and avoids issues related to board state (a reboot fully resets the userspace).

Buildroot image creation is assisted with these commands, available in lisa shell Buildroot commands.

Kernel modules#

From Linux v5.3, sched_load_cfs_rq and sched_load_se tracepoints are present in mainline as bare tracepoints without any events in tracefs associated with them.

To help expose these tracepoints (and any additional one we might require in the future) as trace events, an out-of-tree module shipped with lisa is required.

Pre-requisites#
CFI#

Using the out-of-tree build method for kernels with CONFIG_CFI_CLANG=y as all Android kernels come by default requires the module to be built with at least clang-16. This can either be achieved by using the alpine build environment, by having it installed on host and using LLVM=1 or forcing the version with LLVM=-16 in target-conf/kernel/modules/make-variables.

Kernel symbols needed for reading files on Android product kernels#

In order to use some Lisa module features (e.g. the lisa__pixel6_emeter ftrace event) on a product kernel, some symbols forbidden by Google need to be re-enabled.

In order to do that, the kernel will need to be built with:

./update_symbol_list.sh

The script should be included in the product kernel tree. It will ensure that the required symbols are not stripped from the final kernel image and the module does not get rejected.

Enabling a module#

LISA Python package will compile and load the module automatically when required for tracing so there is usually no reason to do so manually. The most reliable way to configure LISA for building the module is:

  • Kernel config (also available under $LISA_HOME/tools/kmodules/kconfig_fragment.config):

    CONFIG_IKHEADERS=y
CONFIG_IKCONFIG=y
CONFIG_DEBUG_INFO=y
CONFIG_DEBUG_INFO_BTF=y
CONFIG_DEBUG_INFO_REDUCED=n
CONFIG_BPF_SYSCALL=y
CONFIG_FTRACE=y

  • Target configuration (lisa.target.TargetConf):

    target-conf:
    kernel:
        # If this is omitted, LISA will try to download a kernel.org
        # released tarball. If the kernel has only minor differences with
        # upstream, it will work, but can also result in compilation
        # errors due to mismatching headers.
        src: /home/foobar/linux/
        modules:
            # This is not mandatory but will use a tested chroot to build
            # the module. If that is omitted, ``CROSS_COMPILE`` will be
            # used (and inferred if not set).
            build-env: alpine

            # It is advised not to set that, but in case overlayfs is
            # unusable (e.g. inside an LXC or docker container for a CI
            # system depending on config), this should do the trick.
            # overlay-backend: copy

Note

If build-env: host is used (default), ensure that your setup is ready to compile a kernel. Notably, ensure that you have kernel build dependencies installed. This can be achieved with install_base.sh --install-kernel-build-dependencies (included in --install-all)

Automatic route#

Once the kernel and LISA’s target have been configured appropriately, the Python API will build and load the module automatically as required (e.g. when ftrace events provided by the module are required).

In order to improve interoperation with other systems, a CLI tool is also provided to load the module easily:

# Compile and load the module.
lisa-load-kmod --conf target_conf.yml

# Runs "echo hello world" with the module loaded, then unloads it.
lisa-load-kmod --conf target_conf.yml -- echo hello world

# See # lisa-load-kmod --help for more options.

Note

The module name may be different if it was compiled manually vs compiled via the Python interface due to backward compatiblity constraints.

Manual route#

Manual build of the module are not supported. You may be able to hack your way but if you do so, you are on your own. Also keep in mind that you will need to re-implement internal mechanisms of LISA that might change at any time, so you will loose any backward compatibility guarantee.

Integrating the module in your kernel tree#

This method is not supported. It falls under the category of manual module build.

Updating#

Over time, we might change/add some dependencies to LISA. As such, if you update your LISA repository, you should make sure your locally-installed packages still match those dependencies. Sourcing init_env from a new shell should suffice, which will hint the user if running lisa-install again is needed.

Note

LISA does not provide any specific mean of keeping a venv up-to-date. Running lisa-install will destroy the venv it create and create a new one afresh, but doing so is the sole responsibility of the user, it will not happen automatically based on releases of new versions of LISA’s dependencies.

What next ?#

The next step depends on the intended use case, further information at Guides.