LISA Documentation

https://tooling.sites.arm.com/lisa
Admin
LISA (Linux Integrated System Analysis) is a toolkit for interactive analysis and automated...
Tokens:2,126,313
Snippets:5,732
Trust Score:9.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install LISA from GitLab Repository

Source: https://tooling.sites.arm.com/lisa/latest/setup

Clones the LISA GitLab repository, fetches changelog notes, installs base dependencies using a script, and initializes the Python virtual environment. This method is recommended for development or when needing a full environment setup.

```shell
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
```

--------------------------------

### Install LISA from PyPI

Source: https://tooling.sites.arm.com/lisa/latest/setup

Installs the LISA package from the Python Package Index (PyPI). This is the standard method for installing LISA on most systems. Ensure you have pip installed.

```shell
pip install lisa-linux
```

--------------------------------

### Install LISA from GitLab Repository

Source: https://tooling.sites.arm.com/lisa/latest/_sources/setup.rst

Clones the LISA repository from GitLab, fetches changelog notes, installs base dependencies, and initializes the Python virtual environment. This method provides a more direct way to get the latest code and manage dependencies.

```shell
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
```

--------------------------------

### Install LISA Packages in Editable Mode

Source: https://tooling.sites.arm.com/lisa/latest/setup

Demonstrates how to install LISA and its dependencies in editable mode using Python's standard packaging practices. This involves using the setup.py script and a requirements file.

```shell
pip install -e .
# or for development dependencies:
pip install -r devmode_requirements.txt
```

--------------------------------

### Install LISA from PyPI

Source: https://tooling.sites.arm.com/lisa/latest/_sources/setup.rst

Installs the LISA package from the Python Package Index (PyPI) using pip. This is the standard method for installing LISA if you have Python and pip set up.

```shell
pip install lisa-linux
```

--------------------------------

### Setup Logging and HoloViews

Source: https://tooling.sites.arm.com/lisa/latest/workflows/ipynb/tests/synthetics_example

Initializes LISA's logging system and configures HoloViews for plotting, typically using the Bokeh extension. This sets up the environment for data visualization and logging during test execution.

```python
import logging
from lisa.utils import setup_logging
setup_logging()

import holoviews as hv
hv.extension('bokeh')
```

--------------------------------

### LISA Logging Setup

Source: https://tooling.sites.arm.com/lisa/latest/_sources/sections/changes/transitioning_from_lisa_legacy.rst

Illustrates the updated method for setting up the LISA logger. The legacy approach used `conf.LisaLogging.setup()`, while the new approach utilizes `lisa.utils.setup_logging()`.

```Python
import logging
from conf import LisaLogging
LisaLogging.setup()
```

```Python
import logging
from lisa.utils import setup_logging
setup_logging()
```

--------------------------------

### TestEnv Initialization (LISA Legacy vs. Next)

Source: https://tooling.sites.arm.com/lisa/latest/_sources/sections/changes/transitioning_from_lisa_legacy.rst

Compares the legacy method of creating a `TestEnv` instance with the new approach using the `lisa.target.Target` class. The new method simplifies configuration and removes the need for explicit devlib module loading.

```APIDOC
LISA Legacy TestEnv Initialization:

    target_conf = {
        "platform": 'linux',
        "board": 'juno',
        "modules": [
            'bl',
            'cpufreq'
        ],
        "host": '192.168.0.1',
        "username": 'root',
        "password": 'root',
        "rtapp-calib": {
            '0': 361, '1': 138, '2': 138, '3': 352, '4': 360, '5': 353
        }
    }
    te = TestEnv(target_conf)

LISA Next Target Initialization:

    # Uses lisa.target.Target and lisa.target.TargetConf
    # Configuration keys have changed (e.g., "platform" to "kind")
    # devlib modules are loaded automatically
    # Example using TargetConf:
    target_conf = {
        "kind": 'linux',
        "name": 'juno',
        "host": '192.168.0.1',
        "username": 'root',
        "password": 'root',
        "rtapp_calib": {
            '0': 361, '1': 138, '2': 138, '3': 352, '4': 360, '5': 353
        }
    }
    te = Target(target_conf)
```

--------------------------------

### LISA Logging Setup

Source: https://tooling.sites.arm.com/lisa/latest/sections/changes/transitioning_from_lisa_legacy

Demonstrates the updated method for setting up the LISA logger, comparing the legacy approach with the new Python 3-only implementation.

