patch-2.4.8 linux/Documentation/s390/chandev.8

• Lines: 322
• Date: Wed Jul 25 14:12:01 2001
• Orig file: v2.4.7/linux/Documentation/s390/chandev.8
• Orig date: Wed Apr 11 19:02:27 2001

diff -u --recursive --new-file v2.4.7/linux/Documentation/s390/chandev.8 linux/Documentation/s390/chandev.8
@@ -7,29 +7,37 @@
 .SH SYNOPSIS
 The channel device layer is a layer to provide a consistent interface for
 configuration & default machine check (devices appearing & disappearing )
-handling Linux for zSeries channel devices.
+handling on Linux for s/390 & z/Series channel devices.
 
-These include among others
+
+s/390 & z/Series channel devices include among others
 
 .Bl -item
 .It
 lcs ( the most common ethernet/token ring/fddi standard on zSeries )
 .It
-ctc/escon hi speed like serial link standard on zSeries.
+ctc/escon hi speed like serial link standard on s/390 & z/Series.
 .It
 claw used to talk to cisco routers.
 .It
 qeth gigabit ethernet.
-.El
-
+.It
+osad used by osa/sf to configure osa devices, e.g. to share a osa card between 2 or more vm guests. osad is just added to the channel device layer for completeness, there are no plans at the current time to write a driver to exploit this under linux.
+.It
 These devices use two channels one read & one write for configuration &
-or communication.
-The motivation behind producing this layer was that there is a lot of
-duplicate code among the drivers for configuration so the lcs & ctc drivers
-tended to fight over 3088/08's & 3088/1F's which could be either 2216/3172
-lcs compatible devices or escons/ctc's & to resolve this fight
-both device drivers had to be reconfigured rather than doing the
-configuration in a single place.
+or communication ( & a third channel the data channel in the case of gigabit ethernet ).
+The motivation behind developing this layer was that there was a lot of
+duplicate code among the channel device drivers for configuration. 
+Also the lcs & ctc drivers tended to fight over 3088/08's & 3088/1F's which could 
+be either 2216/3172 channel attached lcs compatible devices or escon/ctc pipes 
+between guests & to resolve this fight both device drivers had to be configured 
+separately,  this is now simplified by doing the configuration in a single place
+( the channel device layer ).
+
+This layer isn't invasive & it is quite okay to use channel drivers
+which don't use the channel device layer in conjunction with
+drivers which do.
+.El
 
 .SH DESCRIPTION
 The current setup can be read from /proc/chandev
@@ -37,30 +45,65 @@
 .Bl -enum
 .It
 Piping to /proc/chandev.
+e.g. echo reprobe >/proc/chandev
+will cause uninitialised channel devices to be probed.
 .It
-Entering them into /etc/chandev.conf comments are prefixed #.
+Entering them into /etc/chandev.conf comments are prefixed with #.
 .It
 Or from the boot command line using the 'chandev=' keyword
+e.g. chandev=noauto,0x0,0x480d;noauto,0x4810,0xffff
+will allow only devno's 0x480e & 0x480f to be autodetected.
 .El
 .Bl -item
 .It
-Multiple options can be passed separated by semicolons but no spaces are allowed between parameters. The script /bin/chandev will be called automatically on startup or a machine check of a device as follows.
-/bin/chandev <start starting_devnames> <machine_check (devnames pre_recovery_action_status) (post_recovery_action_status)>.
-The chandev layer doesn't open stdin stdout or stderr so it is advisable that you add the following lines to the start of your script.
+Multiple options can be passed separated by semicolons but no spaces are allowed between parameters. To be consistent with other hotpluggable architectures the script pointed to /proc/sys/kernel/hotplug (normally /sbin/hotplug) will be called automatically on startup or a machine check of a device as follows.
+/sbin/hotplug chandev <start starting_devnames> <machine_check (devname last/pre_recovery_status) (current/post_recovery_status)>.
+The chandev layer doesn't open stdin stdout or stderr so it is advisable that you add the following lines to the start of your script, here is a sample script which starts devices as they become available.
 .It
 #!/bin/bash
 .It
 exec >/dev/console 2>&1 0>&1
