README for the ISDN-subsystem

1. Preface

  1.1 Introduction

  This README describes how to set up and how to use the different parts
  of the ISDN-subsystem.

  For using the ISDN-subsystem, some additional userlevel programs are
  necessary. Those programs and some contributed utilities are available
  at

   ftp.isdn4linux.de

   /pub/isdn4linux/isdn4k-utils-<VersionNumber>.tar.gz


  We also have set up a mailing-list:

   The isdn4linux-project originates in Germany, and therefore by historical
   reasons, the mailing-list's primary language is german. However mails
   written in english have been welcome all the time.

   to subscribe: write a email to majordomo@listserv.isdn4linux.de,
   Subject irrelevant, in the message body:
   subscribe isdn4linux <your_email_address>

   To write to the mailing-list, write to isdn4linux@listserv.isdn4linux.de

   This mailinglist is bidirectionally gated to the newsgroup

     de.alt.comm.isdn4linux

  There is also a well maintained FAQ in English available at
     http://www.mhessler.de/i4lfaq/
  It can be viewed online, or downloaded in sgml/text/html format.
  The FAQ can also be viewed online at
     http://www.isdn4inux.de/faq/
  or downloaded from
     ftp://ftp.isdn4linux.de/pub/isdn4linux/FAQ/

  1.1 Technical details

  In the following Text, the terms MSN and EAZ are used.

  MSN is the abbreviation for (M)ultiple(S)ubscriber(N)umber, and applies
  to Euro(EDSS1)-type lines. Usually it is simply the phone number.

  EAZ is the abbreviation of (E)ndgeraete(A)uswahl(Z)iffer and
  applies to German 1TR6-type lines. This is a one-digit string,
  simply appended to the base phone number

  The internal handling is nearly identical, so replace the appropriate
  term to that one, which applies to your local ISDN-environment.

  When the link-level-module isdn.o is loaded, it supports up to 16
  low-level-modules with up to 64 channels. (The number 64 is arbitrarily
  chosen and can be configured at compile-time --ISDN_MAX in isdn.h).
  A low-level-driver can register itself through an interface (which is
  defined in isdnif.h) and gets assigned a slot.
  The following char-devices are made available for each channel:

  A raw-control-device with the following functions:
     write: raw D-channel-messages (format: depends on driver).
     read:  raw D-channel-messages (format: depends on driver).
     ioctl: depends on driver, i.e. for the ICN-driver, the base-address of
            the ports and the shared memory on the card can be set and read
            also the boot-code and the protocol software can be loaded into
            the card.

   O N L Y !!!  for debugging (no locking against other devices):
   One raw-data-device with the following functions:
     write: data to B-channel.
     read:  data from B-channel.

   In addition the following devices are made available:

   128 tty-devices (64 cuix and 64 ttyIx) with integrated modem-emulator:
   The functionality is almost the same as that of a serial device
   (the line-discs are handled by the kernel), which lets you run
   SLIP, CSLIP and asynchronous PPP through the devices. We have tested
   Seyon, minicom, CSLIP (uri-dip) PPP, mgetty, XCept and Hylafax.

   The modem-emulation supports the following:
           1.3.1 Commands:

               ATA      Answer incoming call.
               ATD<No.> Dial, the number may contain:
                        [0-9] and [,#.*WPT-S]
                        the latter are ignored until 'S'.
                        The 'S' must precede the number, if
                        the line is a SPV (German 1TR6).
               ATE0     Echo off.
               ATE1     Echo on (default).
               ATH      Hang-up.
               ATH1     Off hook (ignored).
               ATH0     Hang-up.
               ATI      Return "ISDN for Linux...".
               ATI0        "
               ATI1        "
               ATI2     Report of last connection.
               ATO      On line (data mode).
               ATQ0     Enable result codes (default).
               ATQ1     Disable result codes (default).
               ATSx=y   Set register x to y.
               ATSx?    Show contents of register x.
               ATV0     Numeric responses.
               ATV1     English responses (default).
               ATZ      Load registers and EAZ/MSN from Profile.
               AT&Bx    Set Send-Packet-size to x (max. 4000)
                        The real packet-size may be limited by the
                        low-level-driver used. e.g. the HiSax-Module-
                        limit is 2000. You will get NO Error-Message,
                        if you set it to higher values, because at the
                        time of giving this command the corresponding
                        driver may not be selected (see "Automatic
                        Assignment") however the size of outgoing packets
                        will be limited correctly.
               AT&D0    Ignore DTR
               AT&D2    DTR-low-edge: Hang up and return to
                        command mode (default).
               AT&D3    Same as AT&D2 but also resets all registers.
               AT&Ex    Set the EAZ/MSN for this channel to x.
               AT&F     Reset all registers and profile to "factory-defaults"
               AT&Lx    Set list of phone numbers to listen on.  x is a
                        list of wildcard patterns separated by semicolon.
                        If this is set, it has precedence over the MSN set
                        by AT&E.
               AT&Rx    Select V.110 bitrate adaption.
                        This command enables V.110 protocol with 9600 baud
                        (x=9600), 19200 baud (x=19200) or 38400 baud
                        (x=38400). A value of x=0 disables V.110 switching
                        back to default X.75. This command sets the following
                        Registers:
                          Reg 14 (Layer-2 protocol):
                            x = 0:     0
                            x = 9600:  7
                            x = 19200: 8
                            x = 38400: 9
                          Reg 18.2 = 1
                          Reg 19 (Additional Service Indicator):
                            x = 0:       0
                            x = 9600:  197
                            x = 19200: 199
                            x = 38400: 198
                          Note on value in Reg 19:
                            There is _NO_ common convention for 38400 baud.
                            The value 198 is chosen arbitrarily. Users
                            _MUST_ negotiate this value before establishing
                            a connection.
               AT&Sx    Set window-size (x = 1..8) (not yet implemented)
               AT&V     Show all settings.
               AT&W0    Write registers and EAZ/MSN to profile. See also
                        iprofd (5.c in this README).
               AT&X0    BTX-mode and T.70-mode off (default)
               AT&X1    BTX-mode on. (S13.1=1, S13.5=0 S14=0, S16=7, S18=7, S19=0)
               AT&X2    T.70-mode on. (S13.1=1, S13.5=1, S14=0, S16=7, S18=7, S19=0)
               AT+Rx    Resume a suspended call with CallID x (x = 1,2,3...)
               AT+Sx    Suspend a call with CallID x (x = 1,2,3...)

           For voice-mode commands refer to README.audio

           1.3.2 Escape sequence:
               During a connection, the emulation reacts just like
               a normal modem to the escape sequence <DELAY>+++<DELAY>.
               (The escape character - default '+' - can be set in the
               register 2).
               The DELAY must at least be 1.5 seconds long and delay
               between the escape characters must not exceed 0.5 seconds.

           1.3.3 Registers:

              Nr.  Default  Description
              0    0        Answer on ring number.
                            (no auto-answer if S0=0).
              1    0        Count of rings.
              2    43       Escape character.
                            (a value >= 128 disables the escape sequence).
              3    13       Carriage return character (ASCII).
              4    10       Line feed character (ASCII).
              5    8        Backspace character (ASCII).
              6    3        Delay in seconds before dialing.
              7    60       Wait for carrier.
              8    2        Pause time for comma (ignored)
              9    6        Carrier detect time (ignored)
             10    7        Carrier loss to disconnect time (ignored).
             11    70       Touch tone timing (ignored).
             12    69       Bit coded register:
                            Bit 0:    0 = Suppress response messages.
                                      1 = Show response messages.
                            Bit 1:    0 = English response messages.
                                      1 = Numeric response messages.
                            Bit 2:    0 = Echo off.
                                      1 = Echo on.
                            Bit 3     0 = DCD always on.
                                      1 = DCD follows carrier.
                            Bit 4     0 = CTS follows RTS
                                      1 = Ignore RTS, CTS always on.
                            Bit 5     0 = return to command mode on DTR low.
                                      1 = Same as 0 but also resets all
                                          registers.
                                      See also register 13, bit 2
                            Bit 6     0 = DSR always on.
                                      1 = DSR only on if channel is available.
                            Bit 7     0 = Cisco-PPP-flag-hack off (default).
                                      1 = Cisco-PPP-flag-hack on.
             13   0         Bit coded register:
                            Bit 0:    0 = Use delayed tty-send-algorithm
                                      1 = Direct tty-send.
                            Bit 1:    0 = T.70 protocol (Only for BTX!) off
                                      1 = T.70 protocol (Only for BTX!) on
                            Bit 2:    0 = Don't hangup on DTR low.
                                      1 = Hangup on DTR low.
                            Bit 3:    0 = Standard response messages
                                      1 = Extended response messages
                            Bit 4:    0 = CALLER NUMBER before every RING.
                                      1 = CALLER NUMBER after first RING.
                            Bit 5:    0 = T.70 extended protocol off
                                      1 = T.70 extended protocol on
                            Bit 6:    0 = Special RUNG Message off
                                      1 = Special RUNG Message on
                                          "RUNG" is delivered on a ttyI, if
                                          an incoming call happened (RING) and
                                          the remote party hung up before any
                                          local ATA was given.
			    Bit 7:    0 = Don't show display messages from net
                                      1 = Show display messages from net
				          (S12 Bit 1 must be 0 too)
             14   0         Layer-2 protocol:
                                      0 = X75/LAPB with I-frames
                                      1 = X75/LAPB with UI-frames
                                      2 = X75/LAPB with BUI-frames
                                      3 = HDLC
                                      4 = Transparent (audio)
                                      7 = V.110, 9600 baud
                                      8 = V.110, 19200 baud
                                      9 = V.110, 38400 baud
                                     10 = Analog Modem (only if hardware supports this)
                                     11 = Fax G3 (only if hardware supports this)
             15   0         Layer-3 protocol:
                                      0 = transparent
                                      1 = transparent with audio features (e.g. DSP)
                                      2 = Fax G3 Class 2 commands (S14 has to be set to 11)
                                      3 = Fax G3 Class 1 commands (S14 has to be set to 11)
             16   250       Send-Packet-size/16
             17   8         Window-size (not yet implemented)
             18   4         Bit coded register, Service-Octet-1 to accept,
                            or to be used on dialout:
                            Bit 0:    Service 1 (audio) when set.
                            Bit 1:    Service 5 (BTX) when set.
                            Bit 2:    Service 7 (data) when set.
                            Note: It is possible to set more than one
                                  bit. In this case, on incoming calls
                                  the selected services are accepted,
                                  and if the service is "audio", the
                                  Layer-2-protocol is automatically
                                  changed to 4 regardless of the setting
                                  of register 14. On outgoing calls,
                                  the most significant 1-bit is chosen to
                                  select the outgoing service octet.
             19   0         Service-Octet-2
             20   0         Bit coded register (readonly)
                            Service-Octet-1 of last call.
                            Bit mapping is the same as register 18
             21   0         Bit coded register (readonly)
                            Set on incoming call (during RING) to
                            octet 3 of calling party number IE (Numbering plan)
                            See section 4.5.10 of ITU Q.931
             22   0         Bit coded register (readonly)
                            Set on incoming call (during RING) to
                            octet 3a of calling party number IE (Screening info)
                            See section 4.5.10 of ITU Q.931
             23   0         Bit coded register:
                            Bit 0:    0 = Add CPN to RING message off
                                      1 = Add CPN to RING message on
                            Bit 1:    0 = Add CPN to FCON message off
                                      1 = Add CPN to FCON message on
                            Bit 2:    0 = Add CDN to RING/FCON message off
                                      1 = Add CDN to RING/FCON message on

  Last but not least a (at the moment fairly primitive) device to request
  the line-status (/dev/isdninfo) is made available.

  Automatic assignment of devices to lines:

  All inactive physical lines are listening to all EAZs for incoming
  calls and are NOT assigned to a specific tty or network interface.
  When an incoming call is detected, the driver looks first for a network
  interface and then for an opened tty which:

  1. is configured for the same EAZ.
  2. has the same protocol settings for the B-channel.
  3. (only for network interfaces if the security flag is set)
     contains the caller number in its access list.
  4. Either the channel is not bound exclusively to another Net-interface, or
     it is bound AND the other checks apply to exactly this interface.
     (For usage of the bind-features, refer to the isdnctrl-man-page)

  Only when a matching interface or tty is found is the call accepted
  and the "connection" between the low-level-layer and the link-level-layer
  is established and kept until the end of the connection.
  In all other cases no connection is established. Isdn4linux can be
  configured to either do NOTHING in this case (which is useful, if
  other, external devices with the same EAZ/MSN are connected to the bus)
  or to reject the call actively. (isdnctrl busreject ...)

  For an outgoing call, the inactive physical lines are searched.
  The call is placed on the first physical line, which supports the
  requested protocols for the B-channel. If a net-interface, however
  is pre-bound to a channel, this channel is used directly.

  This makes it possible to configure several network interfaces and ttys
  for one EAZ, if the network interfaces are set to secure operation.
  If an incoming call matches one network interface, it gets connected to it.
  If another incoming call for the same EAZ arrives, which does not match
  a network interface, the first tty gets a "RING" and so on.

2 System prerequisites:

  ATTENTION!

  Always use the latest module utilities. The current version is
  named in Documentation/Changes. Some old versions of insmod
  are not capable of setting the driver-Ids correctly.

3. Lowlevel-driver configuration.

   Configuration depends on how the drivers are built. See the
   README.<yourDriver> for information on driver-specific setup.

4. Device-inodes

   The major and minor numbers and their names are described in
   Documentation/devices.txt. The major numbers are:

     43 for the ISDN-tty's.
     44 for the ISDN-callout-tty's.
     45 for control/info/debug devices.

5. Application

   a) For some card-types, firmware has to be loaded into the cards, before
      proceeding with device-independent setup. See README.<yourDriver>
      for how to do that.

   b) If you only intend to use ttys, you are nearly ready now.

   c) If you want to have really permanent "Modem"-settings on disk, you
      can start the daemon iprofd. Give it a path to a file at the command-
      line. It will store the profile-settings in this file every time
      an AT&W0 is performed on any ISDN-tty. If the file already exists,
      all profiles are initialized from this file. If you want to unload
      any of the modules, kill iprofd first.

   d) For networking, continue: Create an interface:
       isdnctrl addif isdn0

   e) Set the EAZ (or MSN for Euro-ISDN):
       isdnctrl eaz isdn0 2

     (For 1TR6 a single digit is allowed, for Euro-ISDN the number is your
      real MSN e.g.: Phone-Number)

   f) Set the number for outgoing calls on the interface:
       isdnctrl addphone isdn0 out 1234567
       ... (this can be executed more than once, all assigned numbers are
            tried in order)
      and the number(s) for incoming calls:
       isdnctrl addphone isdn0 in 1234567

   g) Set the timeout for hang-up:
       isdnctrl huptimeout isdn0 <timeout_in_seconds>

   h) additionally you may activate charge-hang-up (= Hang up before
      next charge-info, this only works, if your isdn-provider transmits
      the charge-info during and after the connection):
       isdnctrl chargehup isdn0 on

   i) Set the dial mode of the interface:
       isdnctrl dialmode isdn0 auto
      "off" means that you (or the system) cannot make any connection
        (neither incoming or outgoing connections are possible). Use
        this if you want to be sure that no connections will be made.
      "auto" means that the interface is in auto-dial mode, and will
        attempt to make a connection whenever a network data packet needs
        the interface's link. Note that this can cause unexpected dialouts,
        and lead to a high phone bill! Some daemons or other pc's that use
        this interface can cause this.
        Incoming connections are also possible.
      "manual" is a dial mode created to prevent the unexpected dialouts.
        In this mode, the interface will never make any connections on its
        own. You must explicitly initiate a connection with "isdnctrl dial
        isdn0". However, after an idle time of no traffic as configured for
	the huptimeout value with isdnctrl, the connection _will_ be ended.
	If you don't want any automatic hangup, set the huptimeout value to 0.
        "manual" is the default.

   j) Setup the interface with ifconfig as usual, and set a route to it.

   k) (optional) If you run X11 and have Tcl/Tk-wish version 4.0, you can use
     the script tools/tcltk/isdnmon. You can add actions for line-status
     changes. See the comments at the beginning of the script for how to
     do that. There are other tty-based tools in the tools-subdirectory
     contributed by Michael Knigge (imon), Volker G�tz (imontty) and
     Andreas Kool (isdnmon).

   l) For initial testing, you can set the verbose-level to 2 (default: 0).
      Then all incoming calls are logged, even if they are not addressed
      to one of the configured net-interfaces:
      isdnctrl verbose 2

  Now you are ready! A ping to the set address should now result in an
  automatic dial-out (look at syslog kernel-messages).
  The phone numbers and EAZs can be assigned at any time with isdnctrl.
  You can add as many interfaces as you like with addif following the
  directions above. Of course, there may be some limitations. But we have
  tested as many as 20 interfaces without any problem. However, if you
  don't give an interface name to addif, the  kernel will assign a name
  which starts with "eth". The number of "eth"-interfaces is limited by
  the kernel.

