Initial commit of open source Workload Automation.

wlauto/common/android/__init__.py

@@ -0,0 +1,16 @@
+#    Copyright 2014-2015 ARM Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+

wlauto/common/android/device.py

@@ -0,0 +1,678 @@
+#    Copyright 2013-2015 ARM Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# pylint: disable=E1101
+import os
+import sys
+import re
+import time
+import tempfile
+import shutil
+import threading
+from subprocess import CalledProcessError
+
+from wlauto.core.extension import Parameter
+from wlauto.common.linux.device import BaseLinuxDevice
+from wlauto.exceptions import DeviceError, WorkerThreadError, TimeoutError, DeviceNotRespondingError
+from wlauto.utils.misc import convert_new_lines
+from wlauto.utils.types import boolean, regex
+from wlauto.utils.android import (adb_shell, adb_background_shell, adb_list_devices,
+                                  adb_command, AndroidProperties, ANDROID_VERSION_MAP)
+
+
+SCREEN_STATE_REGEX = re.compile('(?:mPowerState|mScreenOn)=([0-9]+|true|false)', re.I)
+
+
+class AndroidDevice(BaseLinuxDevice):  # pylint: disable=W0223
+    """
+    Device running Android OS.
+
+    """
+
+    platform = 'android'
+
+    parameters = [
+        Parameter('adb_name',
+                  description='The unique ID of the device as output by "adb devices".'),
+        Parameter('android_prompt', kind=regex, default=re.compile('^.*(shell|root)@.*:/ [#$] ', re.MULTILINE),
+                  description='The format  of matching the shell prompt in Android.'),
+        Parameter('working_directory', default='/sdcard/wa-working',
+                  description='Directory that will be used WA on the device for output files etc.'),
+        Parameter('binaries_directory', default='/system/bin',
+                  description='Location of binaries on the device.'),
+        Parameter('package_data_directory', default='/data/data',
+                  description='Location of of data for an installed package (APK).'),
+        Parameter('external_storage_directory', default='/sdcard',
+                  description='Mount point for external storage.'),
+        Parameter('connection', default='usb', allowed_values=['usb', 'ethernet'],
+                  description='Specified the nature of adb connection.'),
+        Parameter('logcat_poll_period', kind=int,
+                  description="""
+                  If specified and is not ``0``, logcat will be polled every
+                  ``logcat_poll_period`` seconds, and buffered on the host. This
+                  can be used if a lot of output is expected in logcat and the fixed
+                  logcat buffer on the device is not big enough. The trade off is that
+                  this introduces some minor runtime overhead. Not set by default.
+                  """),
+        Parameter('enable_screen_check', kind=boolean, default=False,
+                  description="""
+                  Specified whether the device should make sure that the screen is on
+                  during initialization.
+                  """),
+    ]
+
+    default_timeout = 30
+    delay = 2
+    long_delay = 3 * delay
+    ready_timeout = 60
+
+    # Overwritten from Device. For documentation, see corresponding method in
+    # Device.
+
+    @property
+    def is_rooted(self):
+        if self._is_rooted is None:
+            try:
+                result = adb_shell(self.adb_name, 'su', timeout=1)
+                if 'not found' in result:
+                    self._is_rooted = False
+                else:
+                    self._is_rooted = True
+            except TimeoutError:
+                self._is_rooted = True
+            except DeviceError:
+                self._is_rooted = False
+        return self._is_rooted
+
+    @property
+    def abi(self):
+        return self.getprop()['ro.product.cpu.abi'].split('-')[0]
+
+    @property
+    def supported_eabi(self):
+        props = self.getprop()
+        result = [props['ro.product.cpu.abi']]
+        if 'ro.product.cpu.abi2' in props:
+            result.append(props['ro.product.cpu.abi2'])
+        if 'ro.product.cpu.abilist' in props:
+            for eabi in props['ro.product.cpu.abilist'].split(','):
+                if eabi not in result:
+                    result.append(eabi)
+        return result
+
+    def __init__(self, **kwargs):
+        super(AndroidDevice, self).__init__(**kwargs)
+        self._logcat_poller = None
+
+    def reset(self):
+        self._is_ready = False
+        self._just_rebooted = True
+        adb_command(self.adb_name, 'reboot', timeout=self.default_timeout)
+
+    def hard_reset(self):
+        super(AndroidDevice, self).hard_reset()
+        self._is_ready = False
+        self._just_rebooted = True
+
+    def boot(self, **kwargs):
+        self.reset()
+
+    def connect(self):  # NOQA pylint: disable=R0912
+        iteration_number = 0
+        max_iterations = self.ready_timeout / self.delay
+        available = False
+        self.logger.debug('Polling for device {}...'.format(self.adb_name))
+        while iteration_number < max_iterations:
+            devices = adb_list_devices()
+            if self.adb_name:
+                for device in devices:
+                    if device.name == self.adb_name and device.status != 'offline':
+                        available = True
+            else:  # adb_name not set
+                if len(devices) == 1:
+                    available = True
+                elif len(devices) > 1:
+                    raise DeviceError('More than one device is connected and adb_name is not set.')
+
+            if available:
+                break
+            else:
+                time.sleep(self.delay)
+                iteration_number += 1
+        else:
+            raise DeviceError('Could not boot {} ({}).'.format(self.name, self.adb_name))
+
+        while iteration_number < max_iterations:
+            available = (1 == int('0' + adb_shell(self.adb_name, 'getprop sys.boot_completed', timeout=self.default_timeout)))
+            if available:
+                break
+            else:
+                time.sleep(self.delay)
+                iteration_number += 1
+        else:
+            raise DeviceError('Could not boot {} ({}).'.format(self.name, self.adb_name))
+
+        if self._just_rebooted:
+            self.logger.debug('Waiting for boot to complete...')
+            # On some devices, adb connection gets reset some time after booting.
+            # This  causes errors during execution. To prevent this, open a shell
+            # session and wait for it to be killed. Once its killed, give adb
+            # enough time to restart, and then the device should be ready.
+            # TODO: This is more of a work-around rather than an actual solution.
+            #       Need to figure out what is going on the "proper" way of handling it.
+            try:
+                adb_shell(self.adb_name, '', timeout=20)
+                time.sleep(5)  # give adb time to re-initialize
+            except TimeoutError:
+                pass  # timed out waiting for the session to be killed -- assume not going to be.
+
+            self.logger.debug('Boot completed.')
+            self._just_rebooted = False
+        self._is_ready = True
+
+    def initialize(self, context, *args, **kwargs):
+        self.execute('mkdir -p {}'.format(self.working_directory))
+        if self.is_rooted:
+            if not self.executable_is_installed('busybox'):
+                self.busybox = self.deploy_busybox(context)
+            else:
+                self.busybox = 'busybox'
+            self.disable_screen_lock()
+            self.disable_selinux()
+        if self.enable_screen_check:
+            self.ensure_screen_is_on()
+        self.init(context, *args, **kwargs)
+
+    def disconnect(self):
+        if self._logcat_poller:
+            self._logcat_poller.close()
+
+    def ping(self):
+        try:
+            # May be triggered inside initialize()
+            adb_shell(self.adb_name, 'ls /', timeout=10)
+        except (TimeoutError, CalledProcessError):
+            raise DeviceNotRespondingError(self.adb_name or self.name)
+
+    def start(self):
+        if self.logcat_poll_period:
+            if self._logcat_poller:
+                self._logcat_poller.close()
+            self._logcat_poller = _LogcatPoller(self, self.logcat_poll_period, timeout=self.default_timeout)
+            self._logcat_poller.start()
+
+    def stop(self):
+        if self._logcat_poller:
+            self._logcat_poller.stop()
+
+    def get_android_version(self):
+        return ANDROID_VERSION_MAP.get(self.get_sdk_version(), None)
+
+    def get_android_id(self):
+        """
+        Get the device's ANDROID_ID. Which is
+
+            "A 64-bit number (as a hex string) that is randomly generated when the user
+            first sets up the device and should remain constant for the lifetime of the
+            user's device."
+
+        .. note:: This will get reset on userdata erasure.
+
+        """
+        return self.execute('settings get secure android_id').strip()
+
+    def get_sdk_version(self):
+        try:
+            return int(self.getprop('ro.build.version.sdk'))
+        except (ValueError, TypeError):
+            return None
+
+    def get_installed_package_version(self, package):
+        """
+        Returns the version (versionName) of the specified package if it is installed
+        on the device, or ``None`` otherwise.
+
+        Added in version 2.1.4
+
+        """
+        output = self.execute('dumpsys package {}'.format(package))
+        for line in convert_new_lines(output).split('\n'):
+            if 'versionName' in line:
+                return line.split('=', 1)[1]
+        return None
+
+    def list_packages(self):
+        """
+        List packages installed on the device.
+
+        Added in version 2.1.4
+
+        """
+        output = self.execute('pm list packages')
+        output = output.replace('package:', '')
+        return output.split()
+
+    def package_is_installed(self, package_name):
+        """
+        Returns ``True`` the if a package with the specified name is installed on
+        the device, and ``False`` otherwise.
+
+        Added in version 2.1.4
+
+        """
+        return package_name in self.list_packages()
+
+    def executable_is_installed(self, executable_name):
+        return executable_name in self.listdir(self.binaries_directory)
+
+    def is_installed(self, name):
+        return self.executable_is_installed(name) or self.package_is_installed(name)
+
+    def listdir(self, path, as_root=False, **kwargs):
+        contents = self.execute('ls {}'.format(path), as_root=as_root)
+        return [x.strip() for x in contents.split()]
+
+    def push_file(self, source, dest, as_root=False, timeout=default_timeout):  # pylint: disable=W0221
+        """
+        Modified in version 2.1.4: added  ``as_root`` parameter.
+
+        """
+        self._check_ready()
+        if not as_root:
+            adb_command(self.adb_name, "push '{}' '{}'".format(source, dest), timeout=timeout)
+        else:
+            device_tempfile = self.path.join(self.file_transfer_cache, source.lstrip(self.path.sep))
+            self.execute('mkdir -p {}'.format(self.path.dirname(device_tempfile)))
+            adb_command(self.adb_name, "push '{}' '{}'".format(source, device_tempfile), timeout=timeout)
+            self.execute('cp {} {}'.format(device_tempfile, dest), as_root=True)
+
+    def pull_file(self, source, dest, as_root=False, timeout=default_timeout):  # pylint: disable=W0221
+        """
+        Modified in version 2.1.4: added  ``as_root`` parameter.
+
+        """
+        self._check_ready()
+        if not as_root:
+            adb_command(self.adb_name, "pull '{}' '{}'".format(source, dest), timeout=timeout)
+        else:
+            device_tempfile = self.path.join(self.file_transfer_cache, source.lstrip(self.path.sep))
+            self.execute('mkdir -p {}'.format(self.path.dirname(device_tempfile)))
+            self.execute('cp {} {}'.format(source, device_tempfile), as_root=True)
+            adb_command(self.adb_name, "pull '{}' '{}'".format(device_tempfile, dest), timeout=timeout)
+
+    def delete_file(self, filepath, as_root=False):  # pylint: disable=W0221
+        self._check_ready()
+        adb_shell(self.adb_name, "rm '{}'".format(filepath), as_root=as_root, timeout=self.default_timeout)
+
+    def file_exists(self, filepath):
+        self._check_ready()
+        output = adb_shell(self.adb_name, 'if [ -e \'{}\' ]; then echo 1; else echo 0; fi'.format(filepath),
+                           timeout=self.default_timeout)
+        if int(output):
+            return True
+        else:
+            return False
+
+    def install(self, filepath, timeout=default_timeout, with_name=None):  # pylint: disable=W0221
+        ext = os.path.splitext(filepath)[1].lower()
+        if ext == '.apk':
+            return self.install_apk(filepath, timeout)
+        else:
+            return self.install_executable(filepath, with_name)
+
+    def install_apk(self, filepath, timeout=default_timeout):  # pylint: disable=W0221
+        self._check_ready()
+        ext = os.path.splitext(filepath)[1].lower()
+        if ext == '.apk':
+            return adb_command(self.adb_name, "install {}".format(filepath), timeout=timeout)
+        else:
+            raise DeviceError('Can\'t install {}: unsupported format.'.format(filepath))
+
+    def install_executable(self, filepath, with_name=None):
+        """
+        Installs a binary executable on device. Requires root access. Returns
+        the path to the installed binary, or ``None`` if the installation has failed.
+        Optionally, ``with_name`` parameter may be used to specify a different name under
+        which the executable will be installed.
+
+        Added in version 2.1.3.
+        Updated in version 2.1.5 with ``with_name`` parameter.
+
+        """
+        executable_name = with_name or os.path.basename(filepath)
+        on_device_file = self.path.join(self.working_directory, executable_name)
+        on_device_executable = self.path.join(self.binaries_directory, executable_name)
+        self.push_file(filepath, on_device_file)
+        matched = []
+        for entry in self.list_file_systems():
+            if self.binaries_directory.rstrip('/').startswith(entry.mount_point):
+                matched.append(entry)
+
+        if matched:
+            entry = sorted(matched, key=lambda x: len(x.mount_point))[-1]
+            if 'rw' not in entry.options:
+                self.execute('mount -o rw,remount {} {}'.format(entry.device, entry.mount_point), as_root=True)
+            self.execute('cp {} {}'.format(on_device_file, on_device_executable), as_root=True)
+            self.execute('chmod 0777 {}'.format(on_device_executable), as_root=True)
+            return on_device_executable
+        else:
+            raise DeviceError('Could not find mount point for binaries directory {}'.format(self.binaries_directory))
+
+    def uninstall(self, package):
+        self._check_ready()
+        adb_command(self.adb_name, "uninstall {}".format(package), timeout=self.default_timeout)
+
+    def uninstall_executable(self, executable_name):
+        """
+        Requires root access.
+
+        Added in version 2.1.3.
+
+        """
+        on_device_executable = self.path.join(self.binaries_directory, executable_name)
+        for entry in self.list_file_systems():
+            if entry.mount_point == '/system':
+                if 'rw' not in entry.options:
+                    self.execute('mount -o rw,remount {} /system'.format(entry.device), as_root=True)
+        self.delete_file(on_device_executable)
+
+    def execute(self, command, timeout=default_timeout, check_exit_code=True, background=False,
+                as_root=False, busybox=False, **kwargs):
+        """
+        Execute the specified command on the device using adb.
+
+        Parameters:
+
+            :param command: The command to be executed. It should appear exactly
+                            as if you were typing it into a shell.
+            :param timeout: Time, in seconds, to wait for adb to return before aborting
+                            and raising an error. Defaults to ``AndroidDevice.default_timeout``.
+            :param check_exit_code: If ``True``, the return code of the command on the Device will
+                                    be check and exception will be raised if it is not 0.
+                                    Defaults to ``True``.
+            :param background: If ``True``, will execute adb in a subprocess, and will return
+                               immediately, not waiting for adb to return. Defaults to ``False``
+            :param busybox: If ``True``, will use busybox to execute the command. Defaults to ``False``.
+
+                            Added in version 2.1.3
+
+                            .. note:: The device must be rooted to be able to use busybox.
+
+            :param as_root: If ``True``, will attempt to execute command in privileged mode. The device
+                            must be rooted, otherwise an error will be raised. Defaults to ``False``.
+
+                            Added in version 2.1.3
+
+        :returns: If ``background`` parameter is set to ``True``, the subprocess object will
+                  be returned; otherwise, the contents of STDOUT from the device will be returned.
+
+        :raises: DeviceError if adb timed out  or if the command returned non-zero exit
+                 code on the device, or if attempting to execute a command in privileged mode on an
+                 unrooted device.
+
+        """
+        self._check_ready()
+        if as_root and not self.is_rooted:
+            raise DeviceError('Attempting to execute "{}" as root on unrooted device.'.format(command))
+        if busybox:
+            if not self.is_rooted:
+                DeviceError('Attempting to execute "{}" with busybox. '.format(command) +
+                            'Busybox can only be deployed to rooted devices.')
+            command = ' '.join([self.busybox, command])
+        if background:
+            return adb_background_shell(self.adb_name, command, as_root=as_root)
+        else:
+            return adb_shell(self.adb_name, command, timeout, check_exit_code, as_root)
+
+    def kick_off(self, command):
+        """
+        Like execute but closes adb session and returns immediately, leaving the command running on the
+        device (this is different from execute(background=True) which keeps adb connection open and returns
+        a subprocess object).
+
+        .. note:: This relies on busybox's nohup applet and so won't work on unrooted devices.
+
+        Added in version 2.1.4
+
+        """
+        if not self.is_rooted:
+            raise DeviceError('kick_off uses busybox\'s nohup applet and so can only be run a rooted device.')
+        try:
+            command = 'cd {} && busybox nohup {}'.format(self.working_directory, command)
+            output = self.execute(command, timeout=1, as_root=True)
+        except TimeoutError:
+            pass
+        else:
+            raise ValueError('Background command exited before timeout; got "{}"'.format(output))
+
+    def get_properties(self, context):
+        """Captures and saves the information from /system/build.prop and /proc/version"""
+        props = {}
+        props['android_id'] = self.get_android_id()
+        buildprop_file = os.path.join(context.host_working_directory, 'build.prop')
+        if not os.path.isfile(buildprop_file):
+            self.pull_file('/system/build.prop', context.host_working_directory)
+        self._update_build_properties(buildprop_file, props)
+        context.add_run_artifact('build_properties', buildprop_file, 'export')
+
+        version_file = os.path.join(context.host_working_directory, 'version')
+        if not os.path.isfile(version_file):
+            self.pull_file('/proc/version', context.host_working_directory)
+        self._update_versions(version_file, props)
+        context.add_run_artifact('device_version', version_file, 'export')
+        return props
+
+    def getprop(self, prop=None):
+        """Returns parsed output of Android getprop command. If a property is
+        specified, only the value for that property will be returned (with
+        ``None`` returned if the property doesn't exist. Otherwise,
+        ``wlauto.utils.android.AndroidProperties`` will be returned, which is
+        a dict-like object."""
+        props = AndroidProperties(self.execute('getprop'))
+        if prop:
+            return props[prop]
+        return props
+
+    # Android-specific methods. These either rely on specifics of adb or other
+    # Android-only concepts in their interface and/or implementation.
+
+    def forward_port(self, from_port, to_port):
+        """
+        Forward a port on the device to a port on localhost.
+
+        :param from_port: Port on the device which to forward.
+        :param to_port: Port on the localhost to which the device port will be forwarded.
+
+        Ports should be specified using adb spec. See the "adb forward" section in "adb help".
+
+        """
+        adb_command(self.adb_name, 'forward {} {}'.format(from_port, to_port), timeout=self.default_timeout)
+
+    def dump_logcat(self, outfile, filter_spec=None):
+        """
+        Dump the contents of logcat, for the specified filter spec to the
+        specified output file.
+        See http://developer.android.com/tools/help/logcat.html
+
+        :param outfile: Output file on the host into which the contents of the
+                        log will be written.
+        :param filter_spec: Logcat filter specification.
+                            see http://developer.android.com/tools/debugging/debugging-log.html#filteringOutput
+
+        """
+        if self._logcat_poller:
+            return self._logcat_poller.write_log(outfile)
+        else:
+            if filter_spec:
+                command = 'logcat -d -s {} > {}'.format(filter_spec, outfile)
+            else:
+                command = 'logcat -d > {}'.format(outfile)
+            return adb_command(self.adb_name, command, timeout=self.default_timeout)
+
+    def clear_logcat(self):
+        """Clear (flush) logcat log."""
+        if self._logcat_poller:
+            return self._logcat_poller.clear_buffer()
+        else:
+            return adb_shell(self.adb_name, 'logcat -c', timeout=self.default_timeout)
+
+    def capture_screen(self, filepath):
+        """Caputers the current device screen into the specified file in a PNG format."""
+        on_device_file = self.path.join(self.working_directory, 'screen_capture.png')
+        self.execute('screencap -p  {}'.format(on_device_file))
+        self.pull_file(on_device_file, filepath)
+        self.delete_file(on_device_file)
+
+    def is_screen_on(self):
+        """Returns ``True`` if the device screen is currently on, ``False`` otherwise."""
+        output = self.execute('dumpsys power')
+        match = SCREEN_STATE_REGEX.search(output)
+        if match:
+            return boolean(match.group(1))
+        else:
+            raise DeviceError('Could not establish screen state.')
+
+    def ensure_screen_is_on(self):
+        if not self.is_screen_on():
+            self.execute('input keyevent 26')
+
+    def disable_screen_lock(self):
+        """
+        Attempts to disable he screen lock on the device.
+
+        .. note:: This does not always work...
+
+        Added inversion 2.1.4
+
+        """
+        lockdb = '/data/system/locksettings.db'
+        sqlcommand = "update locksettings set value=\\'0\\' where name=\\'screenlock.disabled\\';"
+        self.execute('sqlite3 {} "{}"'.format(lockdb, sqlcommand), as_root=True)
+
+    def disable_selinux(self):
+        # This may be invoked from intialize() so we can't use execute() or the
+        # standard API for doing this.
+        api_level = int(adb_shell(self.adb_name, 'getprop ro.build.version.sdk',
+                                  timeout=self.default_timeout).strip())
+        # SELinux was added in Android 4.3 (API level 18). Trying to
+        # 'getenforce' in earlier versions will produce an error.
+        if api_level >= 18:
+            se_status = self.execute('getenforce', as_root=True).strip()
+            if se_status == 'Enforcing':
+                self.execute('setenforce 0', as_root=True)
+
+    # Internal methods: do not use outside of the class.
+
+    def _update_build_properties(self, filepath, props):
+        try:
+            with open(filepath) as fh:
+                for line in fh:
+                    line = re.sub(r'#.*', '', line).strip()
+                    if not line:
+                        continue
+                    key, value = line.split('=', 1)
+                    props[key] = value
+        except ValueError:
+            self.logger.warning('Could not parse build.prop.')
+
+    def _update_versions(self, filepath, props):
+        with open(filepath) as fh:
+            text = fh.read()
+            props['version'] = text
+            text = re.sub(r'#.*', '', text).strip()
+            match = re.search(r'^(Linux version .*?)\s*\((gcc version .*)\)$', text)
+            if match:
+                props['linux_version'] = match.group(1).strip()
+                props['gcc_version'] = match.group(2).strip()
+            else:
+                self.logger.warning('Could not parse version string.')
+
+
+class _LogcatPoller(threading.Thread):
+
+    join_timeout = 5
+
+    def __init__(self, device, period, timeout=None):
+        super(_LogcatPoller, self).__init__()
+        self.adb_device = device.adb_name
+        self.logger = device.logger
+        self.period = period
+        self.timeout = timeout
+        self.stop_signal = threading.Event()
+        self.lock = threading.RLock()
+        self.buffer_file = tempfile.mktemp()
+        self.last_poll = 0
+        self.daemon = True
+        self.exc = None
+
+    def run(self):
+        self.logger.debug('Starting logcat polling.')
+        try:
+            while True:
+                if self.stop_signal.is_set():
+                    break
+                with self.lock:
+                    current_time = time.time()
+                    if (current_time - self.last_poll) >= self.period:
+                        self._poll()
+                time.sleep(0.5)
+        except Exception:  # pylint: disable=W0703
+            self.exc = WorkerThreadError(self.name, sys.exc_info())
+        self.logger.debug('Logcat polling stopped.')
+
+    def stop(self):
+        self.logger.debug('Stopping logcat polling.')
+        self.stop_signal.set()
+        self.join(self.join_timeout)
+        if self.is_alive():
+            self.logger.error('Could not join logcat poller thread.')
+        if self.exc:
+            raise self.exc  # pylint: disable=E0702
+
+    def clear_buffer(self):
+        self.logger.debug('Clearing logcat buffer.')
+        with self.lock:
+            adb_shell(self.adb_device, 'logcat -c', timeout=self.timeout)
+            with open(self.buffer_file, 'w') as _:  # NOQA
+                pass
+
+    def write_log(self, outfile):
+        self.logger.debug('Writing logbuffer to {}.'.format(outfile))
+        with self.lock:
+            self._poll()
+            if os.path.isfile(self.buffer_file):
+                shutil.copy(self.buffer_file, outfile)
+            else:  # there was no logcat trace at this time
+                with open(outfile, 'w') as _:  # NOQA
+                    pass
+
+    def close(self):
+        self.logger.debug('Closing logcat poller.')
+        if os.path.isfile(self.buffer_file):
+            os.remove(self.buffer_file)
+
+    def _poll(self):
+        with self.lock:
+            self.last_poll = time.time()
+            adb_command(self.adb_device, 'logcat -d >> {}'.format(self.buffer_file), timeout=self.timeout)
+            adb_command(self.adb_device, 'logcat -c', timeout=self.timeout)
+
+
+class BigLittleDevice(AndroidDevice):  # pylint: disable=W0223
+
+    parameters = [
+        Parameter('scheduler', default='hmp', override=True),
+    ]
+

