linux/Documentation/telephony/ixj.txt
<<
>>
Prefs
   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
  54today's 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
 111Info on latest versions of the driver are here:
 112
 113http://web.archive.org/web/*/http://www.quicknet.net/develop.htm
 114
 1151.5  Mailing List
 116
 117Quicknet operates a mailing list to provide a public forum on using
 118these drivers.
 119
 120To subscribe to the linux-sdk mailing list, send an email to:
 121
 122   majordomo@linux.quicknet.net
 123
 124In the body of the email, type:
 125
 126   subscribe linux-sdk <your-email-address>
 127
 128Please delete any signature block that you would normally add to the
 129bottom of your email - it tends to confuse majordomo.
 130
 131To send mail to the list, address your mail to 
 132
 133   linux-sdk@linux.quicknet.net
 134
 135Your message will go out to everyone on the list.
 136
 137To unsubscribe to the linux-sdk mailing list, send an email to:
 138
 139   majordomo@linux.quicknet.net
 140
 141In the body of the email, type:
 142
 143   unsubscribe linux-sdk <your-email-address>
 144
 145
 146
 1472.0  Requirements
 148
 1492.1  Quicknet Card(s)
 150
 151You will need at least one Internet PhoneJACK or Internet LineJACK
 152cards.  These are ISA or PCI bus devices that use Plug-n-Play for
 153configuration, and use no IRQs.  The driver will support up to 16
 154cards in any one system, of any mix between the two types.
 155
 156Note that you will need two cards to do any useful testing alone, since
 157you will need a card on both ends of the connection.  Of course, if
 158you are doing collaborative work, perhaps your friends or coworkers
 159have cards too.  If not, we'll gladly sell them some!
 160
 161
 1622.2  ISAPNP
 163
 164Since the Quicknet cards are Plug-n-Play devices, you will need the
 165isapnp tools package to configure the cards, or you can use the isapnp
 166module to autoconfigure them.  The former package probably came with
 167your Linux distribution.  Documentation on this package is available
 168online at:
 169
 170http://mailer.wiwi.uni-marburg.de/linux/LDP/HOWTO/Plug-and-Play-HOWTO.html
 171
 172The isapnp autoconfiguration is available on the Quicknet website at:
 173
 174    http://www.quicknet.net/develop.htm
 175
 176though it may be in the kernel by the time you read this.
 177
 178
 1793.0  Card Configuration 
 180
 181If you did not get your drivers as part of the linux kernel, do the
 182following to install them:
 183
 184   a.  untar the distribution file.  We use the following command:
 185        tar -xvzf ixj-0.x.x.tgz
 186
 187This creates a subdirectory holding all the necessary files.  Go to that
 188subdirectory.
 189
 190   b.  run the "ixj_dev_create" script to remove any stray device
 191files left in the /dev directory, and to create the new officially
 192designated 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
 196module.
 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
 282of this would look like this:
 283
 284        insmod phonedev
 285        insmod ixj dspio=0x320,0x310 xio=0,0x330
 286
 287Then verify the module loaded by running lsmod. If you are not using a
 288module that matches your kernel version, you may need to "force" the
 289load using the -f option in the insmod command.
 290
 291        insmod phonedev
 292        insmod -f ixj dspio=0x320,0x310 xio=0,0x330
 293
 294
 295If you are using isapnp to autoconfigure your card, then you do NOT
 296need any of the above, though you need to use depmod to load the
 297driver, like this:
 298
 299        depmod ixj
 300
 301which will result in the needed drivers getting loaded automatically.
 302
 303   g.  if you are planning on having the kernel automatically request
 304the module for you, then you need to edit /etc/conf.modules and add the
 305following lines:
 306
 307        options ixj dspio=0x340 xio=0x330 ixjdebug=0
 308
 309If you do this, then when you execute an application that uses the
 310module 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 
 313ixj 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        
 327Once this is done, then non-root users should be able to use the
 328devices.  If you have enabled autoloading of modules, then the user
 329should be able to open the device and have the module loaded
 330automatically for them.
 331
 332
 3334.0 Driver Installation problems.
 334
 335We have tested these drivers on the 2.2.9, 2.2.10, 2.2.12, and 2.2.13 kernels
 336and in all cases have eventually been able to get the drivers to load and 
 337run.  We have found four types of problems that prevent this from happening.
 338The problems and solutions are:
 339
 340  a. A step was missed in the installation.  Go back and use section 3
 341as a checklist.  Many people miss running the ixj_dev_create script and thus
 342never load the device names into the filesystem.
 343
 344  b. The kernel is inconsistently linked.  We have found this problem in
 345the Out Of the Box installation of several distributions.  The symptoms 
 346are that neither driver will load, and that the unknown symbols include "jiffy"
 347and "kmalloc".  The solution is to recompile both the kernel and the
 348modules.  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
 356This rebuilds both the kernel and all the modules and makes sure they all 
 357have the same linkages.  This generally solves the problem once the new 
 358kernel is installed and the system rebooted.
 359
 360  c. The kernel has been patched, then unpatched.  This happens when
 361someone decides to use an earlier kernel after they load a later kernel.
 362The symptoms are proceeding through all three above steps and still not
 363being able to load the driver.  What has happened is that the generated
 364header files are out of sync with the kernel itself.  The solution is
 365to recompile (again) using "make mrproper".  This will remove and then
 366regenerate all the necessary header files.  Once this is done, then you 
 367need to install and reboot the kernel.  We have not seen any problem
 368loading one of our drivers after this treatment.
 369
 3705.0  Known Limitations
 371
 372We cannot currently play "dial-tone" and listen for DTMF digits at the
 373same time using the ISA PhoneJACK.  This is a bug in the 8020 DSP chip
 374used on that product.  All other Quicknet products function normally
 375in this regard.  We have a work-around, but it's not done yet.  Until
 376then, if you want dial-tone, you can always play a recorded dial-tone
 377sound 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
 394
 395
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.