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 for the current process.
 187  *
 188  * @param aTopic        lock topic
 189  * @param aLockAdjust   to increase or decrease active locks
 190  * @param aHiddenAdjust to increase or decrease hidden locks
 191  */
 192 void ModifyWakeLock(const nsAString& aTopic, hal::WakeLockControl aLockAdjust,
 193                     hal::WakeLockControl aHiddenAdjust);
 194
 195 /**
 196  * Query the wake lock numbers of aTopic.
 197  * @param aTopic        lock topic
 198  * @param aWakeLockInfo wake lock numbers
 199  */
 200 void GetWakeLockInfo(const nsAString& aTopic,
 201                      hal::WakeLockInformation* aWakeLockInfo);
 202
 203 /**
 204  * Notify of a change in the wake lock state.
 205  * @param aWakeLockInfo The new wake lock information.
 206  */
 207 void NotifyWakeLockChange(const hal::WakeLockInformation& aWakeLockInfo);
 208
 209 /**
 210  * Lock the screen orientation to the specific orientation.
 211  * @return A promise indicating that the screen orientation has been locked.
 212  */
 213 [[nodiscard]] RefPtr<GenericNonExclusivePromise> LockScreenOrientation(
 214     const hal::ScreenOrientation& aOrientation);
 215
 216 /**
 217  * Unlock the screen orientation.
 218  */
 219 void UnlockScreenOrientation();
 220
 221 /**
 222  * Set the priority of the given process.
 223  *
 224  * Exactly what this does will vary between platforms.  On *nix we might give
 225  * background processes higher nice values.  On other platforms, we might
 226  * ignore this call entirely.
 227  */
 228 void SetProcessPriority(int aPid, hal::ProcessPriority aPriority);
 229
 230 /**
 231  * Creates a PerformanceHintSession.
 232  *
 233  * A PerformanceHintSession represents a workload shared by a group of threads
 234  * that should be completed in a target duration each cycle.
 235  *
 236  * Each cycle, the actual work duration should be reported using
 237  * PerformanceHintSession::ReportActualWorkDuration(). The system can then
 238  * adjust the scheduling accordingly in order to achieve the target.
 239  */
 240 UniquePtr<hal::PerformanceHintSession> CreatePerformanceHintSession(
 241     const nsTArray<PlatformThreadHandle>& aThreads,
 242     mozilla::TimeDuration aTargetWorkDuration);
 243
 244 /**
 245  * Returns information categorizing the CPUs on the system by performance class.
 246  *
 247  * Returns Nothing if we are unable to calculate the required information.
 248  *
 249  * See the definition of hal::HeterogeneousCpuInfo for more details.
 250  */
 251 const Maybe<hal::HeterogeneousCpuInfo>& GetHeterogeneousCpuInfo();
 252
 253 }  // namespace MOZ_HAL_NAMESPACE
 254 }  // namespace mozilla
 255
 256 #ifdef MOZ_DEFINED_HAL_NAMESPACE
 257 #  undef MOZ_DEFINED_HAL_NAMESPACE
 258 #  undef MOZ_HAL_NAMESPACE
 259 #endif
 260
 261 #endif  // mozilla_Hal_h