Target

Introduction

Our Target is a wrapper around devlib.target.Target. In short, it’s a device communication abstraction library that gives us a simple Python interface for playing around with a device (shell, file transfer…).

If you want to execute some command on a target, it’s as simple as this:

out = target.execute("ls -al .")

Have a look at the devlib documentation for more details. Our wrapper brings additionnal features which are documented below.

As a rule of thumb, if you want to add a feature to Target, chances are this should be contributed to devlib instead.

Connecting to a target

Connecting to a target means creating a Target instance. This can be as a simple as this:

target = Target(kind="linux", host="192.168.0.1", username="root", password="root")

For more convenience, you can also save the relevant connection information for a given target in a configuration file, which would let you create a Target like so:

target = Target.from_one_conf("path/to/my/conf.yml")

Platform data

The main source of information for tests come from Trace and PlatformInfo. The latter gives access to information autodetected from the devlib.target.Target or filled in by the user.

This information ranges from the current kernel version to the available platform frequencies.

API

Target

class lisa.target.PasswordKeyDesc(name, help, classinfo, newtype=None, deepcopy_val=True)[source]

Bases: KeyDesc

pretty_format(v)[source]

Format the value for pretty printing.

Parameters:: v (object) – Value of the key that is being printed
Returns:: A string

class lisa.target.TargetConf(conf=None, src='user', add_default_src=True)[source]

Bases: SimpleMultiSrcConf, HideExekallID

Target connection settings.

Only keys defined below are allowed, with the given meaning and type:

target-conf: target connection settings

name (str): Board name, free-form value only used to embelish logs.

kind (Literal): Target kind. Can be “linux” (ssh) or “android” (adb).

host (str or None): Hostname or IP address of the SSH or ADB server.

username (str or None): SSH username. On ADB connections, “root” username will root adb upon target connection.

password (str or None): SSH password.

port (int or None): SSH or ADB server port.

device (str or None): ADB device.

keyfile (str or None): SSH private key file.

strict-host-check (bool or None): Equivalent to StrictHostKeyChecking option of OpenSSH.

workdir (str): Remote target workdir.

tools (Sequence): List of tools to install on the target.

lazy-platinfo (bool): Lazily autodect the platform information to speed up the connection.

kernel: kernel information

src (str or None): Path to kernel source tree matching the kernel running on the target used to build modules.

modules: Kernel module build environment

build-env (Literal): Environment used to build modules. Can be any of “alpine” (Alpine Linux chroot, recommended) or “host” (command ran directly on host system).

build-env-settings: build-env settings

host: Settings for host build-env

toolchain-path (str): Folder to prepend to PATH when executing toolchain command in the host build env.

alpine: Settings for Alpine linux build-env

version (None or str): Alpine linux version, e.g. 3.18.0.

packages (None or Sequence): List of Alpine linux packages to install. If that is provided, then errors while installing the package list provided by LISA will not raise an exception, so that the user can provide their own replacement for them. This allows future-proofing hardcoded package names in LISA, as Alpine package names might evolve between versions..

overlay-backend (str): Backend to use for overlaying folders while building modules. Can be “overlayfs” (overlayfs filesystem, recommended and fastest) or “copy (plain folder copy).

make-variables (Dict): Extra variables to pass to “make” command, such as “CC”.

modules: modules settings

<module-name>: For each module. The module shipped by LISA is “lisa”

overlays (Dict): Overlays to apply to the sources of the given module.

wait-boot: Wait for the target to finish booting

enable (bool): Enable the boot check.

timeout (int): Timeout of the boot check.

devlib: devlib configuration

platform: devlib.platform.Platform subclass specification

class (str): Name of the class to use.

args (Mapping): Keyword arguments to build the Platform object.

excluded-modules (Sequence): List of devlib modules to not load.

file-xfer (Sequence): File transfer method. Can be “sftp” (default) or “scp”. (Only valid for linux targets).

max-async (int or None): Maximum number of asynchronous commands in flight at any time.

An instance can be created by calling TargetConf with a dictionary. The top-level target-conf key is not needed here:

TargetConf({
    'name': 'myboard',
    'host': 192.0.2.1,
    'kind': 'linux',
    'username': 'foo',
    'password': 'bar',
})

Or alternatively, from a YAML configuration file:

Content of target_conf.yml:

