lisa.target.TargetConf#

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 (typing.Literal['linux', 'android', 'host']): 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 (typing.Sequence[str]): 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 (typing.Literal['host', 'alpine']): 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. Toolchain autodetection will be restricted to that folder..
      - alpine: Settings for Alpine linux build-env
        
        version (None or str): Alpine linux version, e.g. 3.18.0.
        
        packages (None or typing.Sequence[str]): 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), “fuse-overlayfs” (suitable for environments where user namespaces are disabled), “copy (plain folder copy).
    - make-variables (typing.Dict[str, object]): 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 (typing.Dict[str, lisa._kmod.OverlayResource]): Overlays to apply to the sources of the given module.
        
        conf (object): Configuration of the 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 (collections.abc.Mapping): Keyword arguments to build the Platform object.
  - excluded-modules (typing.Sequence[str]): List of devlib modules to not load.
  - file-xfer (typing.Sequence[str]): 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/disable for all the experiment
        # excluded-modules: []
        #
        # devlib Platform subclass 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

Attributes

`DEFAULT_SRC`	Source added automatically using `add_src()` under the name ‘default’ when instances are built.
`STRUCTURE`	Regular top-level key descriptor, with only one level.
`ATTRIBUTES_SERIALIZATION` ^inherited	Attributes to be treated specially during serialization.
`DEFAULT_SERIALIZATION_FMT` ^inherited	Default format used when serializing objects.
`YAML_ENCODING` ^inherited	Encoding used for YAML files.
`__reversed__` ^inherited	See `collections.abc.Mapping.__reversed__`

Properties

`as_yaml_map` ^inherited	Give a mapping suitable for storing in a YAML configuration file.
`logger` ^inherited	Convenience short-hand for `self.get_logger()`.

Methods

`__class_getitem__()` ^inherited	See `collections.abc.Iterable.__class_getitem__()`
`__contains__()` ^inherited	See `collections.abc.Mapping.__contains__()`
`__copy__()` ^inherited	Shallow copy of the nested configuration tree, without duplicating the leaf values.
`__deepcopy__()` ^inherited
`__getitem__()` ^inherited
`__getstate__()` ^inherited	Filter instances of `DeferredValue` that are not computed already since their runtime parameters will probably not be available after deserialization.
`__iter__()` ^inherited
`__len__()` ^inherited
`__setstate__()` ^inherited
`add_src()` ^inherited	Add a source of configuration.
`eval_deferred()` ^inherited	Evaluate instances of `DeferredValue` that can be used for values that are expensive to compute.
`force_src()` ^inherited	Force the source priority list for a given key.
`force_src_nested()` ^inherited	Force the source priority list for all the keys defined in the nested mapping `key_src_map`.
`from_map()` ^inherited	Create a new configuration instance, using the output of `to_map()`.
`from_path()` ^inherited	Deserialize an object from a file.
`from_yaml_map()` ^inherited	Allow reloading from a plain mapping, to avoid having to specify a tag in the configuration file. The content is hosted under the top-level key specified in `STRUCTURE`.
`from_yaml_map_list()` ^inherited	Create a mapping of configuration classes to instance, by loading them from the list of paths using `from_yaml_map()` and merging them.
`get()` ^inherited	See `collections.abc.Mapping.get()`
`get_help()` ^inherited
`get_key()` ^inherited	Get the value of the given key. It returns a deepcopy of the value.
`get_logger()` ^inherited	Provides a `logging.Logger` named after `cls`.
`get_nested_key()` ^inherited	Same as `get_key()` but works on a list of keys to access nested mappings.
`get_src_map()` ^inherited	Get a mapping of all sources for the given `key`, in priority order (first item is the highest priority source).
`items()` ^inherited	Override the default definition of `collections.abc.Mapping.items()` to allow not evaluating deferred values if necessary.
`keys()` ^inherited	See `collections.abc.Mapping.keys()`
`log_locals()` ^inherited	Debugging aid: log the local variables of the calling function.
`pretty_format()` ^inherited	Give a pretty string representation of the configuration.
`resolve_src()` ^inherited	Get the source name that will be used to serve the value of `key`.
`set_default_src()` ^inherited	Set the default source priority list.
`to_map()` ^inherited	Export the configuration as a mapping.
`to_path()` ^inherited	Serialize the object to a file.
`to_yaml()` ^inherited	Return a YAML string with the serialized object.
`to_yaml_map()` ^inherited	Write a configuration file, with the key descriptions in comments.
`to_yaml_map_str()` ^inherited	Return the content of the file that would be create by `to_yaml_map()` in a string.
`values()` ^inherited	See `collections.abc.Mapping.values()`

