Commit f5c39ef3 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by David S. Miller
Browse files

docs: networking: convert operstates.txt to ReST 



- add SPDX header;
- add a document title;
- adjust chapters, adding proper markups;
- mark lists as such;
- adjust identation, whitespaces and blank lines where needed;
- add to networking/index.rst.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent 63893472

Documentation/networking/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -88,6 +88,7 @@ Contents: 
   nf_conntrack-sysctl

   nf_flowtable

   openvswitch

   operstates



.. only::  subproject and html

Documentation/networking/operstates.txt→Documentation/networking/operstates.rst

+33 −12
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



==================

Operational States

==================





1. Introduction

===============



Linux distinguishes between administrative and operational state of an

interface. Administrative state is the result of "ip link set dev
@@ -20,6 +27,7 @@ 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 RTNLGRP_LINK
@@ -30,16 +38,20 @@ 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()



TLV IFLA_OPERSTATE

------------------



contains RFC2863 state of the interface in numeric representation:
@@ -47,26 +59,33 @@ 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.
@@ -75,6 +94,7 @@ 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
@@ -126,6 +146,7 @@ netif_carrier_ok() && !netif_dormant(): 




4. Setting from userspace

=========================



Applications have to use the netlink interface to influence the

RFC2863 operational state of an interface. Setting IFLA_LINKMODE to 1

CRA Git | Maintained and supported by SUSTech CRA and CCSE