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.isdn4linux.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.linux.no/teles_cs.txt
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 zImage; make modules; make modules_install
2. Install the new kernel
     cp /usr/src/linux/arch/x86/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.3 2000/08/06 09:22:51 armin 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.8 1999/07/11 17:17:29 armin 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 longer 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

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

GigaSet 307x Device Driver
==========================

1.   Requirements
     ------------
1.1. Hardware
     --------
     This driver supports the connection of the Gigaset 307x/417x family of
     ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
     connection. The following devices are reported to be compatible:

     Bases:
        Siemens Gigaset 3070/3075 isdn
        Siemens Gigaset 4170/4175 isdn
        Siemens Gigaset SX205/255
        Siemens Gigaset SX353
        T-Com Sinus 45 [AB] isdn
        T-Com Sinus 721X[A] [SE]
        Vox Chicago 390 ISDN (KPN Telecom)

     RS232 data boxes:
        Siemens Gigaset M101 Data
        T-Com Sinus 45 Data 1

     USB data boxes:
        Siemens Gigaset M105 Data
        Siemens Gigaset USB Adapter DECT
        T-Com Sinus 45 Data 2
        T-Com Sinus 721 data
        Chicago 390 USB (KPN)

     See also http://www.erbze.info/sinus_gigaset.htm and
              http://gigaset307x.sourceforge.net/

     We had also reports from users of Gigaset M105 who could use the drivers
     with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.)
     If you have another device that works with our driver, please let us know.

     Chances of getting an USB device to work are good if the output of
        lsusb
     at the command line contains one of the following:
        ID 0681:0001
        ID 0681:0002
        ID 0681:0009
        ID 0681:0021
        ID 0681:0022

1.2. Software
     --------
     The driver works with the Kernel CAPI subsystem as well as the old
     ISDN4Linux subsystem, so it can be used with any software which is able
     to use CAPI 2.0 or ISDN4Linux for ISDN connections (voice or data).

     There are some user space tools available at
     http://sourceforge.net/projects/gigaset307x/
     which provide access to additional device specific functions like SMS,
     phonebook or call journal.


2.   How to use the driver
     ---------------------
2.1. Modules
     -------
     For the devices to work, the proper kernel modules have to be loaded.
     This normally happens automatically when the system detects the USB
     device (base, M105) or when the line discipline is attached (M101). It
     can also be triggered manually using the modprobe(8) command, for example
     for troubleshooting or to pass module parameters.

     The module ser_gigaset provides a serial line discipline N_GIGASET_M101
     which uses the regular serial port driver to access the device, and must
     therefore be attached to the serial device to which the M101 is connected.
     The ldattach(8) command (included in util-linux-ng release 2.14 or later)
     can be used for that purpose, for example:
	ldattach GIGASET_M101 /dev/ttyS1
     This will open the device file, attach the line discipline to it, and
     then sleep in the background, keeping the device open so that the line
     discipline remains active. To deactivate it, kill the daemon, for example
     with
	killall ldattach
     before disconnecting the device. To have this happen automatically at
     system startup/shutdown on an LSB compatible system, create and activate
     an appropriate LSB startup script /etc/init.d/gigaset. (The init name
     'gigaset' is officially assigned to this project by LANANA.)
     Alternatively, just add the 'ldattach' command line to /etc/rc.local.

     The modules accept the following parameters:

	Module	 	Parameter  Meaning

	gigaset	 	debug	   debug level (see section 3.2.)

			startmode  initial operation mode (see section 2.5.):
	bas_gigaset )		   1=ISDN4linux/CAPI (default), 0=Unimodem
	ser_gigaset )
	usb_gigaset )	cidmode    initial Call-ID mode setting (see section
				   2.5.): 1=on (default), 0=off

     Depending on your distribution you may want to create a separate module
     configuration file like /etc/modprobe.d/gigaset.conf for these.