```python
import logging
from conf import LisaLogging
LisaLogging.setup()
```

```python
import logging
from lisa.utils import setup_logging
setup_logging()
```

--------------------------------

### Target Configuration for Kernel Modules

Source: https://tooling.sites.arm.com/lisa/latest/_sources/setup.rst

YAML configuration snippet for LISA's target setup. It specifies the kernel source directory and the build environment for kernel modules, such as using an 'alpine' chroot for cross-compilation.

```yaml
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
```

--------------------------------

### HWMon Energy Meter Instantiation

Source: https://tooling.sites.arm.com/lisa/latest/sections/changes/transitioning_from_lisa_legacy

Illustrates two methods for creating an instance of the HWMon energy meter. The first method involves directly building the instance with necessary parameters, while the second uses a configuration file (YAML) to define the meter's properties.

```python
target = Target.from_default_conf()
res_dir = "/foo/bar"

# Directly build an instance
emeter = HWMon(target, channel_map=..., res_dir=res_dir)
```

```python
target = Target.from_default_conf()
res_dir = "/foo/bar"

# Or using a configuration file
conf = HWMonConf.from_yaml_map('path/to/hwmon_conf.yml')
emeter = HWMon.from_conf(target, conf, res_dir)
```

--------------------------------

### Disable LISA-Managed Virtual Environment

Source: https://tooling.sites.arm.com/lisa/latest/_sources/setup.rst

Disables the automatic creation and usage of a LISA-managed virtual environment by setting an environment variable. This allows users to manage their own virtual environments or operate in a pre-configured multi-tool setup.

```shell
export LISA_USE_VENV=0
```

--------------------------------

### Creating TestEnv Instance (Legacy)

Source: https://tooling.sites.arm.com/lisa/latest/sections/changes/transitioning_from_lisa_legacy

Demonstrates the legacy method of creating a TestEnv instance using a configuration dictionary. This approach is now superseded by newer class structures.

```python
target_conf = {
    "platform": 'linux',
    "board": 'juno',
    "modules": [
        'bl',
        'cpufreq'
    ],
    "host": '192.168.0.1',
    "username": 'root',
    "password": 'root',
    "rtapp-calib": {
        '0': 361, '1': 138, '2': 138, '3': 352, '4': 360, '5': 353
    }
}

te = TestEnv(target_conf)
```

--------------------------------

### Execute a Simple Profile

Source: https://tooling.sites.arm.com/lisa/latest/sections/api/generated/lisa.wlgen.rta

Demonstrates connecting to a target, defining a profile mapping task names to task objects, creating an RTA object, and running the workload within a context manager.

```python
from lisa.core.target import Target
from lisa.core.rta import RTA

# Connect to a target
target = Target.from_default_conf()

# Mapping of rt-app task names to the phases they will execute
profile = {'task1': task}

# Create the RTA object that configures the profile for the given target
wload = RTA.from_profile(target, profile=profile)

# Workloads are context managers to do some cleanup on exit
with wload:
    wload.run()
```

--------------------------------

### Read Kconfig Fragment

Source: https://tooling.sites.arm.com/lisa/latest/_sources/setup.rst

Python code snippet to read a kernel configuration fragment file from the LISA assets path. This fragment is used to configure LISA for building kernel modules, ensuring compatibility and proper setup.

```python
from pathlib import Path
from lisa._assets import ASSETS_PATH
frag_path = Path(ASSETS_PATH) / 'kmodules' / 'kconfig_fragment.config'
frag = frag_path.read_text()
print(frag)
```

--------------------------------

### Get RT-App Phase Start Times DataFrame

Source: https://tooling.sites.arm.com/lisa/latest/_modules/lisa/analysis/rta

Provides a pandas DataFrame containing the start times for all RT-App phases of a specified task. The DataFrame includes columns for the task's communication name, PID, and phase counter. The index represents the timestamp of each phase start event. It uses the internal `_get_rtapp_phases` method.

