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

doc: Misc fixes

Browse Source 
Fix typos, formatting and irrelevant information.
This commit is contained in:
Marc Bonnici
2018-05-14 17:21:59 +01:00
committed by setrofim
parent f4dd1a1c84
commit 04fe3768af
19 changed files with 241 additions and 216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
doc/source/how_tos/developers/adding_plugins.rst
View File

@@ -11,7 +11,7 @@ then the ``initialize`` method should be decorated with the ``@once``
method which is decorated instead. Please note if doing this then any installed
paths should be added as class attributes rather than instance variables. As a
general rule if binaries are installed as part of ``initialize`` then they
should be installed in the complementary ``finalize`` method.
should be uninstalled in the complementary ``finalize`` method.
Part of an example workload demonstrating this is shown below:
@@ -41,11 +41,11 @@ Part of an example workload demonstrating this is shown below:
Adding a Workload Examples
==========================
The easiest way to create a new workload is to use the create command. ``wa
create workload <args>``. This will use predefined templates to create a
workload based on the options that are supplied to be used as a starting point
for the workload. For more information on using the create workload command see
``wa create workload -h``
The easiest way to create a new workload is to use the
:ref:`create <create-command>` command. ``wa create workload <args>``. This
will use predefined templates to create a workload based on the options that are
supplied to be used as a starting point for the workload. For more information
on using the create workload command see ``wa create workload -h``
The first thing to decide is the type of workload you want to create depending
on the OS you will be using and the aim of the workload. The are currently 6
@@ -55,7 +55,7 @@ Once you have decided what type of workload you wish to choose this can be
specified with ``-k <workload_kind>`` followed by the workload name. This
will automatically generate a workload in the your ``WA_CONFIG_DIR/plugins``. If
you wish to specify a custom location this can be provided with ``-p
<directory>``
<path>``
Adding a Basic Workload Example
--------------------------------
@@ -68,10 +68,9 @@ This will generate a very basic workload with dummy methods for the workload
interface and it is left to the developer to add any required functionality to
the workload.
This example shows a simple workload that times how long it takes to compress a
file of a particular size on the device, not all the methods are required to be
implements however as many as possible have been used to demonstrate their
purpose.
Not all the methods are required to be implemented, this example shows how a
subset might be used to implement a simple workload that times how long it takes
to compress a file of a particular size on the device.
.. note:: This is intended as an example of how to implement the Workload
@@ -92,7 +91,6 @@ purpose.
This workload was created for illustration purposes only. It should not be
used to collect actual measurements.
'''
parameters = [
@@ -137,9 +135,9 @@ purpose.
This method is used to extract any results from the target for
example we want to pull the file containing the timing information
that we will use to generate metrics for our workload and then we
add this file as a artifact as a 'raw' file which once WA has
finished processing it will allow it to decide whether to keep the
file or not.
add this file as an artifact with a 'raw' kind, which means once WA
has finished processing it will allow it to decide whether to keep
the file or not.
"""
super(ZipTestWorkload, self).extract_results(context)
# Pull the results file to the host
@@ -149,9 +147,9 @@ purpose.
def update_output(self, context):
"""
In this method we can do any generation of metric that we wish to
In this method we can do any generation of metrics that we wish to
for our workload. In this case we are going to simply convert the
times reported to seconds and add them as 'metrics' to WA which can
times reported into seconds and add them as 'metrics' to WA which can
then be displayed to the user along with any others in a format
dependant on which output processors they have enabled for the run.
"""
@@ -343,7 +341,8 @@ command::
This will generate a revent based workload you will end up with a very similar
python file as to the one outlined in generating a :ref:`UiAutomator based
workload <apkuiautomator-example>` except without the java automation files.
workload <apkuiautomator-example>` however without the accompanying java
automation files.
The main difference between the two is that this workload will subclass
``ApkReventWorkload`` instead of ``ApkUiautomatorWorkload`` as shown below.
@@ -367,7 +366,7 @@ The main difference between the two is that this workload will subclass
Adding an Instrument Example
=============================
This is an example of how we would create a instrument which will trace device
errors. For more detailed information please see
errors using a custom "trace" binary file. For more detailed information please see
:ref:`here <instrument-reference>`. The first thing to do is to subclass
:class:`Instrument`, overwrite the variable name with what we want our instrument
to be called and locate our binary for our instrument.
@@ -388,7 +387,7 @@ We then declare and implement the required methods as detailed
:ref:`here <instrument-api>`. For the ``initialize`` method, we want to install
the executable file to the target so we can use the target's ``install``
method which will try to copy the file to a location on the device that
supports execution, will change the file mode appropriately and return the
supports execution, change the file mode appropriately and return the
file path on the target. ::
def initialize(self, context):
@@ -398,7 +397,7 @@ Then we implemented the start method, which will simply run the file to start
tracing. Supposing that the call to this binary requires some overhead to begin
collecting errors we might want to decorate the method with the ``@slow``
decorator to try and reduce the impact on other running instruments. For more
information on prioritization please see :ref:`here <prioritization>`::
information on prioritization please see :ref:`here <prioritization>`. ::
@slow
def start(self, context):
@@ -406,7 +405,7 @@ information on prioritization please see :ref:`here <prioritization>`::
Lastly, we need to stop tracing once the workload stops and this happens in the
stop method, assuming stopping the collection also require some overhead we have
again decorated the method::
again decorated the method. ::
@slow
def stop(self, context):
@@ -425,9 +424,9 @@ example for trace data we will want to pull it to the device and add it as a
Once we have retrieved the data we can now do any further processing and add any
relevant :ref:`Metrics <metrics>` to the :ref:`context <context>`. For this we
will use the the ``add_metric`` method and to add the instruments results to the
final result for that workload. The method can be passed 4 params, which are the
metric `key`, `value`, `unit` and `lower_is_better`. ::
will use the the ``add_metric`` method to add the results to the final output
for that workload. The method can be passed 4 params, which are the metric
`key`, `value`, `unit` and `lower_is_better`. ::
def update_output(self, context):
# parse the file if needs to be parsed, or add result directly to
@@ -442,7 +441,7 @@ instruments and the code to clear these file goes in teardown method. ::
def teardown(self, context):
self.target.remove(os.path.join(self.target.working_directory, 'trace.txt'))
At the very end of the run we would want to uninstall the binary we deployed earlier ::
At the very end of the run we would want to uninstall the binary we deployed earlier. ::
def finalize(self, context):
self.target.uninstall(self.binary_name)
@@ -499,7 +498,7 @@ Next we need to implement any relevant methods, (please see
available methods). In this case we only want to implement the
``export_run_output`` method as we are not generating any new artifacts and
we only care about the overall output rather than the individual job
outputs. And the implementation is very simple, it just loops through all
outputs. The implementation is very simple, it just loops through all
the available metrics for all the available jobs and adds them to a list
which is written to file and then added as an :ref:`artifact <artifact>` to
the :ref:`context <context>`.
@@ -514,7 +513,7 @@ the :ref:`context <context>`.
class Table(OutputProcessor):
name = 'table'
description = 'Generates a text file containing a column-aligned table with run results.'
description = 'Generates a text file containing a column-aligned table of run results.'
def export_run_output(self, output, target_info):
rows = []
@@ -527,7 +526,7 @@ the :ref:`context <context>`.
outfile = output.get_path('table.txt')
with open(outfile, 'w') as wfh:
write_table(rows, wfh)
output.add_artifact('results_table', 'table.txt, 'export')
output.add_artifact('results_table', 'table.txt', 'export')
.. _adding-custom-target-example:

18
doc/source/how_tos/users/agenda.rst
View File

@@ -347,8 +347,8 @@ Classifiers
------------
Classifiers can be used in 2 distinct ways, the first use is being supplied in
an agenda as a set of key-value pairs which can be used to help identify sub-
tests of a run, for example if you have multiple sections in your agenda running
an agenda as a set of key-value pairs which can be used to help identify sub-tests
of a run, for example if you have multiple sections in your agenda running
your workloads at different frequencies you might want to set a classifier
specifying which frequencies are being used. These can then be utilized later,
for example with the ``csv`` :ref:`output processor <output-processors>` with
@@ -384,9 +384,9 @@ An example agenda is shown here:
The other way that they can used is by being automatically added by some
workloads to identify their results metrics and artifacts. For example some
workloads perform multiple tests with the same execution run and therefore will
use metrics to differentiate between them, For example the ``recentfling``
workload will use classifiers to distinguish between which loop a particular
result is for or whether it is an average across all loops ran.
use metrics to differentiate between them, e.g. the ``recentfling`` workload
will use classifiers to distinguish between which loop a particular result is
for or whether it is an average across all loops ran.
The output from the agenda above will produce a csv file similar to what is
shown below. Some columns have been omitted for clarity however as can been seen
@@ -500,7 +500,7 @@ turn override global settings.
Augmentationts
Augmentations
--------------
Augmentations are plugins that augment the execution of workload jobs with
@@ -509,7 +509,7 @@ metrics and/or artifacts, such as traces or logs. There are two types of
augmentations:
Instruments
These "instrument" a WA run in order to change it's behavior (e.g.
These "instrument" a WA run in order to change it's behaviour (e.g.
introducing delays between successive job executions), or collect
additional measurements (e.g. energy usage). Some instruments may depend
on particular features being enabled on the target (e.g. cpufreq), or
@@ -677,9 +677,11 @@ Each workload will be run in two configurations: once, to collect energy
measurements, and once to collect thermal data and kernel trace. Trace can give
insight into why a workload is using more or less energy than expected, but it
can be relatively intrusive and might impact absolute energy and performance
metrics, which is why it is collected separately. classifiers_ are used to
metrics, which is why it is collected separately. Classifiers_ are used to
separate metrics from the two configurations in the results.
.. _other-agenda-configuration:
Other Configuration
-------------------

42
doc/source/how_tos/users/device_setup.rst
View File

@@ -20,12 +20,11 @@ Android
General Device Setup
^^^^^^^^^^^^^^^^^^^^
You can specify the device interface by setting ``device`` setting in
``~/.workload_automation/config.yaml``. Available interfaces can be viewed by
running ``wa list targets`` command. If you don't see your specific platform
listed (which is likely unless you're using one of the Arm-supplied platforms), then
you should use ``generic_android`` interface (this is set in the config by
default).
You can specify the device interface by setting ``device`` setting in a
``config`` file or section. Available interfaces can be viewed by running ``wa
list targets`` command. If you don't see your specific platform listed (which is
likely unless you're using one of the Arm-supplied platforms), then you should
use ``generic_android`` interface (this is what is used by the default config).
.. code-block:: yaml
@@ -38,7 +37,8 @@ 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
need to set this to indicate to WA which device you want it to use.
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
@@ -81,7 +81,7 @@ A typical ``device_config`` inside ``config.yaml`` may look something like
device_config:
device: 0123456789ABCDEF
# ...
# ...
or a more specific config could be be
@@ -172,12 +172,11 @@ Linux
General Device Setup
^^^^^^^^^^^^^^^^^^^^
You can specify the device interface by setting ``device`` setting in
``~/.workload_automation/config.yaml``. Available interfaces can be viewed by
running ``wa list targets`` command. If you don't see your specific platform
listed (which is likely unless you're using one of the Arm-supplied platforms), then
you should use ``generic_linux`` interface (this is set in the config by
default).
You can specify the device interface by setting ``device`` setting in a
``config`` file or section. Available interfaces can be viewed by running
``wa list targets`` command. If you don't see your specific platform listed
(which is likely unless you're using one of the Arm-supplied platforms), then
you should use ``generic_linux`` interface.
.. code-block:: yaml
@@ -239,25 +238,24 @@ Chrome OS
General Device Setup
^^^^^^^^^^^^^^^^^^^^
You can specify the device interface by setting ``device`` setting in
``~/.workload_automation/config.yaml``. Available interfaces can be viewed by
You can specify the device interface by setting ``device`` setting in a
``config`` file or section. Available interfaces can be viewed by
running ``wa list targets`` command. If you don't see your specific platform
listed (which is likely unless you're using one of the Arm-supplied platforms), then
you should use ``generic_chromeos`` interface (this is set in the config by
default).
you should use ``generic_chromeos`` interface.
.. code-block:: yaml
device: generic_chromeos
The device interface may be configured through ``device_config`` setting, who's
value is a ``dict`` mapping setting names to their values. The chrome os target
value is a ``dict`` mapping setting names to their values. The ChromeOS target
is essentially the same as a linux device and requires a similar setup, however
it also optionally supports connecting to an android container running on the
device which will be automatically deted if present. If the device supports
device which will be automatically detected if present. If the device supports
android applications then the android configuration is also supported. In order
to support this then WA will open 2 connections to the device, one via SSH to
the main ChomeOS OS and another via ADB to the android container where a limited
to support this WA will open 2 connections to the device, one via SSH to
the main OS and another via ADB to the android container where a limited
subset of functionality can be performed.
In order to distinguish between the two connections some of the android specific

2
doc/source/how_tos/users/revent.rst
View File

@@ -94,7 +94,7 @@ command with an example output shown below::
INFO Recording(s) are available at: '$WA_USER_DIRECTORY/dependencies/angrybirds_rio/revent_files'
Once you have made your desired recordings, you can either manually playback
individual recordings using the :ref:`reply <replay-command>` command or, with
individual recordings using the :ref:`replay <replay-command>` command or, with
the recordings in the appropriate dependencies location, simply run the workload
using the :ref:`run <run-command>` command and then all the available recordings will be
played back automatically.