docs: networking: convert lapb-module.txt to ReST
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Thu, 30 Apr 2020 16:03:57 +0000 (18:03 +0200)
committerDavid S. Miller <davem@davemloft.net>
Thu, 30 Apr 2020 19:56:35 +0000 (12:56 -0700)
- add SPDX header;
- adjust title markup;
- mark code blocks and literals as such;
- mark tables as such;
- adjust identation, whitespaces and blank lines;
- add to networking/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
Documentation/networking/index.rst
Documentation/networking/lapb-module.rst [new file with mode: 0644]
Documentation/networking/lapb-module.txt [deleted file]
MAINTAINERS
net/lapb/Kconfig

index 0c5d7a037983b517ac234ed5c59df8db4605af79..acd2567cf0d48ef69351d73849cf232805d5497c 100644 (file)
@@ -75,6 +75,7 @@ Contents:
    ipvs-sysctl
    kcm
    l2tp
+   lapb-module
 
 .. only::  subproject and html
 
diff --git a/Documentation/networking/lapb-module.rst b/Documentation/networking/lapb-module.rst
new file mode 100644 (file)
index 0000000..ff586bc
--- /dev/null
@@ -0,0 +1,305 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================
+The Linux LAPB Module Interface
+===============================
+
+Version 1.3
+
+Jonathan Naylor 29.12.96
+
+Changed (Henner Eisen, 2000-10-29): int return value for data_indication()
+
+The LAPB module will be a separately compiled module for use by any parts of
+the Linux operating system that require a LAPB service. This document
+defines the interfaces to, and the services provided by this module. The
+term module in this context does not imply that the LAPB module is a
+separately loadable module, although it may be. The term module is used in
+its more standard meaning.
+
+The interface to the LAPB module consists of functions to the module,
+callbacks from the module to indicate important state changes, and
+structures for getting and setting information about the module.
+
+Structures
+----------
+
+Probably the most important structure is the skbuff structure for holding
+received and transmitted data, however it is beyond the scope of this
+document.
+
+The two LAPB specific structures are the LAPB initialisation structure and
+the LAPB parameter structure. These will be defined in a standard header
+file, <linux/lapb.h>. The header file <net/lapb.h> is internal to the LAPB
+module and is not for use.
+
+LAPB Initialisation Structure
+-----------------------------
+
+This structure is used only once, in the call to lapb_register (see below).
+It contains information about the device driver that requires the services
+of the LAPB module::
+
+       struct lapb_register_struct {
+               void (*connect_confirmation)(int token, int reason);
+               void (*connect_indication)(int token, int reason);
+               void (*disconnect_confirmation)(int token, int reason);
+               void (*disconnect_indication)(int token, int reason);
+               int  (*data_indication)(int token, struct sk_buff *skb);
+               void (*data_transmit)(int token, struct sk_buff *skb);
+       };
+
+Each member of this structure corresponds to a function in the device driver
+that is called when a particular event in the LAPB module occurs. These will
+be described in detail below. If a callback is not required (!!) then a NULL
+may be substituted.
+
+
+LAPB Parameter Structure
+------------------------
+
+This structure is used with the lapb_getparms and lapb_setparms functions
+(see below). They are used to allow the device driver to get and set the
+operational parameters of the LAPB implementation for a given connection::
+
+       struct lapb_parms_struct {
+               unsigned int t1;
+               unsigned int t1timer;
+               unsigned int t2;
+               unsigned int t2timer;
+               unsigned int n2;
+               unsigned int n2count;
+               unsigned int window;
+               unsigned int state;
+               unsigned int mode;
+       };
+
+T1 and T2 are protocol timing parameters and are given in units of 100ms. N2
+is the maximum number of tries on the link before it is declared a failure.
+The window size is the maximum number of outstanding data packets allowed to
+be unacknowledged by the remote end, the value of the window is between 1
+and 7 for a standard LAPB link, and between 1 and 127 for an extended LAPB
+link.
+
+The mode variable is a bit field used for setting (at present) three values.
+The bit fields have the following meanings:
+
+======  =================================================
+Bit    Meaning
+======  =================================================
+0      LAPB operation (0=LAPB_STANDARD 1=LAPB_EXTENDED).
+1      [SM]LP operation (0=LAPB_SLP 1=LAPB=MLP).
+2      DTE/DCE operation (0=LAPB_DTE 1=LAPB_DCE)
+3-31   Reserved, must be 0.
+======  =================================================
+
+Extended LAPB operation indicates the use of extended sequence numbers and
+consequently larger window sizes, the default is standard LAPB operation.
+MLP operation is the same as SLP operation except that the addresses used by
+LAPB are different to indicate the mode of operation, the default is Single
+Link Procedure. The difference between DCE and DTE operation is (i) the
+addresses used for commands and responses, and (ii) when the DCE is not
+connected, it sends DM without polls set, every T1. The upper case constant
+names will be defined in the public LAPB header file.
+
+
+Functions
+---------
+
+The LAPB module provides a number of function entry points.
+
+::
+
+    int lapb_register(void *token, struct lapb_register_struct);
+
+This must be called before the LAPB module may be used. If the call is
+successful then LAPB_OK is returned. The token must be a unique identifier
+generated by the device driver to allow for the unique identification of the
+instance of the LAPB link. It is returned by the LAPB module in all of the
+callbacks, and is used by the device driver in all calls to the LAPB module.
+For multiple LAPB links in a single device driver, multiple calls to
+lapb_register must be made. The format of the lapb_register_struct is given
+above. The return values are:
+
+=============          =============================
+LAPB_OK                        LAPB registered successfully.
+LAPB_BADTOKEN          Token is already registered.
+LAPB_NOMEM             Out of memory
+=============          =============================
+
+::
+
+    int lapb_unregister(void *token);
+
+This releases all the resources associated with a LAPB link. Any current
+LAPB link will be abandoned without further messages being passed. After
+this call, the value of token is no longer valid for any calls to the LAPB
+function. The valid return values are:
+
+=============          ===============================
+LAPB_OK                        LAPB unregistered successfully.
+LAPB_BADTOKEN          Invalid/unknown LAPB token.
+=============          ===============================
+
+::
+
+    int lapb_getparms(void *token, struct lapb_parms_struct *parms);
+
+This allows the device driver to get the values of the current LAPB
+variables, the lapb_parms_struct is described above. The valid return values
+are:
+
+=============          =============================
+LAPB_OK                        LAPB getparms was successful.
+LAPB_BADTOKEN          Invalid/unknown LAPB token.
+=============          =============================
+
+::
+
+    int lapb_setparms(void *token, struct lapb_parms_struct *parms);
+
+This allows the device driver to set the values of the current LAPB
+variables, the lapb_parms_struct is described above. The values of t1timer,
+t2timer and n2count are ignored, likewise changing the mode bits when
+connected will be ignored. An error implies that none of the values have
+been changed. The valid return values are:
+
+=============          =================================================
+LAPB_OK                        LAPB getparms was successful.
+LAPB_BADTOKEN          Invalid/unknown LAPB token.
+LAPB_INVALUE           One of the values was out of its allowable range.
+=============          =================================================
+
+::
+
+    int lapb_connect_request(void *token);
+
+Initiate a connect using the current parameter settings. The valid return
+values are:
+
+==============         =================================
+LAPB_OK                        LAPB is starting to connect.
+LAPB_BADTOKEN          Invalid/unknown LAPB token.
+LAPB_CONNECTED         LAPB module is already connected.
+==============         =================================
+
+::
+
+    int lapb_disconnect_request(void *token);
+
+Initiate a disconnect. The valid return values are:
+
+=================      ===============================
+LAPB_OK                        LAPB is starting to disconnect.
+LAPB_BADTOKEN          Invalid/unknown LAPB token.
+LAPB_NOTCONNECTED      LAPB module is not connected.
+=================      ===============================
+
+::
+
+    int lapb_data_request(void *token, struct sk_buff *skb);
+
+Queue data with the LAPB module for transmitting over the link. If the call
+is successful then the skbuff is owned by the LAPB module and may not be
+used by the device driver again. The valid return values are:
+
+=================      =============================
+LAPB_OK                        LAPB has accepted the data.
+LAPB_BADTOKEN          Invalid/unknown LAPB token.
+LAPB_NOTCONNECTED      LAPB module is not connected.
+=================      =============================
+
+::
+
+    int lapb_data_received(void *token, struct sk_buff *skb);
+
+Queue data with the LAPB module which has been received from the device. It
+is expected that the data passed to the LAPB module has skb->data pointing
+to the beginning of the LAPB data. If the call is successful then the skbuff
+is owned by the LAPB module and may not be used by the device driver again.
+The valid return values are:
+
+=============          ===========================
+LAPB_OK                        LAPB has accepted the data.
+LAPB_BADTOKEN          Invalid/unknown LAPB token.
+=============          ===========================
+
+Callbacks
+---------
+
+These callbacks are functions provided by the device driver for the LAPB
+module to call when an event occurs. They are registered with the LAPB
+module with lapb_register (see above) in the structure lapb_register_struct
+(see above).
+
+::
+
+    void (*connect_confirmation)(void *token, int reason);
+
+This is called by the LAPB module when a connection is established after
+being requested by a call to lapb_connect_request (see above). The reason is
+always LAPB_OK.
+
+::
+
+    void (*connect_indication)(void *token, int reason);
+
+This is called by the LAPB module when the link is established by the remote
+system. The value of reason is always LAPB_OK.
+
+::
+
+    void (*disconnect_confirmation)(void *token, int reason);
+
+This is called by the LAPB module when an event occurs after the device
+driver has called lapb_disconnect_request (see above). The reason indicates
+what has happened. In all cases the LAPB link can be regarded as being
+terminated. The values for reason are:
+
+=================      ====================================================
+LAPB_OK                        The LAPB link was terminated normally.
+LAPB_NOTCONNECTED      The remote system was not connected.
+LAPB_TIMEDOUT          No response was received in N2 tries from the remote
+                       system.
+=================      ====================================================
+
+::
+
+    void (*disconnect_indication)(void *token, int reason);
+
+This is called by the LAPB module when the link is terminated by the remote
+system or another event has occurred to terminate the link. This may be
+returned in response to a lapb_connect_request (see above) if the remote
+system refused the request. The values for reason are:
+
+=================      ====================================================
+LAPB_OK                        The LAPB link was terminated normally by the remote
+                       system.
+LAPB_REFUSED           The remote system refused the connect request.
+LAPB_NOTCONNECTED      The remote system was not connected.
+LAPB_TIMEDOUT          No response was received in N2 tries from the remote
+                       system.
+=================      ====================================================
+
+::
+
+    int (*data_indication)(void *token, struct sk_buff *skb);
+
+This is called by the LAPB module when data has been received from the
+remote system that should be passed onto the next layer in the protocol
+stack. The skbuff becomes the property of the device driver and the LAPB
+module will not perform any more actions on it. The skb->data pointer will
+be pointing to the first byte of data after the LAPB header.
+
+This method should return NET_RX_DROP (as defined in the header
+file include/linux/netdevice.h) if and only if the frame was dropped
+before it could be delivered to the upper layer.
+
+::
+
+    void (*data_transmit)(void *token, struct sk_buff *skb);
+
+This is called by the LAPB module when data is to be transmitted to the
+remote system by the device driver. The skbuff becomes the property of the
+device driver and the LAPB module will not perform any more actions on it.
+The skb->data pointer will be pointing to the first byte of the LAPB header.
diff --git a/Documentation/networking/lapb-module.txt b/Documentation/networking/lapb-module.txt
deleted file mode 100644 (file)
index d4fc8f2..0000000
+++ /dev/null
@@ -1,263 +0,0 @@
-               The Linux LAPB Module Interface 1.3
-
-                     Jonathan Naylor 29.12.96
-
-Changed (Henner Eisen, 2000-10-29): int return value for data_indication() 
-
-The LAPB module will be a separately compiled module for use by any parts of
-the Linux operating system that require a LAPB service. This document
-defines the interfaces to, and the services provided by this module. The
-term module in this context does not imply that the LAPB module is a
-separately loadable module, although it may be. The term module is used in
-its more standard meaning.
-
-The interface to the LAPB module consists of functions to the module,
-callbacks from the module to indicate important state changes, and
-structures for getting and setting information about the module.
-
-Structures
-----------
-
-Probably the most important structure is the skbuff structure for holding
-received and transmitted data, however it is beyond the scope of this
-document.
-
-The two LAPB specific structures are the LAPB initialisation structure and
-the LAPB parameter structure. These will be defined in a standard header
-file, <linux/lapb.h>. The header file <net/lapb.h> is internal to the LAPB
-module and is not for use.
-
-LAPB Initialisation Structure
------------------------------
-
-This structure is used only once, in the call to lapb_register (see below).
-It contains information about the device driver that requires the services
-of the LAPB module.
-
-struct lapb_register_struct {
-       void (*connect_confirmation)(int token, int reason);
-       void (*connect_indication)(int token, int reason);
-       void (*disconnect_confirmation)(int token, int reason);
-       void (*disconnect_indication)(int token, int reason);
-       int  (*data_indication)(int token, struct sk_buff *skb);
-       void (*data_transmit)(int token, struct sk_buff *skb);
-};
-
-Each member of this structure corresponds to a function in the device driver
-that is called when a particular event in the LAPB module occurs. These will
-be described in detail below. If a callback is not required (!!) then a NULL
-may be substituted.
-
-
-LAPB Parameter Structure
-------------------------
-
-This structure is used with the lapb_getparms and lapb_setparms functions
-(see below). They are used to allow the device driver to get and set the
-operational parameters of the LAPB implementation for a given connection.
-
-struct lapb_parms_struct {
-       unsigned int t1;
-       unsigned int t1timer;
-       unsigned int t2;
-       unsigned int t2timer;
-       unsigned int n2;
-       unsigned int n2count;
-       unsigned int window;
-       unsigned int state;
-       unsigned int mode;
-};
-
-T1 and T2 are protocol timing parameters and are given in units of 100ms. N2
-is the maximum number of tries on the link before it is declared a failure.
-The window size is the maximum number of outstanding data packets allowed to
-be unacknowledged by the remote end, the value of the window is between 1
-and 7 for a standard LAPB link, and between 1 and 127 for an extended LAPB
-link.
-
-The mode variable is a bit field used for setting (at present) three values.
-The bit fields have the following meanings:
-
-Bit    Meaning
-0      LAPB operation (0=LAPB_STANDARD 1=LAPB_EXTENDED).
-1      [SM]LP operation (0=LAPB_SLP 1=LAPB=MLP).
-2      DTE/DCE operation (0=LAPB_DTE 1=LAPB_DCE)
-3-31   Reserved, must be 0.
-
-Extended LAPB operation indicates the use of extended sequence numbers and
-consequently larger window sizes, the default is standard LAPB operation.
-MLP operation is the same as SLP operation except that the addresses used by
-LAPB are different to indicate the mode of operation, the default is Single
-Link Procedure. The difference between DCE and DTE operation is (i) the
-addresses used for commands and responses, and (ii) when the DCE is not
-connected, it sends DM without polls set, every T1. The upper case constant
-names will be defined in the public LAPB header file.
-
-
-Functions
----------
-
-The LAPB module provides a number of function entry points.
-
-
-int lapb_register(void *token, struct lapb_register_struct);
-
-This must be called before the LAPB module may be used. If the call is
-successful then LAPB_OK is returned. The token must be a unique identifier
-generated by the device driver to allow for the unique identification of the
-instance of the LAPB link. It is returned by the LAPB module in all of the
-callbacks, and is used by the device driver in all calls to the LAPB module.
-For multiple LAPB links in a single device driver, multiple calls to
-lapb_register must be made. The format of the lapb_register_struct is given
-above. The return values are:
-
-LAPB_OK                        LAPB registered successfully.
-LAPB_BADTOKEN          Token is already registered.
-LAPB_NOMEM             Out of memory
-
-
-int lapb_unregister(void *token);
-
-This releases all the resources associated with a LAPB link. Any current
-LAPB link will be abandoned without further messages being passed. After
-this call, the value of token is no longer valid for any calls to the LAPB
-function. The valid return values are:
-
-LAPB_OK                        LAPB unregistered successfully.
-LAPB_BADTOKEN          Invalid/unknown LAPB token.
-
-
-int lapb_getparms(void *token, struct lapb_parms_struct *parms);
-
-This allows the device driver to get the values of the current LAPB
-variables, the lapb_parms_struct is described above. The valid return values
-are:
-
-LAPB_OK                        LAPB getparms was successful.
-LAPB_BADTOKEN          Invalid/unknown LAPB token.
-
-
-int lapb_setparms(void *token, struct lapb_parms_struct *parms);
-
-This allows the device driver to set the values of the current LAPB
-variables, the lapb_parms_struct is described above. The values of t1timer,
-t2timer and n2count are ignored, likewise changing the mode bits when
-connected will be ignored. An error implies that none of the values have
-been changed. The valid return values are:
-
-LAPB_OK                        LAPB getparms was successful.
-LAPB_BADTOKEN          Invalid/unknown LAPB token.
-LAPB_INVALUE           One of the values was out of its allowable range.
-
-
-int lapb_connect_request(void *token);
-
-Initiate a connect using the current parameter settings. The valid return
-values are:
-
-LAPB_OK                        LAPB is starting to connect.
-LAPB_BADTOKEN          Invalid/unknown LAPB token.
-LAPB_CONNECTED         LAPB module is already connected.
-
-
-int lapb_disconnect_request(void *token);
-
-Initiate a disconnect. The valid return values are:
-
-LAPB_OK                        LAPB is starting to disconnect.
-LAPB_BADTOKEN          Invalid/unknown LAPB token.
-LAPB_NOTCONNECTED      LAPB module is not connected.
-
-
-int lapb_data_request(void *token, struct sk_buff *skb);
-
-Queue data with the LAPB module for transmitting over the link. If the call
-is successful then the skbuff is owned by the LAPB module and may not be
-used by the device driver again. The valid return values are:
-
-LAPB_OK                        LAPB has accepted the data.
-LAPB_BADTOKEN          Invalid/unknown LAPB token.
-LAPB_NOTCONNECTED      LAPB module is not connected.
-
-
-int lapb_data_received(void *token, struct sk_buff *skb);
-
-Queue data with the LAPB module which has been received from the device. It
-is expected that the data passed to the LAPB module has skb->data pointing
-to the beginning of the LAPB data. If the call is successful then the skbuff
-is owned by the LAPB module and may not be used by the device driver again.
-The valid return values are:
-
-LAPB_OK                        LAPB has accepted the data.
-LAPB_BADTOKEN          Invalid/unknown LAPB token.
-
-
-Callbacks
----------
-
-These callbacks are functions provided by the device driver for the LAPB
-module to call when an event occurs. They are registered with the LAPB
-module with lapb_register (see above) in the structure lapb_register_struct
-(see above).
-
-
-void (*connect_confirmation)(void *token, int reason);
-
-This is called by the LAPB module when a connection is established after
-being requested by a call to lapb_connect_request (see above). The reason is
-always LAPB_OK.
-
-
-void (*connect_indication)(void *token, int reason);
-
-This is called by the LAPB module when the link is established by the remote
-system. The value of reason is always LAPB_OK.
-
-
-void (*disconnect_confirmation)(void *token, int reason);
-
-This is called by the LAPB module when an event occurs after the device
-driver has called lapb_disconnect_request (see above). The reason indicates
-what has happened. In all cases the LAPB link can be regarded as being
-terminated. The values for reason are:
-
-LAPB_OK                        The LAPB link was terminated normally.
-LAPB_NOTCONNECTED      The remote system was not connected.
-LAPB_TIMEDOUT          No response was received in N2 tries from the remote
-                       system.
-
-
-void (*disconnect_indication)(void *token, int reason);
-
-This is called by the LAPB module when the link is terminated by the remote
-system or another event has occurred to terminate the link. This may be
-returned in response to a lapb_connect_request (see above) if the remote
-system refused the request. The values for reason are:
-
-LAPB_OK                        The LAPB link was terminated normally by the remote
-                       system.
-LAPB_REFUSED           The remote system refused the connect request.
-LAPB_NOTCONNECTED      The remote system was not connected.
-LAPB_TIMEDOUT          No response was received in N2 tries from the remote
-                       system.
-
-
-int (*data_indication)(void *token, struct sk_buff *skb);
-
-This is called by the LAPB module when data has been received from the
-remote system that should be passed onto the next layer in the protocol
-stack. The skbuff becomes the property of the device driver and the LAPB
-module will not perform any more actions on it. The skb->data pointer will
-be pointing to the first byte of data after the LAPB header.
-
-This method should return NET_RX_DROP (as defined in the header
-file include/linux/netdevice.h) if and only if the frame was dropped
-before it could be delivered to the upper layer.
-
-
-void (*data_transmit)(void *token, struct sk_buff *skb);
-
-This is called by the LAPB module when data is to be transmitted to the
-remote system by the device driver. The skbuff becomes the property of the
-device driver and the LAPB module will not perform any more actions on it.
-The skb->data pointer will be pointing to the first byte of the LAPB header.
index 3a5f52a3c055185164ef8ef907a4c06145f1c688..956999d2d979d0ea4d1ba8a25978dc856bc9c0ba 100644 (file)
@@ -9515,7 +9515,7 @@ F:        drivers/soc/lantiq
 LAPB module
 L:     linux-x25@vger.kernel.org
 S:     Orphan
-F:     Documentation/networking/lapb-module.txt
+F:     Documentation/networking/lapb-module.rst
 F:     include/*/lapb.h
 F:     net/lapb/
 
index 6acfc999c9523eed2b232556c5a743ea4c45a353..5b50e8d64f26ddaa55943307ca1b359b31300f1d 100644 (file)
@@ -15,7 +15,7 @@ config LAPB
          currently supports LAPB only over Ethernet connections. If you want
          to use LAPB connections over Ethernet, say Y here and to "LAPB over
          Ethernet driver" below. Read
-         <file:Documentation/networking/lapb-module.txt> for technical
+         <file:Documentation/networking/lapb-module.rst> for technical
          details.
 
          To compile this driver as a module, choose M here: the