| blob | 7ba42a1cb168cd522b2232b0ed5591dde7e45016 |
2 Short technical overview of isdn4bsd
3 ====================================
5 Copyright (c) 1998 Hellmuth Michaelis. All rights reserved.
7 $FreeBSD: src/share/examples/isdn/Overview,v 1.3 1999/08/28 00:19:19 peter Exp $
8 $DragonFly: src/share/examples/isdn/Overview,v 1.2 2003/06/17 04:36:57 dillon Exp $
10 Last edit-date: [Tue Oct 27 11:26:03 1998]
12 -hm starting an overview ...
15 Contents:
16 ---------
17 Functional block diagram
18 Layer 1
19 Layer 2
20 Layer 3
21 Debugging control
22 Layer 4
23 ISDN protocol trace
26 Functional block diagram
27 ========================
29 isdndebug isdnd isdntrace
30 +-------+ +----------------------------------------------------+ +--------+
31 | | | | | |
32 | | | | | |
33 +-------+ +----------------------------------------------------+ +--------+
34 | | |
35 | | |
36 | /dev/i4bctl Userland | /dev/i4b /dev/i4btrc<n> |
37 ===============================================================================
38 | Kernel | |
39 | | |
40 +-------+ +----------------------------------------------------+ +--------+
41 | | | | | |
42 |i4bctl | | i4b | | i4btrc |
43 | (6) | | (7) | | (8) |
44 | debug | | Layer 4 - common call control interface | | ISDN |
45 |control| | | | trace |
46 +:-:-:--+ +----------------------------------------------------+ +--------+
47 : : : ^ ^ ^
48 : : : Call | various ptr arrays | Call %
49 . . . Control | in i4b_l3l4.h | Control %
50 V V %
51 +----------------------+ +----------------------+ %
52 | | | | %
53 | i4bq931 | ISDN | active card | %
54 | (5) | ##### | %
55 | Layer 3 (Q.931) | # | driver | %
56 | | # | | %
57 +----------------------+ # +----------------------+ %
58 ^ # B + %
59 | i4b_l2l3_func function # | + +------------+ %
60 | ptr array in i4b_l2l3.h # C +++++ isp |----> %
61 V # h + +------------+ IP %
62 +----------------------+ # a + Subsys %
63 | | # n + +------------+ %
64 | i4bq921 | # n +++++ ipr |----> %
65 | (4) | # e + +------------+ IP %
66 | Layer 2 (Q.921) | # l + Subsys %
67 | | # + +------------+ %
68 +----------------------+ # D +++++ tel/rbch |----> %
69 ^ # a + +------------+ to %
70 | i4b_l1l2_func function # t + /dev/i4btel<n> %
71 | ptr array in i4b_l1l2.h # a + or /dev/i4brbch<n>%
72 V # + %
73 +----------------------+ # +---------------------+ %
74 | | # | | %
75 | isic (ISAC part) | D-ch trace # | isic (HSCX part) |B-ch%
76 | (2) |%%%%%%%%%%%% # | (3) |%%%%%
77 | Layer 1 (I.430) | % # | non-HDLC / HDLC |trc %
78 | | % # | | %
79 +----------------------+ % # +---------------------+ %
80 ^ % # ^ %
81 D-channel | % # B-channels | %
82 +-----------------------------------------------+ %
83 | function ptr in % # %
84 | in isic_softc in %%%%%%%%#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
85 V i4b_l1.h #
86 +----------------------+ #
87 | | #
88 | isic | #
89 | (1) | #
90 | Card hardware driver | #
91 | for Teles, AVM, USR | #
92 | | #
93 +----------#-----------+ #
94 # #
95 # #
96 # #
97 # #
98 |=========#===============================#============================|
99 ISDN S0 bus
102 Layer 1
103 =======
105 (1) A driver for a special card hardware consists of a
106 - probe routine
107 - attach routine
108 - FIFO read
109 - FIFO write
110 - register read
111 - register write
112 routines. These routines handle the card/manufacturer specific stuff
113 required to talk to a particular card.
115 This addresses of the read/write routines are put into a arrays found
116 in struct isic_softc and they are later called by the macros:
118 ISAC_READ(r), ISAC_WRITE(r,v), ISAC_RDFIFO(b,s), ISAC_WRFIFO(b,s),
119 HSCX_READ(n,r), HSCX_WRITE(n,r,v), HSCX_RDFIFO(n,b,s), HSCX_WRFIFO(n,b,s)
121 (see file layer1/i4b_l1.h)
123 Files currently used for this purpose are
124 - i4b_avm_a1.c AVM A1 and AVM Fritz!Card drivers
125 - i4b_ctx_s0P.c Creatix S0 PnP (experimental!)
126 - i4b_tel_s016.c Teles S0/16 and clones
127 - i4b_tel_s0163.c Teles S0/16.3
128 - i4b_tel_s08.c Teles S0/8 and clones
129 - i4b_tel_s0P.c Teles S0/16 PnP (experimental!)
130 - i4b_usr_sti.c 3Com USRobotics Sportster
133 (2) The files i4b_isac.c and i4b_isac.h contain the code to control the
134 ISAC chip by using the above mentioned macros.
136 Files i4b_l1.c and i4b_l1.h handle stuff used to access layer 1
137 functions from layer 2.
139 Layer 1 and layer 2 access functionality of each other by using
140 a well known function pointer array, which contains addresses of
141 "primitives" functions which are defined in I.430 and Q.921. The
142 function pointer array for layer 1/2 communication is defined in
143 file include/i4b_l1l2.h and is initialized i4b_l1.c at the very
144 beginning.
146 File i4b_isic.c contains the main code for the "isic" device driver.
148 i4b_l1fsm.c is the heart of layer 1 containing the state machine which
149 implements the protocol described in I.430 and the ISAC data book.
152 (3) All above code is used for handling of the D channel, the files
153 i4b_bchan.c, i4b_hscx.c and i4b_hscx.h contain the code for handling
154 the B-channel, the HSCX is used to interface the userland drivers
155 isp, ipr, tel and rbch to one of the B-channels and i4b_hscx.c and
156 i4b_hscx.h contain the code to handle it (also by using the above
157 mentioned macros). i4b_bchan.c contains various maintenance code for
158 interfacing to the upper layers.
161 Layer 2
162 =======
164 (4) Layer 2 implements the LAPD protocol described in Q.920/Q.921. Layer 2
165 interfaces to layer 1 by the above described function pointer array,
166 where layer 1 calls layer 2 functions to provide input to layer 2 and
167 layer 2 calls layer 1 functions to feed data to layer 1.
169 The same mechanism is used for layer 2 / layer 3 communication, the
170 pointer array interface is defined in include/i4b_l2l3.h ad the array
171 is initialized at the very beginning of i4b_l2.c which also contains
172 some layer 1 and some layer 3 interface routines. As with l1/l2, the
173 l2/l3 array also contains addresses for "primitives" functions which
174 are specified in Q.920/Q.921 and Q.931.
176 i4b_l2.h contains the definition of l2_softc_t, which describes the
177 complete state of a layer 2 link between the exchange and the local
178 terminal equipment.
180 i4b_l2.c contains the entrance of data from layer 1 into the system,
181 which is split up in i4b_ph_data_ind() into the 3 classes of layer 2
182 frames called S-frame, I-frame and U-frame. They are handled in files
183 i4b_sframe.c, i4b_iframe.c and i4b_uframe.c together with the respective
184 routines to send data with each ones frame type.
186 i4b_l2timer.c implements the timers required by Q.921.
188 i4b_tei.c contains the TEI handling routines.
190 i4b_lme.c implements a rudimentary layer management entity.
192 i4b_util.c implements the many utility functions specified
193 in Q.921 together wit some misc routines required for overall
194 functionality.
196 i4b_mbuf.c handles all (!) requests for mbufs and frees all mbufs used
197 by the whole isdn4bsd kernel part. It should probably be moved else-
198 where.
200 i4b_l2fsm.c and i4b_l2fsm.h contain the heart of layer 2, the state-
201 machine implementing the protocol as specified in Q.921.
203 Layer 3
204 =======
206 (5) i4b_l2if.c and i4b_l4if.c contain the interface routines to communicate
207 to layer 2 and layer 4 respectively.
209 i4b_l3timer.c implements the timers required by layer 3.
211 i4b_q931.c and i4b_q931.h implement the message and information element
212 decoding of the Q.931 protocol.
214 i4b_q932fac.c and i4b_q932fac.h implement a partial decoding of facility
215 messages and/or information elements; the only decoding done here is
216 the decoding of AOCD and AOCE, advice of charge during and at end of
217 call.
219 As usual, i4b_l3fsm.c and i4b_l3fsm.h contain the state machine required
220 to handle the protocol as specified in Q.931.
222 Layer 3 uses a structure defined in include/i4b_l3l4.h to store and
223 request information about one particular isdncontroller, it is called
224 ctrl_desc_t (controller descriptor). It contains information on the
225 state of a controller (controller ready/down and which B channels are
226 used or idle) as well as a pointer array used for communication of
227 layer 4 with layer 3: layer 3 "knows" the routines to call within
228 layer 4 by name, but in case layer 4 has to call layer 3, several
229 possibilities exist (i.e. active / passive cards) so it has to call
230 the routines which the ISDN controller had put into the the function
231 pointer array (N_CONNECT_REQUEST, N_CONNECT_RESPONSE etc) at init time.
233 Layer 3 shares a structure called call_desc_t (call descriptor) with
234 layer 4. This structure is used to describe the state of one call. The
235 reference to layer 3 is the Q.931 call reference value, the reference to
236 layer 4 (and the isdn daemon, isdnd) is the cdid, an unique integer
237 value uniquely describing one call, the call descriptor id.
238 This structure is used to build an array of this structures
239 (call_desc[N_CALL_DESC]), which must be large enough to hold as many
240 calls as there are B channels in the system PLUS a reserve to be able
241 to handle incoming SETUP messages although all channels are in use.
243 More, this structure contains the so called "link table pointers"
244 (isdn_link_t *ilt and drvr_link_t *dlt) which contain function pointers
245 to "link" a B-channel (better the addresses of functions each participant
246 needs to access each others functionality) after a successful call setup
247 to a userland driver (such as isp, ipr, rbch or tel) to exchange user
248 data in the desired protocol and format.
250 Debugging control
251 =================
253 (6) the device driver for /dev/i4bctl in conjunction with the userland
254 program isdndebug(8) is used to set the debug level for each of the
255 layers and several other parts of the system, information how to use
256 this is contained in machine/i4b_debug.h and all parts of the kernel
257 sources. It is only usable for passive cards.
260 Layer 4
261 =======
263 (7) Layer 4 is "just" an abstraction layer used to shield the differences
264 of the various possible Layer 3 interfaces (passive cards based on
265 Siemens chip-sets, passive cards based on other chip-sets, active cards
266 from different manufacturers using manufacturer-specific interfaces)
267 and to provide a uniform interface to the isdnd userland daemon, which
268 is used to handle all the required actions to setup and close calls
269 and to the necessary retry handling and management functionality.
271 Layer 4 communicates with the userland by using a well defined protocol
272 consisting of "messages" sent to userland and which are read(2) by the
273 isdnd. The isdnd in turn sends "messages" to the kernel by using the
274 ioctl(2) call. This protocol and the required messages for both
275 directions are documented in the machine/i4b_ioctl.h file and are
276 implemented in files i4b_i4bdrv.c and i4b_l4.c, the latter also
277 containing much of the Layer 4 interface to the lower layers.
279 i4b_l4mgmt.c contains all the required routines to manage the above
280 mentioned call descriptor id (cdid) in conjunction with the call
281 descriptor (array) and the call reference seen from layer 3.
283 i4b_l4timer.c implements a timeout timer for Layer 4.
286 ISDN protocol trace
287 ===================
289 (8) ISDN D-channel protocol trace for layers 2 and 3 is possible by using
290 hooks in the ISAC handling routines.
292 In case D-channel trace is enabled, every frame is prepended with a
293 header containing further data such as a time stamp and sent via the
294 i4btrc driver found in driver/i4b_trace.c to one of the /dev/i4btrc<n>
295 devices, where <n> corresponds to a passive controller unit number.
297 If desired, B-channel data can be made available using the same
298 mechanism - hooks in the HSCX handler send data up to the i4btrc
299 device.
301 The raw data is then read by the isdntrace userland program which
302 decodes the layer 2 and/or layer 3 protocol and formats it to be
303 easily readable by the user.
305 B-channel data is not interpreted but dumped as a hex-dump.
308 /* EOF */