DESIGN

   1 Design of the the network interface daemon (netifd)
   2 ----------------------------------------------------
   3
   4 The primary elements of netifd's state are devices and interfaces.
   5
   6 Devices
   7 -------
   8
   9 A device represents either a physical Linux interface (e.g. eth0), or a
  10 virtual link, bound to a static route, a socket or some other external trigger
  11 (e.g. for VPN links or tunnels).
  12
  13 Anything that needs to be aware of device state registers a device_user, which
  14 is bound to the device and contains a callback for receiving events on device
  15 changes. As soon as the last device_user is removed, the device itself is freed
  16 immediately.
  17
  18 Devices can also internally reference other devices, this is used to manage
  19 specific kinds of devices, such as bridges or vlans, which do not require
  20 special treatment from interfaces or other high level data structures, with
  21 the exception of adding more member interfaces via hotplug, which is useful
  22 for bridges or bonding interfaces.
  23
  24 The device up/down state is managed through refcounting. A device can be
  25 brought up using claim_device(), and its reference released again with
  26 release_device(). As soon as the refcount goes to zero, the device is
  27 immediately brought down.
  28 If the device cannot be brought up, claim_device() will return a non-zero
  29 status and the caller will not have increased the refcount.
  30
  31 A registered device may not be available immediately, an interface or another
  32 device could also be attached to it, waiting for it to appear in the system,
  33 to support triggering interfaces via hotplug.
  34
  35 All device state transitions are announced via events to all the device_user
  36 callbacks. The following event types are supported:
  37
  38 DEV_EVENT_ADD:
  39   The device is now present in the system. When a device_user is being added
  40   to a device and the device was already present, this event is generated
  41   immediately.
  42
  43 DEV_EVENT_REMOVE:
  44   The device is no longer available. Either it is currently being removed,
  45   or it has already disappeared. All users should drop their references
  46   immediately and clean up their state for this device.
  47
  48 DEV_EVENT_SETUP:
  49   The device is about to be brought up. This allows device users to apply
  50   some low level configuration parameters if necessary, however this event
  51   may not be emitted in all cases. Externally managed devices added via
  52   hotplug may be already up, and in that case this notification is skipped.
  53
  54 DEV_EVENT_UP:
  55   The device has been successfully brought up.
  56
  57 DEV_EVENT_TEARDOWN:
  58   The device is about to be brought down
  59
  60 DEV_EVENT_DOWN:
  61   The device has been brought down
  62
  63 The following optional events are supported on some devices:
  64
  65 DEV_EVENT_LINK_UP: a link has been established on this device
  66 DEV_EVENT_LINK_DOWN: the link has been lost
  67
  68
  69
  70 Interfaces
  71 ----------
  72
  73 An interface represents a high level configuration applied to one or more
  74 devices. An active interface must always be bound to one main device and
  75 to a layer 3 device. By default, the layer 3 device points at the reference
  76 to the main device, based on how simple protocols like static, dhcp, etc.
  77 are set up. More complex protcol handlers such as ppp/pptp or VPN software
  78 can remap the layer 3 interface to something else, and external modules
  79 such as the firewall can take care of both interfaces if necessary.
  80
  81 An interface always has the following state information:
  82
  83 active:
  84   The interface can be brought up (its main device is available)
  85
  86 up:
  87   The interface has been brought up.
  88
  89 autostart:
  90   If the interface switches from inactive to active, netifd will attempt
  91   to bring it up immediately. Manually setting an interface to up (regardless
  92   of whether that was successful or not) will set this flag.
  93
  94 An interface references only one protocol handler state, modular protocol
  95 handlers such as PPP are expected to be written in a way that allows them
  96 to be set up as slave to another protocol handler if necessary (useful for
  97 PPPoE or PPTP).
  98
  99
 100 ## TODO: Protocol handlers, Configuration management, ubus callbacks