Merge branch 'upstream-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mfashe...
[linux-2.6] / Documentation / telephony / ixj.txt
1 Linux Quicknet-Drivers-Howto
2 Quicknet Technologies, Inc. (www.quicknet.net)
3 Version 0.3.4  December 18, 1999
4
5 1.0  Introduction
6
7 This document describes the first GPL release version of the Linux
8 driver for the Quicknet Internet PhoneJACK and Internet LineJACK
9 cards.  More information about these cards is available at
10 www.quicknet.net.  The driver version discussed in this document is
11 0.3.4.
12
13 These cards offer nice telco style interfaces to use your standard
14 telephone/key system/PBX as the user interface for VoIP applications.
15 The Internet LineJACK also offers PSTN connectivity for a single line
16 Internet to PSTN gateway.  Of course, you can add more than one card
17 to a system to obtain multi-line functionality.  At this time, the
18 driver supports the POTS port on both the Internet PhoneJACK and the
19 Internet LineJACK, but the PSTN port on the latter card is not yet
20 supported.
21
22 This document, and the drivers for the cards, are intended for a
23 limited audience that includes technically capable programmers who
24 would like to experiment with Quicknet cards.  The drivers are
25 considered in ALPHA status and are not yet considered stable enough
26 for general, widespread use in an unlimited audience.
27
28 That's worth saying again:
29
30 THE LINUX DRIVERS FOR QUICKNET CARDS ARE PRESENTLY IN A ALPHA STATE
31 AND SHOULD NOT BE CONSIDERED AS READY FOR NORMAL WIDESPREAD USE.
32
33 They are released early in the spirit of Internet development and to
34 make this technology available to innovators who would benefit from
35 early exposure.
36
37 When we promote the device driver to "beta" level it will be
38 considered ready for non-programmer, non-technical users.  Until then,
39 please be aware that these drivers may not be stable and may affect
40 the performance of your system.
41
42
43 1.1 Latest Additions/Improvements
44
45 The 0.3.4 version of the driver is the first GPL release.  Several
46 features had to be removed from the prior binary only module, mostly
47 for reasons of Intellectual Property rights.  We can't release
48 information that is not ours - so certain aspects of the driver had to
49 be removed to protect the rights of others.  
50
51 Specifically, very old Internet PhoneJACK cards have non-standard
52 G.723.1 codecs (due to the early nature of the DSPs in those days).
53 The auto-conversion code to bring those cards into compliance with
54 todays standards is available as a binary only module to those people
55 needing it.  If you bought your card after 1997 or so, you are OK -
56 it's only the very old cards that are affected.
57
58 Also, the code to download G.728/G.729/G.729a codecs to the DSP is
59 available as a binary only module as well.  This IP is not ours to
60 release.  
61
62 Hooks are built into the GPL driver to allow it to work with other
63 companion modules that are completely separate from this module.
64
65 1.2 Copyright, Trademarks, Disclaimer, & Credits 
66
67 Copyright
68
69 Copyright (c) 1999 Quicknet Technologies, Inc.  Permission is granted
70 to freely copy and distribute this document provided you preserve it
71 in its original form. For corrections and minor changes contact the
72 maintainer at linux@quicknet.net.
73
74 Trademarks
75
76 Internet PhoneJACK and Internet LineJACK are registered trademarks of
77 Quicknet Technologies, Inc.
78
79 Disclaimer
80
81 Much of the info in this HOWTO is early information released by
82 Quicknet Technologies, Inc. for the express purpose of allowing early
83 testing and use of the Linux drivers developed for their products.
84 While every attempt has been made to be thorough, complete and
85 accurate, the information contained here may be unreliable and there
86 are likely a number of errors in this document. Please let the
87 maintainer know about them. Since this is free documentation, it
88 should be obvious that neither I nor previous authors can be held
89 legally responsible for any errors.
90
91 Credits
92
93 This HOWTO was written by:
94
95         Greg Herlein <gherlein@quicknet.net>
96         Ed Okerson <eokerson@quicknet.net> 
97
98 1.3  Future Plans: You Can Help 
99
100 Please let the maintainer know of any errors in facts, opinions,
101 logic, spelling, grammar, clarity, links, etc.  But first, if the date
102 is over a month old, check to see that you have the latest
103 version. Please send any info that you think belongs in this document.
104
105 You can also contribute code and/or bug-fixes for the sample
106 applications.
107
108
109 1.4  Where to get things
110
111 You can download the latest versions of the driver from:
112
113 http://www.quicknet.net/develop.htm
114
115 You can download the latest version of this document from:
116
117 http://www.quicknet.net/develop.htm
118
119
120 1.5  Mailing List
121
122 Quicknet operates a mailing list to provide a public forum on using
123 these drivers.
124
125 To subscribe to the linux-sdk mailing list, send an email to:
126
127    majordomo@linux.quicknet.net
128
129 In the body of the email, type:
130
131    subscribe linux-sdk <your-email-address>
132
133 Please delete any signature block that you would normally add to the
134 bottom of your email - it tends to confuse majordomo.
135
136 To send mail to the list, address your mail to 
137
138    linux-sdk@linux.quicknet.net
139
140 Your message will go out to everyone on the list.
141
142 To unsubscribe to the linux-sdk mailing list, send an email to:
143
144    majordomo@linux.quicknet.net
145
146 In the body of the email, type:
147
148    unsubscribe linux-sdk <your-email-address>
149
150
151
152 2.0  Requirements
153
154 2.1  Quicknet Card(s)
155
156 You will need at least one Internet PhoneJACK or Internet LineJACK
157 cards.  These are ISA or PCI bus devices that use Plug-n-Play for
158 configuration, and use no IRQs.  The driver will support up to 16
159 cards in any one system, of any mix between the two types.
160
161 Note that you will need two cards to do any useful testing alone, since
162 you will need a card on both ends of the connection.  Of course, if
163 you are doing collaborative work, perhaps your friends or coworkers
164 have cards too.  If not, we'll gladly sell them some!
165
166
167 2.2  ISAPNP
168
169 Since the Quicknet cards are Plug-n-Play devices, you will need the
170 isapnp tools package to configure the cards, or you can use the isapnp
171 module to autoconfigure them.  The former package probably came with
172 your Linux distribution.  Documentation on this package is available
173 online at:
174
175 http://mailer.wiwi.uni-marburg.de/linux/LDP/HOWTO/Plug-and-Play-HOWTO.html
176
177 The isapnp autoconfiguration is available on the Quicknet website at:
178
179     http://www.quicknet.net/develop.htm
180
181 though it may be in the kernel by the time you read this.
182
183
184 3.0  Card Configuration 
185
186 If you did not get your drivers as part of the linux kernel, do the
187 following to install them:
188
189    a.  untar the distribution file.  We use the following command:
190         tar -xvzf ixj-0.x.x.tgz
191
192 This creates a subdirectory holding all the necessary files.  Go to that
193 subdirectory.
194
195    b.  run the "ixj_dev_create" script to remove any stray device
196 files left in the /dev directory, and to create the new officially
197 designated device files.  Note that the old devices were called 
198 /dev/ixj, and the new method uses /dev/phone.  
199
200    c.  type "make;make install" - this will compile and install the
201 module.
202
203    d.  type "depmod -av" to rebuild all your kernel version dependencies.
204
205    e.  if you are using the isapnp module to configure the cards
206        automatically, then skip to step f.  Otherwise, ensure that you
207        have run the isapnp configuration utility to properly configure
208        the cards.
209
210        e1. The Internet PhoneJACK has one configuration register that
211            requires 16 IO ports.  The Internet LineJACK card has two
212            configuration registers and isapnp reports that IO 0
213            requires 16 IO ports and IO 1 requires 8.  The Quicknet
214            driver assumes that these registers are configured to be
215            contiguous, i.e. if IO 0 is set to 0x340 then IO 1 should
216            be set to 0x350.
217
218            Make sure that none of the cards overlap if you have
219            multiple cards in the system.
220
221            If you are new to the isapnp tools, you can jumpstart
222            yourself by doing the following:
223
224       e2.  go to the /etc directory and run pnpdump to get a blank
225            isapnp.conf file.
226
227                 pnpdump > /etc/isapnp.conf
228
229       e3.  edit the /etc/isapnp.conf file to set the IO warnings and
230            the register IO addresses. The IO warnings means that you
231            should find the line in the file that looks like this:
232
233            (CONFLICT (IO FATAL)(IRQ FATAL)(DMA FATAL)(MEM FATAL)) # or WARNING
234
235            and you should edit the line to look like this:
236
237            (CONFLICT (IO WARNING)(IRQ FATAL)(DMA FATAL)(MEM FATAL)) #
238            or WARNING
239
240            The next step is to set the IO port addresses.  The issue
241            here is that isapnp does not identify all of the ports out
242            there.  Specifically any device that does not have a driver
243            or module loaded by Linux will not be registered.  This
244            includes older sound cards and network cards.  We have
245            found that the IO port 0x300 is often used even though
246            isapnp claims that no-one is using those ports.  We
247            recommend that for a single card installation that port
248            0x340 (and 0x350) be used.  The IO port line should change
249            from this:
250
251            (IO 0 (SIZE 16) (BASE 0x0300) (CHECK))
252
253            to this:
254
255            (IO 0 (SIZE 16) (BASE 0x0340) )
256
257        e4.  if you have multiple Quicknet cards, make sure that you do
258             not have any overlaps.  Be especially careful if you are
259             mixing Internet PhoneJACK and Internet LineJACK cards in
260             the same system.  In these cases we recommend moving the
261             IO port addresses to the 0x400 block.  Please note that on
262             a few machines the 0x400 series are used.  Feel free to
263             experiment with other addresses.  Our cards have been
264             proven to work using IO addresses of up to 0xFF0.
265
266        e5.  the last step is to uncomment the activation line so the
267             drivers will be associated with the port.  This means the
268             line (immediately below) the IO line should go from this:
269
270             # (ACT Y)
271
272             to this:
273
274             (ACT Y)
275
276             Once you have finished editing the isapnp.conf file you
277             must submit it into the pnp driverconfigure the cards.
278             This is done using the following command:
279
280             isapnp isapnp.conf
281
282             If this works you should see a line that identifies the
283             Quicknet device, the IO port(s) chosen, and a message
284             "Enabled OK".
285
286    f.  if you are loading the module by hand, use insmod.  An example
287 of this would look like this:
288
289         insmod phonedev
290         insmod ixj dspio=0x320,0x310 xio=0,0x330
291
292 Then verify the module loaded by running lsmod. If you are not using a
293 module that matches your kernel version, you may need to "force" the
294 load using the -f option in the insmod command.
295
296         insmod phonedev
297         insmod -f ixj dspio=0x320,0x310 xio=0,0x330
298
299
300 If you are using isapnp to autoconfigure your card, then you do NOT
301 need any of the above, though you need to use depmod to load the
302 driver, like this:
303
304         depmod ixj
305
306 which will result in the needed drivers getting loaded automatically.
307
308    g.  if you are planning on having the kernel automatically request
309 the module for you, then you need to edit /etc/conf.modules and add the
310 following lines:
311
312         options ixj dspio=0x340 xio=0x330 ixjdebug=0
313
314 If you do this, then when you execute an application that uses the
315 module the kernel will request that it is loaded.
316
317   h.  if you want non-root users to be able to read and write to the 
318 ixj devices (this is a good idea!) you should do the following:
319
320      - decide upon a group name to use and create that group if 
321        needed.  Add the user names to that group that you wish to 
322        have access to the device.  For example, we typically will
323        create a group named "ixj" in /etc/group and add all users
324        to that group that we want to run software that can use the 
325        ixjX devices.
326
327      - change the permissions on the device files, like this:
328         
329        chgrp ixj /dev/ixj*      
330        chmod 660 /dev/ixj*
331         
332 Once this is done, then non-root users should be able to use the
333 devices.  If you have enabled autoloading of modules, then the user
334 should be able to open the device and have the module loaded
335 automatically for them.
336
337
338 4.0 Driver Installation problems.
339
340 We have tested these drivers on the 2.2.9, 2.2.10, 2.2.12, and 2.2.13 kernels
341 and in all cases have eventually been able to get the drivers to load and 
342 run.  We have found four types of problems that prevent this from happening.
343 The problems and solutions are:
344
345   a. A step was missed in the installation.  Go back and use section 3
346 as a checklist.  Many people miss running the ixj_dev_create script and thus
347 never load the device names into the filesystem.
348
349   b. The kernel is inconsistently linked.  We have found this problem in
350 the Out Of the Box installation of several distributions.  The symptoms 
351 are that neither driver will load, and that the unknown symbols include "jiffy"
352 and "kmalloc".  The solution is to recompile both the kernel and the
353 modules.  The command string for the final compile looks like this:
354
355     In the kernel directory:
356     1.  cp .config /tmp
357     2.  make mrproper
358     3.  cp /tmp/.config .
359     4.  make clean;make bzImage;make modules;make modules_install
360
361 This rebuilds both the kernel and all the modules and makes sure they all 
362 have the same linkages.  This generally solves the problem once the new 
363 kernel is installed and the system rebooted.
364
365   c. The kernel has been patched, then unpatched.  This happens when
366 someone decides to use an earlier kernel after they load a later kernel.
367 The symptoms are proceeding through all three above steps and still not
368 being able to load the driver.  What has happened is that the generated
369 header files are out of sync with the kernel itself.  The solution is
370 to recompile (again) using "make mrproper".  This will remove and then
371 regenerate all the necessary header files.  Once this is done, then you 
372 need to install and reboot the kernel.  We have not seen any problem
373 loading one of our drivers after this treatment.
374
375 5.0  Known Limitations
376
377 We cannot currently play "dial-tone" and listen for DTMF digits at the
378 same time using the ISA PhoneJACK.  This is a bug in the 8020 DSP chip
379 used on that product.  All other Quicknet products function normally
380 in this regard.  We have a work-around, but it's not done yet.  Until
381 then, if you want dial-tone, you can always play a recorded dial-tone
382 sound into the audio until you have gathered the DTMF digits.
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399