1Linux Quicknet-Drivers-Howto 2Quicknet Technologies, Inc. (www.quicknet.net) 3Version 0.3.4 December 18, 1999 4 51.0 Introduction 6 7This document describes the first GPL release version of the Linux 8driver for the Quicknet Internet PhoneJACK and Internet LineJACK 9cards. More information about these cards is available at 10www.quicknet.net. The driver version discussed in this document is 110.3.4. 12 13These cards offer nice telco style interfaces to use your standard 14telephone/key system/PBX as the user interface for VoIP applications. 15The Internet LineJACK also offers PSTN connectivity for a single line 16Internet to PSTN gateway. Of course, you can add more than one card 17to a system to obtain multi-line functionality. At this time, the 18driver supports the POTS port on both the Internet PhoneJACK and the 19Internet LineJACK, but the PSTN port on the latter card is not yet 20supported. 21 22This document, and the drivers for the cards, are intended for a 23limited audience that includes technically capable programmers who 24would like to experiment with Quicknet cards. The drivers are 25considered in ALPHA status and are not yet considered stable enough 26for general, widespread use in an unlimited audience. 27 28That's worth saying again: 29 30THE LINUX DRIVERS FOR QUICKNET CARDS ARE PRESENTLY IN A ALPHA STATE 31AND SHOULD NOT BE CONSIDERED AS READY FOR NORMAL WIDESPREAD USE. 32 33They are released early in the spirit of Internet development and to 34make this technology available to innovators who would benefit from 35early exposure. 36 37When we promote the device driver to "beta" level it will be 38considered ready for non-programmer, non-technical users. Until then, 39please be aware that these drivers may not be stable and may affect 40the performance of your system. 41 42 431.1 Latest Additions/Improvements 44 45The 0.3.4 version of the driver is the first GPL release. Several 46features had to be removed from the prior binary only module, mostly 47for reasons of Intellectual Property rights. We can't release 48information that is not ours - so certain aspects of the driver had to 49be removed to protect the rights of others. 50 51Specifically, very old Internet PhoneJACK cards have non-standard 52G.723.1 codecs (due to the early nature of the DSPs in those days). 53The auto-conversion code to bring those cards into compliance with 54todays standards is available as a binary only module to those people 55needing it. If you bought your card after 1997 or so, you are OK - 56it's only the very old cards that are affected. 57 58Also, the code to download G.728/G.729/G.729a codecs to the DSP is 59available as a binary only module as well. This IP is not ours to 60release. 61 62Hooks are built into the GPL driver to allow it to work with other 63companion modules that are completely separate from this module. 64 651.2 Copyright, Trademarks, Disclaimer, & Credits 66 67Copyright 68 69Copyright (c) 1999 Quicknet Technologies, Inc. Permission is granted 70to freely copy and distribute this document provided you preserve it 71in its original form. For corrections and minor changes contact the 72maintainer at linux@quicknet.net. 73 74Trademarks 75 76Internet PhoneJACK and Internet LineJACK are registered trademarks of 77Quicknet Technologies, Inc. 78 79Disclaimer 80 81Much of the info in this HOWTO is early information released by 82Quicknet Technologies, Inc. for the express purpose of allowing early 83testing and use of the Linux drivers developed for their products. 84While every attempt has been made to be thorough, complete and 85accurate, the information contained here may be unreliable and there 86are likely a number of errors in this document. Please let the 87maintainer know about them. Since this is free documentation, it 88should be obvious that neither I nor previous authors can be held 89legally responsible for any errors. 90 91Credits 92 93This HOWTO was written by: 94 95 Greg Herlein <gherlein@quicknet.net> 96 Ed Okerson <eokerson@quicknet.net> 97 981.3 Future Plans: You Can Help 99 100Please let the maintainer know of any errors in facts, opinions, 101logic, spelling, grammar, clarity, links, etc. But first, if the date 102is over a month old, check to see that you have the latest 103version. Please send any info that you think belongs in this document. 104 105You can also contribute code and/or bug-fixes for the sample 106applications. 107 108 1091.4 Where to get things 110 111You can download the latest versions of the driver from: 112 113http://www.quicknet.net/develop.htm 114 115You can download the latest version of this document from: 116 117http://www.quicknet.net/develop.htm 118 119 1201.5 Mailing List 121 122Quicknet operates a mailing list to provide a public forum on using 123these drivers. 124 125To subscribe to the linux-sdk mailing list, send an email to: 126 127 majordomo@linux.quicknet.net 128 129In the body of the email, type: 130 131 subscribe linux-sdk <your-email-address> 132 133Please delete any signature block that you would normally add to the 134bottom of your email - it tends to confuse majordomo. 135 136To send mail to the list, address your mail to 137 138 linux-sdk@linux.quicknet.net 139 140Your message will go out to everyone on the list. 141 142To unsubscribe to the linux-sdk mailing list, send an email to: 143 144 majordomo@linux.quicknet.net 145 146In the body of the email, type: 147 148 unsubscribe linux-sdk <your-email-address> 149 150 151 1522.0 Requirements 153 1542.1 Quicknet Card(s) 155 156You will need at least one Internet PhoneJACK or Internet LineJACK 157cards. These are ISA or PCI bus devices that use Plug-n-Play for 158configuration, and use no IRQs. The driver will support up to 16 159cards in any one system, of any mix between the two types. 160 161Note that you will need two cards to do any useful testing alone, since 162you will need a card on both ends of the connection. Of course, if 163you are doing collaborative work, perhaps your friends or coworkers 164have cards too. If not, we'll gladly sell them some! 165 166 1672.2 ISAPNP 168 169Since the Quicknet cards are Plug-n-Play devices, you will need the 170isapnp tools package to configure the cards, or you can use the isapnp 171module to autoconfigure them. The former package probably came with 172your Linux distribution. Documentation on this package is available 173online at: 174 175http://mailer.wiwi.uni-marburg.de/linux/LDP/HOWTO/Plug-and-Play-HOWTO.html 176 177The isapnp autoconfiguration is available on the Quicknet website at: 178 179 http://www.quicknet.net/develop.htm 180 181though it may be in the kernel by the time you read this. 182 183 1843.0 Card Configuration 185 186If you did not get your drivers as part of the linux kernel, do the 187following to install them: 188 189 a. untar the distribution file. We use the following command: 190 tar -xvzf ixj-0.x.x.tgz 191 192This creates a subdirectory holding all the necessary files. Go to that 193subdirectory. 194 195 b. run the "ixj_dev_create" script to remove any stray device 196files left in the /dev directory, and to create the new officially 197designated 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 201module. 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 287of this would look like this: 288 289 insmod phonedev 290 insmod ixj dspio=0x320,0x310 xio=0,0x330 291 292Then verify the module loaded by running lsmod. If you are not using a 293module that matches your kernel version, you may need to "force" the 294load using the -f option in the insmod command. 295 296 insmod phonedev 297 insmod -f ixj dspio=0x320,0x310 xio=0,0x330 298 299 300If you are using isapnp to autoconfigure your card, then you do NOT 301need any of the above, though you need to use depmod to load the 302driver, like this: 303 304 depmod ixj 305 306which will result in the needed drivers getting loaded automatically. 307 308 g. if you are planning on using kerneld to automatically load the 309module for you, then you need to edit /etc/conf.modules and add the 310following lines: 311 312 options ixj dspio=0x340 xio=0x330 ixjdebug=0 313 314If you do this, then when you execute an application that uses the 315module kerneld will load the module for you. Note that to do this, 316you need to have your kernel set to support kerneld. You can check 317for this by looking at /usr/src/linux/.config and you should see this: 318 319 # Loadable module support 320 # 321 <snip> 322 CONFIG_KMOD=y 323 324 h. if you want non-root users to be able to read and write to the 325ixj devices (this is a good idea!) you should do the following: 326 327 - decide upon a group name to use and create that group if 328 needed. Add the user names to that group that you wish to 329 have access to the device. For example, we typically will 330 create a group named "ixj" in /etc/group and add all users 331 to that group that we want to run software that can use the 332 ixjX devices. 333 334 - change the permissions on the device files, like this: 335 336 chgrp ixj /dev/ixj* 337 chmod 660 /dev/ixj* 338 339Once this is done, then non-root users should be able to use the 340devices. If you have enabled autoloading of modules, then the user 341should be able to open the device and have the module loaded 342automatically for them. 343 344 3454.0 Driver Installation problems. 346 347We have tested these drivers on the 2.2.9, 2.2.10, 2.2.12, and 2.2.13 kernels 348and in all cases have eventually been able to get the drivers to load and 349run. We have found four types of problems that prevent this from happening. 350The problems and solutions are: 351 352 a. A step was missed in the installation. Go back and use section 3 353as a checklist. Many people miss running the ixj_dev_create script and thus 354never load the device names into the filesystem. 355 356 b. The kernel is inconsistently linked. We have found this problem in 357the Out Of the Box installation of several distributions. The symptoms 358are that neither driver will load, and that the unknown symbols include "jiffy" 359and "kmalloc". The solution is to recompile both the kernel and the 360modules. The command string for the final compile looks like this: 361 362 In the kernel directory: 363 1. cp .config /tmp 364 2. make mrproper 365 3. cp /tmp/.config . 366 4. make clean;make bzImage;make modules;make modules_install 367 368This rebuilds both the kernel and all the modules and makes sure they all 369have the same linkages. This generally solves the problem once the new 370kernel is installed and the system rebooted. 371 372 c. The kernel has been patched, then unpatched. This happens when 373someone decides to use an earlier kernel after they load a later kernel. 374The symptoms are proceeding through all three above steps and still not 375being able to load the driver. What has happened is that the generated 376header files are out of sync with the kernel itself. The solution is 377to recompile (again) using "make mrproper". This will remove and then 378regenerate all the necessary header files. Once this is done, then you 379need to install and reboot the kernel. We have not seen any problem 380loading one of our drivers after this treatment. 381 3825.0 Known Limitations 383 384We cannot currently play "dial-tone" and listen for DTMF digits at the 385same time using the ISA PhoneJACK. This is a bug in the 8020 DSP chip 386used on that product. All other Quicknet products function normally 387in this regard. We have a work-around, but it's not done yet. Until 388then, if you want dial-tone, you can always play a recorded dial-tone 389sound into the audio until you have gathered the DTMF digits. 390