5. Additional options for isdnctrl:

   "isdnctrl secure <InterfaceName> on"
   Only incoming calls, for which the caller-id is listed in the access
   list of the interface are accepted. You can add caller-id's With the
   command "isdnctrl addphone <InterfaceName> in <caller-id>"
   Euro-ISDN does not transmit the leading '0' of the caller-id for an
   incoming call, therefore you should configure it accordingly.
   If the real number for the dialout e.g. is "09311234567" the number
   to configure here is "9311234567". The pattern-match function
   works similar to the shell mechanism.

     ?     one arbitrary digit
     *     zero or arbitrary many digits
     [123] one of the digits in the list
     [1-5] one digit between '1' and '5'
           a '^' as the first character in a list inverts the list


   "isdnctrl secure <InterfaceName> off"
   Switch off secure operation (default).

   "isdnctrl ihup <InterfaceName> [on|off]"
   Switch the hang-up-timer for incoming calls on or off.

   "isdnctrl eaz <InterfaceName>"
   Returns the EAZ of an interface.

   "isdnctrl delphone <InterfaceName> in|out <number>"
   Deletes a number from one of the access-lists of the interface.

   "isdnctrl delif <InterfaceName>"
   Removes the interface (and possible slaves) from the kernel.
   (You have to unregister it with "ifconfig <InterfaceName> down" before).

   "isdnctrl callback <InterfaceName> [on|off]"
   Switches an interface to callback-mode. In this mode, an incoming call
   will be rejected and after this the remote-station will be called. If
   you test this feature by using ping, some routers will re-dial very
   quickly, so that the callback from isdn4linux may not be recognized.
   In this case use ping with the option -i <sec> to increase the interval
   between echo-packets.

   "isdnctrl cbdelay <InterfaceName> [seconds]"
   Sets the delay (default 5 sec) between an incoming call and start of
   dialing when callback is enabled.

   "isdnctrl cbhup <InterfaceName> [on|off]"
   This enables (default) or disables an active hangup (reject) when getting an
   incoming call for an interface which is configured for callback.

   "isdnctrl encap <InterfaceName> <EncapType>"
   Selects the type of packet-encapsulation. The encapsulation can be changed
   only while an interface is down.

   At the moment the following values are supported:

   rawip    (Default) Selects raw-IP-encapsulation. This means, MAC-headers
            are stripped off.
   ip       IP with type-field. Same as IP but the type-field of the MAC-header
            is preserved.
   x25iface X.25 interface encapsulation (first byte semantics as defined in
            ../networking/x25-iface.txt). Use this for running the linux
            X.25 network protocol stack (AF_X25 sockets) on top of isdn.
   cisco-h  A special-mode for communicating with a Cisco, which is configured
            to do "hdlc"
   ethernet No stripping. Packets are sent with full MAC-header.
            The Ethernet-address of the interface is faked, from its
            IP-address: fc:fc:i1:i2:i3:i4, where i1-4 are the IP-addr.-values.
   syncppp  Synchronous PPP

   uihdlc   HDLC with UI-frame-header (for use with DOS ISPA, option -h1)


   NOTE:    x25iface encapsulation is currently experimental. Please
            read README.x25 for further details


   Watching packets, using standard-tcpdump will fail for all encapsulations
   except ethernet because tcpdump does not know how to handle packets
   without MAC-header. A patch for tcpdump is included in the utility-package
   mentioned above.

   "isdnctrl l2_prot <InterfaceName> <L2-ProtocolName>"
   Selects a layer-2-protocol.
   (With the ICN-driver and the HiSax-driver, "x75i" and "hdlc" is available.
   With other drivers, "x75ui", "x75bui", "x25dte", "x25dce" may be
   possible too. See README.x25 for x25 related l2 protocols.)

   isdnctrl l3_prot <InterfaceName> <L3-ProtocolName>
   The same for layer-3. (At the moment only "trans" is allowed)

   "isdnctrl list <InterfaceName>"
   Shows all parameters of an interface and the charge-info.
   Try "all" as the interface name.

   "isdnctrl hangup <InterfaceName>"
   Forces hangup of an interface.

   "isdnctrl bind <InterfaceName> <DriverId>,<ChannelNumber> [exclusive]"
   If you are using more than one ISDN card, it is sometimes necessary to
   dial out using a specific card or even preserve a specific channel for
   dialout of a specific net-interface. This can be done with the above
   command. Replace <DriverId> by whatever you assigned while loading the
   module. The <ChannelNumber> is counted from zero. The upper limit
   depends on the card used. At the moment no card supports more than
   2 channels, so the upper limit is one.

   "isdnctrl unbind <InterfaceName>"
   unbinds a previously bound interface.

   "isdnctrl busreject <DriverId> on|off"
   If switched on, isdn4linux replies a REJECT to incoming calls, it
   cannot match to any configured interface.
   If switched off, nothing happens in this case.
   You normally should NOT enable this feature, if the ISDN adapter is not
   the only device connected to the S0-bus. Otherwise it could happen that
   isdn4linux rejects an incoming call, which belongs to another device on
   the bus.

   "isdnctrl addslave <InterfaceName> <SlaveName>
   Creates a slave interface for channel-bundling. Slave interfaces are
   not seen by the kernel, but their ISDN-part can be configured with
   isdnctrl as usual. (Phone numbers, EAZ/MSN, timeouts etc.) If more
   than two channels are to be bundled, feel free to create as many as you
   want. InterfaceName must be a real interface, NOT a slave. Slave interfaces
   start dialing, if the master interface resp. the previous slave interface
   has a load of more than 7000 cps. They hangup if the load goes under 7000
   cps, according to their "huptimeout"-parameter.

   "isdnctrl sdelay <InterfaceName> secs."
   This sets the minimum time an Interface has to be fully loaded, until
   it sends a dial-request to its slave.

   "isdnctrl dial <InterfaceName>"
   Forces an interface to start dialing even if no packets are to be
   transferred.

   "isdnctrl mapping <DriverId> MSN0,MSN1,MSN2,...MSN9"
   This installs a mapping table for EAZ<->MSN-mapping for a single line.
   Missing MSN's have to be given as "-" or can be omitted, if at the end
   of the commandline.
   With this command, it's now possible to have an interface listening to
   mixed 1TR6- and Euro-Type lines. In this case, the interface has to be
   configured to a 1TR6-type EAZ (one digit). The mapping is also valid
   for tty-emulation. Seen from the interface/tty-level the mapping
   CAN be used, however it's possible to use single tty's/interfaces with
   real MSN's (more digits) also, in which case the mapping will be ignored.
   Here is an example:

   You have a 1TR6-type line with base-nr. 1234567 and a Euro-line with
   MSN's 987654, 987655 and 987656. The DriverId for the Euro-line is "EURO".

   isdnctrl mapping EURO -,987654,987655,987656,-,987655
   ...
   isdnctrl eaz isdn0 1      # listen on 12345671(1tr6) and 987654(euro)
   ...
   isdnctrl eaz isdn1 4      # listen on 12345674(1tr6) only.
   ...
   isdnctrl eaz isdn2 987654 # listen on 987654(euro) only.

   Same scheme is used with AT&E...  at the tty's.

6. If you want to write a new low-level-driver, you are welcome.
   The interface to the link-level-module is described in the file INTERFACE.
   If the interface should be expanded for any reason, don't do it
   on your own, send me a mail containing the proposed changes and
   some reasoning about them.
   If other drivers will not be affected, I will include the changes
   in the next release.
   For developers only, there is a second mailing-list. Write to me
   (fritz@isdn4linux.de), if you want to join that list.

Have fun!

 -Fritz

The FAQ for isdn4linux
======================

Please note that there is a big FAQ available in the isdn4k-utils.
You find it in:
 isdn4k-utils/FAQ/i4lfaq.sgml

In case you just want to see the FAQ online, or download the newest version,
you can have a look at my website:
http://www.mhessler.de/i4lfaq/ (view + download)
or:
http://www.isdn4linux.de/faq/ (view)

As the extension tells, the FAQ is in SGML format, and you can convert it
into text/html/... format by using the sgml2txt/sgml2html/... tools.
Alternatively, you can also do a 'configure; make all' in the FAQ directory.


Please have a look at the FAQ before posting anything in the Mailinglist,
or the newsgroup!


Matthias Hessler
hessler@isdn4linux.de

HiSax is a Linux hardware-level driver for passive ISDN cards with Siemens
chipset (ISAC_S 2085/2086/2186, HSCX SAB 82525). It is based on the Teles
driver from Jan den Ouden.
It is meant to be used with isdn4linux, an ISDN link-level module for Linux
written by Fritz Elfert.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


Supported cards
---------------

Teles 8.0/16.0/16.3 and compatible ones
Teles 16.3c
Teles S0/PCMCIA
Teles PCI
Teles S0Box
Creatix S0Box
Creatix PnP S0
Compaq ISDN S0 ISA card
AVM A1 (Fritz, Teledat 150)
AVM Fritz PCMCIA
AVM Fritz PnP
AVM Fritz PCI
ELSA Microlink PCC-16, PCF, PCF-Pro, PCC-8
ELSA Quickstep 1000
ELSA Quickstep 1000PCI
ELSA Quickstep 3000 (same settings as QS1000)
ELSA Quickstep 3000PCI
ELSA PCMCIA
ITK ix1-micro Rev.2
Eicon Diva 2.0 ISA and PCI (S0 and U interface, no PRO version)
Eicon Diva 2.01 ISA and PCI
Eicon Diva 2.02 PCI
Eicon Diva Piccola
ASUSCOM NETWORK INC. ISDNLink 128K PC adapter (order code I-IN100-ST-D)
Dynalink IS64PH (OEM version of ASUSCOM NETWORK INC. ISDNLink 128K adapter)
PCBIT-DP (OEM version of ASUSCOM NETWORK INC. ISDNLink)
HFC-2BS0 based cards (TeleInt SA1)
Sedlbauer Speed Card (Speed Win, Teledat 100, PCI, Fax+)
Sedlbauer Speed Star/Speed Star2 (PCMCIA)
Sedlbauer ISDN-Controller PC/104
USR Sportster internal TA (compatible Stollmann tina-pp V3)
USR internal TA PCI
ith Kommunikationstechnik GmbH MIC 16 ISA card
Traverse Technologie NETjet PCI S0 card and NETspider U card
Ovislink ISDN sc100-p card (NETjet driver)
Dr. Neuhaus Niccy PnP/PCI
Siemens I-Surf 1.0
Siemens I-Surf 2.0 (with IPAC, try type 12 asuscom)
ACER P10
HST Saphir
Berkom Telekom A4T
Scitel Quadro
Gazel ISDN cards
HFC-PCI based cards
Winbond W6692 based cards
HFC-S+, HFC-SP/PCMCIA cards
formula-n enternow
Gerdes Power ISDN

Note: PCF, PCF-Pro: up to now, only the ISDN part is supported
      PCC-8: not tested yet
      Eicon.Diehl Diva U interface not tested

If you know other passive cards with the Siemens chipset, please let me know.
You can combine any card, if there is no conflict between the resources
(io, mem, irq).


Configuring the driver
----------------------

The HiSax driver can either be built directly into the kernel or as a module.
It can be configured using the command line feature while loading the kernel
with LILO or LOADLIN or, if built as a module, using insmod/modprobe with
parameters.
There is also some config needed before you compile the kernel and/or
modules. It is included in the normal "make [menu]config" target at the
kernel. Don't forget it, especially to select the right D-channel protocol.

Please note: In older versions of the HiSax driver, all PnP cards
needed to be configured with isapnp and worked only with the HiSax
driver used as a module.

In the current version, HiSax will automatically use the in-kernel
ISAPnP support, provided you selected it during kernel configuration
(CONFIG_ISAPNP), if you don't give the io=, irq= command line parameters.

The affected card types are: 4,7,12,14,19,27-30

a) when built as a module
-------------------------

insmod/modprobe  hisax.o \
  io=iobase irq=IRQ mem=membase type=card_type \
  protocol=D_channel_protocol id=idstring

or, if several cards are installed:

insmod/modprobe hisax.o \
  io=iobase1,iobase2,... irq=IRQ1,IRQ2,... mem=membase1,membase2,... \
  type=card_type1,card_type2,... \
  protocol=D_channel_protocol1,D_channel_protocol2,... \
  id=idstring1%idstring2 ...

