linux/Documentation/isdn/README.hysdn
<<
>>
Prefs
   1$Id: README.hysdn,v 1.3.6.1 2001/02/10 14:41:19 kai Exp $
   2The hysdn driver has been written by
   3Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
   4for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
   5under the GNU General Public License.
   6
   7The CAPI 2.0-support was added by Ulrich Albrecht (ualbrecht@hypercope.de)
   8for Hypercope GmbH Aachen, Germany.
   9
  10
  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.
  15
  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.
  20
  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.
  24
  25Table of contents
  26=================
  27
  281. About the driver
  29
  302. Loading/Unloading the driver
  31
  323. Entries in the /proc filesystem
  33
  344. The /proc/net/hysdn/cardconfX file
  35
  365. The /proc/net/hysdn/cardlogX file
  37
  386. Where to get additional info and help
  39
  40
  411. About the driver
  42
  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.
  48
  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.
  54
  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.
  60   
  61
  622. Loading/Unloading the driver
  63
  64   The module has no command line parameters and auto detects up to 10 cards
  65   in the id-range 0-9.
  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
  69   unload.
  70   
  71   If you are using the CAPI 2.0-interface, make sure to load/modprobe the
  72   kernelcapi-module first.
  73
  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).
  77
  783. Entries in the /proc filesystem
  79
  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.
  85
  864. The /proc/net/hysdn/cardconfX file
  87
  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:
  92
  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)   
  96
  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.
 103
 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
 108
 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. 
 114
 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):
 124
 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
 137
 138   Additional info about error reasons may be fetched from the log output. 
 139
 1405. The /proc/net/hysdn/cardlogX file
 141          
 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.
 148
 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:
 153
 154   For example: 
 155   echo "0x34560078" > /proc/net/hysdn/cardlog0
 156   to output the hex log mask 34560078 for card 0.
 157 
 158   The written value is regarded as an unsigned 32-Bit value, bit ored for 
 159   desired output. The following bits are already assigned:
 160
 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
 174   
 1756. Where to get additional info and help
 176
 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).
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.