sascha/workload-automation
1
0
Fork 0
mirror of https://github.com/ARM-software/workload-automation.git synced 2025-01-18 20:11:20 +00:00
Code Issues Releases Wiki Activity

doc: Make config listsing a consistent style

Browse Source
This commit is contained in:
Marc Bonnici 2018-06-21 14:55:31 +01:00 committed by setrofim
parent b6e91630b8
commit 716af1b966
4 changed files with 57 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/source/developer_information/developer_reference/writing_plugins.rst
View File

@ -479,12 +479,12 @@ All plugins can be parametrized. Parameters are specified using
:class:`wa.framework.plugin.Parameter` instances. The following attributes can be
specified on parameter creation:
name
:name:
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
Python identifier.
kind
:kind:
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``
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
``None``, then set ``mandatory`` (see below) to ``True``.
allowed_values
:allowed_values:
A list of the only allowed values for this parameter.
.. 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
than the composite value itself.
default
:default:
The default value to be used for this parameter if one has not been
specified by the user. Defaults to ``None``.
mandatory
:mandatory:
A ``bool`` indicating whether this parameter is mandatory. Setting this
to ``True`` will make ``None`` an illegal value for the parameter.
Defaults to ``False``.
@ -521,13 +521,13 @@ mandatory
(e.g. something like login credentials), should you consider
making it mandatory.
constraint
:constraint:
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
that takes a single argument -- the user-supplied value -- and returns
a ``bool`` indicating whether the constraint has been satisfied).
override
:override:
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 the same name as already exists, you will get an error. If you do

67
doc/source/user_information/how_tos/agenda.rst
View File

@ -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
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
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.
:force_install: If this setting is enabled WA will *always* use the APK file on
the host, and re-install it on every iteration. If there is no APK on the
host that is a suitable version and/or ABI for the workload WA will error
when ``force_install`` is enabled.
.. 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
re-install it on every iteration. If there is no APK on the host that is a
suitable version and/or ABI for the workload WA will error when
``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
: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
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
:ref:`agenda <agenda>`.
.. confval:: 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 version.
: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
version.
IDs and Labels

40
doc/source/user_information/how_tos/device_setup.rst
View File

@ -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
common parameters you might want to change are outlined below.
.. confval:: device
If you have multiple Android devices connected to the host machine, you will
:device: 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
be the adb name the is displayed when running ``adb devices``
.. confval:: working_directory
WA needs a "working" directory on the device which it will use for collecting
:working_directory: 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
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
specify an alternative working directory (e.g. under ``/data/local``).
.. confval:: modules
A list of additional modules to be installed for the target. Devlib
:modules: A list of additional modules to be installed for the target. Devlib
implements functionality for particular subsystems as modules. A number of
"default" modules (e.g. for cpufreq subsystem) are loaded automatically,
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:
.. confval:: core_names
``core_names`` should be a list of core names matching the order in which
:core_names: ``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
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
@ -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.
.. 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.
.. confval:: username
The login name of the user on the device that WA will use. This user should
: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
using ``working_directory`` config -- see below), and, for full
functionality, the user should have sudo rights (WA will be able to use
sudo-less acounts but some instruments or workload may not work).
.. confval:: password
Password for the account on the device. Either this of a ``keyfile`` (see
:password: Password for the account on the device. Either this of a ``keyfile`` (see
below) must be specified.
.. confval:: keyfile
If key-based authentication is used, this may be used to specify the SSH identity
:keyfile: If key-based authentication is used, this may be used to specify the SSH identity
file instead of the password.
.. confval:: property_files
This is a list of paths that will be pulled for each WA run into the __meta
:property_files: 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
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
@ -261,9 +243,7 @@ subset of functionality can be performed.
In order to distinguish between the two connections some of the android specific
configuration has been renamed to reflect the destination.
.. confval:: android_working_directory
WA needs a "working" directory on the device which it will use for collecting
:android_working_directory: 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
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

25
doc/source/user_information/user_reference/configuration.rst
View File

@ -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
various assets when it starts.
.. confval:: 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 variable is not set,
the default location is ``~/.workload_automation`` (this is created when WA
is installed).
: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
variable is not set, 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.
.. confval:: 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 available. If the is not
set, the default value of ``1000`` will be used. This should sufficient for
most scenarios, however this may need to be increased, e.g. if plugin loader
scans a very large number of locations; this may also be set to a lower
value to reduce WA's memory footprint on memory-constrained hosts.
: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
available. If the is not set, the default value of ``1000`` will be used.
This should sufficient for most scenarios, however this may need to be
increased, e.g. if plugin loader scans a very large number of locations;
this may also be set to a lower value to reduce WA's memory footprint on
memory-constrained hosts.
---------------------