LISA shell

Description

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, scripts and environment variables.

For more details, see https://tooling.sites.arm.com/lisa/latest/

Activation

In order to use the shell, source the script:

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 man lisa to see an overview of the provided LISA commands.

Commands

Most LISA Shell commands start with lisa-, thus using shell completion it is easy to get a list of all the available commands.

Here is the documentation of the simple ones, more complex scripts have integrated --help documentation, a section in the online documentation, or man pages.

Maintenance commands

  • lisa-help - Show this help

  • lisa-install - Remove the previous venv and do a fresh ven install

  • lisa-version - Dump info on the LISA in use

  • lisa-activate-venv - Activate the LISA venv, and create it if it does not exist

  • lisa-deactivate-venv - Deactivate the LISA venv, and create it if it does not exist

  • lisa-update-subtrees - Update the subtrees by pulling their latest changes

  • lisa-log-subtree - Git log on the squashed commits of the given subtree. All other options are passed to git log.

  • lisa-doc-build - Build the documentation

  • lisa-build-asset - Download and cross-compile the binary assets in lisa/_assets/binaries

Notebooks commands

  • lisa-jupyter - Start/Stop the Jupyter Notebook server.

    Usage: lisa-jupyter CMD [NETIF [PORT]]

    CMD

    start to start the jupyter notebook server, stop to stop it (default: start)

    NETIF

    the network interface to start the server on (default: lo)

    PORT

    the tcp port for the server (default: 8888)

  • lisa-execute-notebook - Execute the given notebook as a script.

Test commands

  • lisa-test - Run LISA synthetic tests.

    This is just a wrapper around exekall that selects all tests modules and use positional arguments as --select patterns. The default configuration file ($LISA_CONF) will be used if available. This can be extended with user-supplied --conf. If multiple iterations are requested using -n, the lisa.target.Target instance will be reused across iterations, to avoid the overhead of setting up the target environment.

    Usage: lisa-test TEST_PATTERN ... [EXEKALL_OPTIONS ...]

    Example: lisa-test 'OneSmallTask*' --list

  • lisa-wltest-series - See wltest main documentation

  • exekall - See exekall main documentation

  • bisector - See bisector main documentation

Buildroot commands

  • lisa-buildroot-create-rootfs- Create a buildroot based rootfs to be used as userland for testing

  • lisa-buildroot-update-kernel-config - Update a kernel config to bake a buildroot initramfs into the kernel.

Misc commands

  • lisa-plot - Generate various plots from a trace.dat file. See lisa-plot -h for available plots.

  • lisa-platinfo-extract - Extract a platform information file (lisa.platforms.platinfo.PlatformInfo) from the target, containing all the knowledge of the target tests or plot functions need.

  • lisa-conf-cat - Parse a LISA YAML configuration file and pretty print it on it’s standard output with help for each key and values of tags computed and interpolated.

Environment variables

The following environment variables are available:

EXEKALL_ARTIFACT_ROOT

Default root for exekall’s artifacts

results

LISA_CONF

Default configuration file for exekall

target_conf.yml

LISA_DEVMODE

By default use internal libraries

1

LISA_HOME

Base directory of LISA environment

.

LISA_HOST_ABI

Add some shell utilities to the PATH, based on the host ABI. Priority is determined by LISA_USE_SYSTEM_BIN

x86_64

LISA_PRESERVE_SHELL

By default use Lisa’s PS1 and colorscheme for the shell

0

LISA_PYTHON

Python binary to use. This allows users to install multiple versions in parallel, and ease testing

python3

LISA_RESULT_ROOT

By default, store the results under that folder

results

LISA_UPGRADE_VENV

1 to make lisa-install upgrade the venv specified in LISA_VENV_PATH. If 0, lisa-install will destroy the venv and re-create anew

0

LISA_USE_SYSTEM_BIN

Use the system binaries if 1, will use the ones shipped with LISA if 0

0

LISA_USE_VENV

1 to make lisa-install use a venv specified in LISA_VENV_PATH, 0 otherwise

1

LISA_VENV_PATH

Path to venv to be used by lisa-install

.lisa-venv-<python version>

If an environment variable is defined prior to sourcing init_env, it will keep its value.