Add ISDN (i4b) documentation and examples

6 files changed, 1583 insertions, 0 deletions

diff --git a/share/examples/isdn/FAQ b/share/examples/isdn/FAQ
new file mode 100644
index 0000000..8dd1d71
--- /dev/null
+++ b/share/examples/isdn/FAQ
@@ -0,0 +1,517 @@
+--------------------------------------------------------------------------------
+
+                   ISDN4BSD Frequently Asked Questions
+                   ===================================
+
+                last edit-date: [Fri Dec 25 19:59:21 1998]
+
+--------------------------------------------------------------------------------
+
+Contents:
+=========
+
+	 1. How do I get started with synchronous PPP (sPPP) ?
+	 2. does anyone know a software that can receive/send fax over ISDN ?
+	 3. does i4b callback only work with setups where the remote end 
+		returns a busy ?
+	 4. trouble with kernel options IPFIREWALL and IPDIVERT and natd
+	 5. I want to use -r with isdnd but it does not work
+	 6. How do I configure and run the answering machine ?
+	 7. Teles S0/16.3 ... unknown ?
+	 8. How do i integrate a new lowlevel driver into i4b ?
+	 9. Why it always says "no Space in TX FIFO - State F4 awaiting" ?
+	10. Incoming alert - what does it mean ?
+	11. How do i change irq's on my teles 16.3 card ?
+
+
+
+1. How do I get started with synchronous PPP (sPPP) ?
+================================================================================
+
+  Of course you first have to have sPPP interfaces in your kernel. If
+  you installed everything using FreeBSD/install.sh then the correct
+  entries should have been automatically made in /sys/conf/files for you.
+  For NetBSD it isn't quite as simple since NetBSD/install-netbsd.sh does
+  not do it for you.
+  
+  Then all you need to do is put an entry like this:
+  
+  	pseudo-device   "i4bisppp"      4
+  
+  into your kernel configuration file (if it's not already there) and
+  generate and boot the new kernel. The above line will give you 4
+  sPPP interfaces - isp0 to isp3.
+  
+  Then just modify /etc/isdn/isdnd.rc (see the example in etc-isdn/isdnd.rc)
+  to suit your needs (telephone numbers, etc).
+  
+  The next step is to read the spppcontrol man page and then to look at
+  etc/rc.isdn-PPP. spppcontrol is a very important component in getting
+  sPPP working correctly and the spppcontrol lines in your /etc/rc.isdn
+  must be correct.
+  
+  In my experience there are two things which can cause problems:
+  
+  1) the authproto line has to agree with what your ISP desires. In
+     general I've found that it's best to have something like this -
+  
+  	spppcontrol <interface> myauthproto={pap,chap} myauthname=<AuthName>
+  		myauthsecret=<AuthSecret> hisauthproto=none callin
+  
+     The "hisauthproto=none" is usually needed because the ISP does not want
+     to authorise himself to you; he expects you to authorize yourself to him !
+     I once forgot to set hisauthproto and it took me quite a while to figure
+     out why I couldn't connect.
+  
+  2) the IP address at your ISP's end must be correct.
+  
+  How can I find out (1) whether my ISP wants pap or chap and (2) what his
+  IP address is ? you might ask. Generally, your ISP should have provide
+  this information to you. But, if he didn't, or you've mislayed the
+  documentation (as I did), there's still hope.
+  
+  Fortunately, J"org Wunsch implemented the sPPP kernel code so that it
+  provides all the information required if the interface is configured
+  with the debug flag set (e.g. ``ifconfig isp0 debug''). It's just a
+  little cryptic.
+  
+  By the way, I suggest turning the debug flag on until you have things
+  working and then turning it off. The debug output is rather voluminous
+  and could fill up your /var partition, otherwise.
+  
+  The debug output will appear on the console and also be logged to
+  /var/log/messages (under FreeBSD) unless you changed /etc/syslog.conf.
+  
+  A. How to figure out the authproto
+  ----------------------------------
+  
+  Here is an example where I configured isp0 with myauthproto=pap, my
+  ISP wanted chap, but was willing to accept pap:
+  
+  /kernel: isp0: lcp up(starting)
+  /kernel: isp0: lcp output <conf-req id=0x7 len=10 5-6-34-e4-30-5a>
+  /kernel: isp0: lcp input(req-sent): <conf-req id=0x1 len=30 0-4-0-0-1-4-5-
+  f4-3-5-c2-23-5-11-4-5-f4-13-9-3-0-c0-7b-6e-fe-b5>
+         ^^^^^
+             |___ c223 is chap, it's what the ISP wants to use
+  
+  /kernel: isp0: lcp parse opts:  0x0 [rej]  mru  auth-proto  0x11 [rej]
+  x13 [rej]  send conf-rej (I didn't agree)
+  /kernel: isp0: lcp output <conf-rej id=0x1 len=21 0-4-0-0-11-4-5-f4-13-9-3-
+  0-c0-7b-6e-fe-b5>
+  /kernel: isp0: lcp input(req-sent): <conf-ack id=0x7 len=10 5-6-34-e4-30-5a>
+  /kernel: isp0: lcp input(ack-rcvd): <conf-req id=0x2 len=13 1-4-5-f4-3-5-
+  c2-23-5>
+  /kernel: isp0: lcp parse opts:  mru  auth-proto
+  /kernel: isp0: lcp parse opt values:  mru 1524  auth-proto [mine 0x0 !=
+  his chap]  send conf-nak (we want to use pap, not chap)
+  /kernel: isp0: lcp output <conf-nak id=0x2 len=9 3-5-c0-23-5>
+                                                         ^^^^^
+                                                             |___ c023 is pap
+  
+  /kernel: isp0: lcp input(ack-rcvd): <conf-req id=0x3 len=12 1-4-5-f4-3-4-
+  c0-23> (he agrees to use pap)
+  /kernel: isp0: lcp parse opts:  mru  auth-proto
+  /kernel: isp0: lcp parse opt values:  mru 1524  auth-proto  send conf-ack
+  /kernel: isp0: lcp output <conf-ack id=0x3 len=12 1-4-5-f4-3-4-c0-23>
+  					he agrees to use pap ___|^^^^^
+  
+  so, if you have problems in the lcp phase, check which authentication method
+  your ISP wants to use. Usually chap is prefered, but pap will be accepted.
+  
+  B. How to figure out the ISP's IP address
+  -----------------------------------------
+  
+  I also intentionally configured the interface with the wrong address for
+  my ISP, like this:
+  
+  	ifconfig isp0 0.0.0.0 10.0.0.1 debug link1
+  
+  this means that I want the ISP to assign me an address (the 0.0.0.0) and
+  that I expect him to use 10.0.0.1 (which is wrong). Here's the result:
+  (note that these addresses have been changed by me)
+  
+  /kernel: isp0: phase network
+  /kernel: isp0: ipcp open(initial)
+  /kernel: isp0: ipcp up(starting)
+  /kernel: isp0: ipcp output <conf-req id=0x9 len=10 3-6-0-0-0-0>
+  /kernel: isp0: ipcp input(req-sent): <conf-req id=0x1 len=16 2-6-0-2d-f-1-
+  3-6-c-22-38-4e>
+  /kernel: isp0: ipcp parse opts:  compression [rej]  address  send conf-rej
+  /kernel: isp0: ipcp output <conf-rej id=0x1 len=10 2-6-0-2d-f-1>
+  /kernel: isp0: ipcp input(req-sent): <conf-nak id=0x9 len=10 3-6-c-22-38-4e>
+  /kernel: isp0: ipcp nak opts:  address [wantaddr 12.34.56.78] [agree]
+                                                     ^^^^^
+                                                         |___ he assigns me this
+  
+  /kernel: isp0: ipcp output <conf-req id=0xa len=10 3-6-c3-b4-eb-63>
+  /kernel: isp0: ipcp input(req-sent): <conf-req id=0x2 len=10 3-6-62-4c-36-20>
+  /kernel: isp0: ipcp parse opts:  address
+  /kernel: isp0: ipcp parse opt values:  address 98.76.54.32 [not agreed]
+                                                   ^^^^^
+                                                        |_this is *his* address
+  send conf-nak
+  /kernel: isp0: ipcp output <conf-nak id=0x2 len=10 3-6-a-0-0-1>
+  	I expect a different address and (incorrectly) reject what he wants.
+  	I tell him that I expect 10.0.0.1. After this the connection fails.
+  
+  Anyway, I now know that his address is really 98.76.54.32 and can use
+  it to correctly configure the interface.
+  
+  With the correct IP address I shoulkd now be able to connect with no
+  problems. As stated above, the authorization protocol is normally not
+  so important since most ISPs are willing to use pap, although chap is
+  more secure. Generally, I'd try chap first and only switch to pap if
+  the ISP doesn't accept it.
+  
+  (by Gary Jennejohn, Home - garyj@muc.de, Work - garyj@fkr.dec.com)
+
+
+
+2. does anyone know a software that can receive/send fax over ISDN ?
+================================================================================
+
+ > Hi,
+ > 
+ > does anyone know a software that can receive/send fax over ISDN? I am
+ > using a Fritz!Card, which can handle group 3 (analogous) fax, but I
+ > can't find any hint in the i4b software that this is supported in any
+ > way.
+ 
+This is probably not implemented.
+
+Implementing G3 fax in ISDN would mean simulating an analog modem
+on the digital link. This means having to generate the right waveforms
+for the modulated data, and receive analog data from the other end
+which you had to run FFT analysis on and then interpret.
+
+In addition you have to do this in realtime, to be able to deal with
+the timing involved in the fax protocol, something neither
+FreeBSD or Linux is good at in their native form.. 
+
+A third point is that a software simulated faxmodem usually does not
+work well. I tested Teles software faxmodem in Win-95 towards an Ericsson V34
+HE modem, and was able to send faxes from the ISDN card at 4800 baud
+only, and receive faxes ad 9600 baud only(!) (And it is not the
+Ericsson modems fault, it works flawlessly towards other fax machines.)
+
+My point is that the best thing to do is to use an ordinary faxmodem
+to handle faxes with Hylafax of mgetty+sendfax or efax, or you may use
+a combined ISDN card with an analog part.
+
+Of course, if you are crazy enough, you may try to implement a
+software simulated modem in e.g. RT-linux, or a similar realtime
+extension for FreeBSD.
+
+Best regards,
+Nils Ulltveit-Moe	(etonumo@eto.ericsson.se)
+
+
+
+3. does i4b callback only work with setups where the remote end returns a busy ?
+================================================================================
+
+> Is my assumption correct, does i4b callback only work with setups where
+> the remote end returns a busy on the dialin?
+
+Yes - otherwise you'll pay for the connection, at least here in Germany.
+
+Most routers support two kind of callbacks - the one that i4b supports
+means: the called system rejects (so no charge for this connection), waits
+a configurable time and the calls back. Information on who has called and
+who is to be called back relies on the ISDN calling party number information
+and stuff statically configured in the routers (or isnd's) configuration.
+
+The other type of callback (not supported by i4b right now) means: the 
+called system accepts the connection and starts ppp negotiation. During this
+the ppp's aggree to do a callback. Information on who called in and who is 
+going to be called back is subject to the authentication/negotiation already
+done by the two ppp's. Then ppp closes down, the connection is disconnected
+and the called system calls back.
+
+I've never seen someone actually use the second type due to its obvious 
+disadvantages. It may be usefull if you travel, call in from an unknown
+number and want to be called back at that number.
+
+Martin Husemann <martin@rumolt.teuto.de>
+
+
+4. trouble with kernel options IPFIREWALL and IPDIVERT and natd
+================================================================================
+
+   NOTICE: section obsolete since IP address changes are handled properly now!
+   ===========================================================================
+
+This section
+> Trying to build a router/gateway between my privat Ethernet and
+> the Internet (via my ISP), I have problems with I4B or NAT (I think:).
+> 
+> The 2.2.5-R kernel with options IPFIREWALL and IPDIVERT works fine
+> with ISDN4BSD 0.50-alpha and firewall rule 'pass all from any to any'.
+> However, when I add 'divert natd all from any to any via isp0'
+> and start natd, name server lookups to the ISP's NS don't work.
+> 
+> Also, ping and nslookup fails from any other internal host.
+
+I had exactly the same problems. natd doesn't seem to get a message if
+the IP address of the interface changes (after successful dialout).
+I have to manually send a HUP signal to natd. I do this via the following
+(ugly?!) hack:
+
+I added the following two lines to the system section of isdnd.rc:
+regexpr         = "call active"         # look for matches in log messages
+regprog         = hup_natd              # execute program whan match is found
+
+The small script "hup_natd", located in /etc/isdn, looks like:
+#!/bin/sh
+pid=`cat /var/run/natd.pid`
+kill -HUP $pid
+sleep 3
+kill -HUP $pid
+sleep 5
+kill -HUP $pid
+
+It looks ugly, but at least for me it works. The two sleeps are necessary
+since I have to wait for ppp negotiation to complete (I don't get a message 
+from isdnd for that). If I'm lucky I have my connection after 3 seconds, 
+but 8 seconds should suffice for worst case (the first HUP without a sleep 
+sometimes even succeeded on an slow 486/33 with 8MB RAM, more HUPs don't hurt).
+
+I'm really interested in some more elegant method.
+
+Daniel		(rock@cs.uni-sb.de)
+
+
+Arve Ronning replied:
+=====================
+
+> I had exactly the same problems. natd doesn't seem to get a message if
+> the IP address of the interface changes (after successful dialout).
+
+Well, it (natd) _does_ pick up the dynamic address supplied for isp0.
+Try 'natd -verbose ...' and you'll see it. Otherwise I agree, there is
+certainly something missing in natd's functionality, or maybe sppp
+does'nt
+supply what it's supposed to ??
+
+> I have to manually send a HUP signal to natd. I do this via the following
+> (ugly?!) hack:
+
+YES...super; strange but correct. It works when I send natd a -HUP after
+sppp is up. Thanx for the tip. However, natd must be -HUPed _every_ time
+sppp has been down (idle timeout) and comes back up!
+
+> I'm really interested in some more elegant method.
+
+So am I, let's see what may come out of the discussion on the list.
+
+
+
+5. I want to use -r with isdnd but it does not work
+================================================================================
+
+> > Use isdnd in fullscreen mode.
+> 
+> I tried that already, but got an error when I start isdnd that way:
+> 
+>       /usr/local/bin/isdnd -d 0xf9 -f -r /dev/ttyv1 -t cons25
+> 
+> root is logged in on device /dev/ttyv1, the message in /var/log/messages looks like:
+> 
+> "May 22 11:52:28 asterix isdnd[4160]: ERR ERROR, cannot setup tty as controlling terminal: Operation not permitted"
+> 
+> How can I give this device permission ?
+  
+
+In case you want to use switch "-r" noone else _must_ use the tty you redirect
+to, you have to remove the getty from the virtual terminal in /etc/ttys and 
+restart the init process.
+
+
+6. How do I configure and run the answering machine (under FreeBSD 2.2.x) ?
+================================================================================
+
+The answering machine will be activated, when isdnd executes the program
+that has been named in "/etc/isdn/isdnd.rc" in the section "telephone
+answering" at entry "answerprog = ". If the program is executed
+without a pathname, the answer program is expected in "/etc/isdn".
+Examples of such programs can be found in "/etc/isdn/samples". They
+are named:
+
+	"answer"	answers only, no recording
+	"record"	answers, and records messages
+	"tell"		the number of the calling person is told,
+			no recording.
+	"tell-record"	calling number as answer, message is recorded
+	"isdntel.sh"	answers and records messages; by using the
+			program "isdntel", one has the control over
+			the recorded messages in the directory 
+			"/var/isdn". Look at "man isdntel" and
+			"man isdntelctl".
+
+These programs have to be altered to suit your needs. Unfortunately there
+is no program with which you can record your answer message. This is not
+really bad, because you only have to alter the above mentioned program
+"record" a bit (comment out the "if ... fi" statements for the beep
+and msg messages). You have to create the directory "/var/isdn" first in
+order to record messages. They will be stored in this location then.
+
+Stefan Herrmann <stefan@asterix.webaffairs.net>
+
+
+7. Teles S0/16.3 ... unknown ?
+================================================================================
+Hi,
+
+I have just purchased a Teles S0/16.3 card.
+But it's not what i4b is looking for .... I mean, it's a different card.
+
+The docs  (and sources)of i4b talks about a Telws S0/16.3 card with 3
+address: d80 etc.
+
+This one (is not PnP) has jumpers for 0x180 0x280 0x380.
+
+It has the SIemens Chips numbered PSB 21525 N (HSCX TE V2.1) and PSB
+2186N V1.1 (ISAC-S TE).
+
+I undestand that the 16.3c is not supported, but over this board is
+written "TELES.S0/16.3 Revision 1.3"
+
+Can anybody tell me what is this card ???
+
+answer:
+-------
+
+It's not a different card. The jumpers are documented to select
+IO-address 0x180, 0x280 or 0x380 in some TELES manuals.
+But in fact they select the addresses 0xd80, 0xe80 or 0xf80.
+
+Wolfgang
+
+
+And an additional note from Poul-Henning Kamp:
+----------------------------------------------
+There is an intricate story behind this, in short some ISA cards
+only decode the first 10 address bits (0x3ff), which over the years
+has resulted in a mutation the "de-facto-spec" such that addressbits
+10-15 can be used by the card for selecting various stuff.  This
+is extensively used on obscure cards with massive IO needs, sound,
+IEEE488 and ISDN cards often belong in this category.
+
+
+
+8. How do i integrate a new lowlevel driver into i4b ?
+================================================================================
+
+1) Request a flag value from me
+2) add an entry for the card into FreeBSD/CONFIG
+3) add driver filename to FreeBSD/files.i386.cat
+4) add entry for the card to FreeBSD/options.i386.cat
+5) add support to print type of card to diehl/diehlctl/main.c
+6) add support to print type of card to isdnd/support.c, name_of_controller()
+7) place your file as named in 3) into directory layer1
+8) add the flag value and function prototypes to layer1/i4b_l1.h
+9) add support for NetBSD to layer1/isa_isic.c
+10) add support for attach/probe to layer1/i4b_isic.c
+11) add card type to machine/i4b_ioctl.h and update CARD_TYPEP_MAX
+12) add an entry to the man page man/isic.4
+
+Produce diffs (please use context diffs, flag "-c" for diff) and send them in.
+
+
+9. Why it always says "no Space in TX FIFO - State F4 awaiting" ?
+================================================================================
+
+as I wrote about two weeks ago I had massive problems concerning this
+"no space in TX FIFO"-thing,
+
+/kernel: i4b-L1-ph_data_req: No Space in TX FIFO, state = F4 Awaiting Signal
+
+Even though I used a correctly recognized Teles S0/16.3 nonpnp isdncard,
+nothing worked, errormsgs were flooding the console until I rebooted the box.
+
+I decided to play around in the BIOS-settings, I first just set them all
+to default, which didn't work, and then changed lots of things - unfortunately
+I can't remember them. After about hundreds of trial 'n errors I gave up.
+
+A few days ago I just made another attempt, booted the box and to my surprise
+it all worked without the smallest problem, great data rates :)
+
+I tried hard to found what the something special was I changed in the BIOS
+settings, but I just couldnt get isdnd back to its stupid behaviour it
+showed all the time before, but I would recommend everybody who has this
+kind of problem to look into his BIOS. 
+
+			(from Meike Aulbach, strange@stoned.rhein-main.de)
+
+
+i4b now works for me, I had a USB-device interfering on IRQ 9,
+which was supposed to be only for my Creatix Card.
+(NetBSD 1.3, Creatix)
+	
+Strange enough, my DOS s0-test worked, are they just polling the card?
+	
+Even when the testsoftware under DOS is working, don't be shure, that
+your hw-setup is correct for xxx(x)BSD. Triplecheck all your IRQ and
+enable and disable PNP to triple-verify. Even unconfigured devices can
+block your card. .....
+	
+And that took me more than 2 months to discover :-((((
+	
+			(from Andreas Lohrum, andreas.lohrum@consol.de)
+
+
+when i changed the mainboard of a box that ran i4b alright, i forgot to
+set 'used by isa' in the pnp-bios-settings for the irq of my teles
+isdn-card. because of that some pci-card got the interrupt that the
+isdn-card should have gotten.
+i then also got this error: 'No space in TX FIFO'.
+
+The reason occurred to my rather quick, but i would think, that this would
+be a nice hint in a FAQ :)
+
+			(from Heiko Schaefer, hschaefer@fto.de)
+
+
+after my huge amount of problems, Meike's hint (changing the
+ISA/PNP-settings in the BIOS) finally fixed things.
+I have only tried out this stuff with my Creatix-card, I'll check
+out the PNP-stuff with my Sedlbauer-card soon too though.
+
+			(from Harold Gutch, logix@foobar.franken.de)
+
+
+10. Incoming alert - what does it mean ?
+================================================================================
+
+In the log on vty6 (isdnd full screen log) I'm seeing 
+
+16.07.98 11:42:35 CHD 00001 rwth rate 90 sec/unit (rate)
+16.07.98 11:42:35 CHD 00001 rwth dialing from 4191236 to 441291234
+16.07.98 11:42:35 CHD 00001 rwth outgoing call proceeding (ctl 0, ch 0)
+16.07.98 11:42:35 CHD 00001 rwth incoming alert  <<<<<<<<<<<<<<<
+16.07.98 11:42:35 CHD 00001 rwth outgoing call active (ctl 0, ch 0)
+
+What does this 'incoming alert' mean?
+
+
+It means that it is "ringing" at the remote end.
+
+
+11. How do i change irq's on my teles 16.3 card ?
+================================================================================
+
+Question:
+
+So how do you change irq's on your teles 16.3 card (under FBSD or DOS,
+I don't have and don't want to have Windows running on that computer) ?
+
+Answer:
+
+The irq is configured into the card each time the driver under whatever
+OS you currently boot initializes the card. Thus, change the irq for the
+isic driver in your kernel config file to one of the supported (!) irqs
+for this card (hint: read "man isic") which is currently unused in your
+machine and generate a new kernel.
+
+
diff --git a/share/examples/isdn/Overview b/share/examples/isdn/Overview
new file mode 100644
index 0000000..2f2fc18
--- /dev/null
+++ b/share/examples/isdn/Overview
@@ -0,0 +1,307 @@
+
+        Short technical overview of isdn4bsd
+        ====================================
+
+	Copyright (c) 1998 Hellmuth Michaelis. All rights reserved.
+
+	$Id: Overview,v 1.3 1998/10/27 10:28:54 hm Exp $
+
+	Last edit-date: [Tue Oct 27 11:26:03 1998]
+
+	-hm	starting an overview ...
+
+
+Contents:
+---------
+	Functional block diagram
+	Layer 1
+	Layer 2
+	Layer 3
+	Debugging control
+	Layer 4    
+	ISDN protocol trace
+
+
+Functional block diagram
+========================
+
+ isdndebug                         isdnd                             isdntrace
+ +-------+  +----------------------------------------------------+   +--------+
+ |       |  |                                                    |   |        |
+ |       |  |                                                    |   |        |
+ +-------+  +----------------------------------------------------+   +--------+
+     |                               |                                    |
+     |                               |                                    |
+     | /dev/i4bctl    Userland       | /dev/i4b            /dev/i4btrc<n> |
+===============================================================================
+     |                Kernel         |                                    |
+     |                               |                                    |
+ +-------+  +----------------------------------------------------+   +--------+
+ |       |  |                                                    |   |        |
+ |i4bctl |  |                       i4b                          |   | i4btrc |
+ |  (6)  |  |                       (7)                          |   |   (8)  |
+ | debug |  |     Layer 4 - common call control interface        |   |  ISDN  |
+ |control|  |                                                    |   | trace  |
+ +:-:-:--+  +----------------------------------------------------+   +--------+
+  : : :          ^                                          ^              ^ 
+  : : :     Call |           various ptr arrays             | Call         %
+  . . .  Control |             in i4b_l3l4.h                | Control      %
+                 V                                          V              %
+ +----------------------+                       +----------------------+   %
+ |                      |                       |                      |   %
+ |       i4bq931        |                  ISDN |     active card      |   %
+ |         (5)          |                   #####                      |   %
+ |    Layer 3 (Q.931)   |                   #   |       driver         |   %
+ |                      |                   #   |                      |   %
+ +----------------------+                   #   +----------------------+   %
+            ^                               #   B +                        %
+            |  i4b_l2l3_func function       #   | +   +------------+       %
+            |  ptr array in i4b_l2l3.h      #   C +++++    isp     |---->  %
+            V                               #   h +   +------------+ IP    %
+ +----------------------+                   #   a +                Subsys  %
+ |                      |                   #   n +   +------------+       %
+ |       i4bq921        |                   #   n +++++    ipr     |---->  %
+ |         (4)          |                   #   e +   +------------+ IP    %
+ |    Layer 2 (Q.921)   |                   #   l +                Subsys  %
+ |                      |                   #     +   +------------+       %
+ +----------------------+                   #   D +++++  tel/rbch  |---->  %
+            ^                               #   a +   +------------+ to    %
+            |  i4b_l1l2_func function       #   t +         /dev/i4btel<n> %
+            |  ptr array in i4b_l1l2.h      #   a +      or /dev/i4brbch<n>%
+            V                               #     +                        %
+ +----------------------+                   #   +---------------------+    %
+ |                      |                   #   |                     |    %
+ |    isic (ISAC part)  |  D-ch trace       #   |   isic (HSCX part)  |B-ch%
+ |         (2)          |%%%%%%%%%%%%       #   |        (3)          |%%%%%
+ |    Layer 1 (I.430)   |           %       #   |   non-HDLC / HDLC   |trc %
+ |                      |           %       #   |                     |    %
+ +----------------------+           %       #   +---------------------+    %
+            ^                       %       #               ^              %
+ D-channel  |                       %       #    B-channels |              %
+            +-----------------------------------------------+              %
+            |  function ptr in      %       #                              %
+            |  in isic_softc in     %%%%%%%%#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+            V  i4b_l1.h                     #
+ +----------------------+                   #
+ |                      |                   #
+ |         isic         |                   #
+ |         (1)          |                   #
+ | Card hardware driver |                   #
+ | for Teles, AVM, USR  |                   #
+ |                      |                   #
+ +----------#-----------+                   #
+            #                               #
+            #                               #
+            #                               #
+            #                               #
+  |=========#===============================#============================|
+        ISDN S0 bus
+
+
+Layer 1
+=======
+
+(1) A driver for a special card hardware consists of a
+	- probe routine
+	- attach routine
+	- FIFO read
+	- FIFO write
+	- register read
+	- register write
+   routines. These routines handle the card/manufacturer specific stuff
+   required to talk to a particular card.
+
+   This addresses of the read/write routines are put into a arrays found
+   in struct isic_softc and they are later called by the macros:
+
+   ISAC_READ(r), ISAC_WRITE(r,v), ISAC_RDFIFO(b,s), ISAC_WRFIFO(b,s),
+   HSCX_READ(n,r), HSCX_WRITE(n,r,v), HSCX_RDFIFO(n,b,s), HSCX_WRFIFO(n,b,s)
+
+   (see file layer1/i4b_l1.h)
+   
+   Files currently used for this purpose are
+   	- i4b_avm_a1.c    AVM A1 and AVM Fritz!Card drivers
+   	- i4b_ctx_s0P.c   Creatix S0 PnP (experimental!)
+   	- i4b_tel_s016.c  Teles S0/16 and clones
+   	- i4b_tel_s0163.c Teles S0/16.3
+   	- i4b_tel_s08.c   Teles S0/8 and clones
+   	- i4b_tel_s0P.c   Teles S0/16 PnP (experimental!)
+   	- i4b_usr_sti.c   3Com USRobotics Sportster
+
+
+(2) The files i4b_isac.c and i4b_isac.h contain the code to control the
+    ISAC chip by using the above mentioned macros.
+
+    Files i4b_l1.c and i4b_l1.h handle stuff used to access layer 1
+    functions from layer 2.
+
+    Layer 1 and layer 2 access functionality of each other by using
+    a well known function pointer array, which contains addresses of
+    "primitives" functions which are defined in I.430 and Q.921. The
+    function pointer array for layer 1/2 communication is defined in
+    file include/i4b_l1l2.h and is initialized i4b_l1.c at the very
+    beginning.
+
+    File i4b_isic.c contains the main code for the "isic" device driver.
+
+    i4b_l1fsm.c is the heart of layer 1 containing the state machine which
+    implements the protocol described in I.430 and the ISAC data book.
+
+
+(3) All above code is used for handling of the D channel, the files
+    i4b_bchan.c, i4b_hscx.c and i4b_hscx.h contain the code for handling
+    the B-channel, the HSCX is used to interface the userland drivers
+    isp, ipr, tel and rbch to one of the B-channels and i4b_hscx.c and
+    i4b_hscx.h contain the code to handle it (also by using the above
+    mentioned macros). i4b_bchan.c contains various maintenance code for
+    interfacing to the upper layers.
+
+
+Layer 2
+=======
+
+(4) Layer 2 implements the LAPD protocol described in Q.920/Q.921. Layer 2
+    interfaces to layer 1 by the above described function pointer array,
+    where layer 1 calls layer 2 functions to provide input to layer 2 and
+    layer 2 calls layer 1 functions to feed data to layer 1.
+
+    The same mechanism is used for layer 2 / layer 3 communication, the
+    pointer array interface is defined in include/i4b_l2l3.h ad the array
+    is initialized at the very beginning of i4b_l2.c which also contains
+    some layer 1 and some layer 3 interface routines. As with l1/l2, the
+    l2/l3 array also contains addresses for "primitives" functions which
+    are specified in Q.920/Q.921 and Q.931.
+
+    i4b_l2.h contains the definition of l2_softc_t, which describes the
+    complete state of a layer 2 link between the exchange and the local
+    terminal equipment.
+
+    i4b_l2.c contains the entrance of data from layer 1 into the system,
+    which is split up in i4b_ph_data_ind() into the 3 classes of layer 2
+    frames called S-frame, I-frame and U-frame. They are handled in files
+    i4b_sframe.c, i4b_iframe.c and i4b_uframe.c together with the respective
+    routines to send data with each ones frame type.
+
+    i4b_l2timer.c implements the timers required by Q.921.
+
+    i4b_tei.c contains the TEI handling routines.
+
+    i4b_lme.c implements a rudimentary layer management entity.
+
+    i4b_util.c implements the many utility functions specified
+    in Q.921 together wit some misc routines required for overall
+    functionality.
+
+    i4b_mbuf.c handles all (!) requests for mbufs and frees all mbufs used
+    by the whole isdn4bsd kernel part. It should probably be moved else-
+    where.
+
+    i4b_l2fsm.c and i4b_l2fsm.h contain the heart of layer 2, the state-
+    machine implementing the protocol as specified in Q.921.
+
+Layer 3
+=======
+
+(5) i4b_l2if.c and i4b_l4if.c contain the interface routines to communicate
+    to layer 2 and layer 4 respectively.
+
+    i4b_l3timer.c implements the timers required by layer 3.
+
+    i4b_q931.c and i4b_q931.h implement the message and information element
+    decoding of the Q.931 protocol.
+
+    i4b_q932fac.c and i4b_q932fac.h implement a partial decoding of facility
+    messages and/or information elements; the only decoding done here is
+    the decoding of AOCD and AOCE, advice of charge during and at end of
+    call.
+
+    As usual, i4b_l3fsm.c and i4b_l3fsm.h contain the state machine required
+    to handle the protocol as specified in Q.931.
+
+    Layer 3 uses a structure defined in include/i4b_l3l4.h to store and
+    request information about one particular isdncontroller, it is called
+    ctrl_desc_t (controller descriptor). It contains information on the
+    state of a controller (controller ready/down and which B channels are
+    used or idle) as well as a pointer array used for communication of
+    layer 4 with layer 3: layer 3 "knows" the routines to call within
+    layer 4 by name, but in case layer 4 has to call layer 3, several
+    possibilities exist (i.e. active / passive cards) so it has to call
+    the routines which the ISDN controller had put into the the function
+    pointer array (N_CONNECT_REQUEST, N_CONNECT_RESPONSE etc) at init time.
+
+    Layer 3 shares a structure called call_desc_t (call descriptor) with
+    layer 4. This structure is used to describe the state of one call. The
+    reference to layer 3 is the Q.931 call reference value, the reference to
+    layer 4 (and the isdn daemon, isdnd) is the cdid, an unique integer
+    value uniquely describing one call, the call descriptor id.
+              This structure is used to build an array of this structures
+    (call_desc[N_CALL_DESC]), which must be large enough to hold as many
+    calls as there are B channels in the system PLUS a reserve to be able
+    to handle incoming SETUP messages although all channels are in use.
+
+    More, this structure contains the so called "link table pointers"
+    (isdn_link_t *ilt and drvr_link_t *dlt) which contain function pointers
+    to "link" a B-channel (better the addresses of functions each participant
+    needs to access each others functionality) after a successful call setup
+    to a userland driver (such as isp, ipr, rbch or tel) to exchange user
+    data in the desired protocol and format.
+
+Debugging control
+=================
+
+(6) the device driver for /dev/i4bctl in conjunction with the userland
+    program isdndebug(8) is used to set the debug level for each of the
+    layers and several other parts of the system, information how to use
+    this is contained in machine/i4b_debug.h and all parts of the kernel
+    sources. It is only usable for passive cards.
+
+
+Layer 4    
+=======
+
+(7) Layer 4 is "just" an abstraction layer used to shield the differences
+    of the various possible Layer 3 interfaces (passive cards based on
+    Siemens chip-sets, passive cards based on other chip-sets, active cards
+    from different manufacturers using manufacturer-specific interfaces)
+    and to provide a uniform interface to the isdnd userland daemon, which
+    is used to handle all the required actions to setup and close calls
+    and to the necessary retry handling and management functionality.
+
+    Layer 4 communicates with the userland by using a well defined protocol
+    consisting of "messages" sent to userland and which are read(2) by the
+    isdnd. The isdnd in turn sends "messages" to the kernel by using the
+    ioctl(2) call. This protocol and the required messages for both
+    directions are documented in the machine/i4b_ioctl.h file and are
+    implemented in files i4b_i4bdrv.c and i4b_l4.c, the latter also
+    containing much of the Layer 4 interface to the lower layers.
+
+    i4b_l4mgmt.c contains all the required routines to manage the above
+    mentioned call descriptor id (cdid) in conjunction with the call
+    descriptor (array) and the call reference seen from layer 3.
+
+    i4b_l4timer.c implements a timeout timer for Layer 4.
+
+
+ISDN protocol trace
+===================
+
+(8) ISDN D-channel protocol trace for layers 2 and 3 is possible by using
+    hooks in the ISAC handling routines.
+
+    In case D-channel trace is enabled, every frame is prepended with a
+    header containing further data such as a time stamp and sent via the
+    i4btrc driver found in driver/i4b_trace.c to one of the /dev/i4btrc<n>
+    devices, where <n> corresponds to a passive controller unit number.
+
+    If desired, B-channel data can be made available using the same
+    mechanism - hooks in the HSCX handler send data up to the i4btrc
+    device.
+
+    The raw data is then read by the isdntrace userland program which
+    decodes the layer 2 and/or layer 3 protocol and formats it to be
+    easily readable by the user.
+
+    B-channel data is not interpreted but dumped as a hex-dump.
+
+
+/* EOF */
diff --git a/share/examples/isdn/README b/share/examples/isdn/README
new file mode 100644
index 0000000..6a84fe8
--- /dev/null
+++ b/share/examples/isdn/README
@@ -0,0 +1,457 @@
+
+
+Note: This is the README from the isdn4bsd 0.70.00 ftp-distribution. Shortly
+      after release, i4b was integrated into the FreeBSD sourcetree and so
+      the following parts about FreeBSD may not apply anymore. 
+
+      For information of how isdn4bsd is integrated into FreeBSD now, please
+      read the file ROADMAP in this directory.
+
+
+--------------------------------------------------------------------------------
+
+                                  ISDN4BSD
+                                  ========
+
+                    beta Version 0.70.00 / December 1998
+
+                                 written by:
+
+			     Hellmuth Michaelis
+                               Hallstrasse 20
+                             D-25462 Rellingen
+
+                           voice: +49 4101 473574
+                            fax: +49 4101 473575
+                             email: hm@kts.org
+
+                                    -----
+
+                          The isdn4bsd package is:
+
+     Copyright (c) 1997, 1998 by Hellmuth Michaelis. All rights reserved. 
+
+                      For details see the file LICENSE.
+
+                                    -----
+
+                   ISDN4BSD would not be what it is without
+                      the help and support of many people,
+                           see file ACKNOWLEDGMENTS !
+
+                                    -----
+
+        Vote with your wallet: in case you want to buy new ISDN hardware,
+          buy it from manufacturers who support the development of i4b,
+         for a list of supporters have a look at file ACKNOWLEDGMENTS!
+
+                                    -----
+
+                       This package is postcard-ware:
+                       ==============================
+
+        The license fee for using isdn4bsd is sending a picture postcard
+       of your home town. My address can be found at the top of this file.
+
+
+--------------------------------------------------------------------------------
+
+Contents:
+---------
+	1.  Disclaimer
+	2.  What is ISDN4BSD ?
+        3.  Which BSD's are supported ?
+	4.  Which ISDN cards are supported ?
+	5.  Where do i find documentation for ISDN4BSD ?
+	6.  How do i install ISDN4BSD ?
+	7.  Where do i get support for ISDN4BSD ?
+	8.  Where do i get commercial support for ISDN4BSD ?
+	9.  How can i help and/or support ISDN4BSD ?
+	10. How do i report bugs ?
+	11. Is there a mailing-list available for ISDN4BSD ?
+	12. Where can i get ISDN4BSD ?
+	13. What is the reward for reading everything in this file ?
+
+
+1. Disclaimer:
+--------------
+
+  It may be illegal in your country to connect an ISDN4BSD based machine 
+  using a passive ISDN card to the ISDN at your site because the protocol 
+  stack of ISDN4BSD, which is necessary to run passive cards, has not been 
+  approved by the telecommunication certification authority of your country. 
+  If in doubt, please contact your local ISDN provider !
+
+
+  THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+  ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+  SUCH DAMAGE.
+
+
+2. What is ISDN4BSD ?
+---------------------
+
+ISDN4BSD (or in short i4b) is a package for interfacing a computer running
+FreeBSD, NetBSD or OpenBSD to the ISDN.
+
+The only ISDN protocol currently supported is the BRI protocol specified in
+I.430, Q.921 and Q.931; better known as DSS1 or Euro-ISDN.  
+
+ISDN4BSD allows you to make IP network connections by using either IP packets
+sent in raw HDLC frames on the B channel or by using synchronous PPP. 
+
+For telephony, ISDN4BSD can answer incoming phone calls like an answering 
+machine.
+
+
+3. Which BSD's are supported ?
+------------------------------
+
+FreeBSD:
+	You need FreeBSD 2.2.6 and higher to run i4b out-of-the-box.
+
+	This is because PnP support is now available in i4b and 
+	FreeBSD 2.2.6 was the first version which included PnP support
+	in the base OS. 
+
+	In case you want to install i4b on FreeBSD < 2.2.6, you have to
+	patch your system with the PnP patches from Luigi Rizzo (available
+	from his home page at http://www.iet.unipi.it/~luigi).
+
+	The install/uninstall script in the FreeBSD directory was tested
+	with 2.2.7 (it should run with 2.2.n, where n >= 6), 3.0-RELEASE
+	and 3.0-CURRENT as of Dec 22, 1998.
+
+	Please take the time to read the file FreeBSD/INSTALLATION (and 
+	the other available documentation) carefully. Thank you!
+
+
+NetBSD/i386:
+
+	Important note for i4b users on NetBSD/i386:
+	============================================
+
+	While the previous releases of i4b mainly supported the latest
+	official releases, this new release now depends on NetBSD-current
+	(1.3G or newer). The old stuff is still there, just in case you
+	are running an older version, but you need to read the installation
+	instructions in NetBSD/INSTALLATION carefully!
+	This step was necessary as installation now differs a lot since i4b
+	has some prerequisites officially included in -current.
+
+	---------
+
+	The NetBSD specific support and the Diehl driver was written by 
+	Martin Husemann, (martin@rumolt.teuto.de). Since i do not intend
+	to run NetBSD and/or Diehl cards, i suggest contacting him in 
+	case of problems in this two areas. 
+	Martin has NetBSD/i386 1.3 running and is supporting ISDN4BSD for
+	that platform as his time permits it.
+
+NetBSD/Amiga:
+	The NetBSD/Atari 1.3F specific support was done by Ignatios Souvatzis,
+	(is@netbsd.org).
+
+NetBSD/Atari:
+	The NetBSD/Atari 1.3 specific support was done by Leo Weppelman,
+	(leo@wau.mis.ah.nl).
+
+OpenBSD/i386:
+	The OpenBSD/i386 2.2 specific support was done by Bas Oude Nijeweme
+	(bon@serious.xs4all.nl). He reports that it is also running fine 
+	under OpenBSD 2.3. Known to work under OpenBSD is currently the 
+	Teles 16.3 and the Teles S0/16, reports for other cards welcome!
+
+	NOTICE:
+	Isdn4bsd version 0.70 has not been tested with OpenBSD at all,
+	it would be great to have someone who likes to work on i4b under
+	OpenBSD regularly and takes over the maintenance for that OS!
+
+
+4. Which ISDN cards are supported ?
+-----------------------------------
+
+  Type (passive, ISA)	FreeBSD		NetBSD/OpenBSD	Notes
+  --------------------- -------		--------------	-----------------------
+  AVM A1		full		full
+  AVM Fritz!Card	full		full		(Note 1)
+  Creatix ISDN-S0/8	full		full		( = Teles S0/8 )
+  Creatix ISDN-S0/16	full		full		( = Teles S0/16 )
+  Dr.Neuhaus Niccy 1008	full		full		( = Teles S0/8 )
+  Dr.Neuhaus Niccy 1016	full		full		( = Teles S0/16 )
+  ITK ix1 micro		full		full		(Note 13)
+  Stollmann Tina-pp	full		full
+  Teles S0/8		full		full
+  Teles S0/16		full		full
+  Teles S0/16.3		full		full		(Note 4)
+  3Com/USR SportsterInt	full		full		( = Stollmann Tina-pp )
+
+  Type (passive, PnP)	FreeBSD		NetBSD/OpenBSD	Notes
+  --------------------- -------		--------------	-----------------------
+  Asuscom I-IN100-ST-DV experimental	unsupported	( = Dynalink IS64PH )
+  Creatix ISDN-S0 PnP	full		full		(Note 2)
+  Dr.Neuhaus Niccy GO@	full		full		(Note 2)
+  Dynalink IS64PH	full		full		(Note 11)
+  ELSA 1000pro ISA	full		full		(Note 3)
+  Sagem Cybermod	full		full		( = Niccy GO@ )
+  Sedlbauer Win Speed	full		full		(Note 9)
+  Teles S0 PnP		experimental	full		(Note 5)
+  3Com USR PnP internal unsupported	unsupported	(under development)
+
+  Type (passive, PnP)	FreeBSD		NetBSD/OpenBSD	Notes
+  --------------------- -------		--------------	-----------------------
+  ELSA 1000pro PCI	full		full
+
+  Type (passive, PCMCIA)FreeBSD		NetBSD/OpenBSD	Notes
+  --------------------- -------		--------------	-----------------------
+  AVM Fritz!Card PCMCIA	full		experimental	(Note 10)
+  ELSA PCMCIA		unsupported	unsupported	(under development)
+
+  Type (passive, Amiga)	FreeBSD		NetBSD/OpenBSD	Notes
+  --------------------- -------		--------------	-----------------------
+  ISDN Blaster		unsupported	experimental	(Note 12, Amiga/NetBSD)
+  ISDN Master		unsupported	experimental	(Note 12, Amiga/NetBSD)
+
+  Type (active)		FreeBSD		NetBSD/OpenBSD	Notes
+  --------------------- -------		--------------	-----------------------
+  AVM B1		unsupported	unsupported	(Note 6)
+  DiehlS,SX,SCOM,QUATRO	unsupported	unsupported	(Note 7)
+  Miro P1		unsupported	unsupported	( = Tina-dd )
+  Stollmann Tina-dd	unsupported	unsupported	(Note 8)
+
+
+Note 1:	Only the ISA, non-PnP AVM Fritz!Card is supported; the PnP and PCI
+	versions are unsupported! The "Teledat 150" sold by the german
+	Telekom seems to be an AVM Fritz!Card.
+
+Note 2:	FreeBSD
+		This is a PnP card. To run it under FreeBSD, you need
+		FreeBSD 2.2.6 RELEASE or higher.
+	NetBSD
+		The NetBSD version has not been verified to work yet.
+
+Note 3: Due to its design, this card produces 128 IRQs/sec. This can be
+	reportedly stopped by disconnecting pin 12 of the 7474 and wiring
+	it to pin 15 of the 74175. Be careful! This procedure has not been
+	verified and doing this will immediately terminate your warranty !!
+	The card will not function anymore with drivers for other OSes and
+	you may not get any further support from the manufacturer! YMMV!
+
+Note 4: Only the 16.3 is supported; the 16.3c and the 16.3 PnP are currently
+	unsupported !
+
+Note 5: The card has not been verified to work yet.
+
+Note 6: This driver is currently under development by Gary Jennejohn who
+	develops under FreeBSD only.
+
+Note 7: This driver is currently under construction by Martin Husemann who
+	develops under NetBSD only.
+
+Note 8: This driver is currently under development by Hellmuth Michaelis who
+	develops under FreeBSD only.
+
+Note 9: This driver was developed by German Tischler, tanis@gaspode.franken.de.
+	Please contact him in case of trouble. The "Teledat 100" sold by the 
+	german Telekom is identical with this card.
+	
+Note 10: This driver is developed by Matthias Apitz, matthias.apitz@sisis.de.
+	FreeBSD
+		Please contact him in case of trouble.
+		Please read the file README.PCCARD in the i4b distribution for
+		additional installation instructions.
+	NetBSD
+		Experimental driver support by Martin Husemann.
+
+Note 11: This driver was developed by Martijn Plak (tigrfhur@xs4all.nl)
+	Please contact him in case of trouble. This driver might also work 
+	for Asuscom cards. (Andrew Gordon wrote: Just to let you know that
+	I've now tried the i4b "dynalink" driver with the ASUSCOM 
+	I-IN100-ST-DV card, and it appears to work fine.)
+
+Note 12: This driver was developed by Ignatios Souvatzis (is@netbsd.org)
+	Please contact him in case of trouble.
+	This driver is supposed to work on the ISDN Master versions and
+	lookalikes, like the ISDN Blaster.
+
+Note 13: This driver was developed by Martin Husemann under NetBSD and has
+	not been tested under FreeBSD yet. Feedback welcome!
+
+
+5. Where do i find documentation for ISDN4BSD ?
+-----------------------------------------------
+
+- For installation instructions have a look under the the FreeBSD, NetBSD
+  and OpenBSD directories, each of these contains a file "INSTALLATION"
+  which describes the installation procedure for isdn4bsd on those operating
+  systems.
+
+- Every program has a man page in the respective subdirectory and every 
+  driver has a man page in the "man" subdirectory. All the man pages are 
+  installed by running "make install" so its very easy to access them
+  (hint: try "apropos isdn4bsd" after you installed isdn4bsd, it displays
+   all available manual pages).
+
+- misc/Overview contains a short technical overview of the inner workings 
+  of isdn4bsd.
+
+- misc/Resources contains URL's and ISBN's to more interesting ISDN related
+  stuff.
+
+- handbook/i4b.ps is the start of a handbook for isdn4bsd.
+
+
+6. How do i install ISDN4BSD ?
+------------------------------
+
+Read the instructions in the file {FreeBSD|NetBSD|OpenBSD}/INSTALLATION. 
+
+In case they are incomplete, unclear, wrong or outdated, please send me an 
+update for inclusion into a future distribution!
+
+
+7. Where do i get support for ISDN4BSD ?
+----------------------------------------
+
+I will support and help with ISDN4BSD as my time permits it. Please 
+keep in mind that in this case support is given on a voluntary basis
+and your questions might not be answered immediately.
+
+Also, i recommend subscribing to the mailing list mentioned below.
+
+Due to the experience gained supporting the predecessor of ISDN4BSD, let
+me please clearly state that there is no guarantee that your bug will be
+fixed within some specific amount of time, in fact there is no guarantee 
+that your bug will be fixed at all; i'll do my best but there might be
+more important things going on in my life than giving free support for
+ISDN4BSD. Some bugs seem to occur only in certain environments and are
+not reproduceable here without access to the equipment you are connected
+to or other equipment like ISDN simulators (which i don't get access to
+for free): in this case you are the only person being able to trace down
+the bug and fix it.
+
+
+8.  Where do i get commercial support for ISDN4BSD ?
+----------------------------------------------------
+
+In case you want to pay for support, maintenance, enhancements, extensions
+to isdn4bsd or whatever else you may need, it is possible to hire me for
+reasonable rates through my employer HCS GmbH; in this case please contact 
+me for details at hm@hcs.de or look at http://www.freebsd-support.de.
+
+
+9. How can i help and/or support ISDN4BSD ?
+-------------------------------------------
+
+I would really like to hear from you! (even if it runs out of the box :-)
+
+I'm open for suggestions, bugreports, fixes, patches, enhancements and 
+comments to improve ISDN4BSD. 
+
+Please send flames to /dev/null and/or start writing your own ISDN package.
+
+ISDN4BSD is a project on a voluntary basis and writing and supporting
+communication systems like ISDN4BSD costs much money and much time.
+
+Any contribution in terms of equipment, cards, documentation, cash
+and/or daytime payed work on ISDN4BSD would be highly appreciated.
+
+You can help by not only reporting bugs, but by sending in a patch for
+the problem together with a bugreport.
+
+In case you cannot fix something yourself, please describe your problem
+as detailed as possible, include information which version of an operating
+system you are running, which ISDN board you are using, to which kind
+of ISDN equipment (like the brand of PBX) you are connected etc. etc.
+
+In case you want to get a currently unsupported card supported, write a
+low level driver for it yourself and submit it. In case you can't write
+it yourself there is a good chance to get it supported if you can donate
+one of those cards and - if at all possible - docs for it.
+
+
+10. How do i report bugs ?
+--------------------------
+
+Please submit patches ONLY as context diffs (diff -c)!
+
+I vastly prefer receiving bug fixes and enhancements that are clearly
+differentiated. I don't always know what to do with large patches that
+contain many bugs and enhances folded into the same context diffs. 
+
+Please keep it to one fix or enhancement per patch!
+
+If your change modifies the external interface of an ISDN4BSD program,
+i.e. more config options, command-line switches, new programs, etc., 
+then please also include patches for the manual pages and documentation.
+
+Thank you!
+
+
+11. Is there a mailing-list available for ISDN4BSD ?
+---------------------------------------------------
+
+There is a mailing list available at
+
+        freebsd-isdn@freebsd.org
+
+The list is maintained by majordomo, so i.e. to subscribe,
+send a mail with the text
+
+        subscribe freebsd-isdn
+        
+in the message body sent to
+
+        majordomo@freebsd.org
+
+This mailing list is NOT (!) FreeBSD specific, everyone is welcome there!
+
+
+12. Where can i get ISDN4BSD ?
+------------------------------
+
+The ISDN4BSD package is available from:
+
+	isdn4bsd@ftp.consol.de/pub
+	--------------------------
+
+you have to log in as user
+
+	isdn4bsd
+	--------
+
+and give your mail address as the password. Then change to the "pub" 
+directory. You will find the latest available ISDN4BSD package.
+
+Anonymous ftp as user "ftp" or "anonymous" will NOT (!) give the desired
+result !
+
+This is a sample session:
+
+	$ ftp ftp.consol.de
+	Connected to stage.consol.de.
+	220 ProFTPD 1.0.0 Server (ConSol* Data Exchange) [stage]
+	Name (ftp.consol.de:root): isdn4bsd
+	331 Anonymous login ok, send your complete e-mail address as password.
+	Password:
+	230 Anonymous access granted, restrictions apply.
+	Remote system type is UNIX.
+	Using binary mode to transfer files.
+	ftp> cd pub
+	250 CWD command successful.
+	ftp>
+
+
+13. What is the reward for reading everything in this file ?
+------------------------------------------------------------
+
+Have fun!
+hellmuth
diff --git a/share/examples/isdn/ROADMAP b/share/examples/isdn/ROADMAP
new file mode 100644
index 0000000..54f6721
--- /dev/null
+++ b/share/examples/isdn/ROADMAP
@@ -0,0 +1,75 @@
+
+	Roadmap of isdn4bsd as integrated into FreeBSD
+	==============================================
+
+	$Id:$
+
+	last edit-date: [Mon Jan 18 14:47:09 1999]
+
+
+1.	Documentation
+---------------------
+
+	The command "apropos isdn" will list all manpages available for 
+	isdn4bsd. Two more manual pages of interest to syncronous PPP 
+	over ISDN users are the pages for sppp and spppcontrol.
+
+	Under directory /usr/share/examples/isdn, you will find:
+
+	FAQ		- isdn4bsd Frequently Asked Questions
+	Overview	- short technical overview (a bit outdated)
+	README		- the original isdn4bsd README file
+	ROADMAP		- this file
+	Resources	- some more information about ISDN
+	isdnd_acct	- perl script to produce accounting reports
+
+
+2.	Configuration
+---------------------
+
+	Configuration of the isdn4bsd package consists of:
+
+	- configuring a kernel suitable for running isdn4bsd. An
+	  example kernel configuration can be found in the file
+	  /usr/src/sys/i386/conf/LINT. The options available for
+	  isic device driver in the kernel configuration file are
+	  described in the output of "man isic".
+
+	- configuring the network interfaces iprX and/or ispX; the
+	  former are used for "IP over raw HDLC" and the latter are
+	  used for "sync PPP over ISDN". To configure the ipr-
+	  interfaces, read the output of "man i4bipr", to configure
+	  the isp-interfaces, read the output of "man i4bisppp",
+	  "man sppp" and "man spppcontrol" carefully.
+	  Most of this configuration is now available thru the ISDN
+	  and spppcontrol sections in /etc/rc.conf.
+
+	- writing a configuration file /etc/isdn/isdnd.rc for the
+	  isdn daemon isdnd(8) which is responsible for the ISDN
+	  call control mechanisms such as: dial on demand, dial
+	  retry, dial recovery, timeout and short hold operation.
+	  A sample (!) file can be found in /etc/isdn. Please read
+	  the output of "man isdnd" and "man isdnd.rc" carefully.
+
+
+2.	Userland programs
+-------------------------
+
+	The userland programs can be found in the sourcetree under
+	/usr/src/usr.sbin/i4b and get installed under /usr/sbin.
+
+	Isdntest will not be installed by default.
+
+
+3.	Kernel part
+-------------------
+
+	The kernel part of isdn4bsd can be found at /usr/src/sys/i4b.
+
+
+4.	Answering machine messages
+----------------------------------
+
+	Messages to be used by the answering machine can be found in
+	/usr/share/isdn, you'll find the numbers 0 to 9, a beep and
+	a short announcement message here.
diff --git a/share/examples/isdn/Resources b/share/examples/isdn/Resources
new file mode 100644
index 0000000..97296d2
--- /dev/null
+++ b/share/examples/isdn/Resources
@@ -0,0 +1,90 @@
+
+Doku: Anwahl von T-Offline mittels i4b und FreeBSD (german)
+===========================================================
+
+	http://www.de.freebsd.org/de/i4b-t-error.html
+
+
+ISDN Information:
+=================
+
+	http://www.alumni.caltech.edu/~dank/isdn/
+
+
+ITU Standards:
+==============
+
+	http://www-library.itsi.disa.mil/org/ituccitt.html
+	ftp://ftp.leo.org/pub/comp/doc/standards/itu
+
+
+SunShine Project - Implementation of the ISDN recommendations Q.921 & Q.931
+===========================================================================
+
+	http://www.tcm.hut.fi/~bos/ISDN/sunshine/SunShine.html
+
+
+CAPI 2.0 documentation
+======================
+
+	http://www.capi.org
+
+
+Siemens ISDN chips Databooks (ISAC/HSCX)
+========================================
+
+	general:
+	--------
+	http://w2.siemens.de/semiconductor/products/ICs/33/33.htm
+	http://www.smi.siemens.com/applications/comm/isdnte/index.html
+
+	ISAC:
+	-----
+	http://w2.siemens.de/semiconductor/products/ICs/33/isac_ste/iste_11m.pdf
+	http://www.smi.siemens.com/pdf/comm/peb2085_6um.pdf
+	http://www.smi.siemens.com/pdf/comm/psb2186um.pdf
+
+	HSCX:
+	-----
+	http://w2.siemens.de/semiconductor/products/ICs/33/hscx/sab82525.pdf
+	http://www.smi.siemens.com/pdf/comm/SAB82526_5.pdf
+	http://www.smi.siemens.com/pdf/comm/psb21525um.pdf
+
+
+CD's:
+=====
+	The Infomagic Standards CDROM:
+	http://www.infomagic.com/catalog5.htm#standards
+
+Books:
+======
+
+	"ISDN: concepts, facilities and services",
+		Gary C. Kessler, McGraw-Hill 1993,
+		ISBN 0-07-034247-4
+	
+	"Integrated services digital networks: architectures, protocols, standards",
+		Herman J. Helgert, Addison-Wesley 1991,
+		ISBN 0-201-52501-1
+	
+	"ISDN and Broadband ISDN with Frame Relay and ATM",
+		William Stallings, Prentice Hall 1995,
+		ISBN 0-02-415513-6
+
+	"Technik der Netze",
+		Gerd Siegmund, R. v. Decker's Verlag 1996,
+		ISBN 3-7685-2495-7
+	
+	"Euro-ISDN fuer Anwender und Techniker"
+		Reinhard Heermeyer und Maria Spath, Festo DIDACTIC 1996,
+		ISBN 3-8127-4334-5
+
+	"ISDN implementors guide: standards, protocols & services",
+		Charles K. Summers, McGraw-Hill 1995,
+		ISBN 0-07-069416-8
+	
+	"PPP Design and Debugging",
+		James Carlson, Addison-Wesley 1998,
+		ISBN 0-0201-18539-3
+
+-- EOF -----------------------------------------------------------------------
diff --git a/share/examples/isdn/isdnd_acct b/share/examples/isdn/isdnd_acct
new file mode 100644
index 0000000..faefaa5
--- /dev/null
+++ b/share/examples/isdn/isdnd_acct
@@ -0,0 +1,137 @@
+#!/usr/bin/perl
+#---------------------------------------------------------------------------
+#
+# Copyright (c) 1996, 1998 Hellmuth Michaelis. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+# SUCH DAMAGE.
+#
+#---------------------------------------------------------------------------
+#
+#	accounting report script for the isdnd daemon accounting info
+#	-------------------------------------------------------------
+#
+#	$Id: isdnd_acct,v 1.1 1998/01/23 13:38:53 hm Exp $
+#
+#	last edit-date: [Mon Jan 18 14:08:10 1999]
+#
+#---------------------------------------------------------------------------
+
+# where the isdnd accounting file resides
+$ACCT_FILE = "/var/log/isdnd.acct";
+
+# the charge for a unit, currently 0,12 DM
+$UNIT_PRICE = 0.12;
+
+# open accounting file
+open(IN, $ACCT_FILE) ||
+	die "ERROR, cannot open $ACCT_FILE !\n";
+
+# set first thru flag
+$first = 1;
+
+# process file line by line
+while (<IN>)
+{
+	# remove ( and ) from length and bytecounts
+	tr/()//d;
+
+	# split line into pieces
+	($from_d, $from_h, $dash, $to_d, $to_h, $name, $units, $secs, $byte)
+		= split(/ /, $_);
+
+	# get starting date
+	if($first)
+	{
+		$from = "$from_d $from_h";
+		$first = 0;
+	}
+		
+	# split bytecount
+	($inb, $outb) = split(/\//, $byte);
+
+	# process fields
+	$a_secs{$name} += $secs;
+	$a_calls{$name}++;
+	$a_units{$name} += $units;
+	$a_charge{$name} += $units * $UNIT_PRICE;
+	$a_inbytes{$name} += $inb;
+	$a_outbytes{$name} += $outb;
+	$a_bytes{$name} = $a_bytes{$name} + $inb + $outb;
+}
+
+# close accouting file
+close(IN);
+
+# write header
+print "\n";
+print "     ISDN Accounting Report   ($from -> $to_d $to_h)\n";
+print "     ==================================================================\n";
+
+#write the sum for each interface/name
+foreach $name (sort(keys %a_secs))
+{
+	$o_secs = $a_secs{$name};
+	$gt_secs += $o_secs;
+	$o_calls = $a_calls{$name};
+	$gt_calls += $o_calls;
+	$o_units = $a_units{$name};
+	$gt_units += $o_units;
+	$o_charge = $a_charge{$name};
+	$gt_charge += $o_charge;
+	$o_inbytes = $a_inbytes{$name};
+	$gt_inbytes += $o_inbytes;
+	$o_outbytes = $a_outbytes{$name};
+	$gt_outbytes += $o_outbytes;
+	$o_bytes = $a_bytes{$name};
+	$gt_bytes += $o_bytes;
+	write;
+}
+
+$o_secs = $gt_secs;
+$o_calls = $gt_calls;
+$o_units = $gt_units;
+$o_charge = $gt_charge;
+$o_inbytes = $gt_inbytes;
+$o_outbytes = $gt_outbytes;
+$o_bytes = $gt_bytes;
+$name = "Total";
+
+print "======= ====== ===== ===== ======== ============ ============ ============\n";
+write;
+
+print "\n\n";
+exit;
+
+# top of page header
+format top =
+
+Name    charge units calls     secs      inbytes     outbytes        bytes
+------- ------ ----- ----- -------- ------------ ------------ ------------
+.
+
+# record template
+format STDOUT =
+@<<<<<< @##.## @#### @#### @####### @########### @########### @###########
+$name,  $o_charge, $o_units, $o_calls, $o_secs, $o_inbytes, $o_outbytes, $o_bytes
+.
+
+# EOF