2.2. Device nodes for user space programs
     ------------------------------------
     The device can be accessed from user space (eg. by the user space tools
     mentioned in 1.2.) through the device nodes:

     - /dev/ttyGS0 for M101 (RS232 data boxes)
     - /dev/ttyGU0 for M105 (USB data boxes)
     - /dev/ttyGB0 for the base driver (direct USB connection)

     If you connect more than one device of a type, they will get consecutive
     device nodes, eg. /dev/ttyGU1 for a second M105.

     You can also set a "default device" for the user space tools to use when
     no device node is given as parameter, by creating a symlink /dev/ttyG to
     one of them, eg.:

	ln -s /dev/ttyGB0 /dev/ttyG

     The devices accept the following device specific ioctl calls
     (defined in gigaset_dev.h):

     ioctl(int fd, GIGASET_REDIR, int *cmd);
     If cmd==1, the device is set to be controlled exclusively through the
     character device node; access from the ISDN subsystem is blocked.
     If cmd==0, the device is set to be used from the ISDN subsystem and does
     not communicate through the character device node.

     ioctl(int fd, GIGASET_CONFIG, int *cmd);
     (ser_gigaset and usb_gigaset only)
     If cmd==1, the device is set to adapter configuration mode where commands
     are interpreted by the M10x DECT adapter itself instead of being
     forwarded to the base station. In this mode, the device accepts the
     commands described in Siemens document "AT-Kommando Alignment M10x Data"
     for setting the operation mode, associating with a base station and
     querying parameters like field strengh and signal quality.
     Note that there is no ioctl command for leaving adapter configuration
     mode and returning to regular operation. In order to leave adapter
     configuration mode, write the command ATO to the device.

     ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);
     (usb_gigaset only)
     Set the break characters on an M105's internal serial adapter to the six
     bytes stored in brkchars[]. Unused bytes should be set to zero.

     ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
     Retrieve version information from the driver. version[0] must be set to
     one of:
     - GIGVER_DRIVER: retrieve driver version
     - GIGVER_COMPAT: retrieve interface compatibility version
     - GIGVER_FWBASE: retrieve the firmware version of the base
     Upon return, version[] is filled with the requested version information.

2.3. CAPI
     ----
     If the driver is compiled with CAPI support (kernel configuration option
     GIGASET_CAPI) the devices will show up as CAPI controllers as soon as the
     corresponding driver module is loaded, and can then be used with CAPI 2.0
     kernel and user space applications. For user space access, the module
     capi.ko must be loaded.

     Legacy ISDN4Linux applications are supported via the capidrv
     compatibility driver. The kernel module capidrv.ko must be loaded
     explicitly with the command
        modprobe capidrv
     if needed, and cannot be unloaded again without unloading the driver
     first. (These are limitations of capidrv.)

     Most distributions handle loading and unloading of the various CAPI
     modules automatically via the command capiinit(1) from the capi4k-utils
     package or a similar mechanism. Note that capiinit(1) cannot unload the
     Gigaset drivers because it doesn't support more than one module per
     driver.

2.4. ISDN4Linux
     ----------
     If the driver is compiled without CAPI support (native ISDN4Linux
     variant), it registers the device with the legacy ISDN4Linux subsystem
     after loading the module. It can then be used with ISDN4Linux
     applications only. Most distributions provide some configuration utility
     for setting up that subsystem. Otherwise you can use some HOWTOs like
         http://www.linuxhaven.de/dlhp/HOWTO/DE-ISDN-HOWTO-5.html