+.It
+# Uncomment line below for debugging.
+.It
+# echo $*
+.It
+if [ "$1" = "chandev" ] && [ "$2" = "start" ]
+.It
+then
+.It
+    shift 2
+.It
+    while [ "$1" != "" ]  && [ "$1" != "machine_check" ]
+.It
+    do
+.It
+        isup=`ifconfig $1 2>/dev/null | grep UP`
+.It
+	if [ "$isup" = "" ]
+.It
+	then
+.It
+	     ifup $1
+.It
+	fi
+.It
+	shift
+.It
+    done
+.It
+fi
+.It
+.It
+e.g. if tr0 & ctc0 were starting up & eth0 & eth1 devices disappeared & eth2 got a revalidate machine check ( which is normally fully recoverable ) nearly simultainously the parameters would be.
+.It
+/sbin/hotplug chandev start tr0 ctc0 machine_check eth0 gone gone eth1 gone gone eth2 revalidate good
+.It
+This can be used for example to call /etc/rc.d/init.d/network start when a device appears & make the ipldelay kernel boot parameter obselete on native machines or recover from bad machine checks where the default machine check handling isn't adequete. The machine checks that can be presented as parameters are good not_operational no_path revalidate device_gone. Normally you wouldn't want to do anything like stop networking when a device disappears as this is hopefully temporary, I just added it to be complete. The chandev layer waits a few seconds for machine checks to settle before running /sbin/hotplug because several machine checks usually happen at once & the forked scripts would possibly race against each other to shutdown & start resources at the same time & behave rather stupidly.
 .El
 
-e.g. if tr0 & ctc0 were starting up & eth0 & eth1 didn't recover from a gone machine check at the same instant the  parameters would be.
-
-
-/bin/chandev start tr0 ctc0 machine_check eth0 gone gone eth1 gone gone
 
 
-This can be used for example to call /etc/rc.d/init.d/network start when a device appears & make the ipldelay kernel boot parameter obselete on native machines or recover from bad machine checks where the default machine check handling isn't adequete. The machine checks that can be presented as parameters are good not_operational no_path revalidate device_gone.
-
 valid chandev arguments are <> indicate optional parameters, | indicate a choice.
 
 .B glossary
@@ -77,21 +120,49 @@
 .It
 
 .Bl -item
-
 .It
-.B (ctc|escon|lcs|osad|qeth|claw)<devif_num>, 
-read_devno, write_devno, <port_no/protocol_no>, <checksum_received_ip_pkts>, <use_hw_stats>
+.B (ctc|escon|lcs|osad|qeth)<devif_num>, 
+read_devno,write_devno,<data_devno,memory_usage_in_k,port_no/protocol_no,checksum_received_ip_pkts,use_hw_stats>
+.It
+devif_num of -1 indicates you don't care what device interface number is chosen, omitting it indicates this is a range of devices for which you want to force to be detected as a particular type.
+The data_devno field is only valid for qeth devices when not forcing a range of devices.
+all parameters after & including memory_usage_in_k can be set optionally if not set they
+go to default values. memory_usage_in_k ( 0 the default ) means let the driver choose,checksum_received_ip_pkts & use_hw_stats are set to false
+.It
+e.g. ctc0,0x7c00,0x7c01
 .It
-e.g. ctc0,0x7c00,0x7c01,0,0,0
+Tells the channel layer to force ctc0 if detected to use cuu's 7c00 & 7c01 port,port_no is the relative adapter no on lcs, on ctc/escon this field is the ctc/escon protocol number ( default 0 ), don't do checksumming on received ip packets & as ctc doesn't have hardware stats so it ignores this parameter. This can be used for instance to force a device if it presents bad sense data to the IO layer & thus autodetection fails.
 .It
-Tells the channel layer to force ctc0 if detected to use cuu's 7c00 & 7c01 port,port_no is the relative adapter no on lcs, on ctc/escon this field is the ctc/escon protocol number ( normally 0 ), don't do checksumming on received ip packets & as ctc doesn't have hardware stats so it ignores this parameter.
+qeth,0x7c00,0x7d00,-1,4096
+All devices between 0x7c00 & 7d00 should be detected as gigabit ethernet, let the driver use 4096k for each instance, don't care what port relative adapter number is chosen, don't checksum received ip packets & use hw stats .
+.It
+qeth1,0x7c00,0x7c01,0x7c02
+.It
+devif_num=1,read=0x7c00,write=0x7c01,data=0x7c02, don't checksum received ip packets & use hw stats.
 .El
 .It
-
+.Bl -item
+.B claw devif_num, 
+read_devno,write_devno<,memory_usage_in_k,checksum_received_ip_pkts,use_hw_stats,>
+host_name,adapter_name,api_type
+.It
+CLAW currently is not autodetected as the host_name,adapter_name & api_type
+need to be set up, possibly some convention for setting these automatically
+may be contrived in the future & auto detection may be done but currently there isn't any.
+The names host_name,adapter_name,api_type may be 8 upto characters in length,
+host_name is the name of this host, adapter_name is the name of the adjacent host,
+api_type may be name 1 to 8 chars in length API & TCPIP are common values.
+The remainder of the parameters are the same as the description for other ctc escon etc. 
+.It
+A typical setup may be
+.It
+claw0,0xe00,0xe01,linuxa,rs6k,TCPIP
+.It
+.El
 .Bl -item
 .It
 .B add_parms
