The Linux LAPB Module Interface

LAPB module interface 개요

LAPB module은 Linux에서 LAPB service가 필요한 하위 시스템이나 device driver가 공통으로 사용하는 구성 요소입니다. 여기서 module이라는 말은 독립적으로 load 가능한 kernel module이라는 뜻으로 한정되지 않고 논리적인 구성 요소를 뜻합니다.

interface는 driver가 LAPB에 호출하는 함수, 중요한 상태 변화를 driver에 알리는 callback, connection별 정보를 조회·설정하는 구조체로 구성됩니다. 문서는 version 1.3이며 `data_indication()`이 `int`를 반환하도록 바뀐 이력도 기록합니다.

.. 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.

등록·parameter 구조체

송수신 data를 담는 핵심 구조체는 `sk_buff`지만 이 문서의 범위 밖입니다. LAPB 전용 공개 구조체는 `<linux/lapb.h>`에 정의되는 초기화 구조체와 parameter 구조체입니다. `<net/lapb.h>`는 LAPB 내부용이므로 driver가 사용하면 안 됩니다.

`struct lapb_register_struct`는 `lapb_register` 때 한 번 전달하며 connect/disconnect confirmation·indication, 상위 계층 data indication, 하위 driver data transmit callback을 담습니다. 필요 없는 callback은 NULL로 둘 수 있습니다.

`struct lapb_parms_struct`는 `lapb_getparms`와 `lapb_setparms`가 사용하는 connection parameter입니다. T1·T2와 현재 timer는 100ms 단위, N2와 현재 count는 link failure 선언 전 최대 재시도와 진행 상태입니다. window는 remote ACK 없이 outstanding일 수 있는 data packet 수로 standard LAPB는 1~7, extended LAPB는 1~127입니다. state와 mode도 함께 보관합니다.

mode bit 0은 standard/extended sequence number, bit 1은 SLP/MLP, bit 2는 DTE/DCE를 선택하고 나머지는 0이어야 합니다. Extended mode는 더 큰 sequence number와 window를 사용합니다. MLP는 주소가 달라 mode를 표시한다는 점을 제외하면 SLP와 같고 기본은 SLP입니다. DTE와 DCE는 command/response 주소가 다르며 연결되지 않은 DCE는 T1마다 poll bit 없는 DM을 보냅니다.

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.

등록, parameter와 data 함수

`lapb_register(token, callbacks)`는 LAPB 사용 전에 호출합니다. token은 driver가 만든 connection별 고유 식별자로 모든 callback에서 되돌아오고 이후 모든 LAPB 호출에 사용됩니다. 한 driver가 여러 LAPB link를 관리하면 각각 등록해야 합니다. 성공은 `LAPB_OK`, 중복 token은 `LAPB_BADTOKEN`, 메모리 부족은 `LAPB_NOMEM`입니다.

`lapb_unregister(token)`은 link의 모든 자원을 놓고 진행 중인 link를 추가 메시지 없이 폐기합니다. 호출 뒤 token은 무효입니다. `lapb_getparms`는 현재 parameter와 timer/counter/state를 읽고, `lapb_setparms`는 설정값을 바꿉니다. 설정 시 `t1timer`, `t2timer`, `n2count`는 무시되고 연결 중 mode 변경도 무시됩니다. 하나라도 범위를 벗어나면 `LAPB_INVALUE`이며 어떤 값도 바뀌지 않습니다.

`lapb_connect_request`와 `lapb_disconnect_request`는 현재 parameter로 연결 또는 해제를 시작합니다. 잘못된 token, 이미 연결됨, 연결되지 않음은 각각 `LAPB_BADTOKEN`, `LAPB_CONNECTED`, `LAPB_NOTCONNECTED`로 알립니다.

`lapb_data_request`는 link로 보낼 `sk_buff`를 LAPB 송신 queue에 넣습니다. 성공하면 buffer 소유권이 LAPB로 넘어가 driver는 다시 사용하면 안 됩니다. `lapb_data_received`는 device에서 받은 LAPB frame을 stack에 넘기며 `skb->data`가 LAPB data 시작을 가리켜야 합니다. 성공 시 이 buffer의 소유권도 LAPB로 넘어갑니다.

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.
=============                ===========================

상태·data callback

callback은 `lapb_register_struct`로 등록한 driver 함수입니다. 로컬 `lapb_connect_request`가 성공해 link가 맺어지면 `connect_confirmation`이 `LAPB_OK`로 호출되고, remote가 link를 맺으면 `connect_indication`이 호출됩니다.

로컬 disconnect 요청 뒤에는 `disconnect_confirmation`이 호출됩니다. `LAPB_OK`는 정상 종료, `LAPB_NOTCONNECTED`는 remote가 연결 상태가 아니었음, `LAPB_TIMEDOUT`은 N2번 시도에도 응답하지 않았음을 뜻하며 어떤 이유든 callback 시점에는 link가 종료된 것으로 봅니다.

remote 종료나 다른 종료 사건은 `disconnect_indication`으로 전달됩니다. 연결 요청 거부도 이 callback에서 `LAPB_REFUSED`로 알 수 있고, 정상 remote 종료·비연결·timeout도 각각 표준 reason으로 구분합니다.

`data_indication`은 remote data를 상위 protocol 계층으로 넘길 때 호출됩니다. buffer 소유권은 driver로 넘어가며 `skb->data`는 LAPB header 다음 첫 payload byte를 가리킵니다. 상위 계층에 전달하기 전에 frame을 버린 경우에만 `NET_RX_DROP`을 반환해야 합니다. `data_transmit`은 LAPB가 driver에 실제 송신을 요청하는 callback으로, buffer 소유권이 driver로 넘어가고 `skb->data`는 LAPB header 첫 byte를 가리킵니다.

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.