where "iobaseN" represents the I/O base address of the Nth card, "membaseN"
the memory base address of the Nth card, etc.

The reason for the delimiter "%" being used in the idstrings is that ","
won't work with the current modules package.

The parameters may be specified in any order. For example, the "io"
parameter may precede the "irq" parameter, or vice versa. If several
cards are installed, the ordering within the comma separated parameter
lists must of course be consistent.

Only parameters applicable to the card type need to be specified. For
example, the Teles 16.3 card is not memory-mapped, so the "mem"
parameter may be omitted for this card. Sometimes it may be necessary
to specify a dummy parameter, however. This is the case when there is
a card of a different type later in the list that needs a parameter
which the preceding card does not. For instance, if a Teles 16.0 card
is listed after a Teles 16.3 card, a dummy memory base parameter of 0
must be specified for the 16.3. Instead of a dummy value, the parameter
can also be skipped by simply omitting the value. For example:
mem=,0xd0000. See example 6 below.

The parameter for the D-Channel protocol may be omitted if you selected the
correct one during kernel config. Valid values are "1" for German 1TR6,
"2" for EDSS1 (Euro ISDN), "3" for leased lines (no D-Channel) and "4"
for US NI1.
With US NI1 you have to include your SPID into the MSN setting in the form
<MSN>:<SPID> for example (your phonenumber is 1234 your SPID 5678):
AT&E1234:5678                       on ttyI interfaces
isdnctrl eaz ippp0 1234:5678        on network devices

The Creatix/Teles PnP cards use io1= and io2= instead of io= for specifying
the I/O addresses of the ISAC and HSCX chips, respectively.

Card types:

    Type                Required parameters (in addition to type and protocol)

    1   Teles 16.0               irq, mem, io
    2   Teles  8.0               irq, mem
    3   Teles 16.3 (non PnP)     irq, io
    4   Creatix/Teles PnP        irq, io0 (ISAC), io1 (HSCX)
    5   AVM A1 (Fritz)           irq, io
    6   ELSA PCC/PCF cards       io or nothing for autodetect (the iobase is
                                 required only if you have more than one ELSA
                                 card in your PC)
    7   ELSA Quickstep 1000      irq, io  (from isapnp setup)
    8   Teles 16.3 PCMCIA     	 irq, io
    9   ITK ix1-micro Rev.2      irq, io
   10   ELSA PCMCIA		 irq, io  (set with card manager)
   11   Eicon.Diehl Diva ISA PnP irq, io
   11   Eicon.Diehl Diva PCI     no parameter
   12   ASUS COM ISDNLink        irq, io  (from isapnp setup)
   13   HFC-2BS0 based cards     irq, io
   14   Teles 16.3c PnP          irq, io
   15   Sedlbauer Speed Card     irq, io
   15   Sedlbauer PC/104         irq, io
   15   Sedlbauer Speed PCI	 no parameter
   16   USR Sportster internal   irq, io
   17   MIC card                 irq, io
   18   ELSA Quickstep 1000PCI   no parameter
   19   Compaq ISDN S0 ISA card  irq, io0, io1, io (from isapnp setup io=IO2)
   20   NETjet PCI card          no parameter
   21   Teles PCI                no parameter
   22   Sedlbauer Speed Star (PCMCIA) irq, io (set with card manager)
   24   Dr. Neuhaus Niccy PnP    irq, io0, io1 (from isapnp setup)
   24   Dr. Neuhaus Niccy PCI    no parameter
   25   Teles S0Box              irq, io (of the used lpt port)
   26   AVM A1 PCMCIA (Fritz!)   irq, io (set with card manager)
   27   AVM PnP (Fritz!PnP)      irq, io  (from isapnp setup)
   27   AVM PCI (Fritz!PCI)      no parameter
   28   Sedlbauer Speed Fax+     irq, io (from isapnp setup)
   29	Siemens I-Surf 1.0       irq, io, memory (from isapnp setup)
   30	ACER P10                 irq, io (from isapnp setup)
   31	HST Saphir               irq, io
   32	Telekom A4T              none
   33	Scitel Quadro		 subcontroller (4*S0, subctrl 1...4)
   34	Gazel ISDN cards (ISA)   irq,io
   34	Gazel ISDN cards (PCI)   none
   35	HFC 2BDS0 PCI            none
   36	W6692 based PCI cards    none
   37	HFC 2BDS0 S+, SP         irq,io
   38	NETspider U PCI card     none
   39	HFC 2BDS0 SP/PCMCIA      irq,io (set with cardmgr)
   40   hotplug interface
   41   Formula-n enter:now PCI  none

At the moment IRQ sharing is only possible with PCI cards. Please make sure
that your IRQ is free and enabled for ISA use.


Examples for module loading

1. Teles 16.3, Euro ISDN, I/O base 280 hex, IRQ 10
   modprobe hisax type=3 protocol=2 io=0x280 irq=10

2. Teles 16.0, 1TR6 ISDN, I/O base d80 hex, IRQ 5, Memory d0000 hex
   modprobe hisax protocol=1 type=1 io=0xd80 mem=0xd0000 irq=5

3. Fritzcard, Euro ISDN, I/O base 340 hex, IRQ 10 and ELSA PCF, Euro ISDN
   modprobe hisax type=5,6 protocol=2,2 io=0x340 irq=10 id=Fritz%Elsa

4. Any ELSA PCC/PCF card, Euro ISDN
   modprobe hisax type=6 protocol=2

5. Teles 16.3 PnP, Euro ISDN, with isapnp configured
   isapnp config:  (INT 0 (IRQ 10 (MODE +E)))
 		   (IO 0 (BASE 0x0580))
                   (IO 1 (BASE 0x0180))
   modprobe hisax type=4 protocol=2 irq=10 io0=0x580 io1=0x180

   In the current version of HiSax, you can instead simply use

   modprobe hisax type=4 protocol=2

   if you configured your kernel for ISAPnP. Don't run isapnp in
   this case!

6. Teles 16.3, Euro ISDN, I/O base 280 hex, IRQ 12 and
   Teles 16.0, 1TR6, IRQ 5, Memory d0000 hex
   modprobe hisax type=3,1 protocol=2,1 io=0x280 mem=0,0xd0000

   Please note the dummy 0 memory address for the Teles 16.3, used as a
   placeholder as described above, in the last example.

7. Teles PCMCIA, Euro ISDN, I/O base 180 hex, IRQ 15 (default values)
   modprobe hisax type=8 protocol=2 io=0x180 irq=15


b) using LILO/LOADLIN, with the driver compiled directly into the kernel
------------------------------------------------------------------------

hisax=typ1,dp1,pa_1,pb_1,pc_1[,typ2,dp2,pa_2 ... \
      typn,dpn,pa_n,pb_n,pc_n][,idstring1[,idstring2,...,idstringn]]

where
     typ1 = type of 1st card (default depends on kernel settings)
     dp1  = D-Channel protocol of 1st card. 1=1TR6, 2=EDSS1, 3=leased
     pa_1 = 1st parameter (depending on the type of the card)
     pb_1 = 2nd parameter (    "     "   "   "   "   "   "  )
     pc_1 = 3rd parameter (    "     "   "   "   "   "   "  )

     typ2,dp2,pa_2,pb_2,pc_2 = Parameters of the second card (defaults: none)
     typn,dpn,pa_n,pb_n,pc_n = Parameters of the n'th card (up to 16 cards are
                                                                     supported)

     idstring = Driver ID for accessing the particular card with utility
                programs and for identification when using a line monitor
                (default: "HiSax")

                Note: the ID string must start with an alphabetical character!

Card types:

type
    1 	Teles 16.0     	        pa=irq  pb=membase  pc=iobase
    2 	Teles  8.0              pa=irq  pb=membase
    3 	Teles 16.3              pa=irq  pb=iobase
    4 	Creatix/Teles PNP     	ONLY WORKS AS A MODULE !
    5 	AVM A1 (Fritz)          pa=irq  pb=iobase
    6 	ELSA PCC/PCF cards      pa=iobase or nothing for autodetect
    7   ELSA Quickstep 1000     ONLY WORKS AS A MODULE !
    8   Teles S0 PCMCIA         pa=irq  pb=iobase
    9   ITK ix1-micro Rev.2     pa=irq  pb=iobase
   10   ELSA PCMCIA             pa=irq, pb=io  (set with card manager)
   11   Eicon.Diehl Diva ISAPnP ONLY WORKS AS A MODULE !
   11   Eicon.Diehl Diva PCI    no parameter
   12   ASUS COM ISDNLink       ONLY WORKS AS A MODULE !
   13	HFC-2BS0 based cards    pa=irq  pb=io
   14   Teles 16.3c PnP         ONLY WORKS AS A MODULE !
   15	Sedlbauer Speed Card    pa=irq  pb=io (Speed Win only as module !)
   15   Sedlbauer PC/104        pa=irq  pb=io
   15   Sedlbauer Speed PCI	no parameter
   16   USR Sportster internal  pa=irq  pb=io
   17   MIC card                pa=irq  pb=io
   18   ELSA Quickstep 1000PCI  no parameter
   19   Compaq ISDN S0 ISA card ONLY WORKS AS A MODULE !
   20   NETjet PCI card         no parameter
   21   Teles PCI               no parameter
   22   Sedlbauer Speed Star (PCMCIA)  pa=irq, pb=io  (set with card manager)
   24   Dr. Neuhaus Niccy PnP   ONLY WORKS AS A MODULE !
   24   Dr. Neuhaus Niccy PCI   no parameter
   25   Teles S0Box             pa=irq, pb=io (of the used lpt port)
   26   AVM A1 PCMCIA (Fritz!)  pa=irq, pb=io (set with card manager)
   27   AVM PnP (Fritz!PnP)     ONLY WORKS AS A MODULE !
   27   AVM PCI (Fritz!PCI)     no parameter
   28   Sedlbauer Speed Fax+    ONLY WORKS AS A MODULE !
   29	Siemens I-Surf 1.0      ONLY WORKS AS A MODULE !
   30	ACER P10                ONLY WORKS AS A MODULE !
   31	HST Saphir              pa=irq, pb=io
   32	Telekom A4T             no parameter
   33	Scitel Quadro		subcontroller (4*S0, subctrl 1...4)
   34	Gazel ISDN cards (ISA)  pa=irq, pb=io
   34	Gazel ISDN cards (PCI)  no parameter
   35	HFC 2BDS0 PCI           no parameter
   36	W6692 based PCI cards   none
   37	HFC 2BDS0 S+,SP/PCMCIA  ONLY WORKS AS A MODULE !
   38	NETspider U PCI card    none
   39	HFC 2BDS0 SP/PCMCIA     ONLY WORKS AS A MODULE !
   40   hotplug interface	ONLY WORKS AS A MODULE !
   41   Formula-n enter:now PCI none

Running the driver
------------------

When you insmod isdn.o and hisax.o (or with the in-kernel version, during
boot time), a few lines should appear in your syslog. Look for something like:

Apr 13 21:01:59 kke01 kernel: HiSax: Driver for Siemens chip set ISDN cards
Apr 13 21:01:59 kke01 kernel: HiSax: Version 2.9
Apr 13 21:01:59 kke01 kernel: HiSax: Revisions 1.14/1.9/1.10/1.25/1.8
Apr 13 21:01:59 kke01 kernel: HiSax: Total 1 card defined
Apr 13 21:01:59 kke01 kernel: HiSax: Card 1 Protocol EDSS1 Id=HiSax1 (0)
Apr 13 21:01:59 kke01 kernel: HiSax: Elsa driver Rev. 1.13
...
Apr 13 21:01:59 kke01 kernel: Elsa: PCF-Pro found at 0x360 Rev.:C IRQ 10
Apr 13 21:01:59 kke01 kernel: Elsa: timer OK; resetting card
Apr 13 21:01:59 kke01 kernel: Elsa: HSCX version A: V2.1  B: V2.1
Apr 13 21:01:59 kke01 kernel: Elsa: ISAC 2086/2186 V1.1
...
Apr 13 21:01:59 kke01 kernel: HiSax: DSS1 Rev. 1.14
Apr 13 21:01:59 kke01 kernel: HiSax: 2 channels added

This means that the card is ready for use.
Cabling problems or line-downs are not detected, and only some ELSA cards can
detect the S0 power.

Remember that, according to the new strategy for accessing low-level drivers
from within isdn4linux, you should also define a driver ID while doing
insmod: Simply append hisax_id=<SomeString> to the insmod command line. This
string MUST NOT start with a digit or a small 'x'!

At this point you can run a 'cat /dev/isdnctrl0' and view debugging messages.

At the moment, debugging messages are enabled with the hisaxctrl tool:

    hisaxctrl <DriverId> DebugCmd <debugging_flags>

<DriverId> default is HiSax, if you didn't specify one.

DebugCmd is  1  for generic debugging
            11  for layer 1 development debugging
            13  for layer 3 development debugging

where <debugging_flags> is the integer sum of the following debugging
options you wish enabled:

With DebugCmd set to 1:

   0x0001  Link-level <--> hardware-level communication
   0x0002  Top state machine
   0x0004  D-Channel Frames for isdnlog
   0x0008  D-Channel Q.921
   0x0010  B-Channel X.75
   0x0020  D-Channel l2
   0x0040  B-Channel l2
   0x0080  D-Channel link state debugging
   0x0100  B-Channel link state debugging
   0x0200  TEI debug
   0x0400  LOCK debug in callc.c
   0x0800  More paranoid debug in callc.c (not for normal use)
   0x1000  D-Channel l1 state debugging
   0x2000  B-Channel l1 state debugging

With DebugCmd set to 11:

   0x0001  Warnings (default: on)
   0x0002  IRQ status
   0x0004  ISAC
   0x0008  ISAC FIFO
   0x0010  HSCX
   0x0020  HSCX FIFO (attention: full B-Channel output!)
   0x0040  D-Channel LAPD frame types
   0x0080  IPAC debug
   0x0100  HFC receive debug
   0x0200  ISAC monitor debug
   0x0400  D-Channel frames for isdnlog (set with 1 0x4 too)
   0x0800  D-Channel message verbose

With DebugCmd set to 13:

         1  Warnings (default: on)
         2  l3 protocol descriptor errors
         4  l3 state machine
         8  charge info debugging (1TR6)

For example, 'hisaxctrl HiSax 1 0x3ff' enables full generic debugging.

Because of some obscure problems with some switch equipment, the delay
between the CONNECT message and sending the first data on the B-channel is now
configurable with

hisaxctrl <DriverId> 2 <delay>
<delay> in ms Value between 50 and 800 ms is recommended.

Downloading Firmware
--------------------
At the moment, the Sedlbauer speed fax+ is the only card, which
needs to download firmware.
The firmware is downloaded with the hisaxctrl tool:

    hisaxctrl <DriverId> 9 <firmware_filename>

<DriverId> default is HiSax, if you didn't specify one,

where <firmware_filename> is the filename of the firmware file.

For example, 'hisaxctrl HiSax 9 ISAR.BIN' downloads the firmware for
ISAR based cards (like the Sedlbauer speed fax+).

Warning
-------
HiSax is a work in progress and may crash your machine.
For certification look at HiSax.cert file.

Limitations
-----------
At this time, HiSax only works on Euro ISDN lines and German 1TR6 lines.
For leased lines see appendix.

Bugs
----
If you find any, please let me know.


Thanks
------
Special thanks to:

        Emil Stephan for the name HiSax which is a mix of HSCX and ISAC.

        Fritz Elfert, Jan den Ouden, Michael Hipp, Michael Wein,
        Andreas Kool, Pekka Sarnila, Sim Yskes, Johan Myrre'en,
	Klaus-Peter Nischke (ITK AG), Christof Petig, Werner Fehn (ELSA GmbH),
	Volker Schmidt
	Edgar Toernig and Marcus Niemann for the Sedlbauer driver
	Stephan von Krawczynski
	Juergen Quade for the Leased Line part
	Klaus Lichtenwalder (Klaus.Lichtenwalder@WebForum.DE), for ELSA PCMCIA support
	Enrik Berkhan (enrik@starfleet.inka.de) for S0BOX specific stuff
	Ton van Rosmalen for Teles PCI
	Petr Novak <petr.novak@i.cz> for Winbond W6692 support
	Werner Cornelius <werner@isdn4linux.de> for HFC-PCI, HFC-S(+/P) and supplementary services support
        and more people who are hunting bugs. (If I forgot somebody, please
	send me a mail).

        Firma ELSA GmbH
        Firma Eicon.Diehl GmbH
        Firma Dynalink NL
	Firma ASUSCOM NETWORK INC. Taiwan
	Firma S.u.S.E
	Firma ith Kommunikationstechnik GmbH
	Firma Traverse Technologie Australia
	Firma Medusa GmbH  (www.medusa.de).
	Firma Quant-X Austria for sponsoring a DEC Alpha board+CPU
	Firma Cologne Chip Designs GmbH

        My girl friend and partner in life Ute for her patience with me.


Enjoy,

Karsten Keil
keil@isdn4linux.de


Appendix: Teles PCMCIA driver
-----------------------------

See
   http://www.stud.uni-wuppertal.de/~ea0141/pcmcia.html
for instructions.

Appendix: Linux and ISDN-leased lines
-------------------------------------

Original from Juergen Quade, new version KKe.

Attention NEW VERSION, the old leased line syntax won't work !!!

You can use HiSax to connect your Linux-Box via an ISDN leased line
to e.g. the Internet:

1. Build a kernel which includes the HiSax driver either as a module
   or as part of the kernel.
     cd /usr/src/linux
     make menuconfig
     <ISDN subsystem - ISDN support -- HiSax>
     make clean; make dep; make zImage; make modules; make modules_install
2. Install the new kernel
     cp /usr/src/linux/arch/i386/boot/zImage /etc/kernel/linux.isdn
     vi /etc/lilo.conf
     <add new kernel in the bootable image section>
     lilo
3. in case the hisax driver is a "fixed" part of the kernel, configure
   the driver with lilo:
     vi /etc/lilo.conf
     <add HiSax driver parameter in the global section (see below)>
     lilo
   Your lilo.conf _might_ look like the following:

	# LILO configuration-file
	# global section
    # teles 16.0 on IRQ=5, MEM=0xd8000, PORT=0xd80
	append="hisax=1,3,5,0xd8000,0xd80,HiSax"
    # teles 16.3 (non pnp) on IRQ=15, PORT=0xd80
	# append="hisax=3,3,5,0xd8000,0xd80,HiSax"
	boot=/dev/sda
	compact        # faster, but won't work on all systems.
	linear
	read-only
	prompt
	timeout=100
	vga = normal    # force sane state
	# Linux bootable partition config begins
	image = /etc/kernel/linux.isdn
	root = /dev/sda1
	label = linux.isdn
	#
	image = /etc/kernel/linux-2.0.30
	root = /dev/sda1
	label = linux.secure

   In the line starting with "append" you have to adapt the parameters
   according to your card (see above in this file)

3. boot the new linux.isdn kernel
4. start the ISDN subsystem:
   a) load - if necessary - the modules (depends, whether you compiled
      the ISDN driver as module or not)
      According to the type of card you have to specify the necessary
      driver parameter (irq, io, mem, type, protocol).
      For the leased line the protocol is "3". See the table above for
      the parameters, which you have to specify depending on your card.
   b) configure i4l
      /sbin/isdnctrl addif isdn0
      # EAZ  1 -- B1 channel   2 --B2 channel
      /sbin/isdnctrl eaz isdn0 1
      /sbin/isdnctrl secure isdn0 on
      /sbin/isdnctrl huptimeout isdn0 0
      /sbin/isdnctrl l2_prot isdn0 hdlc
      # Attention you must not set an outgoing number !!! This won't work !!!
      # The incoming number is LEASED0 for the first card, LEASED1 for the
      # second and so on.
      /sbin/isdnctrl addphone isdn0 in LEASED0
      # Here is no need to bind the channel.
   c) in case the remote partner is a CISCO:
      /sbin/isdnctrl encap isdn0 cisco-h
   d) configure the interface
      /sbin/ifconfig isdn0 ${LOCAL_IP} pointopoint ${REMOTE_IP}
   e) set the routes
      /sbin/route add -host ${REMOTE_IP} isdn0
      /sbin/route add default gw ${REMOTE_IP}
   f) switch the card into leased mode for each used B-channel
      /sbin/hisaxctrl HiSax 5 1