# LISA Target configuration required by devlib to connect to a target.
#
# See the doc for available keys:
# https://tooling.sites.arm.com/lisa/latest/target.html#lisa.target.TargetConf
#

target-conf:
    # Kind of platform
    # - linux   : accessed via SSH connection
    # - android : accessed via ADB connection
    # - host    : run on the local host
    # kind : android

    # Board
    # Optional board name used for better prettier logs
    # name: myboard

    # Target IP or domain name
    # host: 192.168.0.20

    # Target Android device ID
    # device: 00b1346f0878ccb1

    # Login username (has to be sudo enabled)
    # username: root

    # Login credentials
    # You can specify either a password or keyfile
    # password: "mypassword"
    # keyfile: /complete/path/of/your/keyfile

    # Optional kernel module configuration
    # kernel:
        # Path to the kernel sources. If left out, a kernel.org tarball will be
        # used (with varying degree of success)
        # src: /path/to/kernel/src/tree

        # Module compiling options
        # modules:
            # Variables passed to make command line while building modules.
            # make-variables:
                # Setting "LLVM: 1" is a good idea as clang is a cross
                # compiler by default. Just using "CC: clang" will still use
                # parts of the GNU toolchain.
                # LLVM: 1

            # Either "host" or "alpine". If "alpine" is used, an Alpine chroot
            # will be used to build the kernel module in. Works best with
            # "LLVM: 1" for reproducible builds regardless of the build-env.
            #
            # build-env: host
            # It is possible to specify some parameters to build-env, such as
            # Alpine version:
            # build-env:
            #     build-env: alpine
            #     build-env-settings:
            #         alpine:
            #              version: 3.18
            #              packages:
            #                  - foobar

            # Usually not needed: "overlayfs" will overlay folders using
            # overlayfs. "copy" will use plain slow copies.
            # overlay-backend: overlayfs


    # Optional devlib configuration
    # devlib:
        # Devlib modules names to enable/disbale for all the experiment
        # excluded-modules: []
        #
        # devlib Platform sublcass to use, with the keyword arguments to use it
        # platform:
            # Defaults to devlib.platform.Platform
            # class: devlib.platform.Platform
            # args:
                # arg1: foo
                # arg2: bar

    # Optional additional binary tools to install by default for all experiments
    # Currently available tools:
    # - binaries under ./tools/<ARCH>/
    #   where <ARCH> is one of the supported target
    #   architectures
    # - shell scripts under './tools/scripts/
    # tools: []
    #

# Ftrace collector configuration
ftrace-conf:
    # Additional ftrace events and functions collected regardless of the
    # test configuration
    # events: []
    # functions: []
    #
    # ftrace buffer size
    # buffer-size: 42

# Platform information
#
# Various bits of information about the platform used by LISA
#
platform-info:
    # Include a preset platform-info file, instead of defining the keys directly here.
    # Note that you cannot use !include and define keys at the same time.
    # !include $LISA_HOME/lisa/platforms/juno_r0.yml
    # conf:
        # rtapp:
            # # Calibration mapping of CPU numbers to calibration value for rtapp
            # calib: {}

TargetConf.from_yaml_map('target_conf.yml')

The following special YAML tags can be used in the configuration file:

target-conf:
    # "!env:<type> ENV_VAR_NAME" can be used to reference an
    # environment variable.
    name: !env:str BOARD_NAME
    port: !env:int PORT

Note

Only load trusted YAML files as it can lead to abritrary code execution.

Note

That structure in a YAML file is allowed and will work:

file foo.yml:
```
target-conf:
    name: myboard
```
file bar.yml:
```
target-conf:
    !include foo.yml
```

This will result in that structure which would normally be invalid, but is handled as a special case:

target-conf:
    target-conf:
        name: myboard

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

STRUCTURE = <lisa.conf.TopLevelKeyDesc object>

DEFAULT_SRC = {'devlib': {'excluded-modules': [], 'platform': {'class': 'devlib.platform.Platform'}}, 'kernel': {'modules': {'build-env-settings': {'alpine': {}, 'host': {}}, 'modules': {'<module-name>': {}}}}, 'lazy-platinfo': False, 'name': '<noname>', 'tools': [], 'wait-boot': {'enable': True, 'timeout': 10}}: Source added automatically using add_src() under the name ‘default’ when instances are built.

class Device

Target

Introduction

Connecting to a target

Platform data

API

Target

Platform Info