```python
def df_rtapp_phases_start(self, task=None, wlgen_profile=None):
    """
    Dataframe of phases start times.

    :param task: the (optional) rt-app task to filter for
    :type task: int or str or lisa.analysis.tasks.TaskID

    :param wlgen_profile: See :meth:`df_rtapp_loop`
    :type wlgen_profile: dict(str, lisa.wlgen.rta.RTAPhaseBase) or None

    :returns: a :class:`pandas.DataFrame` with:

      * A  ``__comm`` column: the actual rt-app trace task name
      * A  ``__pid``  column: the PID of the task
      * A  ``phase``  column: the phases counter for each ``__pid``:``__comm`` task

      The ``index`` represents the timestamp of a phase start event.
    """
    return self._get_rtapp_phases('start', task, wlgen_profile=wlgen_profile)
```

--------------------------------

### Bisector Execution Example

Source: https://tooling.sites.arm.com/lisa/latest/_sources/bisector/man/man.rst

A shell command demonstrating how to run the bisector tool with steps defined in a configuration file, potentially using systemd-run for enhanced process management.

```shell
# Run the steps and generate a report.
# systemd-run will be used for all steps by using "-o" without specifying a
# step name or category.
```

--------------------------------

### Get rtapp_main Execution Time Range

Source: https://tooling.sites.arm.com/lisa/latest/_modules/lisa/analysis/rta

Calculates and returns the time range (start and end times) during which the rt-app main thread was executing. It relies on the 'start' and 'end' events from the rtapp_main DataFrame. The output is a tuple of (start_time, end_time).

```python
@property
@memoized
@df_rtapp_main.used_events
def rtapp_window(self):
    """
    Return the time range the rt-app main thread executed.

    :returns: a tuple(start_time, end_time)
    """
    df = self.df_rtapp_main()
    return (
        df[df.event == 'start'].index[0],
        df[df.event == 'end'].index[0])
```

--------------------------------

### TargetConf Initialization Example

Source: https://tooling.sites.arm.com/lisa/latest/_modules/lisa/target

Demonstrates how to create an instance of TargetConf by passing a dictionary of connection settings.

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

--------------------------------

### Set LISA Python Binary Environment Variable

Source: https://tooling.sites.arm.com/lisa/latest/_sources/setup.rst

Sets an environment variable to specify which Python 3 binary LISA should use. This is useful when multiple Python versions are installed on the system, ensuring LISA utilizes the correct interpreter.

```shell
export LISA_PYTHON=<name of Python 3 binary>
```

--------------------------------

### lisa.wlgen.rta.PropertyBase Methods

Source: https://tooling.sites.arm.com/lisa/latest/_sources/sections/api/generated/lisa.wlgen.rta.RunForTimeWload.rst

Documentation for the PropertyBase class in lisa.wlgen.rta, specifically its alternative constructor.

```APIDOC
PropertyBase:
  from_key()
    Alternative constructor that is available with the same signature for all properties.
    Inherited from lisa.wlgen.rta.PropertyBase.
```

--------------------------------

### Running an RTA Workload on a Target

Source: https://tooling.sites.arm.com/lisa/latest/_modules/lisa/wlgen/rta

Provides an example of how to connect to a target system, define a workload profile, create an RTA object, and execute the workload. It demonstrates the use of RTA.from_profile and the context manager pattern for running workloads.

```python
from lisa.wlgen.rta import RTA, RTAPhase, PeriodicWload, RunWload, SleepWload, override, delete, WithProperties, task_factory, RTAConf
from lisa.fuzz import Float, Int
from lisa.platforms.platinfo import PlatformInfo
from lisa.target import Target

# Assuming 'task' is defined as shown in previous examples
# task = ...

###################################################
# Alternative 1: create a simple profile and run it
###################################################

# Connect to a target
target = Target.from_default_conf()

# Mapping of rt-app task names to the phases they will execute
profile = {'task1': task}

# Create the RTA object that configures the profile for the given target
wload = RTA.from_profile(target, profile=profile)

# Workloads are context managers to do some cleanup on exit
with wload:
    wload.run()
```

--------------------------------

### Get RT-App Task Window

Source: https://tooling.sites.arm.com/lisa/latest/_modules/lisa/analysis/rta

Retrieves the start and end times for a specified rt-app task. It filters the task's events to find the first 'start' and 'end' events to determine the overall task execution window. Requires the task identifier.

```python
    @memoized
    @df_rtapp_task.used_events
    def task_window(self, task):
        """
        Return the start end end time for the specified task.

        :param task: the rt-app task to filter for
        :type task: int or str or lisa.analysis.tasks.TaskID
        """
        task_df = self.df_rtapp_task(task)
        start_time = task_df[task_df.event == "start"].index[0]
        end_time = task_df[task_df.event == "end"].index[0]

        return (start_time, end_time)
```