Attributes#

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

TargetConf.STRUCTURE = <lisa.conf.TopLevelKeyDesc object>#

TargetConf.ATTRIBUTES_SERIALIZATION = {'allowed': [], 'ignored': [], 'placeholders': {}}#

Inherited attribute, see lisa.utils.Serializable.ATTRIBUTES_SERIALIZATION

Attributes to be treated specially during serialization.

TargetConf.DEFAULT_SERIALIZATION_FMT = 'yaml'#

Inherited attribute, see lisa.utils.Serializable.DEFAULT_SERIALIZATION_FMT

Default format used when serializing objects.

TargetConf.YAML_ENCODING = 'utf-8'#

Inherited attribute, see lisa.utils.Serializable.YAML_ENCODING

Encoding used for YAML files.

TargetConf.__reversed__ = None#

Properties#

property TargetConf.as_yaml_map#

Inherited property, see lisa.conf.MultiSrcConfABC.as_yaml_map

Give a mapping suitable for storing in a YAML configuration file.

property TargetConf.logger#

Inherited property, see lisa.utils.Loggable.logger

Convenience short-hand for self.get_logger().

Methods#

classmethod TargetConf.__class_getitem__()#: Inherited method, see collections.abc.Iterable.__class_getitem__()

TargetConf.__contains__()#: Inherited method, see collections.abc.Mapping.__contains__()

TargetConf.__copy__()#

Inherited method, see lisa.conf.MultiSrcConf.__copy__()

Shallow copy of the nested configuration tree, without duplicating the leaf values.

TargetConf.__deepcopy__(memo)#: Inherited method, see lisa.conf.MultiSrcConf.__deepcopy__()

TargetConf.__getitem__(key)#: Inherited method, see lisa.conf.MultiSrcConf.__getitem__()

TargetConf.__getstate__()#

Inherited method, see lisa.conf.MultiSrcConf.__getstate__()

Filter instances of DeferredValue that are not computed already since their runtime parameters will probably not be available after deserialization.

TargetConf.__iter__()#: Inherited method, see lisa.conf.MultiSrcConf.__iter__()

TargetConf.__len__()#: Inherited method, see lisa.conf.MultiSrcConf.__len__()

TargetConf.__setstate__(dct)#: Inherited method, see lisa.utils.Serializable.__setstate__()

TargetConf.add_src(src, conf, filter_none=False, fallback=False, inplace=True)#

Inherited method, see lisa.conf.MultiSrcConf.add_src()

Add a source of configuration.

TargetConf.eval_deferred(cls=<class 'lisa.conf.DeferredValue'>, src=None, resolve_src=True, error='raise')#

Inherited method, see lisa.conf.MultiSrcConf.eval_deferred()

Evaluate instances of DeferredValue that can be used for values that are expensive to compute.

TargetConf.force_src(key, src_prio)#

Inherited method, see lisa.conf.MultiSrcConf.force_src()

Force the source priority list for a given key.

TargetConf.force_src_nested(key_src_map)#

Inherited method, see lisa.conf.MultiSrcConf.force_src_nested()

Force the source priority list for all the keys defined in the nested mapping key_src_map.