Remarks:
a) Use state of the art isdn4k-utils

Here an example script:
#!/bin/sh
# Start/Stop ISDN leased line connection

I4L_AS_MODULE=yes
I4L_REMOTE_IS_CISCO=no
I4L_MODULE_PARAMS="type=16 io=0x268 irq=7 "
I4L_DEBUG=no
I4L_LEASED_128K=yes
LOCAL_IP=192.168.1.1
REMOTE_IP=192.168.2.1

case "$1" in
    start)
	echo "Starting ISDN ..."
        if [ ${I4L_AS_MODULE} = "yes" ]; then
		echo "loading modules..."
		/sbin/modprobe hisax ${I4L_MODULE_PARAMS}
	fi
	# configure interface
	/sbin/isdnctrl addif isdn0
	/sbin/isdnctrl secure isdn0 on
	if [ ${I4L_DEBUG} = "yes" ]; then
		/sbin/isdnctrl verbose 7
		/sbin/hisaxctrl HiSax 1 0xffff
		/sbin/hisaxctrl HiSax 11 0xff
		cat  /dev/isdnctrl >/tmp/lea.log &
	fi
	if [ ${I4L_REMOTE_IS_CISCO} = "yes" ]; then
		/sbin/isdnctrl encap isdn0 cisco-h
	fi
	/sbin/isdnctrl huptimeout isdn0 0
	# B-CHANNEL 1
	/sbin/isdnctrl eaz isdn0 1
	/sbin/isdnctrl l2_prot isdn0 hdlc
	# 1. card
	/sbin/isdnctrl addphone isdn0 in LEASED0
        if [ ${I4L_LEASED_128K} = "yes" ]; then
		/sbin/isdnctrl addslave isdn0 isdn0s
		/sbin/isdnctrl secure isdn0s on
		/sbin/isdnctrl huptimeout isdn0s 0
		# B-CHANNEL 2
		/sbin/isdnctrl eaz isdn0s 2
		/sbin/isdnctrl l2_prot isdn0s hdlc
		# 1. card
		/sbin/isdnctrl addphone isdn0s in LEASED0
		if [ ${I4L_REMOTE_IS_CISCO} = "yes" ]; then
			/sbin/isdnctrl encap isdn0s cisco-h
		fi
	fi
	/sbin/isdnctrl dialmode isdn0 manual
	# configure tcp/ip
	/sbin/ifconfig isdn0 ${LOCAL_IP} pointopoint ${REMOTE_IP}
	/sbin/route add -host ${REMOTE_IP} isdn0
	/sbin/route add default gw ${REMOTE_IP}
	# switch to leased mode
	# B-CHANNEL 1
	/sbin/hisaxctrl HiSax 5 1
        if [ ${I4L_LEASED_128K} = "yes" ]; then
		# B-CHANNEL 2
		sleep 10; /* Wait for master */
		/sbin/hisaxctrl HiSax 5 2
	fi
	;;
    stop)
	/sbin/ifconfig isdn0 down
	/sbin/isdnctrl delif isdn0
	if [ ${I4L_DEBUG} = "yes" ]; then
		killall cat
	fi
	if [ ${I4L_AS_MODULE} = "yes" ]; then
		/sbin/rmmod hisax
		/sbin/rmmod isdn
		/sbin/rmmod ppp
		/sbin/rmmod slhc
	fi
	;;
    *)
	echo "Usage: $0 {start|stop}"
	exit 1
esac
exit 0

$Id: README.act2000,v 1.1.4.1 2001/11/20 14:19:33 kai Exp $

This document describes the ACT2000 driver for the
IBM Active 2000 ISDN card.

There are 3 Types of this card available. A ISA-, MCA-, and PCMCIA-Bus
Version. Currently, only the ISA-Bus version of the card is supported.
However MCA and PCMCIA will follow soon.

The ISA-Bus Version uses 8 IO-ports. The base port address has to be set
manually using the DIP switches.

Setting up the DIP switches for the IBM Active 2000 ISDN card:

	 Note: S5 and S6 always set off!

     S1  S2  S3  S4  Base-port
     on  on  on  on  0x0200 (Factory default)
     off on  on  on  0x0240
     on  off on  on  0x0280
     off off on  on  0x02c0
     on  on  off on  0x0300
     off on  off on  0x0340
     on  off off on  0x0380
     on  on  on  off 0xcfe0
     off on  on  off 0xcfa0
     on  off on  off 0xcf60
     off off on  off 0xcf20
     on  on  off off 0xcee0
     off on  off off 0xcea0
     on  off off off 0xce60
     off off off off Card disabled

IRQ is configured by software. Possible values are:

  3, 5, 7, 10, 11, 12, 15 and none (polled mode)


The ACT2000 driver may either be built into the kernel or as a module.
Initialization depends on how the driver is built:

Driver built into the kernel:

  The ACT2000 driver can be configured using the commandline-feature while
  loading the kernel with LILO or LOADLIN. It accepts the following syntax:

  act2000=b,p,i[,idstring]

  where

    b = Bus-Type      (1=ISA, 2=MCA, 3=PCMCIA)
    p = portbase      (-1 means autoprobe)
    i = Interrupt     (-1 means use next free IRQ, 0 means polled mode)

  The idstring is an arbitrary string used for referencing the card
  by the actctrl tool later.

  Defaults used, when no parameters given at all:

    1,-1,-1,""

  which means: Autoprobe for an ISA card, use next free IRQ, let the
  ISDN linklevel fill the IdString (usually "line0" for the first card).

  If you like to use more than one card, you can use the program
  "actctrl" from the utility-package to configure additional cards.

  Using the "actctrl"-utility, portbase and irq can also be changed
  during runtime. The D-channel protocol is configured by the "dproto"
  option of the "actctrl"-utility after loading the firmware into the
  card's memory using the "actctrl"-utility.

Driver built as module:

  The module act2000.o can be configured during modprobe (insmod) by
  appending its parameters to the modprobe resp. insmod commandline.
  The following syntax is accepted:

    act_bus=b act_port=p act_irq=i act_id=idstring

  where b, p, i and idstring have the same meanings as the parameters
  described for the builtin version above.

  Using the "actctrl"-utility, the same features apply to the modularized
  version as to the kernel-builtin one. (i.e. loading of firmware and
  configuring the D-channel protocol)

Loading the firmware into the card:

  The firmware is supplied together with the isdn4k-utils package. It
  can be found in the subdirectory act2000/firmware/

  Assuming you have installed the utility-package correctly, the firmware
  will be downloaded into the card using the following command:

    actctrl -d idstring load /etc/isdn/bip11.btl

  where idstring is the Name of the card, given during insmod-time or
  (for kernel-builtin driver) on the kernel commandline. If only one
  ISDN card is used, the -d isdstrin may be omitted.

  For further documentation (adding more IBM Active 2000 cards), refer to
  the manpage actctrl.8 which is included in the isdn4k-utils package.

$Id: README.audio,v 1.1.4.1 2001/11/20 14:19:33 kai Exp $

ISDN subsystem for Linux.
  Description of audio mode.

When enabled during kernel configuration, the tty emulator of the ISDN
subsystem is capable of a reduced set of commands to support audio.
This document describes the commands supported and the format of
audio data.

Commands for enabling/disabling audio mode:

        AT+FCLASS=8      Enable audio mode.
                         This affects the following registers:
                           S18: Bits 0 and 2 are set.
                           S16: Set to 48 and any further change to
                                larger values is blocked.
        AT+FCLASS=0      Disable audio mode.
                         Register 18 is set to 4.
        AT+FCLASS=?      Show possible modes.
        AT+FCLASS?       Report current mode (0 or 8).

Commands supported in audio mode:

All audio mode commands have one of the following forms:

        AT+Vxx?          Show current setting.
        AT+Vxx=?         Show possible settings.
        AT+Vxx=v         Set simple parameter.
        AT+Vxx=v,v ...   Set complex parameter.

where xx is a two-character code and v are alphanumerical parameters.
The following commands are supported:

        AT+VNH=x         Auto hangup setting. NO EFFECT, supported
                         for compatibility only.
        AT+VNH?          Always reporting "1"
        AT+VNH=?         Always reporting "1"

        AT+VIP           Reset all audio parameters.

        AT+VLS=x         Line select. x is one of the following:
                           0 = No device.
                           2 = Phone line.
        AT+VLS=?         Always reporting "0,2"
        AT+VLS?          Show current line.

        AT+VRX           Start recording. Emulator responds with
                         CONNECT and starts sending audio data to
                         the application. See below for data format

        AT+VSD=x,y       Set silence-detection parameters.
                         Possible parameters:
                           x = 0 ... 31  sensitivity threshold level.
                                         (default 0 , deactivated)
                           y = 0 ... 255 range of interval in units
                                         of 0.1 second. (default 70)
        AT+VSD=?         Report possible parameters.
        AT+VSD?          Show current parameters.

        AT+VDD=x,y       Set DTMF-detection parameters.
                         Only possible if online and during this connection.
                         Possible parameters:
                           x = 0 ... 15  sensitivity threshold level.
                                         (default 0 , I4L soft-decode)
                                         (1-15 soft-decode off, hardware on)
                           y = 0 ... 255 tone duration in units of 5ms.
                                         Not for I4L soft decode (default 8, 40ms)
        AT+VDD=?         Report possible parameters.
        AT+VDD?          Show current parameters.

        AT+VSM=x         Select audio data format.
                         Possible parameters:
                           2 = ADPCM-2
                           3 = ADPCM-3
                           4 = ADPCM-4
                           5 = aLAW
                           6 = uLAW
        AT+VSM=?         Show possible audio formats.

        AT+VTX           Start audio playback. Emulator responds
                         with CONNECT and starts sending audio data
                         received from the application via phone line.
