mirror of
https://github.com/ARM-software/workload-automation.git
synced 2025-01-18 20:11:20 +00:00
doc: Make config listsing a consistent style
This commit is contained in:
parent
b6e91630b8
commit
716af1b966
@ -479,12 +479,12 @@ All plugins can be parametrized. Parameters are specified using
|
|||||||
:class:`wa.framework.plugin.Parameter` instances. The following attributes can be
|
:class:`wa.framework.plugin.Parameter` instances. The following attributes can be
|
||||||
specified on parameter creation:
|
specified on parameter creation:
|
||||||
|
|
||||||
name
|
:name:
|
||||||
This is the only mandatory argument. The name will be used to create a
|
This is the only mandatory argument. The name will be used to create a
|
||||||
corresponding attribute in the plugin instance, so it must be a valid
|
corresponding attribute in the plugin instance, so it must be a valid
|
||||||
Python identifier.
|
Python identifier.
|
||||||
|
|
||||||
kind
|
:kind:
|
||||||
This is the type of the value of the parameter. This must be an
|
This is the type of the value of the parameter. This must be an
|
||||||
callable. Normally this should be a standard Python type, e.g. ``int``
|
callable. Normally this should be a standard Python type, e.g. ``int``
|
||||||
or ``float``, or one the types defined in :mod:`wa.utils.types`.
|
or ``float``, or one the types defined in :mod:`wa.utils.types`.
|
||||||
@ -494,7 +494,7 @@ kind
|
|||||||
valid value for a parameter. If you don't want to allow
|
valid value for a parameter. If you don't want to allow
|
||||||
``None``, then set ``mandatory`` (see below) to ``True``.
|
``None``, then set ``mandatory`` (see below) to ``True``.
|
||||||
|
|
||||||
allowed_values
|
:allowed_values:
|
||||||
A list of the only allowed values for this parameter.
|
A list of the only allowed values for this parameter.
|
||||||
|
|
||||||
.. note:: For composite types, such as ``list_of_strings`` or
|
.. note:: For composite types, such as ``list_of_strings`` or
|
||||||
@ -502,11 +502,11 @@ allowed_values
|
|||||||
the value will be checked against ``allowed_values`` rather
|
the value will be checked against ``allowed_values`` rather
|
||||||
than the composite value itself.
|
than the composite value itself.
|
||||||
|
|
||||||
default
|
:default:
|
||||||
The default value to be used for this parameter if one has not been
|
The default value to be used for this parameter if one has not been
|
||||||
specified by the user. Defaults to ``None``.
|
specified by the user. Defaults to ``None``.
|
||||||
|
|
||||||
mandatory
|
:mandatory:
|
||||||
A ``bool`` indicating whether this parameter is mandatory. Setting this
|
A ``bool`` indicating whether this parameter is mandatory. Setting this
|
||||||
to ``True`` will make ``None`` an illegal value for the parameter.
|
to ``True`` will make ``None`` an illegal value for the parameter.
|
||||||
Defaults to ``False``.
|
Defaults to ``False``.
|
||||||
@ -521,13 +521,13 @@ mandatory
|
|||||||
(e.g. something like login credentials), should you consider
|
(e.g. something like login credentials), should you consider
|
||||||
making it mandatory.
|
making it mandatory.
|
||||||
|
|
||||||
constraint
|
:constraint:
|
||||||
This is an additional constraint to be enforced on the parameter beyond
|
This is an additional constraint to be enforced on the parameter beyond
|
||||||
its type or fixed allowed values set. This should be a predicate (a function
|
its type or fixed allowed values set. This should be a predicate (a function
|
||||||
that takes a single argument -- the user-supplied value -- and returns
|
that takes a single argument -- the user-supplied value -- and returns
|
||||||
a ``bool`` indicating whether the constraint has been satisfied).
|
a ``bool`` indicating whether the constraint has been satisfied).
|
||||||
|
|
||||||
override
|
:override:
|
||||||
A parameter name must be unique not only within an plugin but also
|
A parameter name must be unique not only within an plugin but also
|
||||||
with that plugin's class hierarchy. If you try to declare a parameter
|
with that plugin's class hierarchy. If you try to declare a parameter
|
||||||
with the same name as already exists, you will get an error. If you do
|
with the same name as already exists, you will get an error. If you do
|
||||||
|
@ -237,52 +237,43 @@ All ApkWorkloads have parameters that affect the way in which APK files are
|
|||||||
resolved, ``exact_abi``, ``force_install`` and ``prefer_host_package``. Their
|
resolved, ``exact_abi``, ``force_install`` and ``prefer_host_package``. Their
|
||||||
exact behaviours are outlined below.
|
exact behaviours are outlined below.
|
||||||
|
|
||||||
.. confval:: exact_abi
|
:exact_abi: If this setting is enabled WA's resource resolvers will look for the
|
||||||
|
devices ABI with any native code present in the apk. By default this setting
|
||||||
|
is disabled since most apks will work across all devices. You may wish to
|
||||||
|
enable this feature when working with devices that support multiple ABI's
|
||||||
|
(like 64-bit devices that can run 32-bit APK files) and are specifically
|
||||||
|
trying to test one or the other.
|
||||||
|
|
||||||
If this setting is enabled WA's resource resolvers will look for the devices
|
:force_install: If this setting is enabled WA will *always* use the APK file on
|
||||||
ABI with any native code present in the apk. By default this setting is
|
the host, and re-install it on every iteration. If there is no APK on the
|
||||||
disabled since most apks will work across all devices. You may wish to enable
|
host that is a suitable version and/or ABI for the workload WA will error
|
||||||
this feature when working with devices that support multiple ABI's (like
|
when ``force_install`` is enabled.
|
||||||
64-bit devices that can run 32-bit APK files) and are specifically trying to
|
|
||||||
test one or the other.
|
|
||||||
|
|
||||||
.. confval:: force_install
|
:prefer_host_package: This parameter is used to specify a preference over host
|
||||||
|
or target versions of the app. When set to ``True`` WA will prefer the host
|
||||||
|
side version of the APK. It will check if the host has the APK and whether it
|
||||||
|
meets the version requirements of the workload. If so, and the target also
|
||||||
|
already has same version nothing will be done, otherwise WA will overwrite
|
||||||
|
the targets installed application with the host version. If the host is
|
||||||
|
missing the APK or it does not meet version requirements WA will fall back to
|
||||||
|
the app on the target if present and is a suitable version. When this
|
||||||
|
parameter is set to ``False`` WA will prefer to use the version already on
|
||||||
|
the target if it meets the workloads version requirements. If it does not it
|
||||||
|
will fall back to searching the host for the correct version. In both modes
|
||||||
|
if neither the host nor target have a suitable version, WA will produce and
|
||||||
|
error and will not run the workload.
|
||||||
|
|
||||||
If this setting is enabled WA will *always* use the APK file on the host, and
|
:version: This parameter is used to specify which version of uiautomation for
|
||||||
re-install it on every iteration. If there is no APK on the host that is a
|
the workload is used. In some workloads e.g. ``geekbench`` multiple versions
|
||||||
suitable version and/or ABI for the workload WA will error when
|
with drastically different UI's are supported. A APKs version will be
|
||||||
``force_install`` is enabled.
|
|
||||||
|
|
||||||
.. confval:: prefer_host_package
|
|
||||||
|
|
||||||
This parameter is used to specify a preference over host or target versions
|
|
||||||
of the app. When set to ``True`` WA will prefer the host side version of the
|
|
||||||
APK. It will check if the host has the APK and whether it meets the version
|
|
||||||
requirements of the workload. If so, and the target also already has same
|
|
||||||
version nothing will be done, otherwise WA will overwrite the targets
|
|
||||||
installed application with the host version. If the host is missing the APK
|
|
||||||
or it does not meet version requirements WA will fall back to the app on the
|
|
||||||
target if present and is a suitable version. When this parameter is set to
|
|
||||||
``False`` WA will prefer to use the version already on the target if it meets
|
|
||||||
the workloads version requirements. If it does not it will fall back to
|
|
||||||
searching the host for the correct version. In both modes if neither the host
|
|
||||||
nor target have a suitable version, WA will produce and error and will not
|
|
||||||
run the workload.
|
|
||||||
|
|
||||||
.. confval:: version
|
|
||||||
|
|
||||||
This parameter is used to specify which version of uiautomation for the
|
|
||||||
workload is used. In some workloads e.g. ``geekbench`` multiple versions with
|
|
||||||
drastically different UI's are supported. A APKs version will be
|
|
||||||
automatically extracted therefore it is possible to have multiple apks for
|
automatically extracted therefore it is possible to have multiple apks for
|
||||||
different versions of a workload present on the host and select between which
|
different versions of a workload present on the host and select between which
|
||||||
is used for a particular job by specifying the relevant version in your
|
is used for a particular job by specifying the relevant version in your
|
||||||
:ref:`agenda <agenda>`.
|
:ref:`agenda <agenda>`.
|
||||||
|
|
||||||
.. confval:: variant_name
|
:variant_name: Some workloads use variants of APK files, this is usually the
|
||||||
|
case with web browser APK files, these work in exactly the same way as the
|
||||||
Some workloads use variants of APK files, this is usually the case with web
|
version.
|
||||||
browser APK files, these work in exactly the same way as the version.
|
|
||||||
|
|
||||||
|
|
||||||
IDs and Labels
|
IDs and Labels
|
||||||
|
@ -34,24 +34,18 @@ The device interface may be configured through ``device_config`` setting, who's
|
|||||||
value is a ``dict`` mapping setting names to their values. Some of the most
|
value is a ``dict`` mapping setting names to their values. Some of the most
|
||||||
common parameters you might want to change are outlined below.
|
common parameters you might want to change are outlined below.
|
||||||
|
|
||||||
.. confval:: device
|
:device: If you have multiple Android devices connected to the host machine, you will
|
||||||
|
|
||||||
If you have multiple Android devices connected to the host machine, you will
|
|
||||||
need to set this to indicate to WA which device you want it to use. The will
|
need to set this to indicate to WA which device you want it to use. The will
|
||||||
be the adb name the is displayed when running ``adb devices``
|
be the adb name the is displayed when running ``adb devices``
|
||||||
|
|
||||||
.. confval:: working_directory
|
:working_directory: WA needs a "working" directory on the device which it will use for collecting
|
||||||
|
|
||||||
WA needs a "working" directory on the device which it will use for collecting
|
|
||||||
traces, caching assets it pushes to the device, etc. By default, it will
|
traces, caching assets it pushes to the device, etc. By default, it will
|
||||||
create one under ``/sdcard`` which should be mapped and writable on standard
|
create one under ``/sdcard`` which should be mapped and writable on standard
|
||||||
Android builds. If this is not the case for your device, you will need to
|
Android builds. If this is not the case for your device, you will need to
|
||||||
specify an alternative working directory (e.g. under ``/data/local``).
|
specify an alternative working directory (e.g. under ``/data/local``).
|
||||||
|
|
||||||
|
|
||||||
.. confval:: modules
|
:modules: A list of additional modules to be installed for the target. Devlib
|
||||||
|
|
||||||
A list of additional modules to be installed for the target. Devlib
|
|
||||||
implements functionality for particular subsystems as modules. A number of
|
implements functionality for particular subsystems as modules. A number of
|
||||||
"default" modules (e.g. for cpufreq subsystem) are loaded automatically,
|
"default" modules (e.g. for cpufreq subsystem) are loaded automatically,
|
||||||
unless explicitly disabled. If additional modules need to be loaded, they
|
unless explicitly disabled. If additional modules need to be loaded, they
|
||||||
@ -62,9 +56,7 @@ common parameters you might want to change are outlined below.
|
|||||||
|
|
||||||
.. _core-names:
|
.. _core-names:
|
||||||
|
|
||||||
.. confval:: core_names
|
:core_names: ``core_names`` should be a list of core names matching the order in which
|
||||||
|
|
||||||
``core_names`` should be a list of core names matching the order in which
|
|
||||||
they are exposed in sysfs. For example, Arm TC2 SoC is a 2x3 big.LITTLE
|
they are exposed in sysfs. For example, Arm TC2 SoC is a 2x3 big.LITTLE
|
||||||
system; its core_names would be ``['a7', 'a7', 'a7', 'a15', 'a15']``,
|
system; its core_names would be ``['a7', 'a7', 'a7', 'a15', 'a15']``,
|
||||||
indicating that cpu0-cpu2 in cpufreq sysfs structure are A7's and cpu3 and
|
indicating that cpu0-cpu2 in cpufreq sysfs structure are A7's and cpu3 and
|
||||||
@ -187,31 +179,21 @@ value is a ``dict`` mapping setting names to their values. Some of the most
|
|||||||
common parameters you might want to change are outlined below.
|
common parameters you might want to change are outlined below.
|
||||||
|
|
||||||
|
|
||||||
.. confval:: host
|
:host: This should be either the the DNS name or IP address of the device.
|
||||||
|
|
||||||
This should be either the the DNS name or IP address of the device.
|
:username: The login name of the user on the device that WA will use. This user should
|
||||||
|
|
||||||
.. confval:: username
|
|
||||||
|
|
||||||
The login name of the user on the device that WA will use. This user should
|
|
||||||
have a home directory (unless an alternative working directory is specified
|
have a home directory (unless an alternative working directory is specified
|
||||||
using ``working_directory`` config -- see below), and, for full
|
using ``working_directory`` config -- see below), and, for full
|
||||||
functionality, the user should have sudo rights (WA will be able to use
|
functionality, the user should have sudo rights (WA will be able to use
|
||||||
sudo-less acounts but some instruments or workload may not work).
|
sudo-less acounts but some instruments or workload may not work).
|
||||||
|
|
||||||
.. confval:: password
|
:password: Password for the account on the device. Either this of a ``keyfile`` (see
|
||||||
|
|
||||||
Password for the account on the device. Either this of a ``keyfile`` (see
|
|
||||||
below) must be specified.
|
below) must be specified.
|
||||||
|
|
||||||
.. confval:: keyfile
|
:keyfile: If key-based authentication is used, this may be used to specify the SSH identity
|
||||||
|
|
||||||
If key-based authentication is used, this may be used to specify the SSH identity
|
|
||||||
file instead of the password.
|
file instead of the password.
|
||||||
|
|
||||||
.. confval:: property_files
|
:property_files: This is a list of paths that will be pulled for each WA run into the __meta
|
||||||
|
|
||||||
This is a list of paths that will be pulled for each WA run into the __meta
|
|
||||||
subdirectory in the results. The intention is to collect meta-data about the
|
subdirectory in the results. The intention is to collect meta-data about the
|
||||||
device that may aid in reporducing the results later. The paths specified do
|
device that may aid in reporducing the results later. The paths specified do
|
||||||
not have to exist on the device (they will be ignored if they do not). The
|
not have to exist on the device (they will be ignored if they do not). The
|
||||||
@ -261,9 +243,7 @@ subset of functionality can be performed.
|
|||||||
In order to distinguish between the two connections some of the android specific
|
In order to distinguish between the two connections some of the android specific
|
||||||
configuration has been renamed to reflect the destination.
|
configuration has been renamed to reflect the destination.
|
||||||
|
|
||||||
.. confval:: android_working_directory
|
:android_working_directory: WA needs a "working" directory on the device which it will use for collecting
|
||||||
|
|
||||||
WA needs a "working" directory on the device which it will use for collecting
|
|
||||||
traces, caching assets it pushes to the device, etc. By default, it will
|
traces, caching assets it pushes to the device, etc. By default, it will
|
||||||
create one under ``/sdcard`` which should be mapped and writable on standard
|
create one under ``/sdcard`` which should be mapped and writable on standard
|
||||||
Android builds. If this is not the case for your device, you will need to
|
Android builds. If this is not the case for your device, you will need to
|
||||||
|
@ -53,24 +53,21 @@ In addition to standard configuration described above, WA behaviour can be
|
|||||||
altered through environment variables. These can determine where WA looks for
|
altered through environment variables. These can determine where WA looks for
|
||||||
various assets when it starts.
|
various assets when it starts.
|
||||||
|
|
||||||
.. confval:: WA_USER_DIRECTORY
|
:WA_USER_DIRECTORY: This is the location WA will look for config.yaml, plugins,
|
||||||
|
dependencies, and it will also be used for local caches, etc. If this
|
||||||
This is the location WA will look for config.yaml, plugins, dependencies,
|
variable is not set, the default location is ``~/.workload_automation`` (this
|
||||||
and it will also be used for local caches, etc. If this variable is not set,
|
is created when WA is installed).
|
||||||
the default location is ``~/.workload_automation`` (this is created when WA
|
|
||||||
is installed).
|
|
||||||
|
|
||||||
.. note:: This location **must** be writable by the user who runs WA.
|
.. note:: This location **must** be writable by the user who runs WA.
|
||||||
|
|
||||||
|
|
||||||
.. confval:: WA_LOG_BUFFER_CAPACITY
|
:WA_LOG_BUFFER_CAPACITY: Specifies the capacity (in log records) for the early
|
||||||
|
log handler which is used to buffer log records until a log file becomes
|
||||||
Specifies the capacity (in log records) for the early log handler which is
|
available. If the is not set, the default value of ``1000`` will be used.
|
||||||
used to buffer log records until a log file becomes available. If the is not
|
This should sufficient for most scenarios, however this may need to be
|
||||||
set, the default value of ``1000`` will be used. This should sufficient for
|
increased, e.g. if plugin loader scans a very large number of locations;
|
||||||
most scenarios, however this may need to be increased, e.g. if plugin loader
|
this may also be set to a lower value to reduce WA's memory footprint on
|
||||||
scans a very large number of locations; this may also be set to a lower
|
memory-constrained hosts.
|
||||||
value to reduce WA's memory footprint on memory-constrained hosts.
|
|
||||||
|
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user