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

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-load-kmod - Build and load the LISA kernel module on a running target.

  • 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.