Re: [PATCH] Documentation: add missing operstates.txt
On Sun, 7 May 2006 12:18:59 +0200 Stefan Rompf wrote: > Hi, > > seems documentation got lost when the RFC2863-patch was applied. Having > documentation is good, so I resend it ;-) I have a few comments/questions about this. > --- /dev/null 2005-03-19 20:36:14.0 +0100 > +++ linux-2.6.17-rc3/Documentation/networking/operstates.txt 2006-04-27 > 22:15:23.0 +0200 > @@ -0,0 +1,161 @@ > + > +1. Introduction > + > +Linux distinguishes between administrative and operational state of an > +interface. Admininstrative state is the result of "ip link set dev > + up or down" and reflects whether the administrator wants to use > +the device for traffic. > + > +However, an interface is not usable just because the admin enabled it Put hyphen/dash at end of previous line, not on next line. > +- ethernet requires to be plugged into the switch and, depending on 2 small items here, one grammar and the other is that 'switch' isn't always the link partner device. so maybe: ethernet requires a physical link partner and, depending on > +a site's networking policy and configuration, an 802.1X authentication > +to be performed before user data can be transferred. Operational state > +shows the ability of an interface to transmit this user data. > + > +Thanks to 802.1X, userspace must be granted the possibility to > +influence operational state. To accommodate this, operational state is > +split into two parts: Two flags that can be set by the driver only, and > +a RFC2863 compatible state that is derived from these flags, a policy, > +and changeable from userspace under certain rules. > + > + > +2. Querying from userspace > + > +Both admin and operational state can be queried via the netlink > +operation RTM_GETLINK. It is also possible to subscribe to RTMGRP_LINK > +to be notified of updates. This is important for setting from userspace. > + > +These values contain interface state: > + > +ifinfomsg::if_flags & IFF_UP: > + Interface is admin up > +ifinfomsg::if_flags & IFF_RUNNING: > + Interface is in RFC2863 operational state UP or UNKNOWN. This is for > + backward compatibility, routing daemons, dhcp clients can use this > + flag to determine whether they should use the interface. > +ifinfomsg::if_flags & IFF_LOWER_UP: > + Driver has signaled netif_carrier_on() > +ifinfomsg::if_flags & IFF_DORMANT: > + Driver has signaled netif_dormant_on() Could above list have more spacing added for readability? > +These interface flags can also be queried without netlink using the > +SIOCGIFFLAGS ioctl. > + > +TLV IFLA_OPERSTATE > + > +contains RFC2863 state of the interface in numeric representation: > + > +IF_OPER_UNKNOWN (0): > + Interface is in unknown state, neither driver nor userspace has set > + operational state. Interface must be considered for user data as > + setting operational state has not been implemented in every driver. > +IF_OPER_NOTPRESENT (1): > + Unused in current kernel (notpresent interfaces normally disappear), > + just a numerical placeholder. > +IF_OPER_DOWN (2): > + Interface is unable to transfer data on L1, f.e. ethernet is not > + plugged or interface is ADMIN down. maybe: ethernet is not plugged in or ethernet is not connected or ethernet is not physically connected Also, is "f.e." well known to mean "for example"? I think that I see "e.g." more often than "f.e." and I prefer "e.g.". > +IF_OPER_LOWERLAYERDOWN (3): > + Interfaces stacked on an interface that is IF_OPER_DOWN show this > + state (f.e. VLAN). > +IF_OPER_TESTING (4): > + Unused in current kernel. > +IF_OPER_DORMANT (5): > + Interface is L1 up, but waiting for an external event, f.e. for a > + protocol to establish. (802.1X) > +IF_OPER_UP (6): > + Interface is operational up and can be used. > + > +This TLV can also be queried via sysfs. What is "TLV"? > +TLV IFLA_LINKMODE > + > +contains link policy. This is needed for userspace interaction > +described below. > + > +This TLV can also be queried via sysfs. > + > + > +3. Kernel driver API > + > +Kernel drivers have access to two flags that map to IFF_LOWER_UP and > +IFF_DORMANT. These flags can be set from everywhere, even from > +interrupts. It is guaranteed that only the driver has write access, > +however, if different layers of the driver manipulate the same flag, > +the driver has to provide the synchronisation needed. > + > +__LINK_STATE_NOCARRIER, maps to !IFF_LOWER_UP: > + > +The driver uses netif_carrier_on() to clear and netif_carrier_off() to > +set this flag. On netif_carrier_off(), the scheduler stops sending > +packets. The name 'carrier' and the inversion are historical, think of > +it as lower layer. > + > +netif_carrier_ok() can be used to query that bit. > + > +__LINK_STATE_DORMANT, maps to IFF_DORMANT: > + > +Set by the driver to express that the device cannot yet be used > +because some driver controlled protocol establishment has to > +complete. Corresponding functions are netif_dormant_on() to set the > +flag, netif_dormant_off() to clear it and
Re: [PATCH] Documentation: add missing operstates.txt
From: Stefan Rompf <[EMAIL PROTECTED]> Date: Sun, 7 May 2006 12:18:59 +0200 > seems documentation got lost when the RFC2863-patch was applied. Having > documentation is good, so I resend it ;-) > > Signed-off-by: Stefan Rompf <[EMAIL PROTECTED]> Applied, thanks Stefan. - To unsubscribe from this list: send the line "unsubscribe netdev" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] Documentation: add missing operstates.txt
Hi, seems documentation got lost when the RFC2863-patch was applied. Having documentation is good, so I resend it ;-) Signed-off-by: Stefan Rompf <[EMAIL PROTECTED]> --- /dev/null 2005-03-19 20:36:14.0 +0100 +++ linux-2.6.17-rc3/Documentation/networking/operstates.txt2006-04-27 22:15:23.0 +0200 @@ -0,0 +1,161 @@ + +1. Introduction + +Linux distinguishes between administrative and operational state of an +interface. Admininstrative state is the result of "ip link set dev + up or down" and reflects whether the administrator wants to use +the device for traffic. + +However, an interface is not usable just because the admin enabled it +- ethernet requires to be plugged into the switch and, depending on +a site's networking policy and configuration, an 802.1X authentication +to be performed before user data can be transferred. Operational state +shows the ability of an interface to transmit this user data. + +Thanks to 802.1X, userspace must be granted the possibility to +influence operational state. To accommodate this, operational state is +split into two parts: Two flags that can be set by the driver only, and +a RFC2863 compatible state that is derived from these flags, a policy, +and changeable from userspace under certain rules. + + +2. Querying from userspace + +Both admin and operational state can be queried via the netlink +operation RTM_GETLINK. It is also possible to subscribe to RTMGRP_LINK +to be notified of updates. This is important for setting from userspace. + +These values contain interface state: + +ifinfomsg::if_flags & IFF_UP: + Interface is admin up +ifinfomsg::if_flags & IFF_RUNNING: + Interface is in RFC2863 operational state UP or UNKNOWN. This is for + backward compatibility, routing daemons, dhcp clients can use this + flag to determine whether they should use the interface. +ifinfomsg::if_flags & IFF_LOWER_UP: + Driver has signaled netif_carrier_on() +ifinfomsg::if_flags & IFF_DORMANT: + Driver has signaled netif_dormant_on() + +These interface flags can also be queried without netlink using the +SIOCGIFFLAGS ioctl. + +TLV IFLA_OPERSTATE + +contains RFC2863 state of the interface in numeric representation: + +IF_OPER_UNKNOWN (0): + Interface is in unknown state, neither driver nor userspace has set + operational state. Interface must be considered for user data as + setting operational state has not been implemented in every driver. +IF_OPER_NOTPRESENT (1): + Unused in current kernel (notpresent interfaces normally disappear), + just a numerical placeholder. +IF_OPER_DOWN (2): + Interface is unable to transfer data on L1, f.e. ethernet is not + plugged or interface is ADMIN down. +IF_OPER_LOWERLAYERDOWN (3): + Interfaces stacked on an interface that is IF_OPER_DOWN show this + state (f.e. VLAN). +IF_OPER_TESTING (4): + Unused in current kernel. +IF_OPER_DORMANT (5): + Interface is L1 up, but waiting for an external event, f.e. for a + protocol to establish. (802.1X) +IF_OPER_UP (6): + Interface is operational up and can be used. + +This TLV can also be queried via sysfs. + +TLV IFLA_LINKMODE + +contains link policy. This is needed for userspace interaction +described below. + +This TLV can also be queried via sysfs. + + +3. Kernel driver API + +Kernel drivers have access to two flags that map to IFF_LOWER_UP and +IFF_DORMANT. These flags can be set from everywhere, even from +interrupts. It is guaranteed that only the driver has write access, +however, if different layers of the driver manipulate the same flag, +the driver has to provide the synchronisation needed. + +__LINK_STATE_NOCARRIER, maps to !IFF_LOWER_UP: + +The driver uses netif_carrier_on() to clear and netif_carrier_off() to +set this flag. On netif_carrier_off(), the scheduler stops sending +packets. The name 'carrier' and the inversion are historical, think of +it as lower layer. + +netif_carrier_ok() can be used to query that bit. + +__LINK_STATE_DORMANT, maps to IFF_DORMANT: + +Set by the driver to express that the device cannot yet be used +because some driver controlled protocol establishment has to +complete. Corresponding functions are netif_dormant_on() to set the +flag, netif_dormant_off() to clear it and netif_dormant() to query. + +On device allocation, networking core sets the flags equivalent to +netif_carrier_ok() and !netif_dormant(). + + +Whenever the driver CHANGES one of these flags, a workqueue event is +scheduled to translate the flag combination to IFLA_OPERSTATE as +follows: + +!netif_carrier_ok(): + IF_OPER_LOWERLAYERDOWN if the interface is stacked, IF_OPER_DOWN + otherwise. Kernel can recognise stacked interfaces because their + ifindex != iflink. + +netif_carrier_ok() && netif_dormant(): + IF_OPER_DORMANT + +netif_carrier_ok() && !netif_dormant(): + IF_OPER_UP if userspace interaction is disabled. Otherwise + IF_OPER_DORMANT with the possibility for userspace to initiate the + IF_OPER_UP transition afterwards. + + +4. Setting from userspace + +Applications have to use t
