1============ 2Hysdn Driver 3============ 4 5The hysdn driver has been written by 6Werner Cornelius (werner@isdn4linux.de or werner@titro.de) 7for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver 8under the GNU General Public License. 9 10The CAPI 2.0-support was added by Ulrich Albrecht (ualbrecht@hypercope.de) 11for Hypercope GmbH Aachen, Germany. 12 13 14 This program is free software; you can redistribute it and/or modify 15 it under the terms of the GNU General Public License as published by 16 the Free Software Foundation; either version 2 of the License, or 17 (at your option) any later version. 18 19 This program is distributed in the hope that it will be useful, 20 but WITHOUT ANY WARRANTY; without even the implied warranty of 21 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22 GNU General Public License for more details. 23 24 You should have received a copy of the GNU General Public License 25 along with this program; if not, write to the Free Software 26 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 27 28.. Table of contents 29 30 1. About the driver 31 32 2. Loading/Unloading the driver 33 34 3. Entries in the /proc filesystem 35 36 4. The /proc/net/hysdn/cardconfX file 37 38 5. The /proc/net/hysdn/cardlogX file 39 40 6. Where to get additional info and help 41 42 431. About the driver 44=================== 45 46 The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active 47 PCI isdn cards Champ, Ergo and Metro. To enable support for this cards 48 enable ISDN support in the kernel config and support for HYSDN cards in 49 the active cards submenu. The driver may only be compiled and used if 50 support for loadable modules and the process filesystem have been enabled. 51 52 These cards provide two different interfaces to the kernel. Without the 53 optional CAPI 2.0 support, they register as ethernet card. IP-routing 54 to a ISDN-destination is performed on the card itself. All necessary 55 handlers for various protocols like ppp and others as well as config info 56 and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de. 57 58 With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0 59 compliant devices with either CAPI 2.0 applications 60 (check isdn4k-utils) or -using the capidrv module- as a regular 61 isdn4linux device. This is done via the same mechanism as with the 62 active AVM cards and in fact uses the same module. 63 64 652. Loading/Unloading the driver 66=============================== 67 68 The module has no command line parameters and auto detects up to 10 cards 69 in the id-range 0-9. 70 If a loaded driver shall be unloaded all open files in the /proc/net/hysdn 71 subdir need to be closed and all ethernet interfaces allocated by this 72 driver must be shut down. Otherwise the module counter will avoid a module 73 unload. 74 75 If you are using the CAPI 2.0-interface, make sure to load/modprobe the 76 kernelcapi-module first. 77 78 If you plan to use the capidrv-link to isdn4linux, make sure to load 79 capidrv.o after all modules using this driver (i.e. after hysdn and 80 any avm-specific modules). 81 823. Entries in the /proc filesystem 83================================== 84 85 When the module has been loaded it adds the directory hysdn in the 86 /proc/net tree. This directory contains exactly 2 file entries for each 87 card. One is called cardconfX and the other cardlogX, where X is the 88 card id number from 0 to 9. 89 The cards are numbered in the order found in the PCI config data. 90 914. The /proc/net/hysdn/cardconfX file 92===================================== 93 94 This file may be read to get by everyone to get info about the cards type, 95 actual state, available features and used resources. 96 The first 3 entries (id, bus and slot) are PCI info fields, the following 97 type field gives the information about the cards type: 98 99 - 4 -> Ergo card (server card with 2 b-chans) 100 - 5 -> Metro card (server card with 4 or 8 b-chans) 101 - 6 -> Champ card (client card with 2 b-chans) 102 103 The following 3 fields show the hardware assignments for irq, iobase and the 104 dual ported memory (dp-mem). 105 106 The fields b-chans and fax-chans announce the available card resources of 107 this types for the user. 108 109 The state variable indicates the actual drivers state for this card with the 110 following assignments. 111 112 - 0 -> card has not been booted since driver load 113 - 1 -> card booting is actually in progess 114 - 2 -> card is in an error state due to a previous boot failure 115 - 3 -> card is booted and active 116 117 And the last field (device) shows the name of the ethernet device assigned 118 to this card. Up to the first successful boot this field only shows a - 119 to tell that no net device has been allocated up to now. Once a net device 120 has been allocated it remains assigned to this card, even if a card is 121 rebooted and an boot error occurs. 122 123 Writing to the cardconfX file boots the card or transfers config lines to 124 the cards firmware. The type of data is automatically detected when the 125 first data is written. Only root has write access to this file. 126 The firmware boot files are normally called hyclient.pof for client cards 127 and hyserver.pof for server cards. 128 After successfully writing the boot file, complete config files or single 129 config lines may be copied to this file. 130 If an error occurs the return value given to the writing process has the 131 following additional codes (decimal): 132 133 ==== ============================================ 134 1000 Another process is currently bootng the card 135 1001 Invalid firmware header 136 1002 Boards dual-port RAM test failed 137 1003 Internal firmware handler error 138 1004 Boot image size invalid 139 1005 First boot stage (bootstrap loader) failed 140 1006 Second boot stage failure 141 1007 Timeout waiting for card ready during boot 142 1008 Operation only allowed in booted state 143 1009 Config line too long 144 1010 Invalid channel number 145 1011 Timeout sending config data 146 ==== ============================================ 147 148 Additional info about error reasons may be fetched from the log output. 149 1505. The /proc/net/hysdn/cardlogX file 151==================================== 152 153 The cardlogX file entry may be opened multiple for reading by everyone to 154 get the cards and drivers log data. Card messages always start with the 155 keyword LOG. All other lines are output from the driver. 156 The driver log data may be redirected to the syslog by selecting the 157 appropriate bitmask. The cards log messages will always be send to this 158 interface but never to the syslog. 159 160 A root user may write a decimal or hex (with 0x) value t this file to select 161 desired output options. As mentioned above the cards log dat is always 162 written to the cardlog file independent of the following options only used 163 to check and debug the driver itself: 164 165 For example:: 166 167 echo "0x34560078" > /proc/net/hysdn/cardlog0 168 169 to output the hex log mask 34560078 for card 0. 170 171 The written value is regarded as an unsigned 32-Bit value, bit ored for 172 desired output. The following bits are already assigned: 173 174 ========== ============================================================ 175 0x80000000 All driver log data is alternatively via syslog 176 0x00000001 Log memory allocation errors 177 0x00000010 Firmware load start and close are logged 178 0x00000020 Log firmware record parser 179 0x00000040 Log every firmware write actions 180 0x00000080 Log all card related boot messages 181 0x00000100 Output all config data sent for debugging purposes 182 0x00000200 Only non comment config lines are shown wth channel 183 0x00000400 Additional conf log output 184 0x00001000 Log the asynchronous scheduler actions (config and log) 185 0x00100000 Log all open and close actions to /proc/net/hysdn/card files 186 0x00200000 Log all actions from /proc file entries 187 0x00010000 Log network interface init and deinit 188 ========== ============================================================ 189 1906. Where to get additional info and help 191======================================== 192 193 If you have any problems concerning the driver or configuration contact 194 the Hypercope support team (support@hypercope.de) and or the authors 195 Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or 196 Ulrich Albrecht (ualbrecht@hypercope.de). 197