2 Short technical overview of isdn4bsd
3 ====================================
5 Copyright (c) 1998 Hellmuth Michaelis. All rights reserved.
9 Last edit-date: [Tue Oct 27 11:26:03 1998]
11 -hm starting an overview ...
16 Functional block diagram
25 Functional block diagram
26 ========================
28 isdndebug isdnd isdntrace
29 +-------+ +----------------------------------------------------+ +--------+
32 +-------+ +----------------------------------------------------+ +--------+
35 | /dev/i4bctl Userland | /dev/i4b /dev/i4btrc<n> |
36 ===============================================================================
39 +-------+ +----------------------------------------------------+ +--------+
41 |i4bctl | | i4b | | i4btrc |
42 | (6) | | (7) | | (8) |
43 | debug | | Layer 4 - common call control interface | | ISDN |
44 |control| | | | trace |
45 +:-:-:--+ +----------------------------------------------------+ +--------+
47 : : : Call | various ptr arrays | Call %
48 . . . Control | in i4b_l3l4.h | Control %
50 +----------------------+ +----------------------+ %
52 | i4bq931 | ISDN | active card | %
54 | Layer 3 (Q.931) | # | driver | %
56 +----------------------+ # +----------------------+ %
58 | i4b_l2l3_func function # | + +------------+ %
59 | ptr array in i4b_l2l3.h # C +++++ isp |----> %
60 V # h + +------------+ IP %
61 +----------------------+ # a + Subsys %
62 | | # n + +------------+ %
63 | i4bq921 | # n +++++ ipr |----> %
64 | (4) | # e + +------------+ IP %
65 | Layer 2 (Q.921) | # l + Subsys %
66 | | # + +------------+ %
67 +----------------------+ # D +++++ tel/rbch |----> %
68 ^ # a + +------------+ to %
69 | i4b_l1l2_func function # t + /dev/i4btel<n> %
70 | ptr array in i4b_l1l2.h # a + or /dev/i4brbch<n>%
72 +----------------------+ # +---------------------+ %
74 | isic (ISAC part) | D-ch trace # | isic (HSCX part) |B-ch%
75 | (2) |%%%%%%%%%%%% # | (3) |%%%%%
76 | Layer 1 (I.430) | % # | non-HDLC / HDLC |trc %
78 +----------------------+ % # +---------------------+ %
80 D-channel | % # B-channels | %
81 +-----------------------------------------------+ %
82 | function ptr in % # %
83 | in isic_softc in %%%%%%%%#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
85 +----------------------+ #
89 | Card hardware driver | #
90 | for Teles, AVM, USR | #
92 +----------#-----------+ #
97 |=========#===============================#============================|
104 (1) A driver for a special card hardware consists of a
111 routines. These routines handle the card/manufacturer specific stuff
112 required to talk to a particular card.
114 The addresses of the read/write routines are put into an array found
115 in struct isic_softc and they are later called by the macros:
117 ISAC_READ(r), ISAC_WRITE(r,v), ISAC_RDFIFO(b,s), ISAC_WRFIFO(b,s),
118 HSCX_READ(n,r), HSCX_WRITE(n,r,v), HSCX_RDFIFO(n,b,s), HSCX_WRFIFO(n,b,s)
120 (see file layer1/i4b_l1.h)
122 Files currently used for this purpose are
123 - i4b_avm_a1.c AVM A1 and AVM Fritz!Card drivers
124 - i4b_ctx_s0P.c Creatix S0 PnP (experimental!)
125 - i4b_tel_s016.c Teles S0/16 and clones
126 - i4b_tel_s0163.c Teles S0/16.3
127 - i4b_tel_s08.c Teles S0/8 and clones
128 - i4b_tel_s0P.c Teles S0/16 PnP (experimental!)
129 - i4b_usr_sti.c 3Com USRobotics Sportster
132 (2) The files i4b_isac.c and i4b_isac.h contain the code to control the
133 ISAC chip by using the above mentioned macros.
135 Files i4b_l1.c and i4b_l1.h handle stuff used to access layer 1
136 functions from layer 2.
138 Layer 1 and layer 2 access functionality of each other by using
139 a well known function pointer array, which contains addresses of
140 "primitives" functions which are defined in I.430 and Q.921. The
141 function pointer array for layer 1/2 communication is defined in
142 file include/i4b_l1l2.h and is initialized i4b_l1.c at the very
145 File i4b_isic.c contains the main code for the "isic" device driver.
147 i4b_l1fsm.c is the heart of layer 1 containing the state machine which
148 implements the protocol described in I.430 and the ISAC data book.
151 (3) All above code is used for handling of the D channel, the files
152 i4b_bchan.c, i4b_hscx.c and i4b_hscx.h contain the code for handling
153 the B-channel, the HSCX is used to interface the userland drivers
154 isp, ipr, tel and rbch to one of the B-channels and i4b_hscx.c and
155 i4b_hscx.h contain the code to handle it (also by using the above
156 mentioned macros). i4b_bchan.c contains various maintenance code for
157 interfacing to the upper layers.
163 (4) Layer 2 implements the LAPD protocol described in Q.920/Q.921. Layer 2
164 interfaces to layer 1 by the above described function pointer array,
165 where layer 1 calls layer 2 functions to provide input to layer 2 and
166 layer 2 calls layer 1 functions to feed data to layer 1.
168 The same mechanism is used for layer 2 / layer 3 communication, the
169 pointer array interface is defined in include/i4b_l2l3.h ad the array
170 is initialized at the very beginning of i4b_l2.c which also contains
171 some layer 1 and some layer 3 interface routines. As with l1/l2, the
172 l2/l3 array also contains addresses for "primitives" functions which
173 are specified in Q.920/Q.921 and Q.931.
175 i4b_l2.h contains the definition of l2_softc_t, which describes the
176 complete state of a layer 2 link between the exchange and the local
179 i4b_l2.c contains the entrance of data from layer 1 into the system,
180 which is split up in i4b_ph_data_ind() into the 3 classes of layer 2
181 frames called S-frame, I-frame and U-frame. They are handled in files
182 i4b_sframe.c, i4b_iframe.c and i4b_uframe.c together with the respective
183 routines to send data with each ones frame type.
185 i4b_l2timer.c implements the timers required by Q.921.
187 i4b_tei.c contains the TEI handling routines.
189 i4b_lme.c implements a rudimentary layer management entity.
191 i4b_util.c implements the many utility functions specified
192 in Q.921 together wit some misc routines required for overall
195 i4b_mbuf.c handles all (!) requests for mbufs and frees all mbufs used
196 by the whole isdn4bsd kernel part. It should probably be moved else-
199 i4b_l2fsm.c and i4b_l2fsm.h contain the heart of layer 2, the state-
200 machine implementing the protocol as specified in Q.921.
205 (5) i4b_l2if.c and i4b_l4if.c contain the interface routines to communicate
206 to layer 2 and layer 4 respectively.
208 i4b_l3timer.c implements the timers required by layer 3.
210 i4b_q931.c and i4b_q931.h implement the message and information element
211 decoding of the Q.931 protocol.
213 i4b_q932fac.c and i4b_q932fac.h implement a partial decoding of facility
214 messages and/or information elements; the only decoding done here is
215 the decoding of AOCD and AOCE, advice of charge during and at end of
218 As usual, i4b_l3fsm.c and i4b_l3fsm.h contain the state machine required
219 to handle the protocol as specified in Q.931.
221 Layer 3 uses a structure defined in include/i4b_l3l4.h to store and
222 request information about one particular isdncontroller, it is called
223 ctrl_desc_t (controller descriptor). It contains information on the
224 state of a controller (controller ready/down and which B channels are
225 used or idle) as well as a pointer array used for communication of
226 layer 4 with layer 3: layer 3 "knows" the routines to call within
227 layer 4 by name, but in case layer 4 has to call layer 3, several
228 possibilities exist (i.e. active / passive cards) so it has to call
229 the routines which the ISDN controller had put into the the function
230 pointer array (N_CONNECT_REQUEST, N_CONNECT_RESPONSE etc) at init time.
232 Layer 3 shares a structure called call_desc_t (call descriptor) with
233 layer 4. This structure is used to describe the state of one call. The
234 reference to layer 3 is the Q.931 call reference value, the reference to
235 layer 4 (and the isdn daemon, isdnd) is the cdid, an unique integer
236 value uniquely describing one call, the call descriptor id.
237 This structure is used to build an array of this structures
238 (call_desc[N_CALL_DESC]), which must be large enough to hold as many
239 calls as there are B channels in the system PLUS a reserve to be able
240 to handle incoming SETUP messages although all channels are in use.
242 More, this structure contains the so called "link table pointers"
243 (isdn_link_t *ilt and drvr_link_t *dlt) which contain function pointers
244 to "link" a B-channel (better the addresses of functions each participant
245 needs to access each others functionality) after a successful call setup
246 to a userland driver (such as isp, ipr, rbch or tel) to exchange user
247 data in the desired protocol and format.
252 (6) the device driver for /dev/i4bctl in conjunction with the userland
253 program isdndebug(8) is used to set the debug level for each of the
254 layers and several other parts of the system, information how to use
255 this is contained in i4b/i4b_debug.h and all parts of the kernel
256 sources. It is only usable for passive cards.
262 (7) Layer 4 is "just" an abstraction layer used to shield the differences
263 of the various possible Layer 3 interfaces (passive cards based on
264 Siemens chip-sets, passive cards based on other chip-sets, active cards
265 from different manufacturers using manufacturer-specific interfaces)
266 and to provide a uniform interface to the isdnd userland daemon, which
267 is used to handle all the required actions to setup and close calls
268 and to the necessary retry handling and management functionality.
270 Layer 4 communicates with the userland by using a well defined protocol
271 consisting of "messages" sent to userland and which are read(2) by the
272 isdnd. The isdnd in turn sends "messages" to the kernel by using the
273 ioctl(2) call. This protocol and the required messages for both
274 directions are documented in the i4b/i4b_ioctl.h file and are
275 implemented in files i4b_i4bdrv.c and i4b_l4.c, the latter also
276 containing much of the Layer 4 interface to the lower layers.
278 i4b_l4mgmt.c contains all the required routines to manage the above
279 mentioned call descriptor id (cdid) in conjunction with the call
280 descriptor (array) and the call reference seen from layer 3.
282 i4b_l4timer.c implements a timeout timer for Layer 4.
288 (8) ISDN D-channel protocol trace for layers 2 and 3 is possible by using
289 hooks in the ISAC handling routines.
291 In case D-channel trace is enabled, every frame is prepended with a
292 header containing further data such as a time stamp and sent via the
293 i4btrc driver found in driver/i4b_trace.c to one of the /dev/i4btrc<n>
294 devices, where <n> corresponds to a passive controller unit number.
296 If desired, B-channel data can be made available using the same
297 mechanism - hooks in the HSCX handler send data up to the i4btrc
300 The raw data is then read by the isdntrace userland program which
301 decodes the layer 2 and/or layer 3 protocol and formats it to be
302 easily readable by the user.
304 B-channel data is not interpreted but dumped as a hex-dump.