2.5. Unimodem mode
     -------------
     In this mode the device works like a modem connected to a serial port
     (the /dev/ttyGU0, ... mentioned above) which understands the commands

         ATZ                 init, reset
             => OK or ERROR
         ATD
         ATDT                dial
             => OK, CONNECT,
                BUSY,
                NO DIAL TONE,
                NO CARRIER,
                NO ANSWER
         <pause>+++<pause>   change to command mode when connected
         ATH                 hangup

     You can use some configuration tool of your distribution to configure this
     "modem" or configure pppd/wvdial manually. There are some example ppp
     configuration files and chat scripts in the gigaset-VERSION/ppp directory
     in the driver packages from http://sourceforge.net/projects/gigaset307x/.
     Please note that the USB drivers are not able to change the state of the
     control lines. This means you must use "Stupid Mode" if you are using
     wvdial or you should use the nocrtscts option of pppd.
     You must also assure that the ppp_async module is loaded with the parameter
     flag_time=0. You can do this e.g. by adding a line like

        options ppp_async flag_time=0

     to an appropriate module configuration file, like
     /etc/modprobe.d/gigaset.conf.

     Unimodem mode is needed for making some devices [e.g. SX100] work which
     do not support the regular Gigaset command set. If debug output (see
     section 3.2.) shows something like this when dialing:
         CMD Received: ERROR
         Available Params: 0
         Connection State: 0, Response: -1
         gigaset_process_response: resp_code -1 in ConState 0 !
         Timeout occurred
     then switching to unimodem mode may help.

     If you have installed the command line tool gigacontr, you can enter
     unimodem mode using
         gigacontr --mode unimodem
     You can switch back using
         gigacontr --mode isdn

     You can also put the driver directly into Unimodem mode when it's loaded,
     by passing the module parameter startmode=0 to the hardware specific
     module, e.g.
	modprobe usb_gigaset startmode=0
     or by adding a line like
	options usb_gigaset startmode=0
     to an appropriate module configuration file, like
     /etc/modprobe.d/gigaset.conf

2.6. Call-ID (CID) mode
     ------------------
     Call-IDs are numbers used to tag commands to, and responses from, the
     Gigaset base in order to support the simultaneous handling of multiple
     ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem
     mode"). Without Call-IDs (in Unimodem mode), only a very limited set of
     functions is available. It allows outgoing data connections only, but
     does not signal incoming calls or other base events.

     DECT cordless data devices (M10x) permanently occupy the cordless
     connection to the base while Call-IDs are activated. As the Gigaset
     bases only support one DECT data connection at a time, this prevents
     other DECT cordless data devices from accessing the base.

     During active operation, the driver switches to the necessary mode
     automatically. However, for the reasons above, the mode chosen when
     the device is not in use (idle) can be selected by the user.
     - If you want to receive incoming calls, you can use the default
       settings (CID mode).
     - If you have several DECT data devices (M10x) which you want to use
       in turn, select Unimodem mode by passing the parameter "cidmode=0" to
       the appropriate driver module (ser_gigaset or usb_gigaset).

     If you want both of these at once, you are out of luck.

     You can also use the tty class parameter "cidmode" of the device to
     change its CID mode while the driver is loaded, eg.
        echo 0 > /sys/class/tty/ttyGU0/cidmode

2.7. Dialing Numbers
     ---------------
     The called party number provided by an application for dialing out must
     be a public network number according to the local dialing plan, without
     any dial prefix for getting an outside line.

     Internal calls can be made by providing an internal extension number
     prefixed with "**" (two asterisks) as the called party number. So to dial
     eg. the first registered DECT handset, give "**11" as the called party
     number. Dialing "***" (three asterisks) calls all extensions
     simultaneously (global call).

     This holds for both CAPI 2.0 and ISDN4Linux applications. Unimodem mode
     does not support internal calls.

2.8. Unregistered Wireless Devices (M101/M105)
     -----------------------------------------
     The main purpose of the ser_gigaset and usb_gigaset drivers is to allow
     the M101 and M105 wireless devices to be used as ISDN devices for ISDN
     connections through a Gigaset base. Therefore they assume that the device
     is registered to a DECT base.

     If the M101/M105 device is not registered to a base, initialization of
     the device fails, and a corresponding error message is logged by the
     driver. In that situation, a restricted set of functions is available
     which includes, in particular, those necessary for registering the device
     to a base or for switching it between Fixed Part and Portable Part
     modes. See the gigacontr(8) manpage for details.

3.   Troubleshooting
     ---------------
