Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | ||
a81792f6 JB |
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 | |
1da177e4 LT |
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 | |
a81792f6 | 315 | module the kernel will request that it is loaded. |
1da177e4 LT |
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 |