Documentation/isdn/hysdn.rst

   1 ============
   2 Hysdn Driver
   3 ============
   4
   5 The hysdn driver has been written by
   6 Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
   7 for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
   8 under the GNU General Public License.
   9
  10 The CAPI 2.0-support was added by Ulrich Albrecht (ualbrecht@hypercope.de)
  11 for 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
  43 1. 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
  65 2. 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
  82 3. 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
  91 4. 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
 150 5. 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
 190 6. 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).