--------------------------------

### LISA Target and TargetConf API

Source: https://tooling.sites.arm.com/lisa/latest/sections/changes/transitioning_from_lisa_legacy

Details the new `lisa.target.Target` and `lisa.target.TargetConf` classes, including their constructors and methods for creating Target instances. The configuration parameters have been updated, and module loading is now automatic.

```APIDOC
lisa.target.Target
  __init__(self, conf: TargetConf)
    Initializes a Target instance with a TargetConf object.
    Parameters:
      conf: The TargetConf object containing target configuration.

  from_default_conf() -> Target
    Creates a Target instance from the default configuration file.

  from_cli() -> Target
    Creates a Target instance from command-line arguments.

lisa.target.TargetConf
  __init__(self, **kwargs)
    Initializes a TargetConf instance from keyword arguments.
    Parameters:
      platform (str): Renamed from 'kind'. Specifies the target platform.
      board (str): Pretty-printing name, has no extra impact.
      modules (list[str]): List of devlib modules to load (all loadable modules are loaded by default). Can specify modules to exclude.
      host (str): Host IP address.
      username (str): Username for connection.
      password (str): Password for connection.
      rtapp-calib (dict): Calibration data.

Configuration Changes:
- "platform" is now "kind".
- "board" is replaced by a "name" parameter for pretty-printing.
- Devlib modules are loaded automatically; specify exclusions if needed.
- Configuration file format changed from JSON to YAML (`target_conf.yml`).
```

--------------------------------

### RTAEventsAnalysis: df_rtapp_phase_start - Get RT-App Phase Start Timestamp

Source: https://tooling.sites.arm.com/lisa/latest/sections/api/generated/lisa.analysis.rta.RTAEventsAnalysis

Retrieves the start timestamp for a specified RT-App phase for a given task. Supports filtering by phase ID or name and allows specifying the return dataframe format (pandas or polars-lazyframe). Requires 'userspace@rtapp_loop' trace events.

```APIDOC
RTAEventsAnalysis.df_rtapp_phase_start(task, phase=0, wlgen_profile=None, **kwargs, df_fmt=None)

Description:
  Start of the specified phase for a given task. A negative phase value can be used to count from the oldest, e.g. -1 represents the last phase.

Parameters:
  task (int | str | lisa.analysis.tasks.TaskID): The rt-app task to filter for.
  phase (int | str): The ID (or name with wlgen_profile) of the phase start to return.
  wlgen_profile (dict(str, lisa.wlgen.rta.RTAPhaseBase) | None): See df_rtapp_loop().
  df_fmt (str | None): Format of dataframe to return. One of: "pandas" or "polars-lazyframe".

Returns:
  The return type is determined by the dataframe format chosen for the trace object.

Required trace events:
  * userspace@rtapp_loop
```

--------------------------------

### Bisector Configuration Example

Source: https://tooling.sites.arm.com/lisa/latest/_sources/bisector/man/man.rst

An example YAML file defining a sequence of steps for the bisector tool. Each step specifies a class, command, and execution parameters like timeouts and trials.

```yaml
# Top-level "steps" key is important as the same file can be used to host other
# information.
steps:

   # build step will interpret a non-zero exit status of the command as a
   # bisect untestable status, and zero exit status as bisect good.
    - 
      class: BuildStep
      cmd: make defconfig Image dtbs
      trials: 1

   # flash step will interpret a non-zero exit status of the command as a
   # bisect abort, and zero exit status ignored.
   - 
      class: FlashStep
      cmd: flash-my-board
      timeout: 180
      trials: 5

   # reboot step will interpret a non-zero exit status of the command as a
   # bisect abort, and zero exit status as bisect good.
    - 
      class: reboot
      timeout: 300
      trials: 10
      cmd: reboot-my-board

    # exekall LISA test will interpret a non-zero exit status of the command
    # as bisect bad, and a zero exit status as bisect good.
    - 
      class: LISA-test
      name: one-small-task
      # Using systemd-run ensures all child process is killed if the session
      # is interrupted
      use-systemd-run: true
      timeout: 3600
      cmd: lisa-test 'OneSmallTask*'
```

--------------------------------

### Get RT-App Phase Window

Source: https://tooling.sites.arm.com/lisa/latest/_modules/lisa/analysis/rta