3.1. Solutions to frequently reported problems
     -----------------------------------------
     Problem:
        You have a slow provider and isdn4linux gives up dialing too early.
     Solution:
        Load the isdn module using the dialtimeout option. You can do this e.g.
        by adding a line like

           options isdn dialtimeout=15

        to /etc/modprobe.d/gigaset.conf or a similar file.

     Problem:
        The isdnlog program emits error messages or just doesn't work.
     Solution:
        Isdnlog supports only the HiSax driver. Do not attempt to use it with
	other drivers such as Gigaset.

     Problem:
        You have two or more DECT data adapters (M101/M105) and only the
        first one you turn on works.
     Solution:
        Select Unimodem mode for all DECT data adapters. (see section 2.5.)

     Problem:
	Messages like this:
	    usb_gigaset 3-2:1.0: Could not initialize the device.
	appear in your syslog.
     Solution:
	Check whether your M10x wireless device is correctly registered to the
	Gigaset base. (see section 2.7.)

3.2. Telling the driver to provide more information
     ----------------------------------------------
     Building the driver with the "Gigaset debugging" kernel configuration
     option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional
     information useful for debugging.

     You can control the amount of debugging information the driver produces by
     writing an appropriate value to /sys/module/gigaset/parameters/debug, e.g.
        echo 0 > /sys/module/gigaset/parameters/debug
     switches off debugging output completely,
        echo 0x302020 > /sys/module/gigaset/parameters/debug
     enables a reasonable set of debugging output messages. These values are
     bit patterns where every bit controls a certain type of debugging output.
     See the constants DEBUG_* in the source file gigaset.h for details.

     The initial value can be set using the debug parameter when loading the
     module "gigaset", e.g. by adding a line
        options gigaset debug=0
     to your module configuration file, eg. /etc/modprobe.d/gigaset.conf

     Generated debugging information can be found
     - as output of the command
         dmesg
     - in system log files written by your syslog daemon, usually
       in /var/log/, e.g. /var/log/messages.

3.3. Reporting problems and bugs
     ---------------------------
     If you can't solve problems with the driver on your own, feel free to
     use one of the forums, bug trackers, or mailing lists on
         http://sourceforge.net/projects/gigaset307x
     or write an electronic mail to the maintainers.

     Try to provide as much information as possible, such as
     - distribution
     - kernel version (uname -r)
     - gcc version (gcc --version)
     - hardware architecture (uname -m, ...)
     - type and firmware version of your device (base and wireless module,
       if any)
     - output of "lsusb -v" (if using an USB device)
     - error messages
     - relevant system log messages (it would help if you activate debug
       output as described in 3.2.)

     For help with general configuration problems not specific to our driver,
     such as isdn4linux and network configuration issues, please refer to the
     appropriate forums and newsgroups.

3.4. Reporting problem solutions
     ---------------------------
     If you solved a problem with our drivers, wrote startup scripts for your
     distribution, ... feel free to contact us (using one of the places
     mentioned in 3.3.). We'd like to add scripts, hints, documentation
     to the driver and/or the project web page.


4.   Links, other software
     ---------------------
     - Sourceforge project developing this driver and associated tools
         http://sourceforge.net/projects/gigaset307x
     - Yahoo! Group on the Siemens Gigaset family of devices
         http://de.groups.yahoo.com/group/Siemens-Gigaset
     - Siemens Gigaset/T-Sinus compatibility table
         http://www.erbze.info/sinus_gigaset.htm


5.   Credits
     -------
     Thanks to

     Karsten Keil
        for his help with isdn4linux
     Deti Fliegl
        for his base driver code
     Dennis Dietrich
        for his kernel 2.6 patches
     Andreas Rummel
        for his work and logs to get unimodem mode working
     Andreas Degert
        for his logs and patches to get cx 100 working
     Dietrich Feist
        for his generous donation of one M105 and two M101 cordless adapters
     Christoph Schweers
        for his generous donation of a M34 device

     and all the other people who sent logs and other information.

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.3.6.1 2001/02/10 14:41:19 kai Exp $
The hysdn driver has been written 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 too 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.7 2000/08/06 09:22:51 armin 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.

mISDN is a new modular ISDN driver, in the long term it should replace
the old I4L driver architecture for passiv ISDN cards.
It was designed to allow a broad range of applications and interfaces
but only have the basic function in kernel, the interface to the user
space is based on sockets with a own address family AF_ISDN.

------------------------------------------------------------------------------
 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.

<roque@di.fc.ul.pt>

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