-,chan_type,<string>
+,chan_type,<lo_devno,hi_devno,>string
 .It
 chan_type bitfield 
 .It
@@ -99,22 +170,26 @@
 .It
 This is for device driver specific options passed as a string to the driver
 not dealt with by the channel device layer it can't contain spaces.
+low_devno & hi_devno are optional parameters to specify a range.
+The channel device layer doesn't concatenate strings if device ranges overlap,
+before passing to a device driver.
 .El
 .It
 
 .Bl -item
 .It
 .B del_parms
-<,chan_type,exact_match>
+<,chan_type,exact_match,lo_devno>
 .It
 This deletes some or all device driver specific options not specifying chan_type causes it to delete all the strings. exact_match=1 specifies only to remove driver parms where chan_type is exactly equal exact_match=0 specifies to remove parms where any bit matches chan_type.
+lo_devno is an optional parameter the delete to only happen if lo_devno matches a lo_devno in one of the ranges.
 .El
 .It
 
 .Bl -item
 .It
 .B noauto
-,<lo_devno>-<hi_devno>
+<,lo_devno,hi_devno>
 .It
 Don't probe a range of device numbers for channel devices.
 .El
@@ -128,7 +203,6 @@
 .It
 e.g. a token ring read channel 0x7c00 would have an interface called tr0x7c00 this avoids name collisions on devices.
 .El
-.El
 
 
 .B power user options
@@ -168,7 +242,6 @@
 .It
 .B add_model
 ,chan_type, cu_type, cu_model, dev_type, dev_model, max_port_no, automatic_machine_check_handling
-
 .It
 Tells the channel layer to probe for the device described, -1 for any of the parameters other than chan_type & automatic_machine_check_handling is a wildcard.
 Set max_port_no to 0 for non lcs devices.
@@ -180,18 +253,33 @@
 chan_type bitfield
 .It
 ctc=0x1, escon=0x2, lcs=0x4, osad=0x8, qeth=0x10, claw=0x20
-
-.It
+.El
 .Bl -item
 .It
 .B del_model
 ,cu_type,cu_model,dev_type,dev_model
 .It
--1 for any parameter is a wildcard,
+-1 for any parameter is a wildcard.
 .El
+
+.Bl -item
 .It
 .B del_all_models
+.It 
+should be obvious.
+.El
+.Bl -item
+.It
+.B  non_cautious_auto_detect
+.It
+Tells the channel device layer to attempt to auto detect devices even if their type/model pairs don't unambigously identify the device, e.g. 3088/1F's can either be escon CTC's or channel attached 3172 lcs compatible devices. If the wrong device driver attempts to probe these channels there may be big delays on startup or even a kernel lockup, use this option with caution.
+.El
+.Bl -item
+.It
+.B cautious_auto_detect
 .It
+ See non_cautious_auto_detect this is the default.
+.El
 .Bl -item
 .It
 .B auto_msck
@@ -248,6 +336,19 @@
 .It
 .Bl -item
 .It
+.B unregister_probe <probefunc_addr>
+.It
+unregisters a single probe function or all of them.
+.El
+.Bl -item
+.It
+.B unregister_probe_by_chan_type
+.It
+unregisters all probe functions which match the chan_type bitfield exactly,
+useful if you want a configuration to survice a kernel upgrade.
+.El
+.Bl -item
+.It
 .B read_conf
 .It
 Read instructions from /etc/chandev.conf.
@@ -259,6 +360,16 @@
 .It
 Don't automatically read /etc/chandev.conf on boot.
 .El
+.Bl -item
+.It
+.B persist 
+,chan_type
+.It
+Force drivers modules to stay loaded even if no device is found,
+this is useful for debugging & one wishes to examine debug entries in 
+/proc/s390dbf/ to find out why a module failed to load.
+.El
+
 .It
 e.g the following sequence of commands should be roughly equivalent
 to rebooting for channel devices.
@@ -290,8 +401,8 @@
 .B /proc/chandev
 .It
 cat /proc/chandev to see current options chosen.
-.Iy
-echo <command> >proc/chandev to enter a new command
+.It
+echo <command> >/proc/chandev to enter a new command
 .It
 .B /etc/chandev.conf 
 .It
@@ -302,7 +413,7 @@
 .B 'chandev=' 
 keyword.
 .It
-.B /bin/chandev
+.B /sbin/hotplug
 .It 
 A user script/executable which is run when devices come online "appear"
 or go offline "disappear".