40e79150c1
- 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>
306 lines
11 KiB
ReStructuredText
306 lines
11 KiB
ReStructuredText
.. 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.
|