lisa.wlgen.rta#

This module implements an rt-app JSON programmatic configuration file generator, along the class to run it directly on a Target. This is the backbone of our scheduler tests, allowing to easily run custom workloads.

The most important classes are:

RTA: Subclass of lisa.wlgen.workload.Workload that can run rt-app on a given Target.
RTAConf: An rt-app configuration file. It can be created either from a template JSON or using a programmatic API.
RTAPhase: The entry point of the programmatic API to build rt-app configuration, phase by phase.
WloadPropertyBase: The base class of all workloads that can be given to an RTAPhase. It has the following subclasses:
- BarrierWload: Workload for the barrier event.
- IOWload: Workload for the iorun event.
- LockWload: Workload for the lock and unlock event.
- MemWload: Workload for the mem event.
- PeriodicWload: Periodic task workload.
- RunForTimeWload: Workload for the runtime event.
- RunWload: Workload for the run event.
- SleepWload: Workload for the sleep event.
- TimerWload: Workload for the timer event.
- WaitWload: Workload for the wait, signal and broad events.
- WloadSequence: Sequence of workloads, to be executed one after another.
- YieldWload: Workload for the yield event.

A typical workload would be created this way:

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

task = (
    # Phases can be added together so they will be executed in order
    RTAPhase(
        prop_name='first',
        # The workload of a phase is a subclass of WloadPropertyBase
        prop_wload=RunWload(1),
        prop_uclamp=(256, 512),
    ) +
    RTAPhase(
        prop_name='second',
        prop_wload=(
            # Workloads can be added together too
            SleepWload(5) +
            PeriodicWload(
                duty_cycle_pct=20,
                period=16e-3,
                duration=2,
            )
        )
    )
)

# Alternatively, an async API is available to define tasks.
# Each workload awaited will become a new phase, and WithProperties async
# context manager can be used to set properties for multiple such phases.
#
# Additionally, the random data generators from lisa.fuzz can be used as well.

@task_factory
async def make_task(run_duration):
    async with WithProperties(name='first', uclamp=(256, 512)):
        await RunWload(run_duration)

    # Create a bounded random value
    sleep_duration = await Float(min_=1, max_=5)
    sleep_duration = round(sleep_duration, 2)

    async with WithProperties(name='second'):
        # We could await once on each workload, but that would lead to 2 phases
        # instead of one. Whether this is desired or an issue depends on the
        # use-case.
        await (
            SleepWload(sleep_duration) +
            PeriodicWload(
                duty_cycle_pct=20,
                period=16e-3,
                duration=2,
            )
        )

# "seed" is used to initialize the random number generator. If not
# provided, the seed will be random.
task = make_task(run_duration=1)(seed=1)

# Important note: all the classes in this module are immutable. Modifying
# attributes is not allowed, use the RTAPhase.with_props() if you want to
# get a new object with updated properties.

# You can create a modified RTAPhase using with_props(), and the property
# will be combined with the existing ones.
# For util clamp, it means taking the toughest restrictions, which in this
# case are (300, 512).
task = task.with_props(uclamp=(300, 800))

# If you want to set the clamp and override any existing value rather than
# combining it, you can use the override() function
task = task.with_props(uclamp=override((400, 700)))

# Similarly, you can delete any property that was already set with delete()
task = task.with_props(uclamp=delete())


###################################################
# 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()


###################################################
# Alternative 2: a more complex example generating multiple tasks and dumping a JSON.
###################################################

@task_factory
async def make_profile(plat_info, **kwargs):
    nr_tasks = await Int(1, plat_info['cpus-count'])

    profile = {}
    for i in range(nr_tasks):
        async with WithProperties(name=f'task{i}'):
            profile[f'task{i}'] = await make_task(**kwargs)

    # If we return anything else than None, the return value will not be
    # replaced by the phase defined in the function.
    return profile


plat_info = PlatformInfo.from_yaml_map('./doc/traces/plat_info.yml')

# Display a few randomly generated tasks
for _ in range(2):
    # When called, profile_gen() will create a random profiles
    profile_gen = make_profile(plat_info, run_duration=1)

    # seed (or rng) can be fixed for reproducible results
    # profile = profile_gen(seed=1)
    profile = profile_gen(seed=None)

    conf = RTAConf.from_profile(profile, plat_info=plat_info)
    print(conf.json)

Classes

