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