1.. SPDX-License-Identifier: GPL-2.0
2
3============================-
4X.25 Device Driver Interface
5============================-
6
7Version 1.1
8
9			   Jonathan Naylor 26.12.96
10
11This is a description of the messages to be passed between the X.25 Packet
12Layer and the X.25 device driver. They are designed to allow for the easy
13setting of the LAPB mode from within the Packet Layer.
14
15The X.25 device driver will be coded normally as per the Linux device driver
16standards. Most X.25 device drivers will be moderately similar to the
17already existing Ethernet device drivers. However unlike those drivers, the
18X.25 device driver has a state associated with it, and this information
19needs to be passed to and from the Packet Layer for proper operation.
20
21All messages are held in sk_buff's just like real data to be transmitted
22over the LAPB link. The first byte of the skbuff indicates the meaning of
23the rest of the skbuff, if any more information does exist.
24
25
26Packet Layer to Device Driver
27-----------------------------
28
29First Byte = 0x00 (X25_IFACE_DATA)
30
31This indicates that the rest of the skbuff contains data to be transmitted
32over the LAPB link. The LAPB link should already exist before any data is
33passed down.
34
35First Byte = 0x01 (X25_IFACE_CONNECT)
36
37Establish the LAPB link. If the link is already established then the connect
38confirmation message should be returned as soon as possible.
39
40First Byte = 0x02 (X25_IFACE_DISCONNECT)
41
42Terminate the LAPB link. If it is already disconnected then the disconnect
43confirmation message should be returned as soon as possible.
44
45First Byte = 0x03 (X25_IFACE_PARAMS)
46
47LAPB parameters. To be defined.
48
49
50Device Driver to Packet Layer
51-----------------------------
52
53First Byte = 0x00 (X25_IFACE_DATA)
54
55This indicates that the rest of the skbuff contains data that has been
56received over the LAPB link.
57
58First Byte = 0x01 (X25_IFACE_CONNECT)
59
60LAPB link has been established. The same message is used for both a LAPB
61link connect_confirmation and a connect_indication.
62
63First Byte = 0x02 (X25_IFACE_DISCONNECT)
64
65LAPB link has been terminated. This same message is used for both a LAPB
66link disconnect_confirmation and a disconnect_indication.
67
68First Byte = 0x03 (X25_IFACE_PARAMS)
69
70LAPB parameters. To be defined.
71
72
73
74Possible Problems
75=================
76
77(Henner Eisen, 2000-10-28)
78
79The X.25 packet layer protocol depends on a reliable datalink service.
80The LAPB protocol provides such reliable service. But this reliability
81is not preserved by the Linux network device driver interface:
82
83- With Linux 2.4.x (and above) SMP kernels, packet ordering is not
84  preserved. Even if a device driver calls netif_rx(skb1) and later
85  netif_rx(skb2), skb2 might be delivered to the network layer
86  earlier that skb1.
87- Data passed upstream by means of netif_rx() might be dropped by the
88  kernel if the backlog queue is congested.
89
90The X.25 packet layer protocol will detect this and reset the virtual
91call in question. But many upper layer protocols are not designed to
92handle such N-Reset events gracefully. And frequent N-Reset events
93will always degrade performance.
94
95Thus, driver authors should make netif_rx() as reliable as possible:
96
97SMP re-ordering will not occur if the driver's interrupt handler is
98always executed on the same CPU. Thus,
99
100- Driver authors should use irq affinity for the interrupt handler.
101
102The probability of packet loss due to backlog congestion can be
103reduced by the following measures or a combination thereof:
104
105(1) Drivers for kernel versions 2.4.x and above should always check the
106    return value of netif_rx(). If it returns NET_RX_DROP, the
107    driver's LAPB protocol must not confirm reception of the frame
108    to the peer.
109    This will reliably suppress packet loss. The LAPB protocol will
110    automatically cause the peer to re-transmit the dropped packet
111    later.
112    The lapb module interface was modified to support this. Its
113    data_indication() method should now transparently pass the
114    netif_rx() return value to the (lapb module) caller.
115(2) Drivers for kernel versions 2.2.x should always check the global
116    variable netdev_dropping when a new frame is received. The driver
117    should only call netif_rx() if netdev_dropping is zero. Otherwise
118    the driver should not confirm delivery of the frame and drop it.
119    Alternatively, the driver can queue the frame internally and call
120    netif_rx() later when netif_dropping is 0 again. In that case, delivery
121    confirmation should also be deferred such that the internal queue
122    cannot grow to much.
123    This will not reliably avoid packet loss, but the probability
124    of packet loss in netif_rx() path will be significantly reduced.
125(3) Additionally, driver authors might consider to support
126    CONFIG_NET_HW_FLOWCONTROL. This allows the driver to be woken up
127    when a previously congested backlog queue becomes empty again.
128    The driver could uses this for flow-controlling the peer by means
129    of the LAPB protocol's flow-control service.
130