reset iface->config_state when handling it

[project/netifd.git] / DESIGN

diff --git a/DESIGN b/DESIGN
index 5fb11ea..4d58bcf 100644 (file)
--- a/DESIGN
+++ b/DESIGN
@@ -83,18 +83,58 @@ An interface always has the following state information:
 active:
   The interface can be brought up (its main device is available)
 
-up:
-  The interface has been brought up.
-
 autostart:
   If the interface switches from inactive to active, netifd will attempt
   to bring it up immediately. Manually setting an interface to up (regardless
   of whether that was successful or not) will set this flag.
 
+state:
+  IFS_SETUP:
+    The interface is currently being configured by the protocol handler
+  IFS_UP:
+    The interface is fully configured
+  IFS_TEARDOWN:
+    The interface is being deconfigured
+  IFS_DOWN:
+    The interface is down
+
 An interface references only one protocol handler state, modular protocol
 handlers such as PPP are expected to be written in a way that allows them
 to be set up as slave to another protocol handler if necessary (useful for
 PPPoE or PPTP).
 
 
-## TODO: Protocol handlers, Configuration management, ubus callbacks
+
+Protocol handlers
+-----------------
+
+A protocol handler can be attached to anything that provides a callback
+for state changes. For the simple case it is usually attached to an interface
+directly.
+
+The state of a protocol handler is tracked in a struct interface_proto_state,
+and it depends on the state of the entity that's controlling it.
+
+It responds to PROTO_CMD_SETUP and PROTO_SETUP_TEARDOWN commands, which
+should not block at any point in time. Completion is signalled back to the
+master by sending IFPEV_UP and IFPEV_DOWN events.
+
+If the setup can be done fast without blocking for a noticeable amount of
+time, the callback can do it and send back those events immediately.
+If the setup can take longer, it should use uloop to schedule its actions
+asynchronously and (if necessary) fork.
+
+The protocol handler must be able to abort a setup request that's being
+processed when it encounters a teardown command.
+
+When a PROTO_SETUP_TEARDOWN call is issued and the 'force' parameter is
+set, the protocol handler needs to clean up immediately as good as possible,
+without waiting for its pending actions to complete. If it has spawned
+any child processes, it needs to kill them and clean up their mess.
+
+Simple protocol handlers can set the PROTO_FLAG_IMMEDIATE flag if they
+can perform all required actions immediately without waiting and thus
+do not need to schedule IFPEV_UP and IFPEV_DOWN transitions. This will
+cause those events to be generated by core code instead.
+
+## TODO: Configuration management, ubus callbacks