General behavior and description of data formats/protocol.
    when a connection is made:

      On incoming calls, if the application responds to a RING
      with ATA, depending on the calling service, the emulator
      responds with either CONNECT (data call) or VCON (voice call).

      On outgoing voice calls, the emulator responds with VCON
      upon connection setup.

  Audio recording.

    When receiving audio data, a kind of bisync protocol is used.
    Upon AT+VRX command, the emulator responds with CONNECT, and
    starts sending audio data to the application. There are several
    escape sequences defined, all using DLE (0x10) as Escape char:

    <DLE><ETX>              End of audio data. (i.e. caused by a
                            hangup of the remote side) Emulator stops
                            recording, responding with VCON.
    <DLE><DC4>		    Abort recording, (send by appl.) Emulator
			    stops recording, sends DLE,ETX.
    <DLE><DLE>              Escape sequence for DLE in data stream.
    <DLE>0                  Touchtone "0" received.
         ...
    <DLE>9                  Touchtone "9" received.
    <DLE>#                  Touchtone "#" received.
    <DLE>*                  Touchtone "*" received.
    <DLE>A                  Touchtone "A" received.
    <DLE>B                  Touchtone "B" received.
    <DLE>C                  Touchtone "C" received.
    <DLE>D                  Touchtone "D" received.

    <DLE>q                  quiet. Silence detected after non-silence.
    <DLE>s                  silence. Silence detected from the
                            start of recording.

    Currently unsupported DLE sequences:

    <DLE>c                  FAX calling tone received.
    <DLE>b                  busy tone received.

  Audio playback.

    When sending audio data, upon AT+VTX command, emulator responds with
    CONNECT, and starts transferring data from application to the phone line.
    The same DLE sequences apply to this mode.

  Full-Duplex-Audio:

    When _both_ commands for recording and playback are given in _one_
    AT-command-line (i.e.: "AT+VTX+VRX"), full-duplex-mode is selected.
	In this mode, the only way to stop recording is sending <DLE><DC4>
    and the only way to stop playback is to send <DLE><ETX>.

Driver for active AVM Controller.

The driver provides a kernel capi2.0 Interface (kernelcapi) and
on top of this a User-Level-CAPI2.0-interface (capi)
and a driver to connect isdn4linux with CAPI2.0 (capidrv).
The lowlevel interface can be used to implement a CAPI2.0
also for passive cards since July 1999.

The author can be reached at calle@calle.in-berlin.de.
The command avmcapictrl is part of the isdn4k-utils.
t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware

Currently supported cards:
	B1 ISA (all versions)
	B1 PCI
	T1/T1B (HEMA card)
	M1
	M2
	B1 PCMCIA

Installing
----------

You need at least /dev/capi20 to load the firmware.

mknod /dev/capi20 c 68 0
mknod /dev/capi20.00 c 68 1
mknod /dev/capi20.01 c 68 2
.
.
.
mknod /dev/capi20.19 c 68 20

Running
-------

To use the card you need the t4-files to download the firmware.
AVM GmbH provides several t4-files for the different D-channel
protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn.

if you configure as modules load the modules this way:

insmod /lib/modules/current/misc/capiutil.o
insmod /lib/modules/current/misc/b1.o
insmod /lib/modules/current/misc/kernelcapi.o
insmod /lib/modules/current/misc/capidrv.o
insmod /lib/modules/current/misc/capi.o

if you have an B1-PCI card load the module b1pci.o
insmod /lib/modules/current/misc/b1pci.o
and load the firmware with
avmcapictrl load /lib/isdn/b1.t4 1

if you have an B1-ISA card load the module b1isa.o
and add the card by calling
avmcapictrl add 0x150 15
and load the firmware by calling
avmcapictrl load /lib/isdn/b1.t4 1

if you have an T1-ISA card load the module t1isa.o
and add the card by calling
avmcapictrl add 0x450 15 T1 0
and load the firmware by calling
avmcapictrl load /lib/isdn/t1.t4 1

if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o
before you insert the card.

Leased Lines with B1
--------------------
Init card and load firmware.
For an D64S use "FV: 1" as phone number
For an D64S2 use "FV: 1" and "FV: 2" for multilink
or "FV: 1,2" to use CAPI channel bundling.

/proc-Interface
-----------------

/proc/capi:
  dr-xr-xr-x   2 root     root            0 Jul  1 14:03 .
  dr-xr-xr-x  82 root     root            0 Jun 30 19:08 ..
  -r--r--r--   1 root     root            0 Jul  1 14:03 applications
  -r--r--r--   1 root     root            0 Jul  1 14:03 applstats
  -r--r--r--   1 root     root            0 Jul  1 14:03 capi20
  -r--r--r--   1 root     root            0 Jul  1 14:03 capidrv
  -r--r--r--   1 root     root            0 Jul  1 14:03 controller
  -r--r--r--   1 root     root            0 Jul  1 14:03 contrstats
  -r--r--r--   1 root     root            0 Jul  1 14:03 driver
  -r--r--r--   1 root     root            0 Jul  1 14:03 ncci
  -r--r--r--   1 root     root            0 Jul  1 14:03 users

/proc/capi/applications:
   applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen
	level3cnt: capi_register parameter
	datablkcnt: capi_register parameter
	ncci-cnt: current number of nccis (connections)
	recvqueuelen: number of messages on receive queue
   for example:
1 -2 16 2048 1 0
2 2 7 2048 1 0

/proc/capi/applstats:
   applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg
	recvctlmsg: capi messages received without DATA_B3_IND
	recvdatamsg: capi DATA_B3_IND received
	sentctlmsg: capi messages sent without DATA_B3_REQ
	sentdatamsg: capi DATA_B3_REQ sent
   for example:
1 2057 1699 1721 1699

/proc/capi/capi20: statistics of capi.o (/dev/capi20)
    minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
	minor: minor device number of capi device
	nopen: number of calls to devices open
	nrecvdropmsg: capi messages dropped (messages in recvqueue in close)
	nrecvctlmsg: capi messages received without DATA_B3_IND
	nrecvdatamsg: capi DATA_B3_IND received
	nsentctlmsg: capi messages sent without DATA_B3_REQ
	nsentdatamsg: capi DATA_B3_REQ sent

   for example:
1 2 18 0 16 2

/proc/capi/capidrv: statistics of capidrv.o (capi messages)
    nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
	nrecvctlmsg: capi messages received without DATA_B3_IND
	nrecvdatamsg: capi DATA_B3_IND received
	nsentctlmsg: capi messages sent without DATA_B3_REQ
	nsentdatamsg: capi DATA_B3_REQ sent
   for example:
2780 2226 2256 2226

/proc/capi/controller:
   controller drivername state cardname   controllerinfo
   for example:
1 b1pci      running  b1pci-e000       B1 3.07-01 0xe000 19
2 t1isa      running  t1isa-450        B1 3.07-01 0x450 11 0
3 b1pcmcia   running  m2-150           B1 3.07-01 0x150 5

/proc/capi/contrstats:
    controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
	nrecvctlmsg: capi messages received without DATA_B3_IND
	nrecvdatamsg: capi DATA_B3_IND received
	nsentctlmsg: capi messages sent without DATA_B3_REQ
	nsentdatamsg: capi DATA_B3_REQ sent
   for example:
1 2845 2272 2310 2274
2 2 0 2 0
3 2 0 2 0

/proc/capi/driver:
   drivername ncontroller
   for example:
b1pci                            1
t1isa                            1
b1pcmcia                         1
b1isa                            0

/proc/capi/ncci:
   apllid ncci winsize sendwindow
   for example:
1 0x10101 8 0

/proc/capi/users: kernelmodules that use the kernelcapi.
   name
   for example:
capidrv
capi20

Questions
---------
Check out the FAQ (ftp.isdn4linux.de) or subscribe to the
linux-avmb1@calle.in-berlin.de mailing list by sending
a mail to majordomo@calle.in-berlin.de with
subscribe linux-avmb1
in the body.

German documentation and several scripts can be found at
ftp://ftp.avm.de/cardware/b1/linux/

Bugs
----
If you find any please let me know.

Enjoy,

Carsten Paeth (calle@calle.in-berlin.de)

Description of the "concap" encapsulation protocol interface
============================================================

The "concap" interface is intended to be used by network device
drivers that need to process an encapsulation protocol.
It is assumed that the protocol interacts with a linux network device by
- data transmission
- connection control (establish, release)
Thus, the mnemonic: "CONnection CONtrolling eNCAPsulation Protocol".

This is currently only used inside the isdn subsystem. But it might
also be useful to other kinds of network devices. Thus, if you want
to suggest changes that improve usability or performance of the
interface, please let me know. I'm willing to include them in future
releases (even if I needed to adapt the current isdn code to the
changed interface).


Why is this useful?
===================

The encapsulation protocol used on top of WAN connections or permanent
point-to-point links are frequently chosen upon bilateral agreement.
Thus, a device driver for a certain type of hardware must support
several different encapsulation protocols at once.

The isdn device driver did already support several different
encapsulation protocols. The encapsulation protocol is configured by a
user space utility (isdnctrl). The isdn network interface code then
uses several case statements which select appropriate actions
depending on the currently configured encapsulation protocol.

In contrast, LAN network interfaces always used a single encapsulation
protocol which is unique to the hardware type of the interface. The LAN
encapsulation is usually done by just sticking a header on the data. Thus,
traditional linux network device drivers used to process the
encapsulation protocol directly (usually by just providing a hard_header()
method in the device structure) using some hardware type specific support
functions. This is simple, direct and efficient. But it doesn't fit all
the requirements for complex WAN encapsulations.


   The configurability of the encapsulation protocol to be used
   makes isdn network interfaces more flexible, but also much more
   complex than traditional lan network interfaces.


Many Encapsulation protocols used on top of WAN connections will not just
stick a header on the data. They also might need to set up or release
the WAN connection. They also might want to send other data for their
private purpose over the wire, e.g. ppp does a lot of link level
negotiation before the first piece of user data can be transmitted.
Such encapsulation protocols for WAN devices are typically more complex
than encapsulation protocols for lan devices. Thus, network interface
code for typical WAN devices also tends to be more complex.


In order to support Linux' x25 PLP implementation on top of
isdn network interfaces I could have introduced yet another branch to
the various case statements inside drivers/isdn/isdn_net.c.
This eventually made isdn_net.c even more complex. In addition, it made
isdn_net.c harder to maintain. Thus, by identifying an abstract
interface between the network interface code and the encapsulation
protocol, complexity could be reduced and maintainability could be
increased.


Likewise, a similar encapsulation protocol will frequently be needed by
several different interfaces of even different hardware type, e.g. the
synchronous ppp implementation used by the isdn driver and the
asynchronous ppp implementation used by the ppp driver have a lot of
similar code in them. By cleanly separating the encapsulation protocol
from the hardware specific interface stuff such code could be shared
better in future.


When operating over dial-up-connections (e.g. telephone lines via modem,
non-permanent virtual circuits of wide area networks, ISDN) many
encapsulation protocols will need to control the connection. Therefore,
some basic connection control primitives are supported. The type and
semantics of the connection (i.e the ISO layer where connection service
is provided) is outside our scope and might be different depending on
the encapsulation protocol used, e.g. for a ppp module using our service
on top of a modem connection a connect_request will result in dialing
a (somewhere else configured) remote phone number. For an X25-interface
module (LAPB semantics, as defined in Documentation/networking/x25-iface.txt)
a connect_request will ask for establishing a reliable lapb
datalink connection.


The encapsulation protocol currently provides the following
service primitives to the network device.

- create a new encapsulation protocol instance
- delete encapsulation protocol instance and free all its resources
- initialize (open) the encapsulation protocol instance for use.
- deactivate (close) an encapsulation protocol instance.
- process (xmit) data handed down by upper protocol layer
- receive data from lower (hardware) layer
- process connect indication from lower (hardware) layer
- process disconnect indication from lower (hardware) layer


The network interface driver accesses those primitives via callbacks
provided by the encapsulation protocol instance within a
struct concap_proto_ops.

struct concap_proto_ops{

	/* create a new encapsulation protocol instance of same type */
	struct concap_proto *  (*proto_new) (void);

	/* delete encapsulation protocol instance and free all its resources.
	   cprot may no loger be referenced after calling this */
	void (*proto_del)(struct concap_proto *cprot);

	/* initialize the protocol's data. To be called at interface startup
	   or when the device driver resets the interface. All services of the
	   encapsulation protocol may be used after this*/
	int (*restart)(struct concap_proto *cprot,
		       struct net_device *ndev,
		       struct concap_device_ops *dops);

	/* deactivate an encapsulation protocol instance. The encapsulation
	   protocol may not call any *dops methods after this. */
	int (*close)(struct concap_proto *cprot);

	/* process a frame handed down to us by upper layer */
	int (*encap_and_xmit)(struct concap_proto *cprot, struct sk_buff *skb);

	/* to be called for each data entity received from lower layer*/
	int (*data_ind)(struct concap_proto *cprot, struct sk_buff *skb);

	/* to be called when a connection was set up/down.
	   Protocols that don't process these primitives might fill in
	   dummy methods here */
	int (*connect_ind)(struct concap_proto *cprot);
	int (*disconn_ind)(struct concap_proto *cprot);
};


The data structures are defined in the header file include/linux/concap.h.


A Network interface using encapsulation protocols must also provide
some service primitives to the encapsulation protocol:

- request data being submitted by lower layer (device hardware)
- request a connection being set up by lower layer
- request a connection being released by lower layer

The encapsulation protocol accesses those primitives via callbacks
provided by the network interface within a struct concap_device_ops.

struct concap_device_ops{

	/* to request data be submitted by device */
	int (*data_req)(struct concap_proto *, struct sk_buff *);

