# SPDX-FileCopyrightText: 2020 Frank Hunleth
# SPDX-FileCopyrightText: 2022 Jon Carstens
#
# SPDX-License-Identifier: Apache-2.0
#
defmodule VintageNet.PowerManager do
  @moduledoc """
  This is a behaviour for implementing platform-specific power management.

  From VintageNet's point of view, network devices have the following
  lifecycle:

  ```
  off --->  on ---> powering-off ---> off
  ```

  Power management does not necessarily mean controlling the power. The end
  effect should be similar, since VintageNet will try to toggle the power off
  and on if the network interface doesn't seem to be working. For example,
  unloading the kernel module for the network device on "power off" and loading
  it on "power on" may have the desired effect of getting a network interface
  unstuck.

  When a device is "on", VintageNet expects to be regularly told that the
  device is working ok. Working ok is device dependent, but could be something
  like the device has transmitted and received data. If VintageNet is not told
  that the device is working for a long enough time, it will reset the device
  by powering it off and then back on again.

  VintageNet calls functions here based on how it wants to transition a device.
  VintageNet maintains the device's power status internally, so implementations
  can blindly do what VintageNet tells them too in most cases. Powering on and
  off can be asynchronous to these function calls. VintageNet uses the presence
  of the networking interface (like "wlan0") to determine when the device is
  really available for networking.

  The following timeouts are important to consider (in milliseconds):

  1. `time_to_power_off`
  2. `power_on_hold_time`
  3. `min_power_off_time`
  4. `watchdog_timeout`

  The `time_to_power_off` specifies the time in the `powering-off` state. This
  is the maximum time to allow for a graceful shutdown. VintageNet won't bother
  the device until that time has expired. That means that if there's a request
  to use the device, it will wait the `powering-off` time before calling
  `finish_power_off` and then it will power the device back on. Device app
  notes may have recommendations for this time.

  The `power_on_hold_time` specifies how much time a device should be in the
  `powered-on` state before it is ok to power off again. This allows devices
  some time to initialize and recover on their own.

  The `min_power_off_time` specifies how long the device should remain powered
  off before it is powered back on.

  Finally, `watchdog_timeout` specifies how long to wait between notifications
  that the device is ok. Code reports that a device is ok by calling
  `VintageNet.PowerManager.PMControl.pet_watchdog/1`.

  While normal Erlang supervision expects that it can restart processes
  immediately and without regard to how long they have been running, bad things
  can happen to hardware if too aggressively restarted. Devices also initialize
  asynchronously so it's hard to know when they're fully available and some
  flakiness may be naturally due to VintageNet not knowing how to wait for a
  component to finish initialization. Please review your network device's power
  management guidelines before too aggressively reducing hold times. Cellular
  devices, in particular, want to signal their disconnection from the network
  to the tower and flush any unsaved configuration changes to Flash before
  power removal.

  Here's an example for a cellular device with a reset line connected to it:

  * `power_on` - De-assert the reset line. Return a `power_on_hold_time` of 10
    minutes
  * `start_powering_off` - Open the UART and send the power down command to the
    modem. Return a `time_to_power_off` of 1 minute.
  * `power_off` - Assert the reset line and return that power shouldn't be turned
    back on for another 10 seconds.

  PowerManager implementation lifetimes are the same as VintageNet's. In other
  words, they start and end with VintageNet. This is unlike a network interface
  which runs only as its existence and configuration allow. As such, VintageNet
  needs to know about all PowerManager implementations in its application
  environment.  For example, add something like this to your `config.exs`:

  ```elixir
  config :vintage_net,
    power_managers: [{MyCellularPM, [ifname: "ppp0", watchdog_timeout: 60_000, reset_gpio: 123]}]
  ```

  Each tuple is the implementation's module name and init arguments. VintageNet
  requires `:ifname` to be set. If you're managing the power for an interface
  with a dynamic name, enable predictable interface naming with `VintageNet`
  and use that name. The `watchdog_timeout` parameter is optional and defaults
  to one minute.
  """

  @doc """
  Initialize state for managing the power to the specified interface

  This is called on start and if the power management GenServer restarts. It
  should not assume that hardware is powered down.

  IMPORTANT: VintageNet assumes that `init/1` runs quickly and succeeds. Errors
  and exceptions from calling `init/1` are handled by disabling the PowerManager.
  The reason is that VintageNet has no knowledge on how to recover and disabling
  a power manager was deemed less bad that having supervision tree failures
  propagate upwards to terminate VintageNet. Messages are logged if this does
  happen.
  """
  @callback init(args :: keyword()) :: {:ok, state :: any()}

  @doc """
  Power on the hardware for a network interface

  The function should turn on power rails, deassert reset lines, load kernel
  modules or do whatever else is necessary to make the interface show up in
  Linux.

  Failure handling is not supported by VintageNet yet, so if power up can fail
  and the right handling for that is to try again later, then this function
  should do that.

  It is ok for this function to return immediately. When the network interface
  appears, VintageNet will start trying to use it.

  The return tuple should include the number of milliseconds VintageNet should
  wait before trying to power down the module again. This value should be
  sufficiently large to avoid getting into loops where VintageNet gives up on a
  network interface before it has initialized. 10 minutes (600,000 milliseconds),
  for example, is a reasonable setting.
  """
  @callback power_on(state :: any()) ::
              {:ok, next_state :: any(), hold_time :: non_neg_integer()}

  @doc """
  Start powering off the hardware for a network interface

  This function should start a graceful shutdown of the network interface
  hardware.  It may return immediately. The return value specifies how long in
  milliseconds VintageNet should wait before calling `power_off/2`. The idea is
  that a graceful power off should be allowed some time to complete, but not
  forever.
  """
  @callback start_powering_off(state :: any()) ::
              {:ok, next_state :: any(), time_to_power_off :: non_neg_integer()}

  @doc """
  Power off the hardware

  This function should finish powering off the network interface hardware. Since
  this is called after the graceful power down should have completed, it should
  forcefully turn off the power to the hardware.

  The implementation also returns a time that power must remain off, in milliseconds.
  `power_on/1` won't be called until that time expires.
  """
  @callback power_off(state :: any()) ::
              {:ok, next_state :: any(), min_off_time :: non_neg_integer()}

  @doc """
  Handle other messages

  All unknown messages sent to the power management `GenServer` come here. This
  callback is similar to `c:GenServer.handle_info/2`.

  To receive your own messages here, send them to `self()` in code run in any
  of the other callbacks. Another option is to call
  `VintageNet.PowerManager.PMControl.send_message/2`
  """
  @callback handle_info(msg :: any(), state :: any()) :: {:noreply, new_state :: any()}
end
