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
   9         Last edit-date: [Tue Oct 27 11:26:03 1998]
  10
  11         -hm     starting an overview ...
  12
  13
  14 Contents:
  15 ---------
  16         Functional block diagram
  17         Layer 1
  18         Layer 2
  19         Layer 3
  20         Debugging control
  21         Layer 4
  22         ISDN protocol trace
  23
  24
  25 Functional block diagram
  26 ========================
  27
  28  isdndebug                         isdnd                             isdntrace
  29  +-------+  +----------------------------------------------------+   +--------+
  30  |       |  |                                                    |   |        |
  31  |       |  |                                                    |   |        |
  32  +-------+  +----------------------------------------------------+   +--------+
  33      |                               |                                    |
  34      |                               |                                    |
  35      | /dev/i4bctl    Userland       | /dev/i4b            /dev/i4btrc<n> |
  36 ===============================================================================
  37      |                Kernel         |                                    |
  38      |                               |                                    |
  39  +-------+  +----------------------------------------------------+   +--------+
  40  |       |  |                                                    |   |        |
  41  |i4bctl |  |                       i4b                          |   | i4btrc |
  42  |  (6)  |  |                       (7)                          |   |   (8)  |
  43  | debug |  |     Layer 4 - common call control interface        |   |  ISDN  |
  44  |control|  |                                                    |   | trace  |
  45  +:-:-:--+  +----------------------------------------------------+   +--------+
  46   : : :          ^                                          ^              ^
  47   : : :     Call |           various ptr arrays             | Call         %
  48   . . .  Control |             in i4b_l3l4.h                | Control      %
  49                  V                                          V              %
  50  +----------------------+                       +----------------------+   %
  51  |                      |                       |                      |   %
  52  |       i4bq931        |                  ISDN |     active card      |   %
  53  |         (5)          |                   #####                      |   %
  54  |    Layer 3 (Q.931)   |                   #   |       driver         |   %
  55  |                      |                   #   |                      |   %
  56  +----------------------+                   #   +----------------------+   %
  57             ^                               #   B +                        %
  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>%
  71             V                               #     +                        %
  72  +----------------------+                   #   +---------------------+    %
  73  |                      |                   #   |                     |    %
  74  |    isic (ISAC part)  |  D-ch trace       #   |   isic (HSCX part)  |B-ch%
  75  |         (2)          |%%%%%%%%%%%%       #   |        (3)          |%%%%%
  76  |    Layer 1 (I.430)   |           %       #   |   non-HDLC / HDLC   |trc %
  77  |                      |           %       #   |                     |    %
  78  +----------------------+           %       #   +---------------------+    %
  79             ^                       %       #               ^              %
  80  D-channel  |                       %       #    B-channels |              %
  81             +-----------------------------------------------+              %
  82             |  function ptr in      %       #                              %
  83             |  in isic_softc in     %%%%%%%%#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  84             V  i4b_l1.h                     #
  85  +----------------------+                   #
  86  |                      |                   #
  87  |         isic         |                   #
  88  |         (1)          |                   #
  89  | Card hardware driver |                   #
  90  | for Teles, AVM, USR  |                   #
  91  |                      |                   #
  92  +----------#-----------+                   #
  93             #                               #
  94             #                               #
  95             #                               #
  96             #                               #
  97   |=========#===============================#============================|
  98         ISDN S0 bus
  99
 100
 101 Layer 1
 102 =======
 103
 104 (1) A driver for a special card hardware consists of a
 105         - probe routine
 106         - attach routine
 107         - FIFO read
 108         - FIFO write
 109         - register read
 110         - register write
 111    routines. These routines handle the card/manufacturer specific stuff
 112    required to talk to a particular card.
 113
 114    This addresses of the read/write routines are put into a arrays found
 115    in struct isic_softc and they are later called by the macros:
 116
 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)
 119
 120    (see file layer1/i4b_l1.h)
 121
 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
 130
 131
 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.
 134
 135     Files i4b_l1.c and i4b_l1.h handle stuff used to access layer 1
 136     functions from layer 2.
 137
 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
 143     beginning.
 144
 145     File i4b_isic.c contains the main code for the "isic" device driver.
 146
 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.
 149
 150
 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.
 158
 159
 160 Layer 2
 161 =======
 162
 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.
 167
 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.
 174
 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
 177     terminal equipment.
 178
 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.
 184
 185     i4b_l2timer.c implements the timers required by Q.921.
 186
 187     i4b_tei.c contains the TEI handling routines.
 188
 189     i4b_lme.c implements a rudimentary layer management entity.
 190
 191     i4b_util.c implements the many utility functions specified
 192     in Q.921 together wit some misc routines required for overall
 193     functionality.
 194
 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-
 197     where.
 198
 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.
 201
 202 Layer 3
 203 =======
 204
 205 (5) i4b_l2if.c and i4b_l4if.c contain the interface routines to communicate
 206     to layer 2 and layer 4 respectively.
 207
 208     i4b_l3timer.c implements the timers required by layer 3.
 209
 210     i4b_q931.c and i4b_q931.h implement the message and information element
 211     decoding of the Q.931 protocol.
 212
 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
 216     call.
 217
 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.
 220
 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 function
 230     pointer array (N_CONNECT_REQUEST, N_CONNECT_RESPONSE etc) at init time.
 231
 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.
 241
 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.
 248
 249 Debugging control
 250 =================
 251
 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 machine/i4b_debug.h and all parts of the kernel
 256     sources. It is only usable for passive cards.
 257
 258
 259 Layer 4
 260 =======
 261
 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.
 269
 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 machine/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.
 277
 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.
 281
 282     i4b_l4timer.c implements a timeout timer for Layer 4.
 283
 284
 285 ISDN protocol trace
 286 ===================
 287
 288 (8) ISDN D-channel protocol trace for layers 2 and 3 is possible by using
 289     hooks in the ISAC handling routines.
 290
 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.
 295
 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
 298     device.
 299
 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.
 303
 304     B-channel data is not interpreted but dumped as a hex-dump.
 305
 306
 307 /* EOF */