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