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 import sys
   6
   7 from telemetry.core.platform import linux_platform_backend
   8 from telemetry.core.platform import mac_platform_backend
   9 from telemetry.core.platform import win_platform_backend
  10
  11 class Platform(object):
  12   """The platform that the target browser is running on.
  13
  14   Provides a limited interface to interact with the platform itself, where
  15   possible. It's important to note that platforms may not provide a specific
  16   API, so check with IsFooBar() for availability.
  17   """
  18   def __init__(self, platform_backend):
  19     self._platform_backend = platform_backend
  20
  21   def IsRawDisplayFrameRateSupported(self):
  22     """Platforms may be able to collect GL surface stats."""
  23     return self._platform_backend.IsRawDisplayFrameRateSupported()
  24
  25   def StartRawDisplayFrameRateMeasurement(self):
  26     """Start measuring GL surface stats."""
  27     return self._platform_backend.StartRawDisplayFrameRateMeasurement()
  28
  29   def StopRawDisplayFrameRateMeasurement(self):
  30     """Stop measuring GL surface stats."""
  31     return self._platform_backend.StopRawDisplayFrameRateMeasurement()
  32
  33   class RawDisplayFrameRateMeasurement(object):
  34     def __init__(self, name, value, unit):
  35       self._name = name
  36       self._value = value
  37       self._unit = unit
  38
  39     @property
  40     def name(self):
  41       return self._name
  42
  43     @property
  44     def value(self):
  45       return self._value
  46
  47     @property
  48     def unit(self):
  49       return self._unit
  50
  51   def GetRawDisplayFrameRateMeasurements(self):
  52     """Returns a list of RawDisplayFrameRateMeasurement."""
  53     return self._platform_backend.GetRawDisplayFrameRateMeasurements()
  54
  55   def SetFullPerformanceModeEnabled(self, enabled):
  56     """Platforms may tweak their CPU governor, system status, etc.
  57
  58     Most platforms can operate in a battery saving mode. While good for battery
  59     life, this can cause confusing performance results and add noise. Turning
  60     full performance mode on disables these features, which is useful for
  61     performance testing.
  62     """
  63     return self._platform_backend.SetFullPerformanceModeEnabled(enabled)
  64
  65   def CanMonitorThermalThrottling(self):
  66     """Platforms may be able to detect thermal throttling.
  67
  68     Some fan-less computers go into a reduced performance mode when their heat
  69     exceeds a certain threshold. Performance tests in particular should use this
  70     API to detect if this has happened and interpret results accordingly.
  71     """
  72     return self._platform_backend.CanMonitorThermalThrottling()
  73
  74   def IsThermallyThrottled(self):
  75     """Returns True if the device is currently thermally throttled."""
  76     return self._platform_backend.IsThermallyThrottled()
  77
  78   def HasBeenThermallyThrottled(self):
  79     """Returns True if the device has been thermally throttled."""
  80     return self._platform_backend.HasBeenThermallyThrottled()
  81
  82   def GetOSName(self):
  83     """Returns a string description of the Platform OS.
  84
  85     Examples: WIN, MAC, LINUX, CHROMEOS"""
  86     return self._platform_backend.GetOSName()
  87
  88   def GetOSVersionName(self):
  89     """Returns a logically sortable, string-like description of the Platform OS
  90     version.
  91
  92     Examples: VISTA, WIN7, LION, MOUNTAINLION"""
  93     return self._platform_backend.GetOSVersionName()
  94
  95   def CanFlushIndividualFilesFromSystemCache(self):
  96     """Returns true if the disk cache can be flushed for specific files."""
  97     return self._platform_backend.CanFlushIndividualFilesFromSystemCache()
  98
  99   def FlushEntireSystemCache(self):
 100     """Flushes the OS's file cache completely.
 101
 102     This function may require root or administrator access."""
 103     return self._platform_backend.FlushEntireSystemCache()
 104
 105   def FlushSystemCacheForDirectory(self, directory, ignoring=None):
 106     """Flushes the OS's file cache for the specified directory.
 107
 108     Any files or directories inside |directory| matching a name in the
 109     |ignoring| list will be skipped.
 110
 111     This function does not require root or administrator access."""
 112     return self._platform_backend.FlushSystemCacheForDirectory(
 113         directory, ignoring=ignoring)
 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 CanMonitorPowerSync(self):
 171     """Returns True iff power can be monitored synchronously via
 172     MonitorPowerSync().
 173     """
 174     return self._platform_backend.CanMonitorPowerSync()
 175
 176   def MonitorPowerSync(self, duration_ms):
 177     """Synchronously monitors power for |duration_ms|.
 178
 179     Returns:
 180       A dict of power utilization statistics containing: {
 181         # The instantaneous power (voltage * current) reading in milliwatts at
 182         # each sample.
 183         'power_samples_mw': [mw0, mw1, ..., mwN],
 184
 185         # The total energy consumption during the sampling period in milliwatt
 186         # hours. May be estimated by integrating power samples or may be exact
 187         # on supported hardware.
 188         'energy_consumption_mwh': mwh,
 189
 190         # A platform-specific dictionary of additional details about the
 191         # utilization of individual hardware components.
 192         hw_component_utilization: {
 193            ...
 194         }
 195       }
 196     """
 197     return self._platform_backend.MonitorPowerSync(duration_ms)
 198
 199   def CanMonitorPowerAsync(self):
 200     """Returns True iff power can be monitored asynchronously via
 201     StartMonitoringPowerAsync() and StopMonitoringPowerAsync().
 202     """
 203     return self._platform_backend.CanMonitorPowerAsync()
 204
 205   def StartMonitoringPowerAsync(self):
 206     """Starts monitoring power utilization statistics."""
 207     assert self._platform_backend.CanMonitorPowerAsync()
 208     self._platform_backend.StartMonitoringPowerAsync()
 209
 210   def StopMonitoringPowerAsync(self):
 211     """Stops monitoring power utilization and returns collects stats
 212
 213     Returns:
 214       A dict of power utilization statistics containing: {
 215         # An identifier for the data provider. Allows to evaluate the precision
 216         # of the data. Example values: monsoon, powermetrics, ds2784
 217         'identifier': identifier,
 218
 219         # The instantaneous power (voltage * current) reading in milliwatts at
 220         # each sample.
 221         'power_samples_mw':  [mw0, mw1, ..., mwN],
 222
 223         # The total energy consumption during the sampling period in milliwatt
 224         # hours. May be estimated by integrating power samples or may be exact
 225         # on supported hardware.
 226         'energy_consumption_mwh': mwh,
 227
 228         # A platform-specific dictionary of additional details about the
 229         # utilization of individual hardware components.
 230         hw_component_utilization: {
 231            ...
 232         }
 233       }
 234     """
 235     return self._platform_backend.StopMonitoringPowerAsync()
 236
 237
 238 def CreatePlatformBackendForCurrentOS():
 239   if sys.platform.startswith('linux'):
 240     return linux_platform_backend.LinuxPlatformBackend()
 241   elif sys.platform == 'darwin':
 242     return mac_platform_backend.MacPlatformBackend()
 243   elif sys.platform == 'win32':
 244     return win_platform_backend.WinPlatformBackend()
 245   else:
 246     raise NotImplementedError()