classmethod TargetConf.from_map(*args, **kwargs)#

Inherited method, see lisa.conf.SimpleMultiSrcConf.from_map()

Create a new configuration instance, using the output of to_map().

classmethod TargetConf.from_path(filepath, fmt=None)#

Inherited method, see lisa.utils.Serializable.from_path()

Deserialize an object from a file.

classmethod TargetConf.from_yaml_map(path, add_default_src=True)#

Inherited method, see lisa.conf.MultiSrcConfABC.from_yaml_map()

Allow reloading from a plain mapping, to avoid having to specify a tag in the configuration file. The content is hosted under the top-level key specified in STRUCTURE.

classmethod TargetConf.from_yaml_map_list(path_list, add_default_src=True)#

Inherited method, see lisa.conf.MultiSrcConfABC.from_yaml_map_list()

Create a mapping of configuration classes to instance, by loading them from the list of paths using from_yaml_map() and merging them.

TargetConf.get()#: Inherited method, see collections.abc.Mapping.get()

classmethod TargetConf.get_help(*args, **kwargs)#: Inherited method, see lisa.conf.MultiSrcConf.get_help()

TargetConf.get_key(key, src=None, eval_deferred=True, quiet=False)#

Inherited method, see lisa.conf.MultiSrcConf.get_key()

Get the value of the given key. It returns a deepcopy of the value.

classmethod TargetConf.get_logger(suffix=None)#

Inherited method, see lisa.utils.Loggable.get_logger()

Provides a logging.Logger named after cls.

TargetConf.get_nested_key(key, *args, **kwargs)#

Inherited method, see lisa.conf.MultiSrcConf.get_nested_key()

Same as get_key() but works on a list of keys to access nested mappings.

TargetConf.get_src_map(key)#

Inherited method, see lisa.conf.MultiSrcConf.get_src_map()

Get a mapping of all sources for the given key, in priority order (first item is the highest priority source).

TargetConf.items(eval_deferred=True)#

Inherited method, see lisa.conf.MultiSrcConf.items()

Override the default definition of collections.abc.Mapping.items() to allow not evaluating deferred values if necessary.

TargetConf.keys()#: Inherited method, see collections.abc.Mapping.keys()

classmethod TargetConf.log_locals(var_names=None, level='debug')#

Inherited method, see lisa.utils.Loggable.log_locals()

Debugging aid: log the local variables of the calling function.

TargetConf.pretty_format(eval_deferred=False)#

Inherited method, see lisa.conf.MultiSrcConf.pretty_format()

Give a pretty string representation of the configuration.

TargetConf.resolve_src(key)#

Inherited method, see lisa.conf.MultiSrcConf.resolve_src()

Get the source name that will be used to serve the value of key.

TargetConf.set_default_src(src_prio)#

Inherited method, see lisa.conf.MultiSrcConf.set_default_src()

Set the default source priority list.

TargetConf.to_map()#

Inherited method, see lisa.conf.SimpleMultiSrcConf.to_map()

Export the configuration as a mapping.

TargetConf.to_path(filepath, fmt=None)#

Inherited method, see lisa.utils.Serializable.to_path()

Serialize the object to a file.

TargetConf.to_yaml()#

Inherited method, see lisa.utils.Serializable.to_yaml()

Return a YAML string with the serialized object.

TargetConf.to_yaml_map(path, add_placeholder=False, placeholder='<no default>')#

Inherited method, see lisa.conf.SimpleMultiSrcConf.to_yaml_map()

Write a configuration file, with the key descriptions in comments.

TargetConf.to_yaml_map_str(**kwargs)#

Inherited method, see lisa.conf.MultiSrcConfABC.to_yaml_map_str()

Return the content of the file that would be create by to_yaml_map() in a string.

TargetConf.values()#: Inherited method, see collections.abc.Mapping.values()

lisa.target.TargetConf#

Attributes#

Properties#

Methods#

This Page