	/* Control methods must be set to NULL by devices which do not
	   support connection control. */
	/* to request a connection be set up */
	int (*connect_req)(struct concap_proto *);

	/* to request a connection be released */
	int (*disconn_req)(struct concap_proto *);
};

The network interface does not explicitly provide a receive service
because the encapsulation protocol directly calls netif_rx().




An encapsulation protocol itself is actually the
struct concap_proto{
	struct net_device *net_dev;		/* net device using our service  */
	struct concap_device_ops *dops; /* callbacks provided by device */
 	struct concap_proto_ops  *pops; /* callbacks provided by us */
	int flags;
	void *proto_data;               /* protocol specific private data, to
					   be accessed via *pops methods only*/
	/*
	  :
	  whatever
	  :
	  */
};

Most of this is filled in when the device requests the protocol to
be reset (opend). The network interface must provide the net_dev and
dops pointers. Other concap_proto members should be considered private
data that are only accessed by the pops callback functions. Likewise,
a concap proto should access the network device's private data
only by means of the callbacks referred to by the dops pointer.


A possible extended device structure which uses the connection controlling
encapsulation services could look like this:

struct concap_device{
	struct net_device net_dev;
	struct my_priv  /* device->local stuff */
			/* the my_priv struct might contain a
			   struct concap_device_ops *dops;
	                   to provide the device specific callbacks
			*/
	struct concap_proto *cprot;        /* callbacks provided by protocol */
};



Misc Thoughts
=============

The concept of the concap proto might help to reuse protocol code and
reduce the complexity of certain network interface implementations.
The trade off is that it introduces yet another procedure call layer
when processing the protocol. This has of course some impact on
performance. However, typically the concap interface will be used by
devices attached to slow lines (like telephone, isdn, leased synchronous
lines). For such slow lines, the overhead is probably negligible.
This might no longer hold for certain high speed WAN links (like
ATM).


If general linux network interfaces explicitly supported concap
protocols (e.g. by a member struct concap_proto* in struct net_device)
then the interface of the service function could be changed
by passing a pointer of type (struct net_device*) instead of
type (struct concap_proto*). Doing so would make many of the service
functions compatible to network device support functions.

e.g. instead of the concap protocol's service function

  int (*encap_and_xmit)(struct concap_proto *cprot, struct sk_buff *skb);

we could have

  int (*encap_and_xmit)(struct net_device *ndev, struct sk_buff *skb);

As this is compatible to the dev->hard_start_xmit() method, the device
driver could directly register the concap protocol's encap_and_xmit()
function as its hard_start_xmit() method. This would eliminate one
procedure call layer.


The device's data request function could also be defined as

  int (*data_req)(struct net_device *ndev, struct sk_buff *skb);

This might even allow for some protocol stacking. And the network
interface might even register the same data_req() function directly
as its hard_start_xmit() method when a zero layer encapsulation
protocol is configured. Thus, eliminating the performance penalty
of the concap interface when a trivial concap protocol is used.
Nevertheless, the device remains able to support encapsulation
protocol configuration.

The isdn diversion services are a supporting module working together with
the isdn4linux and the HiSax module for passive cards.
Active cards, TAs and cards using a own or other driver than the HiSax
module need to be adapted to the HL<->LL interface described in a separate
document. The diversion services may be used with all cards supported by
the HiSax driver.
The diversion kernel interface and controlling tool divertctrl were written
by Werner Cornelius (werner@isdn4linux.de or werner@titro.de) under the
GNU General Public License.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Table of contents
=================

1. Features of the i4l diversion services
   (Or what can the i4l diversion services do for me)

2. Required hard- and software

3. Compiling, installing and loading/unloading the module
   Tracing calling and diversion information

4. Tracing calling and diversion information

5. Format of the divert device ASCII output


1. Features of the i4l diversion services
   (Or what can the i4l diversion services do for me)

   The i4l diversion services offers call forwarding and logging normally
   only supported by isdn phones. Incoming calls may be diverted
   unconditionally (CFU), when not reachable (CFNR) or on busy condition
   (CFB).
   The diversions may be invoked statically in the providers exchange
   as normally done by isdn phones. In this case all incoming calls
   with a special (or all) service identifiers are forwarded if the
   forwarding reason is met. Activated static services may also be
   interrogated (queried).
   The i4l diversion services additionally offers a dynamic version of
   call forwarding which is not preprogrammed inside the providers exchange
   but dynamically activated by i4l.
   In this case all incoming calls are checked by rules that may be
   compared to the mechanism of ipfwadm or ipchains. If a given rule matches
   the checking process is finished and the rule matching will be applied
   to the call.
   The rules include primary and secondary service identifiers, called
   number and subaddress, callers number and subaddress and whether the rule
   matches to all filtered calls or only those when all B-channel resources
   are exhausted.
   Actions that may be invoked by a rule are ignore, proceed, reject,
   direct divert or delayed divert of a call.
   All incoming calls matching a rule except the ignore rule a reported and
   logged as ASCII via the proc filesystem (/proc/net/isdn/divert). If proceed
   is selected the call will be held in a proceeding state (without ringing)
   for a certain amount of time to let an external program or client decide
   how to handle the call.


2. Required hard- and software

   For using the i4l diversion services the isdn line must be of a EURO/DSS1
   type. Additionally the i4l services only work together with the HiSax
   driver for passive isdn cards. All HiSax supported cards may be used for
   the diversion purposes.
   The static diversion services require the provider having static services
   CFU, CFNR, CFB activated on an MSN-line. The static services may not be
   used on a point-to-point connection. Further the static services are only
   available in some countries (for example germany). Countries requiring the
   keypad protocol for activating static diversions (like the netherlands) are
   not supported but may use the tty devices for this purpose.
   The dynamic diversion services may be used in all countries if the provider
   enables the feature CF (call forwarding). This should work on both MSN- and
   point-to-point lines.
   To add and delete rules the additional divertctrl program is needed. This
   program is part of the isdn4kutils package.

3. Compiling, installing and loading/unloading the module
   Tracing calling and diversion information


   To compile the i4l code with diversion support you need to say yes to the
   DSS1 diversion services when selecting the i4l options in the kernel
   config (menuconfig or config).
   After having properly activated a make modules and make modules_install all
   required modules will be correctly installed in the needed modules dirs.
   As the diversion services are currently not included in the scripts of most
   standard distributions you will have to add a "insmod dss1_divert" after
   having loaded the global isdn module.
   The module can be loaded without any command line parameters.
   If the module is actually loaded and active may be checked with a
   "cat /proc/modules" or "ls /proc/net/isdn/divert". The divert file is
   dynamically created by the diversion module and removed when the module is
   unloaded.


4. Tracing calling and diversion information

   You also may put a "cat /proc/net/isdn/divert" in the background with the
   output redirected to a file. Then all actions of the module are logged.
   The divert file in the proc system may be opened more than once, so in
   conjunction with inetd and a small remote client on other machines inside
   your network incoming calls and reactions by the module may be shown on
   every listening machine.
   If a call is reported as proceeding an external program or client may
   specify during a certain amount of time (normally 4 to 10 seconds) what
   to do with that call.
   To unload the module all open files to the device in the proc system must
   be closed. Otherwise the module (and isdn.o) may not be unloaded.

5. Format of the divert device ASCII output

   To be done later

$Id: README.eicon,v 1.1.4.1 2001/11/20 14:19:33 kai Exp $

(c) 1999,2000 Armin Schindler (mac@melware.de)
(c) 1999,2000 Cytronics & Melware (info@melware.de)

This document describes the eicon driver for the
Eicon active ISDN cards.

It is meant to be used with isdn4linux, an ISDN link-level module for Linux.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.



Supported Cards
===============

Old ISA type
------------
- S-Card ISA
- SX-Card ISA
- SXn-Card ISA
- SCOM-Card ISA
- Quadro-Card ISA
- S2M-Card ISA

DIVA Server family
------------------
- DIVA Server BRI/PCI 2M
- DIVA Server PRI/PCI 2M (9M 23M 30M)
- DIVA Server 4BRI/PCI
	supported functions of onboard DSPs:
	- analog modem
	- fax group 2/3 (Fax Class 2 commands)
	- DTMF detection


ISDN D-Channel Protocols
------------------------

- ETSI (Euro-DSS1)
- 1TR6 (German ISDN) *not testet*
- other protocols exist for the range of DIVA Server cards,
  but they are not fully testet yet.


You can load the module simply by using the insmod or modprobe function :

  insmod eicon [id=driverid] [membase=<membase>] [irq=<irq>]


The module will automatically probe the PCI-cards. If the id-option
is omitted, the driver will assume 'eicon0' for the first pci card and
increases the digit with each further card. With a given driver-id
the module appends a number starting with '0'.

For ISA-cards you have to specify membase, irq and id. If id or
membase is missing/invalid, the driver will not be loaded except
PCI-cards were found. Additional ISA-cards and irq/membase changes
can be done with the eiconctrl utility.

After loading the module, you have to download the protocol and
dsp-code by using the eiconctrl utility of isdn4k-utils.


Example for loading and starting a BRI card with E-DSS1 Protocol.

	eiconctrl [-d DriverId] load etsi

Example for a BRI card with E-DSS1 Protocol with PtP configuration.

	eiconctrl [-d DriverId] load etsi -n -t1 -s1


Example for loading and starting a PRI card with E-DSS1 Protocol.

	eiconctrl [-d DriverId] load etsi -s2 -n


Details about using the eiconctrl utility are in 'man eiconctrl'
or will be printed by starting eiconctrl without any parameters.

ISDNLOG:
With eicon driver version 1.77 or newer and the eiconctrl utility
of version 1.1 or better, you can use the isdnlog user program
with your DIVA Server BRI card.
Just use "eiconctrl isdnlog on" and the driver will generate
the necessary D-Channel traces for isdnlog.



Thanks to
	Deutsche Mailbox Saar-Lor-Lux GmbH
	for sponsoring and testing fax
	capabilities with Diva Server cards.


Any reports about bugs, errors and even wishes are welcome.


Have fun !

Armin Schindler
mac@melware.de
http://www.melware.de

Fax with isdn4linux
===================

When enabled during kernel configuration, the tty emulator
of the ISDN subsystem is capable of the Fax Class 2 commands.

This only makes sense under the following conditions :

- You need the commands as dummy, because you are using
  hylafax (with patch) for AVM capi.
- You want to use the fax capabilities of your isdn-card.
  (supported cards are listed below)


NOTE: This implementation does *not* support fax with passive
      ISDN-cards (known as softfax). The low-level driver of
      the ISDN-card and/or the card itself must support this.


Supported ISDN-Cards
--------------------

Eicon DIVA Server BRI/PCI
	- full support with both B-channels.

Eicon DIVA Server 4BRI/PCI
	- full support with all B-channels.

Eicon DIVA Server PRI/PCI
	- full support on amount of B-channels
		depending on DSPs on board.



The command set is known as Class 2 (not Class 2.0) and
can be activated by AT+FCLASS=2


The interface between the link-level-module and the hardware-level driver
is described in the files INTERFACE.fax and INTERFACE.

Armin
mac@melware.de

The driver for the HFC-PCI and HFC-PCI-A chips from CCD may be used
for many OEM cards using this chips.
Additionally the driver has a special feature which makes it possible
to read the echo-channel of the isdn bus. So all frames in both directions
may be logged.
When the echo logging feature is used the number of available B-channels
for a HFC-PCI card is reduced to 1. Of course this is only relevant to
the card, not to the isdn line.
To activate the echo mode the following ioctls must be entered:

hisaxctrl <driver/cardname> 10 1

This reduces the available channels to 1. There must not be open connections
through this card when entering the command.
And then:

hisaxctrl <driver/cardname> 12 1

This enables the echo mode. If Hex logging is activated the isdnctrlx
devices show a output with a line beginning of HEX: for the providers
exchange and ECHO: for isdn devices sending to the provider.

If more than one HFC-PCI cards are installed, a specific card may be selected
at the hisax module load command line. Supply the load command with the desired
IO-address of the desired card.
Example:
There tree cards installed in your machine at IO-base addresses 0xd000, 0xd400
and 0xdc00
If you want to use the card at 0xd400 standalone you should supply the insmod
or depmod with type=35 io=0xd400.
If you want to use all three cards, but the order needs to be at 0xdc00,0xd400,
0xd000 you may give the parameters type=35,35,35 io=0xdc00,0xd400,0xd00
Then the desired card will be the initialised in the desired order.
If the io parameter is used the io addresses of all used cards should be
supplied else the parameter is assumed 0 and a auto search for a free card is
invoked which may not give the wanted result.

Comments and reports to werner@isdn4linux.de or werner@isdn-development.de

$Id: README.hysdn,v 1.1.4.1 2001/11/20 14:19:33 kai Exp $
The hysdn driver has been written by
by Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
under the GNU General Public License.

The CAPI 2.0-support was added by Ulrich Albrecht (ualbrecht@hypercope.de)
for Hypercope GmbH Aachen, Germany.


    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Table of contents
=================

1. About the driver

2. Loading/Unloading the driver

3. Entries in the /proc filesystem

4. The /proc/net/hysdn/cardconfX file

5. The /proc/net/hysdn/cardlogX file

6. Where to get additional info and help


1. About the driver

   The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
   PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
   enable ISDN support in the kernel config and support for HYSDN cards in
   the active cards submenu. The driver may only be compiled and used if
   support for loadable modules and the process filesystem have been enabled.

   These cards provide two different interfaces to the kernel. Without the
   optional CAPI 2.0 support, they register as ethernet card. IP-routing
   to a ISDN-destination is performed on the card itself. All necessary
   handlers for various protocols like ppp and others as well as config info
   and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.

   With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
   compliant devices with either CAPI 2.0 applications
   (check isdn4k-utils) or -using the capidrv module- as a regular
   isdn4linux device. This is done via the same mechanism as with the
   active AVM cards and in fact uses the same module.


2. Loading/Unloading the driver

   The module has no command line parameters and auto detects up to 10 cards
   in the id-range 0-9.
   If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
   subdir need to be closed and all ethernet interfaces allocated by this
   driver must be shut down. Otherwise the module counter will avoid a module
   unload.

   If you are using the CAPI 2.0-interface, make sure to load/modprobe the
   kernelcapi-module first.

   If you plan to use the capidrv-link to isdn4linux, make sure to load
   capidrv.o after all modules using this driver (i.e. after hysdn and
   any avm-specific modules).

3. Entries in the /proc filesystem

   When the module has been loaded it adds the directory hysdn in the
   /proc/net tree. This directory contains exactly 2 file entries for each
   card. One is called cardconfX and the other cardlogX, where X is the
   card id number from 0 to 9.
   The cards are numbered in the order found in the PCI config data.

