src/tools/telemetry/telemetry/core/platform/__init__.py

   1 # Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 # Use of this source code is governed by a BSD-style license that can be
   3 # found in the LICENSE file.
   4
   5 class Platform(object):
   6   """The platform that the target browser is running on.
   7
   8   Provides a limited interface to interact with the platform itself, where
   9   possible. It's important to note that platforms may not provide a specific
  10   API, so check with IsFooBar() for availability.
  11   """
  12   def __init__(self, platform_backend):
  13     self._platform_backend = platform_backend
  14
  15   def IsRawDisplayFrameRateSupported(self):
  16     """Platforms may be able to collect GL surface stats."""
  17     return self._platform_backend.IsRawDisplayFrameRateSupported()
  18
  19   def StartRawDisplayFrameRateMeasurement(self):
  20     """Start measuring GL surface stats."""
  21     return self._platform_backend.StartRawDisplayFrameRateMeasurement()
  22
  23   def StopRawDisplayFrameRateMeasurement(self):
  24     """Stop measuring GL surface stats."""
  25     return self._platform_backend.StopRawDisplayFrameRateMeasurement()
  26
  27   class RawDisplayFrameRateMeasurement(object):
  28     def __init__(self, name, value, unit):
  29       self._name = name
  30       self._value = value
  31       self._unit = unit
  32
  33     @property
  34     def name(self):
  35       return self._name
  36
  37     @property
  38     def value(self):
  39       return self._value
  40
  41     @property
  42     def unit(self):
  43       return self._unit
  44
  45   def GetRawDisplayFrameRateMeasurements(self):
  46     """Returns a list of RawDisplayFrameRateMeasurement."""
  47     return self._platform_backend.GetRawDisplayFrameRateMeasurements()
  48
  49   def SetFullPerformanceModeEnabled(self, enabled):
  50     """Platforms may tweak their CPU governor, system status, etc.
  51
  52     Most platforms can operate in a battery saving mode. While good for battery
  53     life, this can cause confusing performance results and add noise. Turning
  54     full performance mode on disables these features, which is useful for
  55     performance testing.
  56     """
  57     return self._platform_backend.SetFullPerformanceModeEnabled(enabled)
  58
  59   def CanMonitorThermalThrottling(self):
  60     """Platforms may be able to detect thermal throttling.
  61
  62     Some fan-less computers go into a reduced performance mode when their heat
  63     exceeds a certain threshold. Performance tests in particular should use this
  64     API to detect if this has happened and interpret results accordingly.
  65     """
  66     return self._platform_backend.CanMonitorThermalThrottling()
  67
  68   def IsThermallyThrottled(self):
  69     """Returns True if the device is currently thermally throttled."""
  70     return self._platform_backend.IsThermallyThrottled()
  71
  72   def HasBeenThermallyThrottled(self):
  73     """Returns True if the device has been thermally throttled."""
  74     return self._platform_backend.HasBeenThermallyThrottled()
  75
  76   def GetOSName(self):
  77     """Returns a string description of the Platform OS.
  78
  79     Examples: WIN, MAC, LINUX, CHROMEOS"""
  80     return self._platform_backend.GetOSName()
  81
  82   def GetOSVersionName(self):
  83     """Returns a logically sortable, string-like description of the Platform OS
  84     version.
  85
  86     Examples: VISTA, WIN7, LION, MOUNTAINLION"""
  87     return self._platform_backend.GetOSVersionName()
  88
  89   def CanFlushIndividualFilesFromSystemCache(self):
  90     """Returns true if the disk cache can be flushed for specific files."""
  91     return self._platform_backend.CanFlushIndividualFilesFromSystemCache()
  92
  93   def FlushEntireSystemCache(self):
  94     """Flushes the OS's file cache completely.
  95
  96     This function may require root or administrator access."""
  97     return self._platform_backend.FlushEntireSystemCache()
  98
  99   def FlushSystemCacheForDirectory(self, directory, ignoring=None):
 100     """Flushes the OS's file cache for the specified directory.
 101
 102     Any files or directories inside |directory| matching a name in the
 103     |ignoring| list will be skipped.
 104
 105     This function does not require root or administrator access."""
 106     return self._platform_backend.FlushSystemCacheForDirectory(
 107         directory, ignoring=ignoring)
 108
 109   def FlushDnsCache(self):
 110     """Flushes the OS's DNS cache completely.
 111
 112     This function may require root or administrator access."""
 113     return self._platform_backend.FlushDnsCache()
 114
 115   def LaunchApplication(self, application, parameters=None,
 116                         elevate_privilege=False):
 117     """"Launches the given |application| with a list of |parameters| on the OS.
 118
 119     Set |elevate_privilege| to launch the application with root or admin rights.
 120
 121     Returns:
 122       A popen style process handle for host platforms.
 123     """
 124     return self._platform_backend.LaunchApplication(
 125         application, parameters, elevate_privilege=elevate_privilege)
 126
 127   def IsApplicationRunning(self, application):
 128     """Returns whether an application is currently running."""
 129     return self._platform_backend.IsApplicationLaunchning(application)
 130
 131   def CanLaunchApplication(self, application):
 132     """Returns whether the platform can launch the given application."""
 133     return self._platform_backend.CanLaunchApplication(application)
 134
 135   def InstallApplication(self, application):
 136     """Installs the given application."""
 137     return self._platform_backend.InstallApplication(application)
 138
 139   def CanCaptureVideo(self):
 140     """Returns a bool indicating whether the platform supports video capture."""
 141     return self._platform_backend.CanCaptureVideo()
 142
 143   def StartVideoCapture(self, min_bitrate_mbps):
 144     """Starts capturing video.
 145
 146     Outer framing may be included (from the OS, browser window, and webcam).
 147
 148     Args:
 149       min_bitrate_mbps: The minimum capture bitrate in MegaBits Per Second.
 150           The platform is free to deliver a higher bitrate if it can do so
 151           without increasing overhead.
 152
 153     Raises:
 154       ValueError if the required |min_bitrate_mbps| can't be achieved.
 155     """
 156     return self._platform_backend.StartVideoCapture(min_bitrate_mbps)
 157
 158   def StopVideoCapture(self):
 159     """Stops capturing video.
 160
 161     Yields:
 162       (time_ms, bitmap) tuples representing each video keyframe. Only the first
 163       frame in a run of sequential duplicate bitmaps is included.
 164         time_ms is milliseconds relative to the first frame.
 165         bitmap is a telemetry.core.Bitmap.
 166     """
 167     for t in self._platform_backend.StopVideoCapture():
 168       yield t
 169
 170   def CanMonitorPower(self):
 171     """Returns True iff power can be monitored asynchronously via
 172     StartMonitoringPower() and StopMonitoringPower().
 173     """
 174     return self._platform_backend.CanMonitorPower()
 175
 176   def StartMonitoringPower(self, browser):
 177     """Starts monitoring power utilization statistics.
 178
 179     Args:
 180       browser: The browser to monitor.
 181     """
 182     assert self._platform_backend.CanMonitorPower()
 183     self._platform_backend.StartMonitoringPower(browser)
 184
 185   def StopMonitoringPower(self):
 186     """Stops monitoring power utilization and returns stats
 187
 188     Returns:
 189       None if power measurement failed for some reason, otherwise a dict of
 190       power utilization statistics containing: {
 191         # An identifier for the data provider. Allows to evaluate the precision
 192         # of the data. Example values: monsoon, powermetrics, ds2784
 193         'identifier': identifier,
 194
 195         # The instantaneous power (voltage * current) reading in milliwatts at
 196         # each sample.
 197         'power_samples_mw':  [mw0, mw1, ..., mwN],
 198
 199         # The total energy consumption during the sampling period in milliwatt
 200         # hours. May be estimated by integrating power samples or may be exact
 201         # on supported hardware.
 202         'energy_consumption_mwh': mwh,
 203
 204         # A platform-specific dictionary of additional details about the
 205         # utilization of individual hardware components.
 206         component_utilization: {
 207
 208           # Platform-specific data not attributed to any particular hardware
 209           # component.
 210           whole_package: {
 211
 212             # Device-specific onboard temperature sensor.
 213             'average_temperature_c': c,
 214
 215             ...
 216           }
 217
 218           ...
 219         }
 220       }
 221     """
 222     return self._platform_backend.StopMonitoringPower()