`AndProperty`	Semigroup property with the `&` operation.
`BarrierWload`	Workload for the `barrier` event.
`CPUProperty`	CPU affinity property.
`ComposableMultiConcretePropertyBase`	Base class for properties that are a collection of values.
`ConcretePropertyBase`	Base class for concrete properties.
`ContaminatingProperty`	Base class for properties that will “contaminate” other instances when combined with them, even if they are closer to the leaf.
`DeadlineDeadlineProperty`	`SCHED_DEADLINE` scheduler policy’s deadline property.
`DeadlinePeriodProperty`	`SCHED_DEADLINE` scheduler policy’s period property.
`DeadlineRuntimeProperty`	`SCHED_DEADLINE` scheduler policy’s runtime property or, since Linux 6.12, `SCHED_OTHER` scheduler policy’s custom slice length.
`DeletedProperty`	Forcefully delete the given property, recursively for all subtrees.
`DurationWload`	Workload parametrized by a duration.
`DutyCycleSweepPhase`	Sweep on the `duty_cycle_pct` parameter of a `PeriodicWload`.
`IOWload`	Workload for the `iorun` event.
`LeafPrecedenceProperty`	Invert the usual combination of order (root to leaf) of property values.
`LockWload`	Workload for the `lock` and `unlock` event.
`MaxProperty`	Semigroup property with the `max()` operation.
`MemWload`	Workload for the `mem` event.
`MetaPropertyBase`	Base class for meta properties.
`MetaStoreProperty`	Plain key-value storage to be used as the user see fit.
`MinProperty`	Semigroup property with the `min()` operation.
`MultiConcreteProperty`	Base class for properties setting multiple JSON keys at once.
`MultiProperty`	Base class for properties setting multiple JSON keys at once.
`NUMAMembindProperty`	NUMA node membind property.
`NameProperty`	Name the phase.
`OrProperty`	Semigroup property with the `\|` operation.
`OverridenProperty`	Forcefully override the value of another property.
`ParametricPhase`	Base class for phases with special behavior beyond their properties.
`PeriodicWload`	Periodic task workload.
`Phase`	Descriptor for an rt-app load phase.
`PlaceHolderValue`	Placeholder value to be passed to `RTAPhaseProperties.from_polymorphic()` to hijack the usual `PropertyBase.from_key()` path and allow `PROPERTY_CLS.from_key` to be called instead.
`PolicyProperty`	Scheduler policy property.
`PriorityProperty`	Task scheduler priority property.
`PropertyBase`	Base class of all properties.
`PropertyMeta`	Metaclass for properties.
`PropertyWrapper`	Base class for properties that are merely wrapper around another property instance.
`RTA`	An rt-app workload.
`RTAConf`	JSON configuration for rt-app.
`RTAMonad`	Monad from derived from `lisa.monad.StateDiscard` used to define `RTAPhaseBase` in a more natural way.
`RTAPhase`	Leaf in a tree of `RTAPhaseTree`.
`RTAPhaseBase`	Base class for rt-app phase modelisation.
`RTAPhaseProperties`	Hold the properties of an `RTAPhaseBase`.
`RTAPhaseTree`	Tree node in an `_RTAPhaseTreeBase`.
`RTAPhaseTreeChildren`	Proxy object used by `RTAPhaseTree` to store the children list.
`RunForTimeWload`	Workload for the `runtime` event.
`RunWload`	Workload for the `run` event.
`SimpleConcreteProperty`	Base class for simple properties that maps to JSON.
`SimpleProperty`	Simple property with dynamic `key`.
`SleepWload`	Workload for the `sleep` event.
`SweepPhase`	Parametric phase creating children by setting the property `key` to values found in `values`, in order.
`TaskGroupProperty`	Task group property.
`TimerWload`	Workload for the `timer` event.
`UclampProperty`	Set util clamp (uclamp) values.
`WaitWload`	Workload for the `wait`, `signal` and `broad` events.
`WithProperties`	Asynchronous context manager used to set properties on the enclosed phases.
`WloadPropertyBase`	Phase workload.
`WloadSequence`	Sequence of workloads, to be executed one after another.
`YieldWload`	Workload for the `yield` event.

Functions

`delete()`	Remove the given property from the phase::.
`leaf_precedence()`	Give precedence to the leaf values when combining with `&`::.
`override()`	Override a property with the given value, rather than combining it with the property-specific `&` implementation::.
`task_factory()`	Coroutine function decorator allowing to create tasks using actions from both `RTAMonad` and `lisa.fuzz.GenMonad`.

Exceptions

CalibrationError

Exception raised when the rt-app calibration is not consistent with the CPU capacities in a way or another.

lisa.wlgen.rta#

This Page