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 */