ixj.txt 14 KB

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