Returns the start and end time window for a specific phase of an rt-app task. It utilizes helper methods to fetch phase start and end timestamps. Supports negative phase indexing (e.g., -1 for the last phase).

```python
    @memoized
    @df_rtapp_phases_start.used_events
    def task_phase_window(self, task, phase, wlgen_profile=None):
        """
        Return the window of a requested task phase.

        For the specified ``task`` it returns a tuple with the (start, end)
        time of the requested ``phase``. A negative phase number can be used to
        count phases backward from the last (-1) toward the first.

        :param task: the rt-app task to filter for
        :type task: int or str or lisa.analysis.tasks.TaskID

        :param phase: the ID (or name with ``wlgen_profile``) of the phase
            to consider.
        :type phase: int or str

        :param wlgen_profile: See :meth:`df_rtapp_loop`
        :type wlgen_profile: dict(str, lisa.wlgen.rta.RTAPhaseBase) or None

        :rtype: PhaseWindow
        """
        phase_start = self.df_rtapp_phase_start(
            task,
            phase,
            wlgen_profile=wlgen_profile,
        )
        phase_end = self.df_rtapp_phase_end(
            task,
            phase,
            wlgen_profile=wlgen_profile,
        )

        return PhaseWindow(phase, phase_start, phase_end, {})
```

--------------------------------

### Get RTApp Phase Start/End Events

Source: https://tooling.sites.arm.com/lisa/latest/_modules/lisa/analysis/rta

Filters and sorts RTApp loop events to extract specific phase start ('start') or end ('end') events. It ensures only the relevant event for each phase loop iteration is kept, preparing data for duration calculation.

```python
@TraceAnalysisBase.df_method
    @df_rtapp_loop.used_events
    def _get_rtapp_phases(self, event, task, wlgen_profile=None):
        """
        Filters and sorts RTApp loop events to get specific phase events.

        :param event: The event type to filter ('start' or 'end').
        :type event: str
        :param task: The rt-app task to filter for.
        :type task: int or str or lisa.analysis.tasks.TaskID
        :param wlgen_profile: See :meth:`df_rtapp_loop`
        :type wlgen_profile: dict(str, lisa.wlgen.rta.RTAPhase) or None
        :returns: DataFrame containing filtered phase events.
        """
        df = self.df_rtapp_loop(task, wlgen_profile=wlgen_profile)
        df = df[df.event == event]

        if event == 'start':
            df = df[df.phase_loop == 0]
        elif event == 'end':
            df = df.sort_values(by=['phase_loop', 'thread_loop'],
                                ascending=False)
        
        grouped = df.groupby(
            ['__comm', '__pid', 'phase', 'event'],
            observed=True,
            sort=False,
            group_keys=False,
        )
        df = grouped.head(1)

        kept_cols = ['__comm', '__pid', 'phase', 'properties']
        kept_cols = order_as(
            set(kept_cols) & set(df.columns),
            order_as=kept_cols
        )
        df = (
            df.sort_index()[kept_cols]
            .reset_index()
            .set_index([col for col in kept_cols if col != 'properties'])
        )
        df.index.name = 'phases'

        return df
```

--------------------------------

### Energy Meter Initialization

Source: https://tooling.sites.arm.com/lisa/latest/_sources/sections/changes/transitioning_from_lisa_legacy.rst

Shows two methods for initializing energy meter instances, specifically for `HWMon`. Instances can be built directly by passing parameters or created via a configuration object loaded from a YAML file using `*Conf.from_yaml_map`.

```python
target = Target.from_default_conf()
res_dir = "/foo/bar"

# Directly build an instance
emeter = HWMon(target, channel_map=..., res_dir=res_dir)
```

```python
conf = HWMonConf.from_yaml_map('path/to/hwmon_conf.yml')
emeter = HWMon.from_conf(target, conf, res_dir)
```

--------------------------------

### Get Specific RT-App Phase Start Time

Source: https://tooling.sites.arm.com/lisa/latest/_modules/lisa/analysis/rta

Retrieves the start timestamp for a specific RT-App phase of a given task. Supports phase identification by integer index (including negative indexing from the end) or by name if a `wlgen_profile` is provided. It leverages `df_rtapp_phases_start` and `df_rtapp_phases_end` internally.

