hal/Hal.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set sw=2 ts=8 et ft=cpp : */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   5  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_Hal_h
   8 #define mozilla_Hal_h
   9
  10 #include "base/platform_thread.h"
  11 #include "nsTArray.h"
  12 #include "mozilla/hal_sandbox/PHal.h"
  13 #include "mozilla/HalScreenConfiguration.h"
  14 #include "mozilla/HalBatteryInformation.h"
  15 #include "mozilla/HalNetworkInformation.h"
  16 #include "mozilla/HalWakeLockInformation.h"
  17 #include "mozilla/HalTypes.h"
  18 #include "mozilla/MozPromise.h"
  19
  20 #include <cstdint>
  21
  22 /*
  23  * Hal.h contains the public Hal API.
  24  *
  25  * By default, this file defines its functions in the hal namespace, but if
  26  * MOZ_HAL_NAMESPACE is defined, we'll define our functions in that namespace.
  27  *
  28  * This is used by HalImpl.h and HalSandbox.h, which define copies of all the
  29  * functions here in the hal_impl and hal_sandbox namespaces.
  30  */
  31
  32 class nsPIDOMWindowInner;
  33
  34 #ifndef MOZ_HAL_NAMESPACE
  35 #  define MOZ_HAL_NAMESPACE hal
  36 #  define MOZ_DEFINED_HAL_NAMESPACE 1
  37 #endif
  38
  39 namespace mozilla {
  40
  41 namespace hal {
  42
  43 class WindowIdentifier;
  44
  45 }  // namespace hal
  46
  47 namespace MOZ_HAL_NAMESPACE {
  48
  49 /**
  50  * Initializes the HAL. This must be called before any other HAL function.
  51  */
  52 void Init();
  53
  54 /**
  55  * Shuts down the HAL. Besides freeing all the used resources this will check
  56  * that all observers have been properly deregistered and assert if not.
  57  */
  58 void Shutdown();
  59
  60 /**
  61  * Turn the default vibrator device on/off per the pattern specified
  62  * by |pattern|.  Each element in the pattern is the number of
  63  * milliseconds to turn the vibrator on or off.  The first element in
  64  * |pattern| is an "on" element, the next is "off", and so on.
  65  *
  66  * If |pattern| is empty, any in-progress vibration is canceled.
  67  *
  68  * Only an active window within an active tab may call Vibrate; calls
  69  * from inactive windows and windows on inactive tabs do nothing.
  70  *
  71  * If you're calling hal::Vibrate from the outside world, pass an
  72  * nsIDOMWindow* in place of the WindowIdentifier parameter.
  73  * The method with WindowIdentifier will be called automatically.
  74  */
  75 void Vibrate(const nsTArray<uint32_t>& pattern, nsPIDOMWindowInner* aWindow);
  76 void Vibrate(const nsTArray<uint32_t>& pattern, hal::WindowIdentifier&& id);
  77
  78 /**
  79  * Cancel a vibration started by the content window identified by
  80  * WindowIdentifier.
  81  *
  82  * If the window was the last window to start a vibration, the
  83  * cancellation request will go through even if the window is not
  84  * active.
  85  *
  86  * As with hal::Vibrate(), if you're calling hal::CancelVibrate from the outside
  87  * world, pass an nsIDOMWindow*. The method with WindowIdentifier will be called
  88  * automatically.
  89  */
  90 void CancelVibrate(nsPIDOMWindowInner* aWindow);
  91 void CancelVibrate(hal::WindowIdentifier&& id);
  92
  93 #define MOZ_DEFINE_HAL_OBSERVER(name_)                             \
  94   /**                                                              \
  95    * Inform the backend there is a new |name_| observer.           \
  96    * @param aObserver The observer that should be added.           \
  97    */                                                              \
  98   void Register##name_##Observer(hal::name_##Observer* aObserver); \
  99   /**                                                              \
 100    * Inform the backend a |name_| observer unregistered.           \
 101    * @param aObserver The observer that should be removed.         \
 102    */                                                              \
 103   void Unregister##name_##Observer(hal::name_##Observer* aObserver);
 104
 105 MOZ_DEFINE_HAL_OBSERVER(Battery);
 106
 107 /**
 108  * Returns the current battery information.
 109  */
 110 void GetCurrentBatteryInformation(hal::BatteryInformation* aBatteryInfo);
 111
 112 /**
 113  * Notify of a change in the battery state.
 114  * @param aBatteryInfo The new battery information.
 115  */
 116 void NotifyBatteryChange(const hal::BatteryInformation& aBatteryInfo);
 117
 118 /**
 119  * Register an observer for the sensor of given type.
 120  *
 121  * The observer will receive data whenever the data generated by the
 122  * sensor is avaiable.
 123  */
 124 void RegisterSensorObserver(hal::SensorType aSensor,
 125                             hal::ISensorObserver* aObserver);
 126
 127 /**
 128  * Unregister an observer for the sensor of given type.
 129  */
 130 void UnregisterSensorObserver(hal::SensorType aSensor,
 131                               hal::ISensorObserver* aObserver);
 132
 133 /**
 134  * Post a value generated by a sensor.
 135  *
 136  * This API is internal to hal; clients shouldn't call it directly.
 137  */
 138 void NotifySensorChange(const hal::SensorData& aSensorData);
 139
 140 /**
 141  * Enable sensor notifications from the backend
 142  *
 143  * This method is only visible from implementation of sensor manager.
 144  * Rest of the system should not try this.
 145  */
 146 void EnableSensorNotifications(hal::SensorType aSensor);
 147
 148 /**
 149  * Disable sensor notifications from the backend
 150  *
 151  * This method is only visible from implementation of sensor manager.
 152  * Rest of the system should not try this.
 153  */
 154 void DisableSensorNotifications(hal::SensorType aSensor);
 155
 156 MOZ_DEFINE_HAL_OBSERVER(Network);
 157
 158 /**
 159  * Returns the current network information.
 160  */
 161 void GetCurrentNetworkInformation(hal::NetworkInformation* aNetworkInfo);
 162
 163 /**
 164  * Notify of a change in the network state.
 165  * @param aNetworkInfo The new network information.
 166  */
 167 void NotifyNetworkChange(const hal::NetworkInformation& aNetworkInfo);
 168
 169 /**
 170  * Enable wake lock notifications from the backend.
 171  *
 172  * This method is only used by WakeLockObserversManager.
 173  */
 174 void EnableWakeLockNotifications();
 175
 176 /**
 177  * Disable wake lock notifications from the backend.
 178  *
 179  * This method is only used by WakeLockObserversManager.
 180  */
 181 void DisableWakeLockNotifications();
 182
 183 MOZ_DEFINE_HAL_OBSERVER(WakeLock);
 184
 185 /**
 186  * Adjust a wake lock's counts on behalf of a given process.
 187  *
 188  * In most cases, you shouldn't need to pass the aProcessID argument; the
 189  * default of CONTENT_PROCESS_ID_UNKNOWN is probably what you want.
 190  *
 191  * @param aTopic        lock topic
 192  * @param aLockAdjust   to increase or decrease active locks
 193  * @param aHiddenAdjust to increase or decrease hidden locks
 194  * @param aProcessID    indicates which process we're modifying the wake lock
 195  *                      on behalf of.  It is interpreted as
 196  *
 197  *                      CONTENT_PROCESS_ID_UNKNOWN: The current process
 198  *                      CONTENT_PROCESS_ID_MAIN: The root process
 199  *                      X: The process with ContentChild::GetID() == X
 200  */
 201 void ModifyWakeLock(const nsAString& aTopic, hal::WakeLockControl aLockAdjust,
 202                     hal::WakeLockControl aHiddenAdjust,
 203                     uint64_t aProcessID = hal::CONTENT_PROCESS_ID_UNKNOWN);
 204
 205 /**
 206  * Query the wake lock numbers of aTopic.
 207  * @param aTopic        lock topic
 208  * @param aWakeLockInfo wake lock numbers
 209  */
 210 void GetWakeLockInfo(const nsAString& aTopic,
 211                      hal::WakeLockInformation* aWakeLockInfo);
 212
 213 /**
 214  * Notify of a change in the wake lock state.
 215  * @param aWakeLockInfo The new wake lock information.
 216  */
 217 void NotifyWakeLockChange(const hal::WakeLockInformation& aWakeLockInfo);
 218
 219 /**
 220  * Lock the screen orientation to the specific orientation.
 221  * @return A promise indicating that the screen orientation has been locked.
 222  */
 223 [[nodiscard]] RefPtr<GenericNonExclusivePromise> LockScreenOrientation(
 224     const hal::ScreenOrientation& aOrientation);
 225
 226 /**
 227  * Unlock the screen orientation.
 228  */
 229 void UnlockScreenOrientation();
 230
 231 /**
 232  * Set the priority of the given process.
 233  *
 234  * Exactly what this does will vary between platforms.  On *nix we might give
 235  * background processes higher nice values.  On other platforms, we might
 236  * ignore this call entirely.
 237  */
 238 void SetProcessPriority(int aPid, hal::ProcessPriority aPriority);
 239
 240 /**
 241  * Creates a PerformanceHintSession.
 242  *
 243  * A PerformanceHintSession represents a workload shared by a group of threads
 244  * that should be completed in a target duration each cycle.
 245  *
 246  * Each cycle, the actual work duration should be reported using
 247  * PerformanceHintSession::ReportActualWorkDuration(). The system can then
 248  * adjust the scheduling accordingly in order to achieve the target.
 249  */
 250 UniquePtr<hal::PerformanceHintSession> CreatePerformanceHintSession(
 251     const nsTArray<PlatformThreadHandle>& aThreads,
 252     mozilla::TimeDuration aTargetWorkDuration);
 253
 254 /**
 255  * Returns information categorizing the CPUs on the system by performance class.
 256  *
 257  * Returns Nothing if we are unable to calculate the required information.
 258  *
 259  * See the definition of hal::HeterogeneousCpuInfo for more details.
 260  */
 261 const Maybe<hal::HeterogeneousCpuInfo>& GetHeterogeneousCpuInfo();
 262
 263 }  // namespace MOZ_HAL_NAMESPACE
 264 }  // namespace mozilla
 265
 266 #ifdef MOZ_DEFINED_HAL_NAMESPACE
 267 #  undef MOZ_DEFINED_HAL_NAMESPACE
 268 #  undef MOZ_HAL_NAMESPACE
 269 #endif
 270
 271 #endif  // mozilla_Hal_h