Migration Guide¶
Contents
Users¶
Configuration¶
Default configuration file change¶
Instead of the standard config.py
file located at
$WA_USER_HOME/config.py
WA now uses a confg.yaml
file (at the same
location) which is written in the YAML format instead of python. Additionally
upon first invocation WA3 will automatically try and detect whether a WA2 config
file is present and convert it to use the new WA3 format. During this process
any known parameter name changes should be detected and updated accordingly.
Plugin Changes¶
Please note that not all plugins that were available for WA2 are currently
available for WA3 so you may need to remove plugins that are no longer present
from your config files. One plugin of note is the standard
results
processor, this has been removed and it’s functionality built into the core
framework.
Agendas¶
WA3 is designed to keep configuration as backwards compatible as possible so most agendas should work out of the box, however the main changes in the style of WA3 agendas are:
Global Section¶
The global
and config
sections have been merged so now all configuration
that was specified under the “global” keyword can now also be specified under
“config”. Although “global” is still a valid keyword you will need to ensure that
there are not duplicated entries in each section.
Instrumentation and Results Processors merged¶
The instrumentation
and results_processors
sections from WA2 have now
been merged into a single augmentations
section to simplify the
configuration process. Although for backwards compatibility, support for the old
sections has be retained.
Per workload enabling of augmentations¶
All augmentations can now been enabled and disabled on a per workload basis.
Setting Runtime Parameters¶
Runtime Parameters are now the preferred way of configuring, cpufreq, hotplug and cpuidle rather setting the corresponding sysfile values as this will perform additional validation and ensure the nodes are set in the correct order to avoid any conflicts.
Parameter Changes¶
Any parameter names changes listed below will also have their old names specified as aliases and should continue to work as normal, however going forward the new parameter names should be preferred:
- The workload parameter
clean_up
has be renamed tocleanup_assets
to better reflect its purpose. - The workload parameter
check_apk
has been renamed toprefer_host_package
to be more explicit in it’s functionality to indicated whether a package on the target or the host should have priority when searching for a suitable package. - The execution order
by_spec
is now calledby_workload
for clarity of purpose. For more information please see Configuration. - The
by_spec
reboot policy has been removed as this is no longer relevant and theeach_iteration
reboot policy has been renamed toeach_job
, please see Configuration for more information.
Individual workload parameters have been attempted to be standardized for the more common operations e.g.:
iterations
is nowloops
to indicate the how many ‘tight loops’ of the workload should be performed, e.g. without the setup/teardown method calls.num_threads
is now consistentlythreads
across workloads.run_timeout
is now consistentlytimeout
across workloads.taskset_mask
andcpus
have been changed to consistently be referred to ascpus
and its types is now acpu_mask
type allowing configuration to be supplied either directly as a mask, as a list of a list of cpu indexes or as a sysfs-style string.
Output¶
Output Directory¶
The output directory’s structure has changed layout
and now includes additional subdirectories. There is now a __meta
directory
that contains copies of the agenda and config files supplied to WA for that
particular run so that all the relevant config is self contained. Additionally
if one or more jobs fail during a run then corresponding output directory will be
moved into a __failed
subdirectory to allow for quicker analysis.
Output API¶
There is now an Output API which can be used to more easily post process the output from a run. For more information please see the Output API documentation.
Developers¶
Framework¶
Imports¶
To distinguish between the different versions of WA, WA3’s package name has been
renamed to wa
. This means that all the old wlauto
imports will need to
be updated. For more information please see the corresponding section in the
developer reference section
Asset Deployment¶
WA3 now contains a generic assets deployment and clean up mechanism so if a
workload was previously doing this in an ad-hoc manner this should be updated to
utilize the new functionality. To make use of this functionality a list of
assets should be set as the workload deployable_assets
attribute, these will
be automatically retrieved via WA’s resource getters and deployed either to the
targets working directory or a custom directory specified as the workloads
assets_directory
attribute. If a custom implementation is required the
deploy_assets
method should be overridden inside the workload. To allow for
the removal of the additional assets any additional file paths should be added
to the self.deployed_assets
list which is used to keep track of any assets
that have been deployed for the workload. This is what is used by the generic
remove_assets
method to clean up any files deployed to the target.
Optionally if the file structure of the deployed assets requires additional
logic then the remove_assets
method can be overridden for a particular
workload as well.
Workloads¶
Python Workload Structure¶
- The
update_results
method has been split out into 2 stages. There is nowextract_results
andupdate_output
which should be used for extracting any results from the target back to the host system and to update the output with any metrics or artefacts for the specific workload iteration respectively. - WA now features execution decorators which can be used to allow for more efficient binary deployment and that they are only installed to the device once per run. For more information of implementing this please see deploying executables to a target.
APK Functionality¶
All apk functionality has re-factored into an APKHandler object which is
available as the apk attribute of the workload. This means that for example
self.launchapplication()
would now become self.apk.start_activity()
UiAutomator Java Structure¶
Instead of a single runUiAutomation
method to perform all of the UiAutomation,
the structure has been refactored into 5 methods that can optionally be overridden.
The available methods are initialize
, setup
, runWorkload
, extactResults
and teardown
to better mimic the different stages in the python workload.
initialize
should be used to retrieve and set any relevant parameters required during the workload.setup
should be used to perform any setup required for the workload, for example dismissing popups or configuring and required settings.runWorkload
should be used to perform the actual measurable work of the workload.extractResults
should be used to extract any relevant results from the target after the workload has been completed.teardown
should be used to perform any final clean up of the workload on the target.
Note
The initialize
method should have the @Before
tag attached
to the method which will cause it to be ran before each of the stages of
the workload. The remaining method should all have the @Test
tag
attached to the method to indicate that this is a test stage that should be
called at the appropriate time.
GUI Functionality¶
For UI based applications all UI functionality has been re-factored to into a
gui
attribute which currently will be either a UiAutomatorGUI
object or
a ReventGUI
depending on the workload type. This means that for example if
you wish to pass parameters to a UiAuotmator workload you will now need to use
self.gui.uiauto_params['Parameter Name'] = value
Attributes¶
The old
package
attribute has been replaced bypackage_names
which expects a list of strings which allows for multiple package names to be specified if required. It is also no longer required to explicitly state the launch-able activity, this will be automatically discovered from the apk so this workload attribute can be removed.The
device
attribute of the workload is now a devlibtarget
. Some of the command names remain the same, however there will be differences. The API can be found at http://devlib.readthedocs.io/en/latest/target.html however some of the more common changes can be found below:Original Method New Method self.device.pull_file(file)
self.target.pull(file)
self.device.push_file(file)
self.target.push(file)
self.device.install_executable(file)
self.target.install(file)
self.device.execute(cmd, background=True)
self.target.background(cmd)