path: root/Documentation/s390/chandev.8

.TH chandev 8
.SH NAME
channel device layer
.Dd December 6, 2000
.Os Linux for Zseries

.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.

These 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.
.It
claw used to talk to cisco routers.
.It
qeth gigabit ethernet.
.El

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.

.SH DESCRIPTION
The current setup can be read from /proc/chandev
arguments can be entered by...
.Bl -enum
.It
Piping to /proc/chandev.
.It
Entering them into /etc/chandev.conf comments are prefixed #.
.It
Or from the boot command line using the 'chandev=' keyword
.El
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)>.

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
.Bl -item
.It
devno: is a 16 bit unsigned number used to uniquely identify a subchannel to a device.
.It
force list: is a term specific to channel device layer describing a range of devno's to be forced to configure in a particular manner as opposed to autodetect
.El

.B commonly used options

.Bl -item
.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>
.It
e.g. ctc0,0x7c00,0x7c01,0,0,0
.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.
.El
.It

.Bl -item
.It
.B add_parms
,chan_type,<string>
.It
chan_type bitfield 
.It
ctc=0x1, escon=0x2, lcs=0x4, osad=0x8, qeth=0x10, claw=0x20.
.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.
.El
.It

.Bl -item
.It
.B del_parms
<,chan_type,exact_match>
.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.
.El
.It

.Bl -item
.It
.B noauto
,<lo_devno>-<hi_devno>
.It
Don't probe a range of device numbers for channel devices.
.El
.It

.Bl -item
.It
.B use_devno_names
.It
Tells the channel layer to assign device names based on the read channel cuu number.
.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


.Bl -item

.It
.Bl -item
.It
.B del_noauto
,<devno>
.It
 Delete a range or all noauto ranges when devno is within a range.
.El

.It
.Bl -item
.It
.B del_force
,read_devno
.It
Delete a forced channel device from force list.
.El

.It
.Bl -item
.It
.B dont_use_devno_names
.It
Opposite to use_devno_names described above.
.El


.It
.Bl -item
.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.
.It
auto machine check recovery bitfield
.It
not_operational=0x1, no_path=0x2, revalidate=0x4, gone=0x8
.It
chan_type bitfield
.It
ctc=0x1, escon=0x2, lcs=0x4, osad=0x8, qeth=0x10, claw=0x20

.It
.Bl -item
.It
.B del_model
,cu_type,cu_model,dev_type,dev_model
.It
-1 for any parameter is a wildcard,
.El
.It
.B del_all_models
.It
.Bl -item
.It
.B auto_msck
<,lo_devno>,<hi_devno>,auto_msck_recovery
.It
This is used to specify the kind of machine check recovery that occurs over a device range.
.El
.It
.Bl -item
.It
.B del_auto_msck
<,devno>
.It
Delete a range or all machine check recovery ranges when devno is within a range.
.El
.It
.Bl -item
.It
.B reset_clean
.It
Resets all model info, forced devices & noauto lists to null.
.El
.It
.Bl -item
.It
.B reset_conf
.It
Resets all model info, forced devices & noauto lists back to default settings.
.El
.It
.Bl -item
.It
.B reset_conf_clean
.It
Resets all model info, forced devices & noauto lists to empty.
.El
.It
.Bl -item
.It
.B shutdown
<device name|read devno>
.It
Shuts down a particular device by device name or read devno,
deregisters it & releases its interrupts
or shuts down all devices if no parameter is used.
.El
.It
.Bl -item
.It
.B reprobe
.It
Calls probe method for channels whose interrupts are not owned.
.El
.It
.Bl -item
.It
.B read_conf
.It
Read instructions from /etc/chandev.conf.
.El
.It
.Bl -item
.It
.B dont_read_conf
.It
Don't automatically read /etc/chandev.conf on boot.
.El
.It
e.g the following sequence of commands should be roughly equivalent
to rebooting for channel devices.
.Bl -item
.It
shutdown
.It
reset_conf
.It
read_conf
.It
reprobe
.El
.El

.SH SEE ALSO
.Bl -item
.It
If you wish to write a driver channel device layer compatible
.It
/linux/include/asm-s390/chandev.h for the apis which are commented.
.It
/linux/drivers/s390/misc/chandev.c for the code.
.El

.SH FILES
.Bl -item
.It
.B /proc/chandev
.It
cat /proc/chandev to see current options chosen.
.Iy
echo <command> >proc/chandev to enter a new command
.It
.B /etc/chandev.conf 
.It
A file which can be used to configure the channel 
device layer.
.It
kernel parameters with the 
.B 'chandev=' 
keyword.
.It
.B /bin/chandev
.It 
A user script/executable which is run when devices come online "appear"
or go offline "disappear".
.El


.SH AUTHORS
DJ Barrow (djbarrow@de.ibm.com,barrow_dj@yahoo.com)