diff options
Diffstat (limited to 'Documentation/isdn')
| -rw-r--r-- | Documentation/isdn/00-INDEX | 42 | ||||
| -rw-r--r-- | Documentation/isdn/CREDITS | 70 | ||||
| -rw-r--r-- | Documentation/isdn/HiSax.cert | 96 | ||||
| -rw-r--r-- | Documentation/isdn/INTERFACE | 759 | ||||
| -rw-r--r-- | Documentation/isdn/INTERFACE.CAPI | 355 | ||||
| -rw-r--r-- | Documentation/isdn/INTERFACE.fax | 163 | ||||
| -rw-r--r-- | Documentation/isdn/README | 599 | ||||
| -rw-r--r-- | Documentation/isdn/README.FAQ | 26 | ||||
| -rw-r--r-- | Documentation/isdn/README.HiSax | 659 | ||||
| -rw-r--r-- | Documentation/isdn/README.audio | 138 | ||||
| -rw-r--r-- | Documentation/isdn/README.avmb1 | 187 | ||||
| -rw-r--r-- | Documentation/isdn/README.concap | 259 | ||||
| -rw-r--r-- | Documentation/isdn/README.diversion | 127 | ||||
| -rw-r--r-- | Documentation/isdn/README.fax | 45 | ||||
| -rw-r--r-- | Documentation/isdn/README.gigaset | 423 | ||||
| -rw-r--r-- | Documentation/isdn/README.hfc-pci | 41 | ||||
| -rw-r--r-- | Documentation/isdn/README.hysdn | 195 | ||||
| -rw-r--r-- | Documentation/isdn/README.mISDN | 6 | ||||
| -rw-r--r-- | Documentation/isdn/README.syncppp | 58 | ||||
| -rw-r--r-- | Documentation/isdn/README.x25 | 184 | ||||
| -rw-r--r-- | Documentation/isdn/syncPPP.FAQ | 224 |
21 files changed, 4656 insertions, 0 deletions
diff --git a/Documentation/isdn/00-INDEX b/Documentation/isdn/00-INDEX new file mode 100644 index 000000000..2d1889b6c --- /dev/null +++ b/Documentation/isdn/00-INDEX @@ -0,0 +1,42 @@ +00-INDEX + - this file (info on ISDN implementation for Linux) +CREDITS + - list of the kind folks that brought you this stuff. +HiSax.cert + - information about the ITU approval certification of the HiSax driver. +INTERFACE + - description of isdn4linux Link Level and Hardware Level interfaces. +INTERFACE.fax + - description of the fax subinterface of isdn4linux. +INTERFACE.CAPI + - description of kernel CAPI Link Level to Hardware Level interface. +README + - general info on what you need and what to do for Linux ISDN. +README.FAQ + - general info for FAQ. +README.HiSax + - info on the HiSax driver which replaces the old teles. +README.audio + - info for running audio over ISDN. +README.avmb1 + - info on driver for AVM-B1 ISDN card. +README.concap + - info on "CONCAP" encapsulation protocol interface used for X.25. +README.diversion + - info on module for isdn diversion services. +README.fax + - info for using Fax over ISDN. +README.gigaset + - info on the drivers for Siemens Gigaset ISDN adapters +README.hfc-pci + - info on hfc-pci based cards. +README.hysdn + - info on driver for Hypercope active HYSDN cards +README.mISDN + - info on the Modular ISDN subsystem (mISDN) +README.syncppp + - info on running Sync PPP over ISDN. +README.x25 + - info for running X.25 over ISDN. +syncPPP.FAQ + - frequently asked questions about running PPP over ISDN. diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/CREDITS new file mode 100644 index 000000000..c1679e913 --- /dev/null +++ b/Documentation/isdn/CREDITS @@ -0,0 +1,70 @@ + +I want to thank all who contributed to this project and especially to: +(in alphabetical order) + +Thomas Bogendörfer (tsbogend@bigbug.franken.de) + Tester, lots of bugfixes and hints. + +Alan Cox (alan@lxorguk.ukuu.org.uk) + For help getting into standard-kernel. + +Henner Eisen (eis@baty.hanse.de) + For X.25 implementation. + +Volker Götz (volker@oops.franken.de) + For contribution of man-pages, the imontty-tool and a perfect + maintaining of the mailing-list at hub-wue. + +Matthias Hessler (hessler@isdn4linux.de) + For creating and maintaining the FAQ. + +Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de) + For creating the FAQ, and the leafsite HOWTO. + +Michael 'Ghandi' Herold (michael@abadonna.franken.de) + For contribution of the vbox answering machine. + +Michael Hipp (Michael.Hipp@student.uni-tuebingen.de) + For his Sync-PPP-code. + +Karsten Keil (keil@isdn4linux.de) + For adding 1TR6-support to the Teles-driver. + For the HiSax-driver. + +Michael Knigge (knick@cove.han.de) + For contributing the imon-tool + +Andreas Kool (akool@Kool.f.EUnet.de) + For contribution of the isdnlog/isdnrep-tool + +Pedro Roque Marques (roque@di.fc.ul.pt) + For lot of new ideas and the pcbit driver. + +Eberhard Mönkeberg (emoenke@gwdg.de) + For testing and help to get into kernel. + +Thomas Neumann (tn@ruhr.de) + For help with Cisco-SLARP and keepalive + +Jan den Ouden (denouden@groovin.xs4all.nl) + For contribution of the original teles-driver + +Carsten Paeth (calle@calle.in-berlin.de) + For the AVM-B1-CAPI2.0 driver + +Thomas Pfeiffer (pfeiffer@pds.de) + For V.110, extended T.70 and Hylafax extensions in isdn_tty.c + +Max Riegel (riegel@max.franken.de) + For making the ICN hardware-documentation and test-equipment available. + +Armin Schindler (mac@melware.de) + For the eicon active card driver. + +Gerhard 'Fido' Schneider (fido@wuff.mayn.de) + For heavy-duty-beta-testing with his BBS ;) + +Thomas Uhl (uhl@think.de) + For distributing the cards. + For pushing me to work ;-) + diff --git a/Documentation/isdn/HiSax.cert b/Documentation/isdn/HiSax.cert new file mode 100644 index 000000000..f2a6fcb8e --- /dev/null +++ b/Documentation/isdn/HiSax.cert @@ -0,0 +1,96 @@ +-----BEGIN PGP SIGNED MESSAGE----- + +First: + + HiSax 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. + +However, if you wish to modify the HiSax sources, please note the following: + +HiSax has passed the ITU approval test suite with ELSA Quickstep ISDN cards +and Eicon Technology Diva 2.01 PCI card. +The certification is only valid for the combination of the tested software +version and the tested hardware. Any changes to the HiSax source code may +therefore affect the certification. + +Additional ITU approval tests have been carried out for all generic cards +using Colognechip single chip solutions HFC-S PCI A for PCI cards as well +as HFC-S USB based USB ISDN ta adapters. +These tests included all layers 1-3 and as well all functional tests for +the layer 1. Because all hardware based on these chips are complete ISDN +solutions in one chip all cards and USB-TAs using these chips are to be +regarded as approved for those tests. Some additional electrical tests +of the layer 1 which are independent of the driver and related to a +special hardware used will be regarded as approved if at least one +solution has been tested including those electrical tests. So if cards +or tas have been completely approved for any other os, the approval +for those electrical tests is valid for linux, too. +Please send any questions regarding this drivers or approval abouts to +werner@isdn-development.de +Additional information and the type approval documents will be found +shortly on the Colognechip website www.colognechip.com + +If you change the main files of the HiSax ISDN stack, the certification will +become invalid. Because in most countries it is illegal to connect +unapproved ISDN equipment to the public network, I have to guarantee that +changes in HiSax do not affect the certification. + +In order to make a valid certification apparent to the user, I have built in +some validation checks that are made during the make process. The HiSax main +files are protected by md5 checksums and the md5sum file is pgp signed by +myself: + +KeyID 1024/FF992F6D 1997/01/16 Karsten Keil <kkeil@suse.de> +Key fingerprint = 92 6B F7 58 EE 86 28 C8 C4 1A E6 DC 39 89 F2 AA + +Only if the checksums are OK, and the signature of the file +"drivers/isdn/hisax/md5sums.asc" match, is the certification valid; a +message confirming this is then displayed during the hisax init process. + +The affected files are: + +drivers/isdn/hisax/isac.c +drivers/isdn/hisax/isdnl1.c +drivers/isdn/hisax/isdnl2.c +drivers/isdn/hisax/isdnl3.c +drivers/isdn/hisax/tei.c +drivers/isdn/hisax/callc.c +drivers/isdn/hisax/l3dss1.c +drivers/isdn/hisax/l3_1tr6.c +drivers/isdn/hisax/cert.c +drivers/isdn/hisax/elsa.c +drivers/isdn/hisax/diva.c +drivers/isdn/hisax/hfc_pci.c + +Please send any changes, bugfixes and patches to me rather than implementing +them directly into the HiSax sources. + +This does not reduce your rights granted by the GNU General Public License. +If you wish to change the sources, go ahead; but note that then the +certification is invalid even if you use one of the approved cards. + +Here are the certification registration numbers for ELSA Quickstep cards: +German D133361J CETECOM ICT Services GmbH 0682 +European D133362J CETECOM ICT Services GmbH 0682 + + +Karsten Keil +keil@isdn4linux.de + +-----BEGIN PGP SIGNATURE----- +Version: 2.6.3i +Charset: noconv + +iQCVAwUBOFAwqTpxHvX/mS9tAQFI2QP9GLDK2iy/KBhwReE3F7LeO+tVhffTVZ3a +20q5/z/WcIg/pnH0uTkl2UgDXBFXYl45zJyDGNpAposIFmT+Edd14o7Vj1w/BBdn +Y+5rBmJf+gyBu61da5d6bv0lpymwRa/um+ri+ilYnZ/XPfg5JKhdjGSBCJuJAElM +d2jFbTrsMYw= +=LNf9 +-----END PGP SIGNATURE----- diff --git a/Documentation/isdn/INTERFACE b/Documentation/isdn/INTERFACE new file mode 100644 index 000000000..5df17e5b2 --- /dev/null +++ b/Documentation/isdn/INTERFACE @@ -0,0 +1,759 @@ +$Id: INTERFACE,v 1.15.8.2 2001/03/13 16:17:07 kai Exp $ + +Description of the Interface between Linklevel and Hardwarelevel + of isdn4linux: + + + The Communication between Linklevel (LL) and Hardwarelevel (HL) + is based on the struct isdn_if (defined in isdnif.h). + + An HL-driver can register itself at LL by calling the function + register_isdn() with a pointer to that struct. Prior to that, it has + to preset some of the fields of isdn_if. The LL sets the rest of + the fields. All further communication is done via callbacks using + the function-pointers defined in isdn_if. + + Changes/Version numbering: + + During development of the ISDN subsystem, several changes have been + made to the interface. Before it went into kernel, the package + had a unique version number. The last version, distributed separately + was 0.7.4. When the subsystem went into kernel, every functional unit + got a separate version number. These numbers are shown at initialization, + separated by slashes: + + c.c/t.t/n.n/p.p/a.a/v.v + + where + + c.c is the revision of the common code. + t.t is the revision of the tty related code. + n.n is the revision of the network related code. + p.p is the revision of the ppp related code. + a.a is the revision of the audio related code. + v.v is the revision of the V.110 related code. + + Changes in this document are marked with '***CHANGEx' where x representing + the version number. If that number starts with 0, it refers to the old, + separately distributed package. If it starts with one of the letters + above, it refers to the revision of the corresponding module. + ***CHANGEIx refers to the revision number of the isdnif.h + +1. Description of the fields of isdn_if: + + int channels; + + This field has to be set by the HL-driver to the number of channels + supported prior to calling register_isdn(). Upon return of the call, + the LL puts an id there, which has to be used by the HL-driver when + invoking the other callbacks. + + int maxbufsize; + + ***CHANGE0.6: New since this version. + + Also to be preset by the HL-driver. With this value the HL-driver + tells the LL the maximum size of a data-packet it will accept. + + unsigned long features; + + To be preset by the HL-driver. Using this field, the HL-driver + announces the features supported. At the moment this is limited to + report the supported layer2 and layer3-protocols. For setting this + field the constants ISDN_FEATURE..., declared in isdnif.h have to be + used. + + ***CHANGE0.7.1: The line type (1TR6, EDSS1) has to be set. + + unsigned short hl_hdrlen; + + ***CHANGE0.7.4: New field. + + To be preset by the HL-driver, if it supports sk_buff's. The driver + should put here the amount of additional space needed in sk_buff's for + its internal purposes. Drivers not supporting sk_buff's should + initialize this field to 0. + + void (*rcvcallb_skb)(int, int, struct sk_buff *) + + ***CHANGE0.7.4: New field. + + This field will be set by LL. The HL-driver delivers received data- + packets by calling this function. Upon calling, the HL-driver must + already have its private data pulled off the head of the sk_buff. + + Parameter: + int driver-Id + int Channel-number locally to the driver. (starting with 0) + struct sk_buff * Pointer to sk_buff, containing received data. + + int (*statcallb)(isdn_ctrl*); + + This field will be set by LL. This function has to be called by the + HL-driver for signaling status-changes or other events to the LL. + + Parameter: + isdn_ctrl* + + The struct isdn_ctrl also defined in isdn_if. The exact meanings of its + fields are described together with the descriptions of the possible + events. Here is only a short description of the fields: + + driver = driver Id. + command = event-type. (one of the constants ISDN_STAT_...) + arg = depends on event-type. + num = depends on event-type. + + Returnvalue: + 0 on success, else -1 + + int (*command)(isdn_ctrl*); + + This field has to be preset by the HL-driver. It points to a function, + to be called by LL to perform functions like dialing, B-channel + setup, etc. The exact meaning of the parameters is described with the + descriptions of the possible commands. + + Parameter: + isdn_ctrl* + driver = driver-Id + command = command to perform. (one of the constants ISDN_CMD_...) + arg = depends on command. + num = depends on command. + + Returnvalue: + >=0 on success, else error-code (-ENODEV etc.) + + int (*writebuf_skb)(int, int, int, struct sk_buff *) + + ***CHANGE0.7.4: New field. + ***CHANGEI.1.21: New field. + + This field has to be preset by the HL-driver. The given function will + be called by the LL for delivering data to be send via B-Channel. + + + Parameter: + int driver-Id ***CHANGE0.7.4: New parameter. + int channel-number locally to the HL-driver. (starts with 0) + int ack ***ChangeI1.21: New parameter + If this is !0, the driver has to signal the delivery + by sending an ISDN_STAT_BSENT. If this is 0, the driver + MUST NOT send an ISDN_STAT_BSENT. + struct sk_buff * Pointer to sk_buff containing data to be send via + B-channel. + + Returnvalue: + Length of data accepted on success, else error-code (-EINVAL on + oversized packets etc.) + + int (*writecmd)(u_char*, int, int, int, int); + + This field has to be preset by the HL-driver. The given function will be + called to perform write-requests on /dev/isdnctrl (i.e. sending commands + to the card) The data-format is hardware-specific. This function is + intended for debugging only. It is not necessary for normal operation + and never will be called by the tty-emulation- or network-code. If + this function is not supported, the driver has to set NULL here. + + Parameter: + u_char* pointer to data. + int length of data. + int flag: 0 = call from within kernel-space. (HL-driver must use + memcpy, may NOT use schedule()) + 1 = call from user-space. (HL-driver must use + memcpy_fromfs, use of schedule() allowed) + int driver-Id. + int channel-number locally to the HL-driver. (starts with 0) + +***CHANGEI1.14: The driver-Id and channel-number are new since this revision. + + Returnvalue: + Length of data accepted on success, else error-code (-EINVAL etc.) + + int (*readstat)(u_char*, int, int, int, int); + + This field has to be preset by the HL-driver. The given function will be + called to perform read-requests on /dev/isdnctrl (i.e. reading replies + from the card) The data-format is hardware-specific. This function is + intended for debugging only. It is not necessary for normal operation + and never will be called by the tty-emulation- or network-code. If + this function is not supported, the driver has to set NULL here. + + Parameter: + u_char* pointer to data. + int length of data. + int flag: 0 = call from within kernel-space. (HL-driver must use + memcpy, may NOT use schedule()) + 1 = call from user-space. (HL-driver must use + memcpy_fromfs, use of schedule() allowed) + int driver-Id. + int channel-number locally to the HL-driver. (starts with 0) + +***CHANGEI1.14: The driver-Id and channel-number are new since this revision. + + Returnvalue: + Length of data on success, else error-code (-EINVAL etc.) + + char id[20]; + ***CHANGE0.7: New since this version. + + This string has to be preset by the HL-driver. Its purpose is for + identification of the driver by the user. Eg.: it is shown in the + status-info of /dev/isdninfo. Furthermore it is used as Id for binding + net-interfaces to a specific channel. If a string of length zero is + given, upon return, isdn4linux will replace it by a generic name. (line0, + line1 etc.) It is recommended to make this string configurable during + module-load-time. (copy a global variable to this string.) For doing that, + modules 1.2.8 or newer are necessary. + +2. Description of the commands, a HL-driver has to support: + + All commands will be performed by calling the function command() described + above from within the LL. The field command of the struct-parameter will + contain the desired command, the field driver is always set to the + appropriate driver-Id. + + Until now, the following commands are defined: + +***CHANGEI1.34: The parameter "num" has been replaced by a union "parm" containing + the old "num" and a new setup_type struct used for ISDN_CMD_DIAL + and ISDN_STAT_ICALL callback. + + ISDN_CMD_IOCTL: + + This command is intended for performing ioctl-calls for configuring + hardware or similar purposes (setting port-addresses, loading firmware + etc.) For this purpose, in the LL all ioctl-calls with an argument + >= IIOCDRVCTL (0x100) will be handed transparently to this + function after subtracting 0x100 and placing the result in arg. + Example: + If a userlevel-program calls ioctl(0x101,...) the function gets + called with the field command set to 1. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_IOCTL + arg = Original ioctl-cmd - IIOCDRVCTL + parm.num = first bytes filled with (unsigned long)arg + + Returnvalue: + Depending on driver. + + + ISDN_CMD_DIAL: + + This command is used to tell the HL-driver it should dial a given + number. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_DIAL + arg = channel-number locally to the driver. (starting with 0) + + parm.setup.phone = An ASCII-String containing the number to dial. + parm.setup.eazmsn = An ASCII-Sting containing the own EAZ or MSN. + parm.setup.si1 = The Service-Indicator. + parm.setup.si2 = Additional Service-Indicator. + + If the Line has been designed as SPV (a special german + feature, meaning semi-leased-line) the phone has to + start with an "S". + ***CHANGE0.6: In previous versions the EAZ has been given in the + highbyte of arg. + ***CHANGE0.7.1: New since this version: ServiceIndicator and AddInfo. + + ISDN_CMD_ACCEPTD: + + With this command, the HL-driver is told to accept a D-Channel-setup. + (Response to an incoming call) + + Parameter: + driver = driver-Id. + command = ISDN_CMD_ACCEPTD + arg = channel-number locally to the driver. (starting with 0) + parm = unused. + + ISDN_CMD_ACCEPTB: + + With this command, the HL-driver is told to perform a B-Channel-setup. + (after establishing D-Channel-Connection) + + Parameter: + driver = driver-Id. + command = ISDN_CMD_ACCEPTB + arg = channel-number locally to the driver. (starting with 0) + parm = unused. + + ISDN_CMD_HANGUP: + + With this command, the HL-driver is told to hangup (B-Channel if + established first, then D-Channel). This command is also used for + actively rejecting an incoming call. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_HANGUP + arg = channel-number locally to the driver. (starting with 0) + parm = unused. + + ISDN_CMD_CLREAZ: + + With this command, the HL-driver is told not to signal incoming + calls to the LL. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_CLREAZ + arg = channel-number locally to the driver. (starting with 0) + parm = unused. + + ISDN_CMD_SETEAZ: + + With this command, the HL-driver is told to signal incoming calls for + the given EAZs/MSNs to the LL. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_SETEAZ + arg = channel-number locally to the driver. (starting with 0) + parm.num = ASCII-String, containing the desired EAZ's/MSN's + (comma-separated). If an empty String is given, the + HL-driver should respond to ALL incoming calls, + regardless of the destination-address. + ***CHANGE0.6: New since this version the "empty-string"-feature. + + ISDN_CMD_GETEAZ: (currently unused) + + With this command, the HL-driver is told to report the current setting + given with ISDN_CMD_SETEAZ. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_GETEAZ + arg = channel-number locally to the driver. (starting with 0) + parm.num = ASCII-String, containing the current EAZ's/MSN's + + ISDN_CMD_SETSIL: (currently unused) + + With this command, the HL-driver is told to signal only incoming + calls with the given Service-Indicators. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_SETSIL + arg = channel-number locally to the driver. (starting with 0) + parm.num = ASCII-String, containing the desired Service-Indicators. + + ISDN_CMD_GETSIL: (currently unused) + + With this command, the HL-driver is told to return the current + Service-Indicators it will respond to. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_SETSIL + arg = channel-number locally to the driver. (starting with 0) + parm.num = ASCII-String, containing the current Service-Indicators. + + ISDN_CMD_SETL2: + + With this command, the HL-driver is told to select the given Layer-2- + protocol. This command is issued by the LL prior to ISDN_CMD_DIAL or + ISDN_CMD_ACCEPTD. + + + Parameter: + driver = driver-Id. + command = ISDN_CMD_SETL2 + arg = channel-number locally to the driver. (starting with 0) + logical or'ed with (protocol-Id << 8) + protocol-Id is one of the constants ISDN_PROTO_L2... + parm = unused. + + ISDN_CMD_GETL2: (currently unused) + + With this command, the HL-driver is told to return the current + setting of the Layer-2-protocol. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_GETL2 + arg = channel-number locally to the driver. (starting with 0) + parm = unused. + Returnvalue: + current protocol-Id (one of the constants ISDN_L2_PROTO) + + ISDN_CMD_SETL3: + + With this command, the HL-driver is told to select the given Layer-3- + protocol. This command is issued by the LL prior to ISDN_CMD_DIAL or + ISDN_CMD_ACCEPTD. + + + Parameter: + driver = driver-Id. + command = ISDN_CMD_SETL3 + arg = channel-number locally to the driver. (starting with 0) + logical or'ed with (protocol-Id << 8) + protocol-Id is one of the constants ISDN_PROTO_L3... + parm.fax = Pointer to T30_s fax struct. (fax usage only) + + ISDN_CMD_GETL2: (currently unused) + + With this command, the HL-driver is told to return the current + setting of the Layer-3-protocol. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_GETL3 + arg = channel-number locally to the driver. (starting with 0) + parm = unused. + Returnvalue: + current protocol-Id (one of the constants ISDN_L3_PROTO) + + ISDN_CMD_PROCEED: + + With this command, the HL-driver is told to proceed with a incoming call. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_PROCEED + arg = channel-number locally to the driver. (starting with 0) + setup.eazmsn= empty string or string send as uus1 in DSS1 with + PROCEED message + + ISDN_CMD_ALERT: + + With this command, the HL-driver is told to alert a proceeding call. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_ALERT + arg = channel-number locally to the driver. (starting with 0) + setup.eazmsn= empty string or string send as uus1 in DSS1 with + ALERT message + + ISDN_CMD_REDIR: + + With this command, the HL-driver is told to redirect a call in proceeding + or alerting state. + + Parameter: + driver = driver-Id. + command = ISDN_CMD_REDIR + arg = channel-number locally to the driver. (starting with 0) + setup.eazmsn= empty string or string send as uus1 in DSS1 protocol + setup.screen= screening indicator + setup.phone = redirected to party number + + ISDN_CMD_PROT_IO: + + With this call, the LL-driver invokes protocol specific features through + the LL. + The call is not implicitely bound to a connection. + + Parameter: + driver = driver-Id + command = ISDN_CMD_PROT_IO + arg = The lower 8 Bits define the addressed protocol as defined + in ISDN_PTYPE..., the upper bits are used to differentiate + the protocol specific CMD. + + para = protocol and function specific. See isdnif.h for detail. + + + ISDN_CMD_FAXCMD: + + With this command the HL-driver receives a fax sub-command. + For details refer to INTERFACE.fax + + Parameter: + driver = driver-Id. + command = ISDN_CMD_FAXCMD + arg = channel-number locally to the driver. (starting with 0) + parm = unused. + + +3. Description of the events to be signaled by the HL-driver to the LL. + + All status-changes are signaled via calling the previously described + function statcallb(). The field command of the struct isdn_cmd has + to be set by the HL-driver with the appropriate Status-Id (event-number). + The field arg has to be set to the channel-number (locally to the driver, + starting with 0) to which this event applies. (Exception: STAVAIL-event) + + Until now, the following Status-Ids are defined: + + ISDN_STAT_AVAIL: + + With this call, the HL-driver signals the availability of new data + for readstat(). Used only for debugging-purposes, see description + of readstat(). + + Parameter: + driver = driver-Id + command = ISDN_STAT_STAVAIL + arg = length of available data. + parm = unused. + + ISDN_STAT_ICALL: + ISDN_STAT_ICALLW: + + With this call, the HL-driver signals an incoming call to the LL. + If ICALLW is signalled the incoming call is a waiting call without + a available B-chan. + + Parameter: + driver = driver-Id + command = ISDN_STAT_ICALL + arg = channel-number, locally to the driver. (starting with 0) + para.setup.phone = Callernumber. + para.setup.eazmsn = CalledNumber. + para.setup.si1 = Service Indicator. + para.setup.si2 = Additional Service Indicator. + para.setup.plan = octet 3 from Calling party number Information Element. + para.setup.screen = octet 3a from Calling party number Information Element. + + Return: + 0 = No device matching this call. + 1 = At least one device matching this call (RING on ttyI). + HL-driver may send ALERTING on the D-channel in this case. + 2 = Call will be rejected. + 3 = Incoming called party number is currently incomplete. + Additional digits are required. + Used for signalling with PtP connections. + 4 = Call will be held in a proceeding state + (HL driver sends PROCEEDING) + Used when a user space prog needs time to interpret a call + para.setup.eazmsn may be filled with an uus1 message of + 30 octets maximum. Empty string if no uus. + 5 = Call will be actively deflected to another party + Only available in DSS1/EURO protocol + para.setup.phone must be set to destination party number + para.setup.eazmsn may be filled with an uus1 message of + 30 octets maximum. Empty string if no uus. + -1 = An error happened. (Invalid parameters for example.) + The keypad support now is included in the dial command. + + + ISDN_STAT_RUN: + + With this call, the HL-driver signals availability of the ISDN-card. + (after initializing, loading firmware) + + Parameter: + driver = driver-Id + command = ISDN_STAT_RUN + arg = unused. + parm = unused. + + ISDN_STAT_STOP: + + With this call, the HL-driver signals unavailability of the ISDN-card. + (before unloading, while resetting/reconfiguring the card) + + Parameter: + driver = driver-Id + command = ISDN_STAT_STOP + arg = unused. + parm = unused. + + ISDN_STAT_DCONN: + + With this call, the HL-driver signals the successful establishment of + a D-Channel-connection. (Response to ISDN_CMD_ACCEPTD or ISDN_CMD_DIAL) + + Parameter: + driver = driver-Id + command = ISDN_STAT_DCONN + arg = channel-number, locally to the driver. (starting with 0) + parm = unused. + + ISDN_STAT_BCONN: + + With this call, the HL-driver signals the successful establishment of + a B-Channel-connection. (Response to ISDN_CMD_ACCEPTB or because the + remote-station has initiated establishment) + + The HL driver should call this when the logical l2/l3 protocol + connection on top of the physical B-channel is established. + + Parameter: + driver = driver-Id + command = ISDN_STAT_BCONN + arg = channel-number, locally to the driver. (starting with 0) + parm.num = ASCII-String, containing type of connection (for analog + modem only). This will be appended to the CONNECT message + e.g. 14400/V.32bis + + ISDN_STAT_DHUP: + + With this call, the HL-driver signals the shutdown of a + D-Channel-connection. This could be a response to a prior ISDN_CMD_HANGUP, + or caused by a remote-hangup or if the remote-station has actively + rejected a call. + + Parameter: + driver = driver-Id + command = ISDN_STAT_DHUP + arg = channel-number, locally to the driver. (starting with 0) + parm = unused. + + ISDN_STAT_BHUP: + + With this call, the HL-driver signals the shutdown of a + B-Channel-connection. This could be a response to a prior ISDN_CMD_HANGUP, + or caused by a remote-hangup. + + The HL driver should call this as soon as the logical l2/l3 protocol + connection on top of the physical B-channel is released. + + Parameter: + driver = driver-Id + command = ISDN_STAT_BHUP + arg = channel-number, locally to the driver. (starting with 0) + parm = unused. + + ISDN_STAT_CINF: + + With this call, the HL-driver delivers charge-unit information to the + LL. + + Parameter: + driver = driver-Id + command = ISDN_STAT_CINF + arg = channel-number, locally to the driver. (starting with 0) + parm.num = ASCII string containing charge-units (digits only). + + ISDN_STAT_LOAD: (currently unused) + + ISDN_STAT_UNLOAD: + + With this call, the HL-driver signals that it will be unloaded now. This + tells the LL to release all corresponding data-structures. + + Parameter: + driver = driver-Id + command = ISDN_STAT_UNLOAD + arg = unused. + parm = unused. + + ISDN_STAT_BSENT: + + With this call the HL-driver signals the delivery of a data-packet. + This callback is used by the network-interfaces only, tty-Emulation + does not need this call. + + Parameter: + driver = driver-Id + command = ISDN_STAT_BSENT + arg = channel-number, locally to the driver. (starting with 0) + parm.length = ***CHANGEI.1.21: New field. + the driver has to set this to the original length + of the skb at the time of receiving it from the linklevel. + + ISDN_STAT_NODCH: + + With this call, the driver has to respond to a prior ISDN_CMD_DIAL, if + no D-Channel is available. + + Parameter: + driver = driver-Id + command = ISDN_STAT_NODCH + arg = channel-number, locally to the driver. (starting with 0) + parm = unused. + + ISDN_STAT_ADDCH: + + This call is for HL-drivers, which are unable to check card-type + or numbers of supported channels before they have loaded any firmware + using ioctl. Those HL-driver simply set the channel-parameter to a + minimum channel-number when registering, and later if they know + the real amount, perform this call, allocating additional channels. + + Parameter: + driver = driver-Id + command = ISDN_STAT_ADDCH + arg = number of channels to be added. + parm = unused. + + ISDN_STAT_CAUSE: + + With this call, the HL-driver delivers CAUSE-messages to the LL. + Currently the LL does not use this messages. Their contents is simply + logged via kernel-messages. Therefore, currently the format of the + messages is completely free. However they should be printable. + + Parameter: + driver = driver-Id + command = ISDN_STAT_NODCH + arg = channel-number, locally to the driver. (starting with 0) + parm.num = ASCII string containing CAUSE-message. + + ISDN_STAT_DISPLAY: + + With this call, the HL-driver delivers DISPLAY-messages to the LL. + Currently the LL does not use this messages. + + Parameter: + driver = driver-Id + command = ISDN_STAT_DISPLAY + arg = channel-number, locally to the driver. (starting with 0) + para.display= string containing DISPLAY-message. + + ISDN_STAT_PROT: + + With this call, the HL-driver delivers protocol specific infos to the LL. + The call is not implicitely bound to a connection. + + Parameter: + driver = driver-Id + command = ISDN_STAT_PROT + arg = The lower 8 Bits define the addressed protocol as defined + in ISDN_PTYPE..., the upper bits are used to differentiate + the protocol specific STAT. + + para = protocol and function specific. See isdnif.h for detail. + + ISDN_STAT_DISCH: + + With this call, the HL-driver signals the LL to disable or enable the + use of supplied channel and driver. + The call may be used to reduce the available number of B-channels after + loading the driver. The LL has to ignore a disabled channel when searching + for free channels. The HL driver itself never delivers STAT callbacks for + disabled channels. + The LL returns a nonzero code if the operation was not successful or the + selected channel is actually regarded as busy. + + Parameter: + driver = driver-Id + command = ISDN_STAT_DISCH + arg = channel-number, locally to the driver. (starting with 0) + parm.num[0] = 0 if channel shall be disabled, else enabled. + + ISDN_STAT_L1ERR: + + ***CHANGEI1.21 new status message. + A signal can be sent to the linklevel if an Layer1-error results in + packet-loss on receive or send. The field errcode of the cmd.parm + union describes the error more precisely. + + Parameter: + driver = driver-Id + command = ISDN_STAT_L1ERR + arg = channel-number, locally to the driver. (starting with 0) + parm.errcode= ISDN_STAT_L1ERR_SEND: Packet lost while sending. + ISDN_STAT_L1ERR_RECV: Packet lost while receiving. + ISDN_STAT_FAXIND: + + With this call the HL-driver signals a fax sub-command to the LL. + For details refer to INTERFACE.fax + + Parameter: + driver = driver-Id. + command = ISDN_STAT_FAXIND + arg = channel-number, locally to the driver. (starting with 0) + parm = unused. + diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI new file mode 100644 index 000000000..021aa9cf1 --- /dev/null +++ b/Documentation/isdn/INTERFACE.CAPI @@ -0,0 +1,355 @@ +Kernel CAPI Interface to Hardware Drivers +----------------------------------------- + +1. Overview + +From the CAPI 2.0 specification: +COMMON-ISDN-API (CAPI) is an application programming interface standard used +to access ISDN equipment connected to basic rate interfaces (BRI) and primary +rate interfaces (PRI). + +Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI +hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI +lingo) with Kernel CAPI to indicate their readiness to provide their service +to CAPI applications. CAPI applications also register with Kernel CAPI, +requesting association with a CAPI device. Kernel CAPI then dispatches the +application registration to an available device, forwarding it to the +corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both +directions between the application and the hardware driver. + +Format and semantics of CAPI messages are specified in the CAPI 2.0 standard. +This standard is freely available from https://www.capi.org. + + +2. Driver and Device Registration + +CAPI drivers optionally register themselves with Kernel CAPI by calling the +Kernel CAPI function register_capi_driver() with a pointer to a struct +capi_driver. This structure must be filled with the name and revision of the +driver, and optionally a pointer to a callback function, add_card(). The +registration can be revoked by calling the function unregister_capi_driver() +with a pointer to the same struct capi_driver. + +CAPI drivers must register each of the ISDN devices they control with Kernel +CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a +struct capi_ctr before they can be used. This structure must be filled with +the names of the driver and controller, and a number of callback function +pointers which are subsequently used by Kernel CAPI for communicating with the +driver. The registration can be revoked by calling the function +detach_capi_ctr() with a pointer to the same struct capi_ctr. + +Before the device can be actually used, the driver must fill in the device +information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr +structure of the device, and signal its readiness by calling capi_ctr_ready(). +From then on, Kernel CAPI may call the registered callback functions for the +device. + +If the device becomes unusable for any reason (shutdown, disconnect ...), the +driver has to call capi_ctr_down(). This will prevent further calls to the +callback functions by Kernel CAPI. + + +3. Application Registration and Communication + +Kernel CAPI forwards registration requests from applications (calls to CAPI +operation CAPI_REGISTER) to an appropriate hardware driver by calling its +register_appl() callback function. A unique Application ID (ApplID, u16) is +allocated by Kernel CAPI and passed to register_appl() along with the +parameter structure provided by the application. This is analogous to the +open() operation on regular files or character devices. + +After a successful return from register_appl(), CAPI messages from the +application may be passed to the driver for the device via calls to the +send_message() callback function. Conversely, the driver may call Kernel +CAPI's capi_ctr_handle_message() function to pass a received CAPI message to +Kernel CAPI for forwarding to an application, specifying its ApplID. + +Deregistration requests (CAPI operation CAPI_RELEASE) from applications are +forwarded as calls to the release_appl() callback function, passing the same +ApplID as with register_appl(). After return from release_appl(), no CAPI +messages for that application may be passed to or from the device anymore. + + +4. Data Structures + +4.1 struct capi_driver + +This structure describes a Kernel CAPI driver itself. It is used in the +register_capi_driver() and unregister_capi_driver() functions, and contains +the following non-private fields, all to be set by the driver before calling +register_capi_driver(): + +char name[32] + the name of the driver, as a zero-terminated ASCII string +char revision[32] + the revision number of the driver, as a zero-terminated ASCII string +int (*add_card)(struct capi_driver *driver, capicardparams *data) + a callback function pointer (may be NULL) + + +4.2 struct capi_ctr + +This structure describes an ISDN device (controller) handled by a Kernel CAPI +driver. After registration via the attach_capi_ctr() function it is passed to +all controller specific lower layer interface and callback functions to +identify the controller to operate on. + +It contains the following non-private fields: + +- to be set by the driver before calling attach_capi_ctr(): + +struct module *owner + pointer to the driver module owning the device + +void *driverdata + an opaque pointer to driver specific data, not touched by Kernel CAPI + +char name[32] + the name of the controller, as a zero-terminated ASCII string + +char *driver_name + the name of the driver, as a zero-terminated ASCII string + +int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata) + (optional) pointer to a callback function for sending firmware and + configuration data to the device + The function may return before the operation has completed. + Completion must be signalled by a call to capi_ctr_ready(). + Return value: 0 on success, error code on error + Called in process context. + +void (*reset_ctr)(struct capi_ctr *ctrlr) + (optional) pointer to a callback function for stopping the device, + releasing all registered applications + The function may return before the operation has completed. + Completion must be signalled by a call to capi_ctr_down(). + Called in process context. + +void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, + capi_register_params *rparam) +void (*release_appl)(struct capi_ctr *ctrlr, u16 applid) + pointers to callback functions for registration and deregistration of + applications with the device + Calls to these functions are serialized by Kernel CAPI so that only + one call to any of them is active at any time. + +u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb) + pointer to a callback function for sending a CAPI message to the + device + Return value: CAPI error code + If the method returns 0 (CAPI_NOERROR) the driver has taken ownership + of the skb and the caller may no longer access it. If it returns a + non-zero (error) value then ownership of the skb returns to the caller + who may reuse or free it. + The return value should only be used to signal problems with respect + to accepting or queueing the message. Errors occurring during the + actual processing of the message should be signaled with an + appropriate reply message. + May be called in process or interrupt context. + Calls to this function are not serialized by Kernel CAPI, ie. it must + be prepared to be re-entered. + +char *(*procinfo)(struct capi_ctr *ctrlr) + pointer to a callback function returning the entry for the device in + the CAPI controller info table, /proc/capi/controller + +const struct file_operations *proc_fops + pointers to callback functions for the device's proc file + system entry, /proc/capi/controllers/<n>; pointer to the device's + capi_ctr structure is available from struct proc_dir_entry::data + which is available from struct inode. + +Note: Callback functions except send_message() are never called in interrupt +context. + +- to be filled in before calling capi_ctr_ready(): + +u8 manu[CAPI_MANUFACTURER_LEN] + value to return for CAPI_GET_MANUFACTURER + +capi_version version + value to return for CAPI_GET_VERSION + +capi_profile profile + value to return for CAPI_GET_PROFILE + +u8 serial[CAPI_SERIAL_LEN] + value to return for CAPI_GET_SERIAL + + +4.3 SKBs + +CAPI messages are passed between Kernel CAPI and the driver via send_message() +and capi_ctr_handle_message(), stored in the data portion of a socket buffer +(skb). Each skb contains a single CAPI message coded according to the CAPI 2.0 +standard. + +For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual +payload data immediately follows the CAPI message itself within the same skb. +The Data and Data64 parameters are not used for processing. The Data64 +parameter may be omitted by setting the length field of the CAPI message to 22 +instead of 30. + + +4.4 The _cmsg Structure + +(declared in <linux/isdn/capiutil.h>) + +The _cmsg structure stores the contents of a CAPI 2.0 message in an easily +accessible form. It contains members for all possible CAPI 2.0 parameters, +including subparameters of the Additional Info and B Protocol structured +parameters, with the following exceptions: + +* second Calling party number (CONNECT_IND) + +* Data64 (DATA_B3_REQ and DATA_B3_IND) + +* Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ) + +* Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP + and SELECT_B_PROTOCOL_REQ) + +Only those parameters appearing in the message type currently being processed +are actually used. Unused members should be set to zero. + +Members are named after the CAPI 2.0 standard names of the parameters they +represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data +types are: + +u8 for CAPI parameters of type 'byte' + +u16 for CAPI parameters of type 'word' + +u32 for CAPI parameters of type 'dword' + +_cstruct for CAPI parameters of type 'struct' + The member is a pointer to a buffer containing the parameter in + CAPI encoding (length + content). It may also be NULL, which will + be taken to represent an empty (zero length) parameter. + Subparameters are stored in encoded form within the content part. + +_cmstruct alternative representation for CAPI parameters of type 'struct' + (used only for the 'Additional Info' and 'B Protocol' parameters) + The representation is a single byte containing one of the values: + CAPI_DEFAULT: The parameter is empty/absent. + CAPI_COMPOSE: The parameter is present. + Subparameter values are stored individually in the corresponding + _cmsg structure members. + +Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert +messages between their transport encoding described in the CAPI 2.0 standard +and their _cmsg structure representation. Note that capi_cmsg2message() does +not know or check the size of its destination buffer. The caller must make +sure it is big enough to accommodate the resulting CAPI message. + + +5. Lower Layer Interface Functions + +(declared in <linux/isdn/capilli.h>) + +void register_capi_driver(struct capi_driver *drvr) +void unregister_capi_driver(struct capi_driver *drvr) + register/unregister a driver with Kernel CAPI + +int attach_capi_ctr(struct capi_ctr *ctrlr) +int detach_capi_ctr(struct capi_ctr *ctrlr) + register/unregister a device (controller) with Kernel CAPI + +void capi_ctr_ready(struct capi_ctr *ctrlr) +void capi_ctr_down(struct capi_ctr *ctrlr) + signal controller ready/not ready + +void capi_ctr_suspend_output(struct capi_ctr *ctrlr) +void capi_ctr_resume_output(struct capi_ctr *ctrlr) + signal suspend/resume + +void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, + struct sk_buff *skb) + pass a received CAPI message to Kernel CAPI + for forwarding to the specified application + + +6. Helper Functions and Macros + +Library functions (from <linux/isdn/capilli.h>): + +void capilib_new_ncci(struct list_head *head, u16 applid, + u32 ncci, u32 winsize) +void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci) +void capilib_release_appl(struct list_head *head, u16 applid) +void capilib_release(struct list_head *head) +void capilib_data_b3_conf(struct list_head *head, u16 applid, + u32 ncci, u16 msgid) +u16 capilib_data_b3_req(struct list_head *head, u16 applid, + u32 ncci, u16 msgid) + + +Macros to extract/set element values from/in a CAPI message header +(from <linux/isdn/capiutil.h>): + +Get Macro Set Macro Element (Type) + +CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16) +CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16) +CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8) +CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8) +CAPIMSG_CMD(m) - Command*256 + + Subcommand (u16) +CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16) + +CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI + (u32) +CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) + + +Library functions for working with _cmsg structures +(from <linux/isdn/capiutil.h>): + +unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg) + Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the + result in *msg. + +unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg) + Disassembles the CAPI 2.0 message in *msg, storing the parameters in + *cmsg. + +unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, + u16 Messagenumber, u32 Controller) + Fills the header part and address field of the _cmsg structure *cmsg + with the given values, zeroing the remainder of the structure so only + parameters with non-default values need to be changed before sending + the message. + +void capi_cmsg_answer(_cmsg *cmsg) + Sets the low bit of the Subcommand field in *cmsg, thereby converting + _REQ to _CONF and _IND to _RESP. + +char *capi_cmd2str(u8 Command, u8 Subcommand) + Returns the CAPI 2.0 message name corresponding to the given command + and subcommand values, as a static ASCII string. The return value may + be NULL if the command/subcommand is not one of those defined in the + CAPI 2.0 standard. + + +7. Debugging + +The module kernelcapi has a module parameter showcapimsgs controlling some +debugging output produced by the module. It can only be set when the module is +loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on +the command line or in the configuration file. + +If the lowest bit of showcapimsgs is set, kernelcapi logs controller and +application up and down events. + +In addition, every registered CAPI controller has an associated traceflag +parameter controlling how CAPI messages sent from and to tha controller are +logged. The traceflag parameter is initialized with the value of the +showcapimsgs parameter when the controller is registered, but can later be +changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE. + +If the value of traceflag is non-zero, CAPI messages are logged. +DATA_B3 messages are only logged if the value of traceflag is > 2. + +If the lowest bit of traceflag is set, only the command/subcommand and message +length are logged. Otherwise, kernelcapi logs a readable representation of +the entire message. diff --git a/Documentation/isdn/INTERFACE.fax b/Documentation/isdn/INTERFACE.fax new file mode 100644 index 000000000..9c8c6d914 --- /dev/null +++ b/Documentation/isdn/INTERFACE.fax @@ -0,0 +1,163 @@ +$Id: INTERFACE.fax,v 1.2 2000/08/06 09:22:50 armin Exp $ + + +Description of the fax-subinterface between linklevel and hardwarelevel of + isdn4linux. + + The communication between linklevel (LL) and hardwarelevel (HL) for fax + is based on the struct T30_s (defined in isdnif.h). + This struct is allocated in the LL. + In order to use fax, the LL provides the pointer to this struct with the + command ISDN_CMD_SETL3 (parm.fax). This pointer expires in case of hangup + and when a new channel to a new connection is assigned. + + +Data handling: + In send-mode the HL-driver has to handle the <DLE> codes and the bit-order + conversion by itself. + In receive-mode the LL-driver takes care of the bit-order conversion + (specified by +FBOR) + +Structure T30_s description: + + This structure stores the values (set by AT-commands), the remote- + capability-values and the command-codes between LL and HL. + + If the HL-driver receives ISDN_CMD_FAXCMD, all needed information + is in this struct set by the LL. + To signal information to the LL, the HL-driver has to set the + parameters and use ISDN_STAT_FAXIND. + (Please refer to INTERFACE) + +Structure T30_s: + + All members are 8-bit unsigned (__u8) + + - resolution + - rate + - width + - length + - compression + - ecm + - binary + - scantime + - id[] + Local faxmachine's parameters, set by +FDIS, +FDCS, +FLID, ... + + - r_resolution + - r_rate + - r_width + - r_length + - r_compression + - r_ecm + - r_binary + - r_scantime + - r_id[] + Remote faxmachine's parameters. To be set by HL-driver. + + - phase + Defines the actual state of fax connection. Set by HL or LL + depending on progress and type of connection. + If the phase changes because of an AT command, the LL driver + changes this value. Otherwise the HL-driver takes care of it, but + only necessary on call establishment (from IDLE to PHASE_A). + (one of the constants ISDN_FAX_PHASE_[IDLE,A,B,C,D,E]) + + - direction + Defines outgoing/send or incoming/receive connection. + (ISDN_TTY_FAX_CONN_[IN,OUT]) + + - code + Commands from LL to HL; possible constants : + ISDN_TTY_FAX_DR signals +FDR command to HL + + ISDN_TTY_FAX_DT signals +FDT command to HL + + ISDN_TTY_FAX_ET signals +FET command to HL + + + Other than that the "code" is set with the hangup-code value at + the end of connection for the +FHNG message. + + - r_code + Commands from HL to LL; possible constants : + ISDN_TTY_FAX_CFR output of +FCFR message. + + ISDN_TTY_FAX_RID output of remote ID set in r_id[] + (+FCSI/+FTSI on send/receive) + + ISDN_TTY_FAX_DCS output of +FDCS and CONNECT message, + switching to phase C. + + ISDN_TTY_FAX_ET signals end of data, + switching to phase D. + + ISDN_TTY_FAX_FCON signals the established, outgoing connection, + switching to phase B. + + ISDN_TTY_FAX_FCON_I signals the established, incoming connection, + switching to phase B. + + ISDN_TTY_FAX_DIS output of +FDIS message and values. + + ISDN_TTY_FAX_SENT signals that all data has been sent + and <DLE><ETX> is acknowledged, + OK message will be sent. + + ISDN_TTY_FAX_PTS signals a msg-confirmation (page sent successful), + depending on fet value: + 0: output OK message (more pages follow) + 1: switching to phase B (next document) + + ISDN_TTY_FAX_TRAIN_OK output of +FDCS and OK message (for receive mode). + + ISDN_TTY_FAX_EOP signals end of data in receive mode, + switching to phase D. + + ISDN_TTY_FAX_HNG output of the +FHNG and value set by code and + OK message, switching to phase E. + + + - badlin + Value of +FBADLIN + + - badmul + Value of +FBADMUL + + - bor + Value of +FBOR + + - fet + Value of +FET command in send-mode. + Set by HL in receive-mode for +FET message. + + - pollid[] + ID-string, set by +FCIG + + - cq + Value of +FCQ + + - cr + Value of +FCR + + - ctcrty + Value of +FCTCRTY + + - minsp + Value of +FMINSP + + - phcto + Value of +FPHCTO + + - rel + Value of +FREL + + - nbc + Value of +FNBC (0,1) + (+FNBC is not a known class 2 fax command, I added this to change the + automatic "best capabilities" connection in the eicon HL-driver) + + +Armin +mac@melware.de + diff --git a/Documentation/isdn/README b/Documentation/isdn/README new file mode 100644 index 000000000..74bd2bdb4 --- /dev/null +++ b/Documentation/isdn/README @@ -0,0 +1,599 @@ +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 + https://www.mhessler.de/i4lfaq/ + It can be viewed online, or downloaded in sgml/text/html format. + The FAQ can also be viewed online at + https://www.isdn4linux.de/faq/i4lfaq.html + 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/admin-guide/devices.rst. 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 + diff --git a/Documentation/isdn/README.FAQ b/Documentation/isdn/README.FAQ new file mode 100644 index 000000000..e5dd1adda --- /dev/null +++ b/Documentation/isdn/README.FAQ @@ -0,0 +1,26 @@ + +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: +https://www.mhessler.de/i4lfaq/ (view + download) +or: +https://www.isdn4linux.de/faq/4lfaq.html (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 + diff --git a/Documentation/isdn/README.HiSax b/Documentation/isdn/README.HiSax new file mode 100644 index 000000000..b1a573cf4 --- /dev/null +++ b/Documentation/isdn/README.HiSax @@ -0,0 +1,659 @@ +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 diff --git a/Documentation/isdn/README.audio b/Documentation/isdn/README.audio new file mode 100644 index 000000000..8ebca1929 --- /dev/null +++ b/Documentation/isdn/README.audio @@ -0,0 +1,138 @@ +$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>. + diff --git a/Documentation/isdn/README.avmb1 b/Documentation/isdn/README.avmb1 new file mode 100644 index 000000000..9e075484e --- /dev/null +++ b/Documentation/isdn/README.avmb1 @@ -0,0 +1,187 @@ +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) diff --git a/Documentation/isdn/README.concap b/Documentation/isdn/README.concap new file mode 100644 index 000000000..a76d74845 --- /dev/null +++ b/Documentation/isdn/README.concap @@ -0,0 +1,259 @@ +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. + diff --git a/Documentation/isdn/README.diversion b/Documentation/isdn/README.diversion new file mode 100644 index 000000000..bddcd5fb8 --- /dev/null +++ b/Documentation/isdn/README.diversion @@ -0,0 +1,127 @@ +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 + diff --git a/Documentation/isdn/README.fax b/Documentation/isdn/README.fax new file mode 100644 index 000000000..5314958a8 --- /dev/null +++ b/Documentation/isdn/README.fax @@ -0,0 +1,45 @@ + +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 + diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/README.gigaset new file mode 100644 index 000000000..9b1ce277c --- /dev/null +++ b/Documentation/isdn/README.gigaset @@ -0,0 +1,423 @@ +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 + (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/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 + https://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 https://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 + https://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 + https://sourceforge.net/projects/gigaset307x + - Yahoo! Group on the Siemens Gigaset family of devices + https://de.groups.yahoo.com/group/Siemens-Gigaset + - Siemens Gigaset/T-Sinus compatibility table + http://www.erbze.info/sinus_gigaset.htm + (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/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. + diff --git a/Documentation/isdn/README.hfc-pci b/Documentation/isdn/README.hfc-pci new file mode 100644 index 000000000..e8a4ef022 --- /dev/null +++ b/Documentation/isdn/README.hfc-pci @@ -0,0 +1,41 @@ +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 + + + diff --git a/Documentation/isdn/README.hysdn b/Documentation/isdn/README.hysdn new file mode 100644 index 000000000..eeca11f00 --- /dev/null +++ b/Documentation/isdn/README.hysdn @@ -0,0 +1,195 @@ +$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). + + + + + + + + + + + + + + + diff --git a/Documentation/isdn/README.mISDN b/Documentation/isdn/README.mISDN new file mode 100644 index 000000000..cd8bf920e --- /dev/null +++ b/Documentation/isdn/README.mISDN @@ -0,0 +1,6 @@ +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. + diff --git a/Documentation/isdn/README.syncppp b/Documentation/isdn/README.syncppp new file mode 100644 index 000000000..27d260095 --- /dev/null +++ b/Documentation/isdn/README.syncppp @@ -0,0 +1,58 @@ +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 + + + diff --git a/Documentation/isdn/README.x25 b/Documentation/isdn/README.x25 new file mode 100644 index 000000000..e561a77c4 --- /dev/null +++ b/Documentation/isdn/README.x25 @@ -0,0 +1,184 @@ + +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 diff --git a/Documentation/isdn/syncPPP.FAQ b/Documentation/isdn/syncPPP.FAQ new file mode 100644 index 000000000..3257a4bc0 --- /dev/null +++ b/Documentation/isdn/syncPPP.FAQ @@ -0,0 +1,224 @@ +simple isdn4linux PPP FAQ .. to be continued .. not 'debugged' +------------------------------------------------------------------- + +Q01: what's pppd, ipppd, syncPPP, asyncPPP ?? +Q02: error message "this system lacks PPP support" +Q03: strange information using 'ifconfig' +Q04: MPPP?? What's that and how can I use it ... +Q05: I tried MPPP but it doesn't work +Q06: can I use asynchronous PPP encapsulation with network devices +Q07: A SunISDN machine can't connect to my i4l system +Q08: I wanna talk to several machines, which need different configs +Q09: Starting the ipppd, I get only error messages from i4l +Q10: I wanna use dynamic IP address assignment +Q11: I can't connect. How can I check where the problem is. +Q12: How can I reduce login delay? + +------------------------------------------------------------------- + +Q01: pppd, ipppd, syncPPP, asyncPPP .. what is that ? + what should I use? +A: The pppd is for asynchronous PPP .. asynchronous means + here, the framing is character based. (e.g when + using ttyI* or tty* devices) + + The ipppd handles PPP packets coming in HDLC + frames (bit based protocol) ... The PPP driver + in isdn4linux pushes all IP packets direct + to the network layer and all PPP protocol + frames to the /dev/ippp* device. + So, the ipppd is a simple external network + protocol handler. + + If you login into a remote machine using the + /dev/ttyI* devices and then enable PPP on the + remote terminal server -> use the 'old' pppd + + If your remote side immediately starts to send + frames ... you probably connect to a + syncPPP machine .. use the network device part + of isdn4linux with the 'syncppp' encapsulation + and make sure, that the ipppd is running and + connected to at least one /dev/ippp*. Check the + isdn4linux manual on how to configure a network device. + +-- + +Q02: when I start the ipppd .. I only get the + error message "this system lacks PPP support" +A: check that at least the device 'ippp0' exists. + (you can check this e.g with the program 'ifconfig') + The ipppd NEEDS this device under THIS name .. + If this device doesn't exists, use: + isdnctrl addif ippp0 + isdnctrl encap ippp0 syncppp + ... (see isdn4linux doc for more) ... +A: Maybe you have compiled the ipppd with another + kernel source tree than the kernel you currently + run ... + +-- + +Q03: when I list the netdevices with ifconfig I see, that + my ISDN interface has a HWaddr and IRQ=0 and Base + address = 0 +A: The device is a fake ethernet device .. ignore IRQ and baseaddr + You need the HWaddr only for ethernet encapsulation. + +-- + +Q04: MPPP?? What's that and how can I use it ... + +A: MPPP or MP or MPP (Warning: MP is also an + acronym for 'Multi Processor') stands for + Multi Point to Point and means bundling + of several channels to one logical stream. + To enable MPPP negotiation you must call the + ipppd with the '+mp' option. + You must also configure a slave device for + every additional channel. (see the i4l manual + for more) + To use channel bundling you must first activate + the 'master' or initial call. Now you can add + the slave channels with the command: + isdnctrl addlink <device> + e.g: + isdnctrl addlink ippp0 + This is different from other encapsulations of + isdn4linux! With syncPPP, there is no automatic + activation of slave devices. + +-- + +Q05: I tried MPPP but it doesn't work .. the ipppd + writes in the debug log something like: + .. rcvd [0][proto=0x3d] c0 00 00 00 80 fd 01 01 00 0a ... + .. sent [0][LCP ProtRej id=0x2 00 3d c0 00 00 00 80 fd 01 ... + +A: you forgot to compile MPPP/RFC1717 support into the + ISDN Subsystem. Recompile with this option enabled. + +-- + +Q06: can I use asynchronous PPP encapsulation + over the network interface of isdn4linux .. + +A: No .. that's not possible .. Use the standard + PPP package over the /dev/ttyI* devices. You + must not use the ipppd for this. + +-- + +Q07: A SunISDN machine tries to connect my i4l system, + which doesn't work. + Checking the debug log I just saw garbage like: +!![ ... fill in the line ... ]!! + +A: The Sun tries to talk asynchronous PPP ... i4l + can't understand this ... try to use the ttyI* + devices with the standard PPP/pppd package + +A: (from Alexanter Strauss: ) +!![ ... fill in mail ]!! + +-- + +Q08: I wanna talk to remote machines, which need + a different configuration. The only way + I found to do this is to kill the ipppd and + start a new one with another config to connect + to the second machine. + +A: you must bind a network interface explicitly to + an ippp device, where you can connect a (for this + interface) individually configured ipppd. + +-- + +Q09: When I start the ipppd I only get error messages + from the i4l driver .. + +A: When starting, the ipppd calls functions which may + trigger a network packet. (e.g gethostbyname()). + Without the ipppd (at this moment, it is not + fully started) we can't handle this network request. + Try to configure hostnames necessary for the ipppd + in your local /etc/hosts file or in a way, that + your system can resolve it without using an + isdn/ippp network-interface. + +-- + +Q10: I wanna use dynamic IP address assignment ... How + must I configure the network device. + +A: At least you must have a route which forwards + a packet to the ippp network-interface to trigger + the dial-on-demand. + A default route to the ippp-interface will work. + Now you must choose a dummy IP address for your + interface. + If for some reason you can't set the default + route to the ippp interface, you may take any + address of the subnet from which you expect your + dynamic IP number and set a 'network route' for + this subnet to the ippp interface. + To allow overriding of the dummy address you + must call the ipppd with the 'ipcp-accept-local' option. + +A: You must know, how the ipppd gets the addresses it wanna + configure. If you don't give any option, the ipppd + tries to negotiate the local host address! + With the option 'noipdefault' it requests an address + from the remote machine. With 'useifip' it gets the + addresses from the net interface. Or you set the address + on the option line with the <a.b.c.d:e.f.g.h> option. + Note: the IP address of the remote machine must be configured + locally or the remote machine must send it in an IPCP request. + If your side doesn't know the IP address after negotiation, it + closes the connection! + You must allow overriding of address with the 'ipcp-accept-*' + options, if you have set your own or the remote address + explicitly. + +A: Maybe you try these options .. e.g: + + /sbin/ipppd :$REMOTE noipdefault /dev/ippp0 + + where REMOTE must be the address of the remote machine (the + machine, which gives you your address) + +-- + +Q11: I can't connect. How can I check where the problem is. + +A: A good help log is the debug output from the ipppd... + Check whether you can find there: + - only a few LCP-conf-req SENT messages (less then 10) + and then a Term-REQ: + -> check whether your ISDN card is well configured + it seems, that your machine doesn't dial + (IRQ,IO,Proto, etc problems) + Configure your ISDN card to print debug messages and + check the /dev/isdnctrl output next time. There + you can see, whether there is activity on the card/line. + - there are at least a few RECV messages in the log: + -> fine: your card is dialing and your remote machine + tries to talk with you. Maybe only a missing + authentication. Check your ipppd configuration again. + - the ipppd exits for some reason: + -> not good ... check /var/adm/syslog and /var/adm/daemon. + Could be a bug in the ipppd. + +-- + +Q12: How can I reduce login delay? + +A: Log a login session ('debug' log) and check which options + your remote side rejects. Next time configure your ipppd + to not negotiate these options. Another 'side effect' is, that + this increases redundancy. (e.g your remote side is buggy and + rejects options in a wrong way). + + + |