```python
def df_rtapp_phase_start(self, task, phase=0, wlgen_profile=None):
    """
    Start of the specified phase for a given task.

    A negative phase value can be used to count from the oldest, e.g. -1
    represents the last phase.

    :param task: the rt-app task to filter for
    :type task: int or str or lisa.analysis.tasks.TaskID

    :param phase: the ID (or name with ``wlgen_profile``) of the phase
        start to return.
    :type phase: int or str

    :param wlgen_profile: See :meth:`df_rtapp_loop`
    :type wlgen_profile: dict(str, lisa.wlgen.rta.RTAPhaseBase) or None

    :returns: the requires task's phase start timestamp
    """
    return self._get_task_phase('start', task, phase, wlgen_profile=wlgen_profile)
```

--------------------------------

### Workload Generation (RTA) Configuration

Source: https://tooling.sites.arm.com/lisa/latest/_sources/sections/changes/transitioning_from_lisa_legacy.rst

Demonstrates the evolution of workload generation using the RTA class. LISA legacy required explicit configuration via `wload.conf()`, whereas LISA next integrates configuration into alternative constructors like `RTA.from_profile` and uses a more structured profile definition.

```python
profile = {}
profile["my_task"] = Periodic(duty_cycle_pct=30).get()

wload = RTA(te.target, "foo", calibration)
wload.conf(kind='profile', params=profile)
```

```python
profile = {
    'my_task': RTAPhase(
        prop_wload=PeriodicWload(
            duty_cycle_pct=30,
            period=16e-3,
            duration=1,
        )
    )
}

wload = RTA.from_profile(te, "foo", profile, res_dir, calibration)
```

--------------------------------

### Get RTApp Phases DataFrame (Python)

Source: https://tooling.sites.arm.com/lisa/latest/sections/api/generated/lisa.analysis.rta.RTAEventsAnalysis

Retrieves actual start times and durations for RTApp phases. It filters by a specified task and can optionally use a wlgen_profile for phase naming. The output is a pandas DataFrame with phase details, duration, and properties, indexed by phase start time. Requires 'userspace@rtapp_loop' trace events.

```APIDOC
RTAEventsAnalysis.df_phases(task, wlgen_profile=None, df_fmt=None)

  Get phases actual start times and durations.

  Parameters:
    task (int | str | lisa.analysis.tasks.TaskID): The rt-app task to filter for.
    wlgen_profile (dict[str, lisa.wlgen.rta.RTAPhase] | None): Profile for phase extraction, see df_rtapp_loop().
    df_fmt (str | None): Format of dataframe to return. Options: "pandas", "polars-lazyframe".

  Returns:
    pandas.DataFrame: With index as start time and columns 'phase', 'duration', 'properties'.

  Required trace events:
    userspace@rtapp_loop
```

--------------------------------

### Commit Message Format Example

Source: https://tooling.sites.arm.com/lisa/latest/contributors_guide

Example of a commit message structure for the LISA project. It follows the 50/72 rule and includes a header highlighting impacted files/classes, prefixed with the module path (e.g., 'lisa.wlgen.rta'). A tag like 'FIX', 'FEATURE', or 'BREAKING CHANGE' is required for changelog generation.

```git
lisa.foo.bar: Fix some foobar

FIX

This fix fixes fixable fixtures by affixing an postfix operator.

```

--------------------------------

### lisa.wlgen.rta.RunForTimeWload Attributes, Properties, and Methods

Source: https://tooling.sites.arm.com/lisa/latest/_sources/sections/api/generated/lisa.wlgen.rta.RunForTimeWload.rst

Comprehensive documentation for the RunForTimeWload class in lisa.wlgen.rta, covering its attributes, properties, and various methods including arithmetic operations and configuration checks.

```APIDOC
RunForTimeWload:
  Attributes:
    KEY: Identifier for the workload type.
    JSON_KEY: Key used in JSON serialization.
    OPTIMIZE_JSON_KEYS: Flag to optimize JSON keys.
    REQUIRED_KCONFIG_KEYS: List of required kernel configuration keys.

  Properties:
    json_value: Returns the JSON representation of the workload.
    key: Returns the unique key for this workload instance.
    logger: Provides a logger instance for this class.
    val: Returns the value associated with the workload.

  Methods:
    HASH_COERCE(): Coerces the object to a hashable type.
    __add__(other): Overloads the addition operator.
    __and__(other): Overloads the bitwise AND operator.
    __await__(): Returns an awaitable object.
    __mul__(other): Overloads the multiplication operator.
    __rmul__(other): Overloads the right multiplication operator.
    check_kconfig(): Validates required kernel configuration keys.
    find_cls(name): Finds a class by its name.
    from_duration(duration: int): Builds a workload from a duration in seconds.
    from_key(): Alternative constructor available for all properties.
    get_logger(): Provides a logger instance named after the class.
    log_locals(): Logs local variables of the calling function for debugging.
    to_default_json(): Returns default values for JSON keys.
    to_events(): Converts workload to a list of events.
    to_json(): Returns JSON content of the property as Python objects.
```

