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
5import sys
6
7from telemetry.core.platform import linux_platform_backend
8from telemetry.core.platform import mac_platform_backend
9from telemetry.core.platform import win_platform_backend
10
11class 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 string description of the Platform OS version.
90
91    Examples: VISTA, WIN7, LION, MOUNTAINLION"""
92    return self._platform_backend.GetOSVersionName()
93
94  def CanFlushIndividualFilesFromSystemCache(self):
95    """Returns true if the disk cache can be flushed for specific files."""
96    return self._platform_backend.CanFlushIndividualFilesFromSystemCache()
97
98  def FlushEntireSystemCache(self):
99    """Flushes the OS's file cache completely.
100
101    This function may require root or administrator access."""
102    return self._platform_backend.FlushEntireSystemCache()
103
104  def FlushSystemCacheForDirectory(self, directory, ignoring=None):
105    """Flushes the OS's file cache for the specified directory.
106
107    Any files or directories inside |directory| matching a name in the
108    |ignoring| list will be skipped.
109
110    This function does not require root or administrator access."""
111    return self._platform_backend.FlushSystemCacheForDirectory(
112        directory, ignoring=ignoring)
113
114  def LaunchApplication(self, application, parameters=None):
115    """"Launchs a given application on the OS."""
116    return self._platform_backend.LaunchApplication(application,
117                                                    parameters)
118
119  def IsApplicationRunning(self, application):
120    """Returns whether an application is currently running."""
121    return self._platform_backend.IsApplicationLaunchning(application)
122
123  def CanLaunchApplication(self, application):
124    """Returns whether the platform can launch the given application."""
125    return self._platform_backend.CanLaunchApplication(application)
126
127  def InstallApplication(self, application):
128    """Installs the given application."""
129    return self._platform_backend.InstallApplication(application)
130
131  def CanCaptureVideo(self):
132    """Returns a bool indicating whether the platform supports video capture."""
133    return self._platform_backend.CanCaptureVideo()
134
135  def StartVideoCapture(self, min_bitrate_mbps):
136    """Starts capturing video.
137
138    Outer framing may be included (from the OS, browser window, and webcam).
139
140    Args:
141      min_bitrate_mbps: The minimum capture bitrate in MegaBits Per Second.
142          The platform is free to deliver a higher bitrate if it can do so
143          without increasing overhead.
144
145    Raises:
146      ValueError if the required |min_bitrate_mbps| can't be achieved.
147    """
148    return self._platform_backend.StartVideoCapture(min_bitrate_mbps)
149
150  def StopVideoCapture(self):
151    """Stops capturing video.
152
153    Yields:
154      (time_ms, bitmap) tuples representing each video keyframe. Only the first
155      frame in a run of sequential duplicate bitmaps is included.
156        time_ms is milliseconds relative to the first frame.
157        bitmap is a telemetry.core.Bitmap.
158    """
159    for t in self._platform_backend.StopVideoCapture():
160      yield t
161
162
163def CreatePlatformBackendForCurrentOS():
164  if sys.platform.startswith('linux'):
165    return linux_platform_backend.LinuxPlatformBackend()
166  elif sys.platform == 'darwin':
167    return mac_platform_backend.MacPlatformBackend()
168  elif sys.platform == 'win32':
169    return win_platform_backend.WinPlatformBackend()
170  else:
171    raise NotImplementedError()
172