Based on kernel version 3.7. Page generated on 2012-12-12 10:01 EST.
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 today's 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 Info on latest versions of the driver are here: 112 113 http://web.archive.org/web/*/http://www.quicknet.net/develop.htm 114 115 1.5 Mailing List 116 117 Quicknet operates a mailing list to provide a public forum on using 118 these drivers. 119 120 To subscribe to the linux-sdk mailing list, send an email to: 121 122 majordomo@linux.quicknet.net 123 124 In the body of the email, type: 125 126 subscribe linux-sdk <your-email-address> 127 128 Please delete any signature block that you would normally add to the 129 bottom of your email - it tends to confuse majordomo. 130 131 To send mail to the list, address your mail to 132 133 linux-sdk@linux.quicknet.net 134 135 Your message will go out to everyone on the list. 136 137 To unsubscribe to the linux-sdk mailing list, send an email to: 138 139 majordomo@linux.quicknet.net 140 141 In the body of the email, type: 142 143 unsubscribe linux-sdk <your-email-address> 144 145 146 147 2.0 Requirements 148 149 2.1 Quicknet Card(s) 150 151 You will need at least one Internet PhoneJACK or Internet LineJACK 152 cards. These are ISA or PCI bus devices that use Plug-n-Play for 153 configuration, and use no IRQs. The driver will support up to 16 154 cards in any one system, of any mix between the two types. 155 156 Note that you will need two cards to do any useful testing alone, since 157 you will need a card on both ends of the connection. Of course, if 158 you are doing collaborative work, perhaps your friends or coworkers 159 have cards too. If not, we'll gladly sell them some! 160 161 162 2.2 ISAPNP 163 164 Since the Quicknet cards are Plug-n-Play devices, you will need the 165 isapnp tools package to configure the cards, or you can use the isapnp 166 module to autoconfigure them. The former package probably came with 167 your Linux distribution. Documentation on this package is available 168 online at: 169 170 http://mailer.wiwi.uni-marburg.de/linux/LDP/HOWTO/Plug-and-Play-HOWTO.html 171 172 The isapnp autoconfiguration is available on the Quicknet website at: 173 174 http://www.quicknet.net/develop.htm 175 176 though it may be in the kernel by the time you read this. 177 178 179 3.0 Card Configuration 180 181 If you did not get your drivers as part of the linux kernel, do the 182 following to install them: 183 184 a. untar the distribution file. We use the following command: 185 tar -xvzf ixj-0.x.x.tgz 186 187 This creates a subdirectory holding all the necessary files. Go to that 188 subdirectory. 189 190 b. run the "ixj_dev_create" script to remove any stray device 191 files left in the /dev directory, and to create the new officially 192 designated device files. Note that the old devices were called 193 /dev/ixj, and the new method uses /dev/phone. 194 195 c. type "make;make install" - this will compile and install the 196 module. 197 198 d. type "depmod -av" to rebuild all your kernel version dependencies. 199 200 e. if you are using the isapnp module to configure the cards 201 automatically, then skip to step f. Otherwise, ensure that you 202 have run the isapnp configuration utility to properly configure 203 the cards. 204 205 e1. The Internet PhoneJACK has one configuration register that 206 requires 16 IO ports. The Internet LineJACK card has two 207 configuration registers and isapnp reports that IO 0 208 requires 16 IO ports and IO 1 requires 8. The Quicknet 209 driver assumes that these registers are configured to be 210 contiguous, i.e. if IO 0 is set to 0x340 then IO 1 should 211 be set to 0x350. 212 213 Make sure that none of the cards overlap if you have 214 multiple cards in the system. 215 216 If you are new to the isapnp tools, you can jumpstart 217 yourself by doing the following: 218 219 e2. go to the /etc directory and run pnpdump to get a blank 220 isapnp.conf file. 221 222 pnpdump > /etc/isapnp.conf 223 224 e3. edit the /etc/isapnp.conf file to set the IO warnings and 225 the register IO addresses. The IO warnings means that you 226 should find the line in the file that looks like this: 227 228 (CONFLICT (IO FATAL)(IRQ FATAL)(DMA FATAL)(MEM FATAL)) # or WARNING 229 230 and you should edit the line to look like this: 231 232 (CONFLICT (IO WARNING)(IRQ FATAL)(DMA FATAL)(MEM FATAL)) # 233 or WARNING 234 235 The next step is to set the IO port addresses. The issue 236 here is that isapnp does not identify all of the ports out 237 there. Specifically any device that does not have a driver 238 or module loaded by Linux will not be registered. This 239 includes older sound cards and network cards. We have 240 found that the IO port 0x300 is often used even though 241 isapnp claims that no-one is using those ports. We 242 recommend that for a single card installation that port 243 0x340 (and 0x350) be used. The IO port line should change 244 from this: 245 246 (IO 0 (SIZE 16) (BASE 0x0300) (CHECK)) 247 248 to this: 249 250 (IO 0 (SIZE 16) (BASE 0x0340) ) 251 252 e4. if you have multiple Quicknet cards, make sure that you do 253 not have any overlaps. Be especially careful if you are 254 mixing Internet PhoneJACK and Internet LineJACK cards in 255 the same system. In these cases we recommend moving the 256 IO port addresses to the 0x400 block. Please note that on 257 a few machines the 0x400 series are used. Feel free to 258 experiment with other addresses. Our cards have been 259 proven to work using IO addresses of up to 0xFF0. 260 261 e5. the last step is to uncomment the activation line so the 262 drivers will be associated with the port. This means the 263 line (immediately below) the IO line should go from this: 264 265 # (ACT Y) 266 267 to this: 268 269 (ACT Y) 270 271 Once you have finished editing the isapnp.conf file you 272 must submit it into the pnp driverconfigure the cards. 273 This is done using the following command: 274 275 isapnp isapnp.conf 276 277 If this works you should see a line that identifies the 278 Quicknet device, the IO port(s) chosen, and a message 279 "Enabled OK". 280 281 f. if you are loading the module by hand, use insmod. An example 282 of this would look like this: 283 284 insmod phonedev 285 insmod ixj dspio=0x320,0x310 xio=0,0x330 286 287 Then verify the module loaded by running lsmod. If you are not using a 288 module that matches your kernel version, you may need to "force" the 289 load using the -f option in the insmod command. 290 291 insmod phonedev 292 insmod -f ixj dspio=0x320,0x310 xio=0,0x330 293 294 295 If you are using isapnp to autoconfigure your card, then you do NOT 296 need any of the above, though you need to use depmod to load the 297 driver, like this: 298 299 depmod ixj 300 301 which will result in the needed drivers getting loaded automatically. 302 303 g. if you are planning on having the kernel automatically request 304 the module for you, then you need to edit /etc/conf.modules and add the 305 following lines: 306 307 options ixj dspio=0x340 xio=0x330 ixjdebug=0 308 309 If you do this, then when you execute an application that uses the 310 module the kernel will request that it is loaded. 311 312 h. if you want non-root users to be able to read and write to the 313 ixj devices (this is a good idea!) you should do the following: 314 315 - decide upon a group name to use and create that group if 316 needed. Add the user names to that group that you wish to 317 have access to the device. For example, we typically will 318 create a group named "ixj" in /etc/group and add all users 319 to that group that we want to run software that can use the 320 ixjX devices. 321 322 - change the permissions on the device files, like this: 323 324 chgrp ixj /dev/ixj* 325 chmod 660 /dev/ixj* 326 327 Once this is done, then non-root users should be able to use the 328 devices. If you have enabled autoloading of modules, then the user 329 should be able to open the device and have the module loaded 330 automatically for them. 331 332 333 4.0 Driver Installation problems. 334 335 We have tested these drivers on the 2.2.9, 2.2.10, 2.2.12, and 2.2.13 kernels 336 and in all cases have eventually been able to get the drivers to load and 337 run. We have found four types of problems that prevent this from happening. 338 The problems and solutions are: 339 340 a. A step was missed in the installation. Go back and use section 3 341 as a checklist. Many people miss running the ixj_dev_create script and thus 342 never load the device names into the filesystem. 343 344 b. The kernel is inconsistently linked. We have found this problem in 345 the Out Of the Box installation of several distributions. The symptoms 346 are that neither driver will load, and that the unknown symbols include "jiffy" 347 and "kmalloc". The solution is to recompile both the kernel and the 348 modules. The command string for the final compile looks like this: 349 350 In the kernel directory: 351 1. cp .config /tmp 352 2. make mrproper 353 3. cp /tmp/.config . 354 4. make clean;make bzImage;make modules;make modules_install 355 356 This rebuilds both the kernel and all the modules and makes sure they all 357 have the same linkages. This generally solves the problem once the new 358 kernel is installed and the system rebooted. 359 360 c. The kernel has been patched, then unpatched. This happens when 361 someone decides to use an earlier kernel after they load a later kernel. 362 The symptoms are proceeding through all three above steps and still not 363 being able to load the driver. What has happened is that the generated 364 header files are out of sync with the kernel itself. The solution is 365 to recompile (again) using "make mrproper". This will remove and then 366 regenerate all the necessary header files. Once this is done, then you 367 need to install and reboot the kernel. We have not seen any problem 368 loading one of our drivers after this treatment. 369 370 5.0 Known Limitations 371 372 We cannot currently play "dial-tone" and listen for DTMF digits at the 373 same time using the ISA PhoneJACK. This is a bug in the 8020 DSP chip 374 used on that product. All other Quicknet products function normally 375 in this regard. We have a work-around, but it's not done yet. Until 376 then, if you want dial-tone, you can always play a recorded dial-tone 377 sound into the audio until you have gathered the DTMF digits. 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393