RFC - document network device carrier management

Since carrier handling is often done incorrectly by new device drivers
be explicit about carrier handling API.

Signed-off-by: Stephen Hemminger <shemminger@vyatta.com>

---
This is a meant as starting point for discussion, it's probably wrong as is.
Since this isn't code, it could be applied for 3.6 and doesn't need for net-next.


--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

On Wed, 2012-08-15 at 08:58 -0700, Stephen Hemminger wrote:
> Since carrier handling is often done incorrectly by new device drivers
> be explicit about carrier handling API.
> 
> Signed-off-by: Stephen Hemminger <shemminger@vyatta.com>
> 
> ---
> This is a meant as starting point for discussion, it's probably wrong as is.
> Since this isn't code, it could be applied for 3.6 and doesn't need for net-next.
> 
> 
> --- a/Documentation/networking/netdevices.txt	2012-06-22 08:27:46.729168196 -0700
> +++ b/Documentation/networking/netdevices.txt	2012-08-15 08:56:31.120429994 -0700
> @@ -45,6 +45,36 @@ drop, truncate, or pass up oversize pack
>  packets is preferred.
>  
> 
> +CARRIER
> +=======
> +Most network devices have an operational state that the device
> +monitors. The Linux kernel uses the name "carrier" for this flag which
> +is a historical reference to old modems. Carrier is reported to
> +userspace via the IFF_RUNNING flag from SIOCGIFFLAGS ioctl.
> +Carrier is controlled in the device driver
> +by the functions netif_carrier_on and netif_carrier_off. These
> +functions trigger the necessary netlink and userspace API changes;
> +device drivers must not change netdevice->flags directly.
> +
> +The carrier defaults to ON when the device is created and registered.
> +Simple devices (such as dummy) do not need to do anything.
> +Ethernet style devices should:
> +   * alloc_etherdev in probe routine
> +   * call netif_carrier_off
> +   * register network device
> +   * start auto negotiation with phy in open routine

Auto-negotiation is only one of several stages of link setup, and of
course is not used in all Ethernet physical layers.  I think the
important point is that once the ndo_open method returns the hardware
and driver should be ready to set up the link and report this state
whenever a suitable partner is physically connected.

> +   * call netif_carrier_on when link is up
> +
> +More complex RFC2863 style operational state is also possible
> +but not required (see operstates.txt).

Drivers are not allowed to set operstate directly.

> +The monitoring of link state is the responsibility of the network
> +device driver. It can be done by polling, interrupt, or any other
> +mechanism. netif_carrier_on/netif_carrier_off are atomic and can
> +safely be called by an interrupt routine. Carrier events are
> +managed by the linkwatch work queue and limited to one per second
> +to avoid overwhelming management applications.
> +
>  struct net_device synchronization rules
>  =======================================
>  ndo_open:

On Wednesday 2012-08-15 17:58, Stephen Hemminger wrote:
>--- a/Documentation/networking/netdevices.txt	2012-06-22 08:27:46.729168196 -0700
>+++ b/Documentation/networking/netdevices.txt	2012-08-15 08:56:31.120429994 -0700
>@@ -45,6 +45,36 @@ drop, truncate, or pass up oversize pack
> packets is preferred.
> 
> 
>+CARRIER
>+=======
>+Most network devices have an operational state that the device
>+monitors. The Linux kernel uses the name "carrier" for this flag which
>+is a historical reference to old modems. Carrier is reported to
>+userspace via the IFF_RUNNING flag from SIOCGIFFLAGS ioctl.

I think Netlink should be mentioned instead:

Carrier is reported to userspace via the IFF_RUNNING flag in
struct ifinfomsg.ifi_flags returned by RTM_GETLINK (see rtnetlink(7)).

--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html