wlauto/common/android/resources.py

@@ -0,0 +1,36 @@
+#    Copyright 2014-2015 ARM Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+
+from wlauto.common.resources import FileResource
+
+
+class ReventFile(FileResource):
+
+    name = 'revent'
+
+    def __init__(self, owner, stage):
+        super(ReventFile, self).__init__(owner)
+        self.stage = stage
+
+
+class JarFile(FileResource):
+
+    name = 'jar'
+
+
+class ApkFile(FileResource):
+
+    name = 'apk'

wlauto/common/android/workload.py

@@ -0,0 +1,425 @@
+#    Copyright 2013-2015 ARM Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import os
+import sys
+import time
+
+from wlauto.core.extension import Parameter
+from wlauto.core.workload import Workload
+from wlauto.core.resource import NO_ONE
+from wlauto.common.resources import ExtensionAsset, Executable
+from wlauto.exceptions import WorkloadError, ResourceError
+from wlauto.utils.android import ApkInfo
+from wlauto.utils.types import boolean
+import wlauto.common.android.resources
+
+
+DELAY = 5
+
+
+class UiAutomatorWorkload(Workload):
+    """
+    Base class for all workloads that rely on a UI Automator JAR file.
+
+    This class should be subclassed by workloads that rely on android UiAutomator
+    to work. This class handles transferring the UI Automator JAR file to the device
+    and invoking it to run the workload. By default, it will look for the JAR file in
+    the same directory as the .py file for the workload (this can be changed by overriding
+    the ``uiauto_file`` property in the subclassing workload).
+
+    To inintiate UI Automation, the fully-qualified name of the Java class and the
+    corresponding method name are needed. By default, the package part of the class name
+    is derived from the class file, and class and method names are ``UiAutomation``
+    and ``runUiAutomaton`` respectively. If you have generated the boilder plate for the
+    UiAutomatior code using ``create_workloads`` utility, then everything should be named
+    correctly. If you're creating the Java project manually, you need to make sure the names
+    match what is expected, or you could override ``uiauto_package``, ``uiauto_class`` and
+    ``uiauto_method`` class attributes with the value that match your Java code.
+
+    You can also pass parameters to the JAR file. To do this add the parameters to
+    ``self.uiauto_params`` dict inside your class's ``__init__`` or ``setup`` methods.
+
+    """
+
+    supported_platforms = ['android']
+
+    uiauto_package = ''
+    uiauto_class = 'UiAutomation'
+    uiauto_method = 'runUiAutomation'
+
+    # Can be overidden by subclasses to adjust to run time of specific
+    # benchmarks.
+    run_timeout = 4 * 60  # seconds
+
+    def __init__(self, device, _call_super=True, **kwargs):  # pylint: disable=W0613
+        if _call_super:
+            super(UiAutomatorWorkload, self).__init__(device, **kwargs)
+        self.uiauto_file = None
+        self.device_uiauto_file = None
+        self.command = None
+        self.uiauto_params = {}
+
+    def init_resources(self, context):
+        self.uiauto_file = context.resolver.get(wlauto.common.android.resources.JarFile(self))
+        if not self.uiauto_file:
+            raise ResourceError('No UI automation JAR file found for workload {}.'.format(self.name))
+        self.device_uiauto_file = self.device.path.join(self.device.working_directory,
+                                                        os.path.basename(self.uiauto_file))
+        if not self.uiauto_package:
+            self.uiauto_package = os.path.splitext(os.path.basename(self.uiauto_file))[0]
+
+    def setup(self, context):
+        method_string = '{}.{}#{}'.format(self.uiauto_package, self.uiauto_class, self.uiauto_method)
+        params_dict = self.uiauto_params
+        params_dict['workdir'] = self.device.working_directory
+        params = ''
+        for k, v in self.uiauto_params.iteritems():
+            params += ' -e {} {}'.format(k, v)
+        self.command = 'uiautomator runtest {}{} -c {}'.format(self.device_uiauto_file, params, method_string)
+        self.device.push_file(self.uiauto_file, self.device_uiauto_file)
+        self.device.killall('uiautomator')
+
+    def run(self, context):
+        result = self.device.execute(self.command, self.run_timeout)
+        if 'FAILURE' in result:
+            raise WorkloadError(result)
+        else:
+            self.logger.debug(result)
+        time.sleep(DELAY)
+
+    def update_result(self, context):
+        pass
+
+    def teardown(self, context):
+        self.device.delete_file(self.device_uiauto_file)
+
+    def validate(self):
+        if not self.uiauto_file:
+            raise WorkloadError('No UI automation JAR file found for workload {}.'.format(self.name))
+        if not self.uiauto_package:
+            raise WorkloadError('No UI automation package specified for workload {}.'.format(self.name))
+
+
+class ApkWorkload(Workload):
+    """
+    A workload based on an APK file.
+
+    Defines the following attributes:
+
+    :package: The package name of the app. This is usually a Java-style name of the form
+              ``com.companyname.appname``.
+    :activity: This is the initial activity of the app. This will be used to launch the
+               app during the setup.
+    :view: The class of the main view pane of the app. This needs to be defined in order
+           to collect SurfaceFlinger-derived statistics (such as FPS) for the app, but
+           may otherwise be left as ``None``.
+    :install_timeout: Timeout for the installation of the APK. This may vary wildly based on
+                      the size and nature of a specific APK, and so should be defined on
+                      per-workload basis.
+
+                      .. note:: To a lesser extent, this will also vary based on the the
+                                device and the nature of adb connection (USB vs Ethernet),
+                                so, as with all timeouts, so leeway must be included in
+                                the specified value.
+
+    .. note:: Both package and activity for a workload may be obtained from the APK using
+              the ``aapt`` tool that comes with the ADT  (Android Developemnt Tools) bundle.
+
+    """
+    package = None
+    activity = None
+    view = None
+    install_timeout = None
+    default_install_timeout = 300
+
+    parameters = [
+        Parameter('uninstall_apk', kind=boolean, default=False,
+                  description="If ``True``, will uninstall workload's APK as part of teardown."),
+    ]
+
+    def __init__(self, device, _call_super=True, **kwargs):
+        if _call_super:
+            super(ApkWorkload, self).__init__(device, **kwargs)
+        self.apk_file = None
+        self.apk_version = None
+        self.logcat_log = None
+        self.force_reinstall = kwargs.get('force_reinstall', False)
+        if not self.install_timeout:
+            self.install_timeout = self.default_install_timeout
+
+    def init_resources(self, context):
+        self.apk_file = context.resolver.get(wlauto.common.android.resources.ApkFile(self), version=getattr(self, 'version', None))
+
+    def setup(self, context):
+        self.initialize_package(context)
+        self.start_activity()
+        self.device.execute('am kill-all')  # kill all *background* activities
+        self.device.clear_logcat()
+
+    def initialize_package(self, context):
+        installed_version = self.device.get_installed_package_version(self.package)
+        host_version = ApkInfo(self.apk_file).version_name
+        if installed_version != host_version:
+            if installed_version:
+                message = '{} host version: {}, device version: {}; re-installing...'
+                self.logger.debug(message.format(os.path.basename(self.apk_file), host_version, installed_version))
+            else:
+                message = '{} host version: {}, not found on device; installing...'
+                self.logger.debug(message.format(os.path.basename(self.apk_file), host_version))
+            self.force_reinstall = True
+        else:
+            message = '{} version {} found on both device and host.'
+            self.logger.debug(message.format(os.path.basename(self.apk_file), host_version))
+        if self.force_reinstall:
+            if installed_version:
+                self.device.uninstall(self.package)
+            self.install_apk(context)
+        else:
+            self.reset(context)
+        self.apk_version = host_version
+
+    def start_activity(self):
+        output = self.device.execute('am start -W -n {}/{}'.format(self.package, self.activity))
+        if 'Error:' in output:
+            self.device.execute('am force-stop {}'.format(self.package))  # this will dismiss any erro dialogs
+            raise WorkloadError(output)
+        self.logger.debug(output)
+
+    def reset(self, context):  # pylint: disable=W0613
+        self.device.execute('am force-stop {}'.format(self.package))
+        self.device.execute('pm clear {}'.format(self.package))
+
+    def install_apk(self, context):
+        output = self.device.install(self.apk_file, self.install_timeout)
+        if 'Failure' in output:
+            if 'ALREADY_EXISTS' in output:
+                self.logger.warn('Using already installed APK (did not unistall properly?)')
+            else:
+                raise WorkloadError(output)
+        else:
+            self.logger.debug(output)
+        self.do_post_install(context)
+
+    def do_post_install(self, context):
+        """ May be overwritten by dervied classes."""
+        pass
+
+    def run(self, context):
+        pass
+
+    def update_result(self, context):
+        self.logcat_log = os.path.join(context.output_directory, 'logcat.log')
+        self.device.dump_logcat(self.logcat_log)
+        context.add_iteration_artifact(name='logcat',
+                                       path='logcat.log',
+                                       kind='log',
+                                       description='Logact dump for the run.')
+
+    def teardown(self, context):
+        self.device.execute('am force-stop {}'.format(self.package))
+        if self.uninstall_apk:
+            self.device.uninstall(self.package)
+
+    def validate(self):
+        if not self.apk_file:
+            raise WorkloadError('No APK file found for workload {}.'.format(self.name))
+
+
+AndroidBenchmark = ApkWorkload  # backward compatibility
+
+
+class ReventWorkload(Workload):
+
+    default_setup_timeout = 5 * 60  # in seconds
+    default_run_timeout = 10 * 60  # in seconds
+
+    def __init__(self, device, _call_super=True, **kwargs):
+        if _call_super:
+            super(ReventWorkload, self).__init__(device, **kwargs)
+        devpath = self.device.path
+        self.on_device_revent_binary = devpath.join(self.device.working_directory, 'revent')
+        self.on_device_setup_revent = devpath.join(self.device.working_directory, '{}.setup.revent'.format(self.device.name))
+        self.on_device_run_revent = devpath.join(self.device.working_directory, '{}.run.revent'.format(self.device.name))
+        self.setup_timeout = kwargs.get('setup_timeout', self.default_setup_timeout)
+        self.run_timeout = kwargs.get('run_timeout', self.default_run_timeout)
+        self.revent_setup_file = None
+        self.revent_run_file = None
+
+    def init_resources(self, context):
+        self.revent_setup_file = context.resolver.get(wlauto.common.android.resources.ReventFile(self, 'setup'))
+        self.revent_run_file = context.resolver.get(wlauto.common.android.resources.ReventFile(self, 'run'))
+
+    def setup(self, context):
+        self._check_revent_files(context)
+        self.device.killall('revent')
+        command = '{} replay {}'.format(self.on_device_revent_binary, self.on_device_setup_revent)
+        self.device.execute(command, timeout=self.setup_timeout)
+
+    def run(self, context):
+        command = '{} replay {}'.format(self.on_device_revent_binary, self.on_device_run_revent)
+        self.logger.debug('Replaying {}'.format(os.path.basename(self.on_device_run_revent)))
+        self.device.execute(command, timeout=self.run_timeout)
+        self.logger.debug('Replay completed.')
+
+    def update_result(self, context):
+        pass
+
+    def teardown(self, context):
+        self.device.delete_file(self.on_device_setup_revent)
+        self.device.delete_file(self.on_device_run_revent)
+
+    def _check_revent_files(self, context):
+        # check the revent binary
+        revent_binary = context.resolver.get(Executable(NO_ONE, self.device.abi, 'revent'))
+        if not os.path.isfile(revent_binary):
+            message = '{} does not exist. '.format(revent_binary)
+            message += 'Please build revent for your system and place it in that location'
+            raise WorkloadError(message)
+        if not self.revent_setup_file:
+            # pylint: disable=too-few-format-args
+            message = '{0}.setup.revent file does not exist, Please provide one for your device, {0}'.format(self.device.name)
+            raise WorkloadError(message)
+        if not self.revent_run_file:
+            # pylint: disable=too-few-format-args
+            message = '{0}.run.revent file does not exist, Please provide one for your device, {0}'.format(self.device.name)
+            raise WorkloadError(message)
+
+        self.on_device_revent_binary = self.device.install_executable(revent_binary)
+        self.device.push_file(self.revent_run_file, self.on_device_run_revent)
+        self.device.push_file(self.revent_setup_file, self.on_device_setup_revent)
+
+
+class AndroidUiAutoBenchmark(UiAutomatorWorkload, AndroidBenchmark):
+
+    def __init__(self, device, **kwargs):
+        UiAutomatorWorkload.__init__(self, device, **kwargs)
+        AndroidBenchmark.__init__(self, device, _call_super=False, **kwargs)
+
+    def init_resources(self, context):
+        UiAutomatorWorkload.init_resources(self, context)
+        AndroidBenchmark.init_resources(self, context)
+
+    def setup(self, context):
+        UiAutomatorWorkload.setup(self, context)
+        AndroidBenchmark.setup(self, context)
+
+    def update_result(self, context):
+        UiAutomatorWorkload.update_result(self, context)
+        AndroidBenchmark.update_result(self, context)
+
+    def teardown(self, context):
+        UiAutomatorWorkload.teardown(self, context)
+        AndroidBenchmark.teardown(self, context)
+
+
+class GameWorkload(ApkWorkload, ReventWorkload):
+    """
+    GameWorkload is the base class for all the workload that use revent files to
+    run.
+
+    For more in depth details on how to record revent files, please see
+    :ref:`revent_files_creation`. To subclass this class, please refer to
+    :ref:`GameWorkload`.
+
+    Additionally, this class defines the following attributes:
+
+    :asset_file: A tarball containing additional assets for the workload. These are the assets
+                 that are not part of the APK but would need to be downloaded by the workload
+                 (usually, on first run of the app). Since the presence of a network connection
+                 cannot be assumed on some devices, this provides an alternative means of obtaining
+                 the assets.
+    :saved_state_file: A tarball containing the saved state for a workload. This tarball gets
+                       deployed in the same way as the asset file. The only difference being that
+                       it is usually much slower and re-deploying the tarball should alone be
+                       enough to reset the workload to a known state (without having to reinstall
+                       the app or re-deploy the other assets).
+    :loading_time: Time it takes for the workload to load after the initial activity has been
+                   started.
+
+    """
+
+    # May be optionally overwritten by subclasses
+    asset_file = None
+    saved_state_file = None
+    view = 'SurfaceView'
+    install_timeout = 500
+    loading_time = 10
+
+    def __init__(self, device, **kwargs):  # pylint: disable=W0613
+        ApkWorkload.__init__(self, device, **kwargs)
+        ReventWorkload.__init__(self, device, _call_super=False, **kwargs)
+        self.logcat_process = None
+        self.module_dir = os.path.dirname(sys.modules[self.__module__].__file__)
+        self.revent_dir = os.path.join(self.module_dir, 'revent_files')
+
+    def init_resources(self, context):
+        ApkWorkload.init_resources(self, context)
+        ReventWorkload.init_resources(self, context)
+
+    def setup(self, context):
+        ApkWorkload.setup(self, context)
+        self.logger.debug('Waiting for the game to load...')
+        time.sleep(self.loading_time)
+        ReventWorkload.setup(self, context)
+
+    def do_post_install(self, context):
+        ApkWorkload.do_post_install(self, context)
+        self._deploy_assets(context)
+
+    def reset(self, context):
+        # If saved state exists, restore it; if not, do full
+        # uninstall/install cycle.
+        if self.saved_state_file:
+            self._deploy_resource_tarball(context, self.saved_state_file)
+        else:
+            ApkWorkload.reset(self, context)
+            self._deploy_assets(context)
+
+    def run(self, context):
+        ReventWorkload.run(self, context)
+
+    def teardown(self, context):
+        if not self.saved_state_file:
+            ApkWorkload.teardown(self, context)
+        else:
+            self.device.execute('am force-stop {}'.format(self.package))
+        ReventWorkload.teardown(self, context)
+
+    def _deploy_assets(self, context, timeout=300):
+        if self.asset_file:
+            self._deploy_resource_tarball(context, self.asset_file, timeout)
+        if self.saved_state_file:  # must be deployed *after* asset tarball!
+            self._deploy_resource_tarball(context, self.saved_state_file, timeout)
+
+    def _deploy_resource_tarball(self, context, resource_file, timeout=300):
+        kind = 'data'
+        if ':' in resource_file:
+            kind, resource_file = resource_file.split(':', 1)
+        ondevice_cache = self.device.path.join(self.device.resource_cache, self.name, resource_file)
+        if not self.device.file_exists(ondevice_cache):
+            asset_tarball = context.resolver.get(ExtensionAsset(self, resource_file))
+            if not asset_tarball:
+                message = 'Could not find resource {} for workload {}.'
+                raise WorkloadError(message.format(resource_file, self.name))
+            # adb push will create intermediate directories if they don't
+            # exist.
+            self.device.push_file(asset_tarball, ondevice_cache)
+
+        device_asset_directory = self.device.path.join(self.device.external_storage_directory, 'Android', kind)
+        deploy_command = 'cd {} && {} tar -xzf {}'.format(device_asset_directory,
+                                                          self.device.busybox,
+                                                          ondevice_cache)
+        self.device.execute(deploy_command, timeout=timeout, as_root=True)