--------------------------------

### LISA Target Creation

Source: https://tooling.sites.arm.com/lisa/latest/_sources/sections/changes/transitioning_from_lisa_legacy.rst

Describes how `lisa.target.Target` instances can be instantiated. They can be created directly from a configuration file using `from_default_conf` or programmatically via the command-line interface using `from_cli`.

```APIDOC
lisa.target.Target:
  __init__(self, ...)
    Initializes a Target instance.

  from_default_conf():
    Creates a Target instance from the default configuration file.
    Returns: Target

  from_cli():
    Creates a Target instance from CLI arguments.
    Returns: Target
```

--------------------------------

### Get Trace Time Range

Source: https://tooling.sites.arm.com/lisa/latest/_modules/lisa/trace

Retrieves the start and end times of the trace. It uses a memoized helper method `_get_time_range` which fetches the 'time-range' metadata.

```python
    @property
    def basetime(self):
        return self._get_time_range()[0]

    @property
    def endtime(self):
        return self._get_time_range()[1]

    @property
    def start(self):
        return self.basetime

    @property
    def end(self):
        return self.endtime

    @memoized
    def _get_time_range(self, parser=None):
        return self._get_metadata('time-range', parser=parser)
```

--------------------------------

### Instantiate Target Connection

Source: https://tooling.sites.arm.com/lisa/latest/workflows/ipynb/examples/typical_experiment

Provides an example of how to create an instance of the `Target` class to connect to a remote or local system. This configuration includes specifying the target's kind (e.g., 'linux'), a unique name, connection details like host and credentials (username, password).

```python
# target = Target(
#     kind='linux',
#     name='myhikey960',
#     host='192.168.0.1',
#     username='root',
#     password='root',
# )
```

--------------------------------

### Get Path for KeyDescBase

Source: https://tooling.sites.arm.com/lisa/latest/_modules/lisa/conf

Retrieves the hierarchical path for a configuration key. It starts with the current key's name and prepends the parent's path if a parent exists.

```python
class KeyDescBase:
    # ... other methods ...
    def path(self):
        """
        Get the path of the key.
        """
        curr = [self.name]
        if self.parent is None:
            return curr
        return self.parent.path + curr
```

--------------------------------

### Build LISA Documentation

Source: https://tooling.sites.arm.com/lisa/latest/_sources/contributors_guide.rst

Provides the shell command to build the project's HTML documentation. It assumes the 'doc' optional dependencies of the 'lisa' package are installed.

```shell
lisa-doc-build
```

--------------------------------

### Exekall Command Line Usage Examples

Source: https://tooling.sites.arm.com/lisa/latest/_sources/exekall/man/man.rst

Provides examples of common `exekall` command-line invocations for running processes, merging artifacts, and comparing databases. Highlights options for controlling artifact directories and filtering discovered expressions.

```bash
# Run exekall, specifying artifact directory
exekall run --artifact-dir ./my_artifacts

# Compare artifact databases
exekall compare

# Run with specific filters for discovered expressions
exekall run --allow '*Conf' --goal '*Stage2'

# Merge artifact folders
exekall merge --artifact-dir ./merged_artifacts ./artifact_dir1 ./artifact_dir2
```

--------------------------------

### LISA Utils: Logging Setup

Source: https://tooling.sites.arm.com/lisa/latest/sections/api/generated/lisa.utils

The `setup_logging` function initializes the logging configuration for all LISA modules. This ensures consistent and standardized logging practices across the project.

```APIDOC
setup_logging(level=None, format=None, handlers=None)
  Initialize logging used for all the LISA modules.
  Parameters:
    level: The logging level (e.g., 'INFO', 'DEBUG').
    format: The log message format string.
    handlers: A list of logging handlers to use.
  Returns: None. Configures the root logger.
```
Tokens:
Raw