A sample rconfig script which completely wipes and reinstalls dragonfly
[dragonfly.git] / share / examples / isdn / Overview
1
2         Short technical overview of isdn4bsd
3         ====================================
4
5         Copyright (c) 1998 Hellmuth Michaelis. All rights reserved.
6
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 $
9
10         Last edit-date: [Tue Oct 27 11:26:03 1998]
11
12         -hm     starting an overview ...
13
14
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
24
25
26 Functional block diagram
27 ========================
28
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
100
101
102 Layer 1
103 =======
104
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.
114
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:
117
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)
120
121    (see file layer1/i4b_l1.h)
122    
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
131
132
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.
135
136     Files i4b_l1.c and i4b_l1.h handle stuff used to access layer 1
137     functions from layer 2.
138
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.
145
146     File i4b_isic.c contains the main code for the "isic" device driver.
147
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.
150
151
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.
159
160
161 Layer 2
162 =======
163
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.
168
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.
175
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.
179
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.
185
186     i4b_l2timer.c implements the timers required by Q.921.
187
188     i4b_tei.c contains the TEI handling routines.
189
190     i4b_lme.c implements a rudimentary layer management entity.
191
192     i4b_util.c implements the many utility functions specified
193     in Q.921 together wit some misc routines required for overall
194     functionality.
195
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.
199
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.
202
203 Layer 3
204 =======
205
206 (5) i4b_l2if.c and i4b_l4if.c contain the interface routines to communicate
207     to layer 2 and layer 4 respectively.
208
209     i4b_l3timer.c implements the timers required by layer 3.
210
211     i4b_q931.c and i4b_q931.h implement the message and information element
212     decoding of the Q.931 protocol.
213
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.
218
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.
221
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.
232
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.
242
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.
249
250 Debugging control
251 =================
252
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.
258
259
260 Layer 4    
261 =======
262
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.
270
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.
278
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.
282
283     i4b_l4timer.c implements a timeout timer for Layer 4.
284
285
286 ISDN protocol trace
287 ===================
288
289 (8) ISDN D-channel protocol trace for layers 2 and 3 is possible by using
290     hooks in the ISAC handling routines.
291
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.
296
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.
300
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.
304
305     B-channel data is not interpreted but dumped as a hex-dump.
306
307
308 /* EOF */