Repository : ssh://git@open-mesh.org/doc
On branches: backup-redmine/2017-07-13,master
commit 3e3eadc3f5304f41f1445d1d76db108105d8cafd Author: Marek Lindner mareklindner@neomailbox.ch Date: Mon Jul 4 15:48:31 2011 +0000
doc: batman-adv/Uevent
3e3eadc3f5304f41f1445d1d76db108105d8cafd batman-adv/Uevent.textile | 66 ++++++++++++++++++++++++++++++----------------- 1 file changed, 42 insertions(+), 24 deletions(-)
diff --git a/batman-adv/Uevent.textile b/batman-adv/Uevent.textile index 82d1b34e..d9722ff7 100644 --- a/batman-adv/Uevent.textile +++ b/batman-adv/Uevent.textile @@ -1,38 +1,56 @@ h1. Uevent
-B.A.T.M.A.N.-Advanced can now throw uevents (asynchronous signals sent by the kernel to the userspace - CHECK). +B.A.T.M.A.N.-Advanced can throw uevents (asynchronous signals sent by the kernel to the user space) to inform the user space about certain events happening in the mesh. User space applications can listen to these messages and take action depending on the event, thus allowing a tight interaction between the kernel mesh and all sorts of applications.
-Thanks to this new feature it is possible to advertise any kind of message to the usespace. -This will probably enable several user applications to interact with B.A.T.M.A.N.-Advanced and obtain results different to achieve before.
-In the code a new function has been defined that can be used for the purpose above. +h2. How to capture uevents ?
-*Function prototype:* -<pre>int throw_uevent(struct bat_priv *bat_priv, enum uev_type type, - enum uev_action action, const char *data);</pre> +A various tools exist which allow to capture events generated by the kernel, for example udev, udev_adm or hotplug. These tools listen to all incoming uevents and often offer a scriptable interface to parse the messages. A batman-adv generated event could looks like this:
-*Arguments explained:* -* type: is the class the uevent belongs to. It is possible to specify new classes into B.A.T.M.A.N. to distinguish between not related uevents -* action: is the class related event that has to be signaled -* data: any meaningful payload that need to be sent to the userspace +<pre> +ACTION = change +DEVPATH = /devices/virtual/net/bat0 +DEVICENAME = bat0 +SUBSYSTEM = net +BATTYPE = gw +BATACTION = del +INTERFACE = bat0 +IFINDEX = 6 +SEQNUM = 613 +</pre>
-*Example:* -* type: GW -* action: ADD/CHANGE/DEL -* data: the gateway MAC address +Each event comes with an automatically created sequence number (SEQNUM). The batman-adv module always sets the ACTION parameter to "change" and the SUBSYSTEM to "net". DEVPATH, DEVICENAME, INTERFACE and IFINDEX point to the corresponding batX interface. Next to these standard uevent values which are part of every uevent message, batman-adv adds its own parameters with the prefix "BAT". Details regarding these parameters can be found below. + + +h2. Gateway uevents
-This is an example of a class of possible uevents to throw to userspace. In case of default gateway change, a uevent is triggered and sent to the userspace with all the needed data. The action field, in this case, represent the event related to the gateway (e.g. ADD: a default gateway for B.A.T.M.A.N. has been found). +When a batman-adv node is in gateway client mode (searching for gateway servers - check [[Gateways|the gateway documentation]] for thorough explanations) it will inform the user space about its gateway mode state changes: Sending an "add message" when the first gateway is chosen, a "change message" when a better gateway was found and a "delete message" when the currently selected gateway vanished and no alternative was available.
-*Userspace interaction:* +In detail: +* BATTYPE: Always set to "GW" for gateway related messages. +* BATACTION: Set to "ADD", "CHANGE" or "DEL". +* BATDATA: When BATACTION is set to ADD or CHANGE it contains the mac address of the selected gateway otherwise the parameter is not sent.
-Uevents are thown by means of the already existent mesh kobject which usually resides at the path: +A script running in user space could start a dhcp client as soon as an "add message" comes in and make the dhcp client request a new IP address when a "change message" is received to ensure it always uses the currently selected batman-adv gateway.
-<pre>/sys/class/net/${SOFT_IFACE}</pre>
-Each event will carry three variables which represents the arguments passed to the _throw_uevent()_ function in the batman-adv code. In particular the variables are: -* BATTYPE - containing the string corresponding to the value of _enum uev_type type_ -* BATACTION - containing the string corresponding to the value of _enum uev_action action_ -* BATDATA - containing the string _const char *data_ +h2. How to add my own uevents to batman-adv ?
+The code contains a function to make adding new uevents as easy as possible.
-The first two variables will contain the string defined respectively into _static char *uev_action_str[]_ and _static char *uev_type_str[]_ (decleared in bat_sysfs.h) while the last one will be directly passed as provided to the function. \ No newline at end of file +Function prototype: +<pre> +int throw_uevent(struct bat_priv *bat_priv, enum uev_type type, + enum uev_action action, const char *data); +</pre> + +Arguments explained: +* bat_priv: The pointer to the soft-interface structure holding all relevant batX information. +* type: Is the class the uevent belongs to (seen as BATTYPE in user space). +* action: Defines the event's action (seen as BATACTION in user space). +* data: Any meaningful payload that need to be sent to the userspace. + +Example: +* type: GW +* action: ADD/CHANGE/DEL +* data: the gateway MAC address