4. The /proc/net/hysdn/cardconfX file

   This file may be read to get by everyone to get info about the cards type,
   actual state, available features and used resources.
   The first 3 entries (id, bus and slot) are PCI info fields, the following
   type field gives the information about the cards type:

   4 -> Ergo card (server card with 2 b-chans)
   5 -> Metro card (server card with 4 or 8 b-chans)
   6 -> Champ card (client card with 2 b-chans)

   The following 3 fields show the hardware assignments for irq, iobase and the
   dual ported memory (dp-mem).
   The fields b-chans and fax-chans announce the available card resources of
   this types for the user.
   The state variable indicates the actual drivers state for this card with the
   following assignments.

   0 -> card has not been booted since driver load
   1 -> card booting is actually in progess
   2 -> card is in an error state due to a previous boot failure
   3 -> card is booted and active

   And the last field (device) shows the name of the ethernet device assigned
   to this card. Up to the first successful boot this field only shows a -
   to tell that no net device has been allocated up to now. Once a net device
   has been allocated it remains assigned to this card, even if a card is
   rebooted and an boot error occurs.

   Writing to the cardconfX file boots the card or transfers config lines to
   the cards firmware. The type of data is automatically detected when the
   first data is written. Only root has write access to this file.
   The firmware boot files are normally called hyclient.pof for client cards
   and hyserver.pof for server cards.
   After successfully writing the boot file, complete config files or single
   config lines may be copied to this file.
   If an error occurs the return value given to the writing process has the
   following additional codes (decimal):

   1000 Another process is currently bootng the card
   1001 Invalid firmware header
   1002 Boards dual-port RAM test failed
   1003 Internal firmware handler error
   1004 Boot image size invalid
   1005 First boot stage (bootstrap loader) failed
   1006 Second boot stage failure
   1007 Timeout waiting for card ready during boot
   1008 Operation only allowed in booted state
   1009 Config line to long
   1010 Invalid channel number
   1011 Timeout sending config data

   Additional info about error reasons may be fetched from the log output.

5. The /proc/net/hysdn/cardlogX file

   The cardlogX file entry may be opened multiple for reading by everyone to
   get the cards and drivers log data. Card messages always start with the
   keyword LOG. All other lines are output from the driver.
   The driver log data may be redirected to the syslog by selecting the
   appropriate bitmask. The cards log messages will always be send to this
   interface but never to the syslog.

   A root user may write a decimal or hex (with 0x) value t this file to select
   desired output options. As mentioned above the cards log dat is always
   written to the cardlog file independent of the following options only used
   to check and debug the driver itself:

   For example:
   echo "0x34560078" > /proc/net/hysdn/cardlog0
   to output the hex log mask 34560078 for card 0.

   The written value is regarded as an unsigned 32-Bit value, bit ored for
   desired output. The following bits are already assigned:

   0x80000000   All driver log data is alternatively via syslog
   0x00000001   Log memory allocation errors
   0x00000010   Firmware load start and close are logged
   0x00000020   Log firmware record parser
   0x00000040   Log every firmware write actions
   0x00000080   Log all card related boot messages
   0x00000100   Output all config data sent for debugging purposes
   0x00000200   Only non comment config lines are shown wth channel
   0x00000400   Additional conf log output
   0x00001000   Log the asynchronous scheduler actions (config and log)
   0x00100000   Log all open and close actions to /proc/net/hysdn/card files
   0x00200000   Log all actions from /proc file entries
   0x00010000   Log network interface init and deinit

6. Where to get additional info and help

   If you have any problems concerning the driver or configuration contact
   the Hypercope support team (support@hypercope.de) and or the authors
   Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
   Ulrich Albrecht (ualbrecht@hypercope.de).

$Id: README.icn,v 1.1.4.1 2001/11/20 14:19:33 kai Exp $

You can get the ICN-ISDN-card from:

Thinking Objects Software GmbH
Versbacher R�the 159
97078 W�rzburg
Tel: +49 931 2877950
Fax: +49 931 2877951

email info@think.de
WWW   http:/www.think.de


The card communicates with the PC by two interfaces:
  1. A range of 4 successive port-addresses, whose base address can be
     configured with the switches.
  2. A memory window with 16KB-256KB size, which can be setup in 16k steps
     over the whole range of 16MB. Isdn4linux only uses a 16k window.
     The base address of the window can be configured when loading
     the lowlevel-module (see README). If using more than one card,
     all cards are mapped to the same window and activated as needed.

Setting up the IO-address dipswitches for the ICN-ISDN-card:

  Two types of cards exist, one with dip-switches and one with
  hook-switches.

  1. Setting for the card with hook-switches:

     (0 = switch closed, 1 = switch open)

     S3 S2 S1  Base-address
      0  0  0  0x300
      0  0  1  0x310
      0  1  0  0x320 (Default for isdn4linux)
      0  1  1  0x330
      1  0  0  0x340
      1  0  1  0x350
      1  1  0  0x360
      1  1  1  NOT ALLOWED!

  2. Setting for the card with dip-switches:

     (0 = switch closed, 1 = switch open)

     S1 S2 S3 S4  Base-Address
      0  0  0  0  0x300
      0  0  0  1  0x310
      0  0  1  0  0x320 (Default for isdn4linux)
      0  0  1  1  0x330
      0  1  0  0  0x340
      0  1  0  1  0x350
      0  1  1  0  0x360
      0  1  1  1  NOT ALLOWED!
      1  0  0  0  0x308
      1  0  0  1  0x318
      1  0  1  0  0x328
      1  0  1  1  0x338
      1  1  0  0  0x348
      1  1  0  1  0x358
      1  1  1  0  0x368
      1  1  1  1  NOT ALLOWED!

The ICN driver may be built into the kernel or as a module. Initialization
depends on how the driver is built:

Driver built into the kernel:

  The ICN driver can be configured using the commandline-feature while
  loading the kernel with LILO or LOADLIN. It accepts the following syntax:

  icn=p,m[,idstring1[,idstring2]]

  where

    p = portbase      (default: 0x320)
    m = shared memory (default: 0xd0000)

  When using the ICN double card (4B), you MUST define TWO idstrings.
  idstring must start with a character! There is no way for the driver
  to distinguish between a 2B and 4B type card. Therefore, by supplying
  TWO idstrings, you tell the driver that you have a 4B installed.

  If you like to use more than one card, you can use the program
  "icnctrl" from the utility-package to configure additional cards.
  You need to configure shared memory only once, since the icn-driver
  maps all cards into the same address-space.

  Using the "icnctrl"-utility, portbase and shared memory can also be
  changed during runtime.

  The D-channel protocol is configured by loading different firmware
  into the card's memory using the "icnctrl"-utility.


Driver built as module:

  The module icn.o can be configured during "insmod'ing" it by
  appending its parameters to the insmod-commandline. The following
  syntax is accepted:

    portbase=p membase=m icn_id=idstring [icn_id2=idstring2]

  where p, m, idstring1 and idstring2 have the same meanings as the
  parameters described for the kernel-version above.

  When using the ICN double card (4B), you MUST define TWO idstrings.
  idstring must start with a character! There is no way for the driver
  to distinguish between a 2B and 4B type card. Therefore, by supplying
  TWO idstrings, you tell the driver that you have a 4B installed.

  Using the "icnctrl"-utility, the same features apply to the modularized
  version like to the kernel-builtin one.

  The D-channel protocol is configured by loading different firmware
  into the card's memory using the "icnctrl"-utility.

Loading the firmware into the card:

  The firmware is supplied together with the isdn4k-utils package. It
  can be found in the subdirectory icnctrl/firmware/

  There are 3 files:

    loadpg.bin   - Image of the bootstrap loader.
    pc_1t_ca.bin - Image of firmware for german 1TR6 protocol.
    pc_eu_ca.bin - Image if firmware for EDSS1 (Euro-ISDN) protocol.

  Assuming you have installed the utility-package correctly, the firmware
  will be downloaded into the 2B-card using the following command:

    icnctrl -d Idstring load /etc/isdn/loadpg.bin /etc/isdn/pc_XX_ca.bin

  where XX is either "1t" or "eu", depending on the D-Channel protocol
  used on your S0-bus and Idstring is the Name of the card, given during
  insmod-time or (for kernel-builtin driver) on the kernel commandline.

  To load a 4B-card, the same command is used, except a second firmware
  file is appended to the commandline of icnctrl.

  -> After downloading firmware, the two LEDs at the back cover of the card
     (ICN-4B: 4 LEDs) must be blinking intermittently now. If a connection
     is up, the corresponding led is lit continuously.

  For further documentation (adding more ICN-cards), refer to the manpage
  icnctrl.8 which is included in the isdn4k-utils package.

------------------------------------------------------------------------------
 README file for the PCBIT-D Device Driver.
------------------------------------------------------------------------------

The PCBIT is a Euro ISDN adapter manufactured in Portugal by Octal and
developed in cooperation with Portugal Telecom and Inesc.
The driver interfaces with the standard kernel isdn facilities
originally developed by Fritz Elfert in the isdn4linux project.

The common versions of the pcbit board require a firmware that is
distributed (and copyrighted) by the manufacturer. To load this
firmware you need "pcbitctl" available on the standard isdn4k-utils
package or in the pcbit package available in:

ftp://ftp.di.fc.ul.pt/pub/systems/Linux/isdn

Known Limitations:

- The board reset procedure is at the moment incorrect and will only
allow you to load the firmware after a hard reset.

- Only HDLC in B-channels is supported at the moment. There is no
current support for X.25 in B or D channels nor LAPD in B
channels. The main reason is that these two other protocol modes have,
to my knowledge, very little use. If you want to see them implemented
*do* send me a mail.

- The driver often triggers errors in the board that I and the
manufacturer believe to be caused by bugs in the firmware. The current
version includes several procedures for error recovery that should
allow normal operation. Plans for the future include cooperation with
the manufacturer in order to solve this problem.

Information/hints/help can be obtained in the linux isdn
mailing list (isdn4linux@listserv.isdn4linux.de) or directly from me.

regards,
  Pedro.

<pedro_m@yahoo.com>

Welcome to Beta Release 2 of the combination ISDN driver for SpellCaster's
ISA ISDN adapters. Please note this release 2 includes support for the
DataCommute/BRI and TeleCommute/BRI adapters only and any other use is
guaranteed to fail. If you have a DataCommute/PRI installed in the test
computer, we recommend removing it as it will be detected but will not
be usable.  To see what we have done to Beta Release 2, see section 3.

Speaking of guarantees, THIS IS BETA SOFTWARE and as such contains
bugs and defects either known or unknown. Use this software at your own
risk. There is NO SUPPORT for this software. Some help may be available
through the web site or the mailing list but such support is totally at
our own option and without warranty. If you choose to assume all and
total risk by using this driver, we encourage you to join the beta
mailing list.

To join the Linux beta mailing list, send a message to:
majordomo@spellcast.com with the words "subscribe linux-beta" as the only
contents of the message. Do not include a signature. If you choose to
remove yourself from this list at a later date, send another message to
the same address with the words "unsubscribe linux-beta" as its only
contents.

TABLE OF CONTENTS
-----------------
	1. Introduction
	 1.1 What is ISDN4Linux?
	 1.2 What is different between this driver and previous drivers?
	 1.3 How do I setup my system with the correct software to use
	     this driver release?

	2. Basic Operations
	 2.1 Unpacking and installing the driver
	 2.2 Read the man pages!!!
	 2.3 Installing the driver
	 2.4 Removing the driver
	 2.5 What to do if it doesn't load
	 2.6 How to setup ISDN4Linux with the driver

	3. Beta Change Summaries and Miscellaneous Notes

1. Introduction
---------------

The revision 2 Linux driver for SpellCaster ISA ISDN adapters is built
upon ISDN4Linux available separately or as included in Linux 2.0 and later.
The driver will support a maximum of 4 adapters in any one system of any
type including DataCommute/BRI, DataCommute/PRI and TeleCommute/BRI for a
maximum of 92 channels for host. The driver is supplied as a module in
source form and needs to be complied before it can be used. It has been
tested on Linux 2.0.20.

1.1 What Is ISDN4Linux

ISDN4Linux is a driver and set of tools used to access and use ISDN devices
on a Linux platform in a common and standard way. It supports HDLC and PPP
protocols and offers channel bundling and MLPPP support. To use ISDN4Linux
you need to configure your kernel for ISDN support and get the ISDN4Linux
tool kit from our web site.

ISDN4Linux creates a channel pool from all of the available ISDN channels
and therefore can function across adapters. When an ISDN4Linux compliant
driver (such as ours) is loaded, all of the channels go into a pool and
are used on a first-come first-served basis. In addition, individual
channels can be specifically bound to particular interfaces.

1.2 What is different between this driver and previous drivers?

The revision 2 driver besides adopting the ISDN4Linux architecture has many
subtle and not so subtle functional differences from previous releases. These
include:
	- More efficient shared memory management combined with a simpler
	  configuration. All adapters now use only 16Kbytes of shared RAM
	  versus between 16K and 64K. New methods for using the shared RAM
	  allow us to utilize all of the available RAM on the adapter through
	  only one 16K page.
	- Better detection of available upper memory. The probing routines
	  have been improved to better detect available shared RAM pages and
	  used pages are now locked.
	- Decreased loading time and a wider range of I/O ports probed.
	  We have significantly reduced the amount of time it takes to load
	  the driver and at the same time doubled the number of I/O ports
	  probed increasing the likelihood of finding an adapter.
	- We now support all ISA adapter models with a single driver instead
	  of separate drivers for each model. The revision 2 driver supports
	  the DataCommute/BRI, DataCommute/PRI and TeleCommute/BRI in any
	  combination up to a maximum of four adapters per system.
	- On board PPP protocol support has been removed in favour of the
	  sync-PPP support used in ISDN4Linux. This means more control of
	  the protocol parameters, faster negotiation time and a more
	  familiar interface.

1.3 How do I setup my system with the correct software to use
    this driver release?

Before you can compile, install and use the SpellCaster ISA ISDN driver, you
must ensure that the following software is installed, configured and running:

	- Linux kernel 2.0.20 or later with the required init and ps
	  versions. Please see your distribution vendor for the correct
	  utility packages. The latest kernel is available from
	  ftp://sunsite.unc.edu/pub/Linux/kernel/v2.0/

	- The latest modules package (modules-2.0.0.tar.gz) from
	  ftp://sunsite.unc.edu/pub/Linux/kernel/modules-2.0.0.tar.gz

	- The ISDN4Linux tools available from
	  ftp://ftp.franken.de/pub/isdn4linux/v2.0/isdn4k-utils-2.0.tar.gz
	  This package may fail to compile for you so you can alternatively
	  get a pre-compiled version from
	  ftp://ftp.spellcast.com/pub/drivers/isdn4linux/isdn4k-bin-2.0.tar.gz


