linux/Documentation/networking/lapb-module.txt

Chinese translated version of Documentation/cpu-load.txt




If you have any comment or update to the content, please contact the
original document maintainer directly.  However, if you have a problem
communicating in English you can also ask the Chinese maintainer for
help.  Contact the Chinese maintainer if this translation is outdated
or if there is a problem with the translation.




Chinese maintainer: linwei
---------------------------------------------------------------------
Documentation-cpu-load.txt 的中文翻译




如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
译存在问题，请联系中文版维护者。




中文版维护者： linwei










以下为正文


The Linux LAPB Module Interface 1.3
         1.3 Linux的的LAPB模块接口
     Jonathan Naylor 29.12.96
           
Changed (Henner Eisen, 2000-10-29): int return value for data_indication() 
修改（Henner Eisen2000-10-29 ） ： data_indication （ ）返回值为int类型


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.


Linux操作系统任何部分要求LAPB服务时 LAPB模块将会被独立汇编使用。此文档
定义了接口，和LAPB模块提供的服务。文中的 模块一词不是意味着LAPB模块是一个
可以单独加载的模块，尽管可能确实是这样。模块 这词 通常以更标准的意思被
使用。


The interface to the LAPB module consists of functions to the module,
callbacks from the module to indicate important state changes, anda
structures for getting and setting information about the module.


LAPB模块的接口由功能模块组成，回调函数是为了通报重要状态改变
anda结构是为了获取和设置模块信息。


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.
skbuff结构可能是最重要的结构，用于保持接收和发送数据，但它是超出了本文的范围
文档。


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的两个具体结构是LAPB初始化结构和LAPB参数结构。这些将被定义在一个标准的头
文件 <linux/lapb.h> 。头文件<net/lapb.h> 是LAPB内部
模块并不使用。




LAPB Initialisation Structure
-----------------------------
LAPB初始化结构


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.
此结构中仅使用一次，在调用lapb_register （见下文） 。
它包含的设备驱动程序需要的LAPB模块的服务信息




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模块中的特定事件发生。这些都将在下面详细描述。
如果不是必需的一个回调（ ！ ），那么一个NULL可以被取代。
LAPB Parameter Structure
------------------------
LAPB参数结构


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.


这个结构是通过lapb_getparms和lapb_setparms功能使用的
（见下文） 。它们被用来允许设备驱动程序，对于一个给定的连接
获取和设置操作参数的LAPB实施的。


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.


T1和T2是协议的时间参数，单位是100ms 。 N2是在声明之前失败的尝试的链接的最大数目。
窗口的大小是允许来自未确认的远程端的优秀数据包的数量，该窗口的值是1之间
和127为一个标准LAPB链接，并且在1和127之间的一个扩展LAPB
链接。


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.


扩展LAPB操作指示使用的扩展的序列号来获得更大的窗口大小，默认为标准LAPB操作。
MLP SLP操作的操作是一样的，除了是在LAPB是不同的指示的操作模式下使用地址，
默认为单链接程序。 DCE和DTE的操作之间的区别是： （i）这些地址被用作命名和响应 
以及（ii）当DCE是不连接时，它会发送DM没有在没有轮到，每个T1 。
公共LAPB头文件的名称将用大写常量来定义。


Functions
---------
功能


The LAPB module provides a number of function entry points.


LAPB模块提供了大量的函数入口点


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模块可能被使用之前调用。如果调用成功，则返回LAPB_OK 。
’token‘ 必须是一个唯一的标识符，是由设备驱动程序生成的 用来允许这唯一标识的
LAPB链路的实例。它通过所有LAPB模块回调函数返回 ，被所有LAPB模块调用的设备
驱动程序所使用。对于单一设备驱动的多个LAPB链接，多个lapb_register的调用必须被
建立。lapb_register_struct是样式如上所示。返回值：




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链路相关的所有资源。如果没有进一步的消息被传递，当前任何LAPB链路将
被放弃。在这个调用之后，token 的值不再对LAPB的任何调用函数有效
。有效的返回值是：


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变量的值， lapb_parms_struct如上所述。
有效的返回值是：


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变量， lapb_parms_struct如上所述。t1timer ，
t2timer和n2count的值被忽略，同样当连接将被忽略时 改变模式位。
错误则意味没有值被更改。有效的返回值是：


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模块的队列数据在链路上传输。如果该调用成功 则skbuff被LAPB模块所拥有
但可能无法再由设备驱动程序使用。有效的返回值是：


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模块的队列从设备接收数据。它预期的数据通过LAPB模块具有的skb - >数据指向
LAPB的数据的开头。如果调用成功，则的skbuff被LAPB模块拥有，
并且不得由设备驱动程序使用。
有效的返回值是：




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


这些回调函数由设备驱动程序提供 ，为LAPB模块响应调用事件。
他们和LAPB与lapb_register模块（见上文）在结构lapb_register_struct一起被注册
（见上文） 。




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.
当有连接在被lapb_connect_request 请求后建立，这个将被lapb模块调用（见上文） 。
原因总是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.


当链接被远程系统建立，这个函数将被调用。结果的价值永远是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_disconnect_request后发生，这个将被跳用。
reason说明发生了什么。在所有的情况下，可以视为LAPB链路
终止。REASON的值是：




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_connect_request是返回
 （见上文）.reason的值是：


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.


当来自远程系统的数据被接受 且该数据应该被传输到下一层协议栈  该函数将被LAPB
模块调用。 skbuff就变成设备驱动函数的独享，LAPB模块将不会执行任何指令。 
SKB- >数据指针指向LAPB的标头之后的数据的第一个字节


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.


此方法应返回NET_RX_DROP （定义在头文件include / LINUX / netdevice.h ）当且仅当帧被丢弃
才能够传递给上位层。


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.


当数据被设备驱动程序发送到远程系统时  这个函数被调用。skbuff成为设备驱动程序的一部分
LAPB模块将不执行任何操作。SKB- >数据指针指向LAPB头部的第一个字节。