summaryrefslogtreecommitdiff
path: root/Documentation/isdn/hysdn.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/isdn/hysdn.rst')
-rw-r--r--Documentation/isdn/hysdn.rst196
1 files changed, 196 insertions, 0 deletions
diff --git a/Documentation/isdn/hysdn.rst b/Documentation/isdn/hysdn.rst
new file mode 100644
index 000000000000..0a168d1cbffc
--- /dev/null
+++ b/Documentation/isdn/hysdn.rst
@@ -0,0 +1,196 @@
+============
+Hysdn Driver
+============
+
+The hysdn driver has been written by
+Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
+for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
+under the GNU General Public License.
+
+The CAPI 2.0-support was added by Ulrich Albrecht (ualbrecht@hypercope.de)
+for Hypercope GmbH Aachen, Germany.
+
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+.. Table of contents
+
+ 1. About the driver
+
+ 2. Loading/Unloading the driver
+
+ 3. Entries in the /proc filesystem
+
+ 4. The /proc/net/hysdn/cardconfX file
+
+ 5. The /proc/net/hysdn/cardlogX file
+
+ 6. Where to get additional info and help
+
+
+1. About the driver
+===================
+
+ The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
+ PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
+ enable ISDN support in the kernel config and support for HYSDN cards in
+ the active cards submenu. The driver may only be compiled and used if
+ support for loadable modules and the process filesystem have been enabled.
+
+ These cards provide two different interfaces to the kernel. Without the
+ optional CAPI 2.0 support, they register as ethernet card. IP-routing
+ to a ISDN-destination is performed on the card itself. All necessary
+ handlers for various protocols like ppp and others as well as config info
+ and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.
+
+ With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
+ compliant devices with either CAPI 2.0 applications
+ (check isdn4k-utils) or -using the capidrv module- as a regular
+ isdn4linux device. This is done via the same mechanism as with the
+ active AVM cards and in fact uses the same module.
+
+
+2. Loading/Unloading the driver
+===============================
+
+ The module has no command line parameters and auto detects up to 10 cards
+ in the id-range 0-9.
+ If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
+ subdir need to be closed and all ethernet interfaces allocated by this
+ driver must be shut down. Otherwise the module counter will avoid a module
+ unload.
+
+ If you are using the CAPI 2.0-interface, make sure to load/modprobe the
+ kernelcapi-module first.
+
+ If you plan to use the capidrv-link to isdn4linux, make sure to load
+ capidrv.o after all modules using this driver (i.e. after hysdn and
+ any avm-specific modules).
+
+3. Entries in the /proc filesystem
+==================================
+
+ When the module has been loaded it adds the directory hysdn in the
+ /proc/net tree. This directory contains exactly 2 file entries for each
+ card. One is called cardconfX and the other cardlogX, where X is the
+ card id number from 0 to 9.
+ The cards are numbered in the order found in the PCI config data.
+
+4. The /proc/net/hysdn/cardconfX file
+=====================================
+
+ This file may be read to get by everyone to get info about the cards type,
+ actual state, available features and used resources.
+ The first 3 entries (id, bus and slot) are PCI info fields, the following
+ type field gives the information about the cards type:
+
+ - 4 -> Ergo card (server card with 2 b-chans)
+ - 5 -> Metro card (server card with 4 or 8 b-chans)
+ - 6 -> Champ card (client card with 2 b-chans)
+
+ The following 3 fields show the hardware assignments for irq, iobase and the
+ dual ported memory (dp-mem).
+
+ The fields b-chans and fax-chans announce the available card resources of
+ this types for the user.
+
+ The state variable indicates the actual drivers state for this card with the
+ following assignments.
+
+ - 0 -> card has not been booted since driver load
+ - 1 -> card booting is actually in progess
+ - 2 -> card is in an error state due to a previous boot failure
+ - 3 -> card is booted and active
+
+ And the last field (device) shows the name of the ethernet device assigned
+ to this card. Up to the first successful boot this field only shows a -
+ to tell that no net device has been allocated up to now. Once a net device
+ has been allocated it remains assigned to this card, even if a card is
+ rebooted and an boot error occurs.
+
+ Writing to the cardconfX file boots the card or transfers config lines to
+ the cards firmware. The type of data is automatically detected when the
+ first data is written. Only root has write access to this file.
+ The firmware boot files are normally called hyclient.pof for client cards
+ and hyserver.pof for server cards.
+ After successfully writing the boot file, complete config files or single
+ config lines may be copied to this file.
+ If an error occurs the return value given to the writing process has the
+ following additional codes (decimal):
+
+ ==== ============================================
+ 1000 Another process is currently bootng the card
+ 1001 Invalid firmware header
+ 1002 Boards dual-port RAM test failed
+ 1003 Internal firmware handler error
+ 1004 Boot image size invalid
+ 1005 First boot stage (bootstrap loader) failed
+ 1006 Second boot stage failure
+ 1007 Timeout waiting for card ready during boot
+ 1008 Operation only allowed in booted state
+ 1009 Config line too long
+ 1010 Invalid channel number
+ 1011 Timeout sending config data
+ ==== ============================================
+
+ Additional info about error reasons may be fetched from the log output.
+
+5. The /proc/net/hysdn/cardlogX file
+====================================
+
+ The cardlogX file entry may be opened multiple for reading by everyone to
+ get the cards and drivers log data. Card messages always start with the
+ keyword LOG. All other lines are output from the driver.
+ The driver log data may be redirected to the syslog by selecting the
+ appropriate bitmask. The cards log messages will always be send to this
+ interface but never to the syslog.
+
+ A root user may write a decimal or hex (with 0x) value t this file to select
+ desired output options. As mentioned above the cards log dat is always
+ written to the cardlog file independent of the following options only used
+ to check and debug the driver itself:
+
+ For example::
+
+ echo "0x34560078" > /proc/net/hysdn/cardlog0
+
+ to output the hex log mask 34560078 for card 0.
+
+ The written value is regarded as an unsigned 32-Bit value, bit ored for
+ desired output. The following bits are already assigned:
+
+ ========== ============================================================
+ 0x80000000 All driver log data is alternatively via syslog
+ 0x00000001 Log memory allocation errors
+ 0x00000010 Firmware load start and close are logged
+ 0x00000020 Log firmware record parser
+ 0x00000040 Log every firmware write actions
+ 0x00000080 Log all card related boot messages
+ 0x00000100 Output all config data sent for debugging purposes
+ 0x00000200 Only non comment config lines are shown wth channel
+ 0x00000400 Additional conf log output
+ 0x00001000 Log the asynchronous scheduler actions (config and log)
+ 0x00100000 Log all open and close actions to /proc/net/hysdn/card files
+ 0x00200000 Log all actions from /proc file entries
+ 0x00010000 Log network interface init and deinit
+ ========== ============================================================
+
+6. Where to get additional info and help
+========================================
+
+ If you have any problems concerning the driver or configuration contact
+ the Hypercope support team (support@hypercope.de) and or the authors
+ Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
+ Ulrich Albrecht (ualbrecht@hypercope.de).