2. Basic Operations
-------------------

2.1 Unpacking and installing the driver

	1. As root, create a directory in a convenient place. We suggest
	   /usr/src/spellcaster.

	2. Unpack the archive with :
		tar xzf sc-n.nn.tar.gz -C /usr/src/spellcaster

	3. Change directory to /usr/src/spellcaster

	4. Read the README and RELNOTES files.

	5. Run 'make' and if all goes well, run 'make install'.

2.2 Read the man pages!!!

Make sure you read the scctrl(8) and sc(4) manual pages before continuing
any further. Type 'man 8 scctrl' and 'man 4 sc'.

2.3 Installing the driver

To install the driver, type '/sbin/insmod sc' as root. sc(4) details options
you can specify but you shouldn't need to use any unless this doesn't work.

Make sure the driver loaded and detected all of the adapters by typing
'dmesg'.

The driver can be configured so that it is loaded upon startup.  To do this,
edit the file "/etc/modules/'uname -f'/'uname -v'" and insert the driver name
"sc" into this file.

2.4 Removing the driver

To remove the driver, delete any interfaces that may exist (see isdnctrl(8)
for more on this) and then type '/sbin/rmmod sc'.

2.5 What to do if it doesn't load

If, when you try to install the driver, you get a message mentioning
'register_isdn' then you do not have the ISDN4Linux system installed. Please
make sure that ISDN support is configured in the kernel.

If you get a message that says 'initialization of sc failed', then the
driver failed to detect an adapter or failed to find resources needed such
as a free IRQ line or shared memory segment. If you are sure there are free
resources available, use the insmod options detailed in sc(4) to override
the probing function.

Upon testing, the following problem was noted, the driver would load without
problems, but the board would not respond beyond that point.  When a check was
done with 'cat /proc/interrupts' the interrupt count for sc was 0.  In the event
of this problem, change the BIOS settings so that the interrupts in question are
reserved for ISA use only.


2.6 How to setup ISDN4Linux with the driver

There are three main configurations which you can use with the driver:

A)	Basic HDLC connection
B)	PPP connection
C)	MLPPP connection

It should be mentioned here that you may also use a tty connection if you
desire. The Documentation directory of the isdn4linux subsystem offers good
documentation on this feature.

A) 10 steps to the establishment of a basic HDLC connection
-----------------------------------------------------------

- please open the isdn-hdlc file in the examples directory and follow along...

	This file is a script used to configure a BRI ISDN TA to establish a
	basic HDLC connection between its two channels.  Two network
	interfaces are created and two routes added between the channels.

	i)   using the isdnctrl utility, add an interface with "addif" and
	     name it "isdn0"
	ii)  add the outgoing and inbound telephone numbers
	iii) set the Layer 2 protocol to hdlc
	iv)  set the eaz of the interface to be the phone number of that
	     specific channel
	v)   to turn the callback features off, set the callback to "off" and
	     the callback delay (cbdelay) to 0.
	vi)  the hangup timeout can be set to a specified number of seconds
	vii) the hangup upon incoming call can be set on or off
	viii) use the ifconfig command to bring up the network interface with
	      a specific IP address and point to point address
	ix)  add a route to the IP address through the isdn0 interface
	x)   a ping should result in the establishment of the connection


B) Establishment of a PPP connection
------------------------------------

- please open the isdn-ppp file in the examples directory and follow along...

	This file is a script used to configure a BRI ISDN TA to establish a
	PPP connection 	between the two channels.  The file is almost
	identical to the HDLC connection example except that the packet
	encapsulation type has to be set.

	use the same procedure as in the HDLC connection from steps i) to
	iii) then, after the Layer 2 protocol is set, set the encapsulation
	"encap" to syncppp. With this done, the rest of the steps, iv) to x)
	can be followed from above.

	Then, the ipppd (ippp daemon) must be setup:

	xi)   use the ipppd function found in /sbin/ipppd to set the following:
	xii)  take out (minus) VJ compression and bsd compression
	xiii) set the mru size to 2000
	xiv)  link the two /dev interfaces to the daemon

NOTE:  A "*" in the inbound telephone number specifies that a call can be
accepted on any number.

C) Establishment of a MLPPP connection
--------------------------------------

- please open the isdn-mppp file in the examples directory and follow along...

	This file is a script used to configure a BRI ISDN TA to accept a
	Multi Link PPP connection.

	i)   using the isdnctrl utility, add an interface with "addif" and
	     name it "ippp0"
	ii)  add the inbound telephone number
	iii) set the Layer 2 protocol to hdlc and the Layer 3 protocol to
	     trans (transparent)
	iv)  set the packet encapsulation to syncppp
	v)   set the eaz of the interface to be the phone number of that
	     specific channel
	vi)  to turn the callback features off, set the callback to "off" and
	     the callback delay (cbdelay) to 0.
	vi)  the hangup timeout can be set to a specified number of seconds
	vii) the hangup upon incoming call can be set on or off
	viii) add a slave interface and name it "ippp32" for example
	ix)  set the similar parameters for the ippp32 interface
	x)   use the ifconfig command to bring-up the ippp0 interface with a
	     specific IP address and point to point address
	xi)  add a route to the IP address through the ippp0 interface
	xii) use the ipppd function found in /sbin/ipppd to set the following:
	xiii) take out (minus) bsd compression
	xiv) set the mru size to 2000
	xv)  add (+) the multi-link function "+mp"
	xvi)  link the two /dev interfaces to the daemon

NOTE:  To use the MLPPP connection to dial OUT to a MLPPP connection, change
the inbound telephone numbers to the outgoing telephone numbers of the MLPPP
host.


3. Beta Change Summaries and Miscellaneous Notes
------------------------------------------------
When using the "scctrl" utility to upload firmware revisions on the board,
please note that the byte count displayed at the end of the operation may be
different from the total number of bytes in the "dcbfwn.nn.sr" file. Please
disregard the displayed byte count.

It was noted that in Beta Release 1, the module would fail to load and result
in a segmentation fault when 'insmod'ed. This problem was created when one of
the isdn4linux parameters, (isdn_ctrl, data field) was filled in. In some
cases, this data field was NULL, and was left unchecked, so when it was
referenced... segv. The bug has been fixed around line 63-68 of event.c.

Some additional information for setting up a syncPPP
connection using network interfaces.
---------------------------------------------------------------

You need one thing beside the isdn4linux package:

  a patched pppd .. (I called it ipppd to show the difference)

Compiling isdn4linux with sync PPP:
-----------------------------------
To compile isdn4linux with the sync PPP part, you have
to answer the appropriate question when doing a "make config"
Don't forget to load the slhc.o
module before the isdn.o module, if VJ-compression support
is not compiled into your kernel. (e.g if you have no PPP or
CSLIP in the kernel)

Using isdn4linux with sync PPP:
-------------------------------
Sync PPP is just another encapsulation for isdn4linux. The
name to enable sync PPP encapsulation is 'syncppp' .. e.g:

  /sbin/isdnctrl encap ippp0 syncppp

The name of the interface is here 'ippp0'. You need
one interface with the name 'ippp0' to saturate the
ipppd, which checks the ppp version via this interface.
Currently, all devices must have the name ipppX where
'X' is a decimal value.

To set up a PPP connection you need the ipppd .. You must start
the ipppd once after installing the modules. The ipppd
communicates with the isdn4linux link-level driver using the
/dev/ippp0 to /dev/ippp15 devices. One ipppd can handle
all devices at once. If you want to use two PPP connections
at the same time, you have to connect the ipppd to two
devices .. and so on.
I've implemented one additional option for the ipppd:
 'useifip' will get (if set to not 0.0.0.0) the IP address
 for the negotiation from the attached network-interface.
(also: ipppd will try to negotiate pointopoint IP as remote IP)
You must disable BSD-compression, this implementation can't
handle compressed packets.

Check the etc/rc.isdn.syncppp in the isdn4kernel-util package
for an example setup script.

To use the MPPP stuff, you must configure a slave device
with isdn4linux. Now call the ipppd with the '+mp' option.
To increase the number of links, you must use the
'addlink' option of the isdnctrl tool. (rc.isdn.syncppp.MPPP is
an example script)

enjoy it,
    michael

X.25 support within isdn4linux
==============================

This is alpha/beta test code. Use it completely at your own risk.
As new versions appear, the stuff described here might suddenly change
or become invalid without notice.

Keep in mind:

You are using several new parts of the 2.2.x kernel series which
have not been tested in a large scale. Therefore, you might encounter
more bugs as usual.

- If you connect to an X.25 neighbour not operated by yourself, ASK the
  other side first. Be prepared that bugs in the protocol implementation
  might result in problems.

- This implementation has never wiped out my whole hard disk yet. But as
  this is experimental code, don't blame me if that happened to you.
  Backing up important data will never harm.

- Monitor your isdn connections while using this software. This should
  prevent you from undesired phone bills in case of driver problems.




How to configure the kernel
===========================

The ITU-T (former CCITT) X.25 network protocol layer has been implemented
in the Linux source tree since version 2.1.16. The isdn subsystem might be
useful to run X.25 on top of ISDN. If you want to try it, select

   "CCITT X.25 Packet Layer"

from the networking options as well as

   "ISDN Support" and "X.25 PLP on Top of ISDN"

from the ISDN subsystem options when you configure your kernel for
compilation. You currently also need to enable
"Prompt for development and/or incomplete code/drivers" from the
"Code maturity level options" menu. For the x25trace utility to work
you also need to enable "Packet socket".

For local testing it is also recommended to enable the isdnloop driver
from the isdn subsystem's configuration menu.

For testing, it is recommended that all isdn drivers and the X.25 PLP
protocol are compiled as loadable modules. Like this, you can recover
from certain errors by simply unloading and reloading the modules.



What's it for? How to use it?
=============================

X.25 on top of isdn might be useful with two different scenarios:

- You might want to access a public X.25 data network from your Linux box.
  You can use i4l if you were physically connected to the X.25 switch
  by an ISDN B-channel (leased line as well as dial up connection should
  work).

  This corresponds to ITU-T recommendation X.31 Case A (circuit-mode
  access to PSPDN [packet switched public data network]).

  NOTE: X.31 also covers a Case B (access to PSPDN via virtual
  circuit / packet mode service). The latter mode (which in theory
  also allows using the D-channel) is not supported by isdn4linux.
  It should however be possible to establish such packet mode connections
  with certain active isdn cards provided that the firmware supports X.31
  and the driver exports this functionality to the user. Currently,
  the AVM B1 driver is the only driver which does so. (It should be
  possible to access D-channel X.31 with active AVM cards using the
  CAPI interface of the AVM-B1 driver).

- Or you might want to operate certain ISDN teleservices on your linux
  box. A lot of those teleservices run on top of the ISO-8208
  (DTE-DTE mode) network layer protocol. ISO-8208 is essentially the
  same as ITU-T X.25.

  Popular candidates of such teleservices are EUROfile transfer or any
  teleservice applying ITU-T recommendation T.90.

To use the X.25 protocol on top of isdn, just create an isdn network
interface as usual, configure your own and/or peer's ISDN numbers,
and choose x25iface encapsulation by

   isdnctrl encap <iface-name> x25iface.

Once encap is set like this, the device can be used by the X.25 packet layer.

All the stuff needed for X.25 is implemented inside the isdn link
level (mainly isdn_net.c and some new source files). Thus, it should
work with every existing HL driver. I was able to successfully open X.25
connections on top of the isdnloop driver and the hisax driver.
"x25iface"-encapsulation bypasses demand dialing. Dialing will be
initiated when the upper (X.25 packet) layer requests the lapb datalink to
be established. But hangup timeout is still active. Whenever a hangup
occurs, all existing X.25 connections on that link will be cleared
It is recommended to use sufficiently large hangup-timeouts for the
isdn interfaces.


In order to set up a conforming protocol stack you also need to
specify the proper l2_prot parameter:

To operate in ISO-8208  X.25 DTE-DTE mode, use

   isdnctrl l2_prot <iface-name> x75i

To access an X.25 network switch via isdn (your linux box is the DTE), use

   isdnctrl l2_prot <iface-name> x25dte

To mimic an X.25 network switch (DCE side of the connection), use

   isdnctrl l2_prot <iface-name> x25dce

However, x25dte or x25dce is currently not supported by any real HL
level driver. The main difference between x75i and x25dte/dce is that
x25d[tc]e uses fixed lap_b addresses. With x75i, the side which
initiates the isdn connection uses the DTE's lap_b address while the
called side used the DCE's lap_b address. Thus, l2_prot x75i might
probably work if you access a public X.25 network as long as the
corresponding isdn connection is set up by you. At least one test
was successful to connect via isdn4linux to an X.25 switch using this
trick. At the switch side, a terminal adapter X.21 was used to connect
it to the isdn.


How to set up a test installation?
==================================

To test X.25 on top of isdn, you need to get

- a recent version of the "isdnctrl" program that supports setting the new
  X.25 specific parameters.

- the x25-utils-2.X package from
  ftp://ftp.hes.iki.fi/pub/ham/linux/ax25/x25utils-*
  (don't confuse the x25-utils with the ax25-utils)

- an application program that uses linux PF_X25 sockets (some are
  contained in the x25-util package).

Before compiling the user level utilities make sure that the compiler/
preprocessor will fetch the proper kernel header files of this kernel
source tree. Either make /usr/include/linux a symbolic link pointing to
this kernel's include/linux directory or set the appropriate compiler flags.

When all drivers and interfaces are loaded and configured you need to
ifconfig the network interfaces up and add X.25-routes to them. Use
the usual ifconfig tool.

ifconfig <iface-name> up

But a special x25route tool (distributed with the x25-util package)
is needed to set up X.25 routes. I.e.

x25route add 01 <iface-name>

will cause all x.25 connections to the destination X.25-address
"01" to be routed to your created isdn network interface.

There are currently no real X.25 applications available. However, for
tests, the x25-utils package contains a modified version of telnet
and telnetd that uses X.25 sockets instead of tcp/ip sockets. You can
use those for your first tests. Furthermore, you might check
ftp://ftp.hamburg.pop.de/pub/LOCAL/linux/i4l-eft/ which contains some
alpha-test implementation ("eftp4linux") of the EUROfile transfer
protocol.

The scripts distributed with the eftp4linux test releases might also
provide useful examples for setting up X.25 on top of isdn.

The x25-utility package also contains an x25trace tool that can be
used to monitor X.25 packets received by the network interfaces.
The /proc/net/x25* files also contain useful information.

- Henner