Writing s390 channel device drivers i

Writing s390 channel device drivers

Writing s390 channel device drivers ii
Copyright 2007 IBM Corp.
This documentation 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
For more details see the le COPYING in the source distribution of Linux.
Writing s390 channel device drivers iii
COLLABORATORS
TITLE :
Writing s390 channel device drivers
ACTION NAME DATE SIGNATURE
WRITTEN BY Cornelia Huck July 31, 2014
REVISION HISTORY
NUMBER DATE DESCRIPTION NAME
Writing s390 channel device drivers iv
Contents
1 Introduction 1
2 The ccw bus 2
2.1 I/O functions for channel-attached devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1.1 struct ccw1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1.2 struct erw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.3 struct erw_eadm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.4 struct sublog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.5 struct esw0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.6 struct esw1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.7 struct esw2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.8 struct esw3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.9 struct esw_eadm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.10 struct irb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.11 struct ciw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.12 struct ccw_dev_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1.13 ccw_dev_id_is_equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 ccw devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.1 struct ccw_device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.2 struct ccw_driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.3 ccw_device_set_ofine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.4 ccw_device_set_online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.5 get_ccwdev_by_dev_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.6 get_ccwdev_by_busid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.7 ccw_driver_register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2.8 ccw_driver_unregister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2.9 ccw_device_siosl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.2.10 ccw_device_set_options_mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.2.11 ccw_device_set_options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.2.12 ccw_device_clear_options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Writing s390 channel device drivers v
2.2.13 ccw_device_is_pathgroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.2.14 ccw_device_is_multipath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2.15 ccw_device_clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2.16 ccw_device_start_key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2.17 ccw_device_start_timeout_key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2.18 ccw_device_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.19 ccw_device_start_timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2.20 ccw_device_halt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2.21 ccw_device_resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.2.22 ccw_device_get_ciw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.2.23 ccw_device_get_path_mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.24 ccw_device_get_chp_desc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.25 ccw_device_get_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.26 ccw_device_tm_start_key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.2.27 ccw_device_tm_start_timeout_key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.2.28 ccw_device_tm_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2.29 ccw_device_tm_start_timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2.30 ccw_device_get_mdc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2.31 ccw_device_tm_intrg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.2.32 ccw_device_get_schid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.3 The channel-measurement facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.3.1 .//arch/s390/include/asm/cmb.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.3.2 enable_cmf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.3.3 disable_cmf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.3.4 cmf_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.3.5 cmf_readall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3 The ccwgroup bus 26
3.1 ccw group devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.1.1 struct ccwgroup_device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.1.2 struct ccwgroup_driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.1.3 ccwgroup_set_online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1.4 ccwgroup_set_ofine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.1.5 ccwgroup_create_dev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.1.6 ccwgroup_driver_register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.1.7 ccwgroup_driver_unregister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.1.8 ccwgroup_probe_ccwdev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.1.9 ccwgroup_remove_ccwdev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Writing s390 channel device drivers vi
4 Generic interfaces 31
4.1 register_adapter_interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.2 unregister_adapter_interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.3 airq_iv_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4 airq_iv_release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.5 airq_iv_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.6 airq_iv_free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.7 airq_iv_scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Writing s390 channel device drivers 1 / 33
Chapter 1
Introduction
This document describes the interfaces available for device drivers that drive s390 based channel attached I/O devices. This
includes interfaces for interaction with the hardware and interfaces for interacting with the common driver core. Those interfaces
are provided by the s390 common I/O layer.
The document assumes a familarity with the technical terms associated with the s390 channel I/O architecture. For a description
of this architecture, please refer to the "z/Architecture: Principles of Operation", IBM publication no. SA22-7832.
While most I/O devices on a s390 system are typically driven through the channel I/O mechanism described here, there are
various other methods (like the diag interface). These are out of the scope of this document.
Some additional information can also be found in the kernel source under Documentation/s390/driver-model.txt.
Writing s390 channel device drivers 2 / 33
Chapter 2
The ccw bus
The ccw bus typically contains the majority of devices available to a s390 system. Named after the channel command word
(ccw), the basic command structure used to address its devices, the ccw bus contains so-called channel attached devices. They
are addressed via I/O subchannels, visible on the css bus. A device driver for channel-attached devices, however, will never
interact with the subchannel directly, but only via the I/O device on the ccw bus, the ccw device.
2.1 I/O functions for channel-attached devices
Some hardware structures have been translated into C structures for use by the common I/O layer and device drivers. For more
information on the hardware structures represented here, please consult the Principles of Operation.
2.1.1 struct ccw1
struct ccw1 channel command word
Synopsis
struct ccw1 {
__u8 cmd_code;
__u8 flags;
__u16 count;
__u32 cda;
};
Members
cmd_code command code
ags ags, like IDA addressing, etc.
count byte count
cda data address
Description
The ccw is the basic structure to build channel programs that perform operations with the device or the control unit. Only
Format-1 channel command words are supported.
Writing s390 channel device drivers 3 / 33
2.1.2 struct erw
struct erw extended report word
Synopsis
struct erw {
__u32 res0:3;
__u32 auth:1;
__u32 pvrf:1;
__u32 cpt:1;
__u32 fsavf:1;
__u32 cons:1;
__u32 scavf:1;
__u32 fsaf:1;
__u32 scnt:6;
__u32 res16:16;
};
Members
res0 reserved
auth authorization check
pvrf path-verication-required ag
cpt channel-path timeout
fsavf failing storage address validity ag
cons concurrent sense
scavf secondary ccw address validity ag
fsaf failing storage address format
scnt sense count, if cons == 1
res16 reserved
2.1.3 struct erw_eadm
struct erw_eadm EADM Subchannel extended report word
Synopsis
struct erw_eadm {
__u32 b:1;
__u32 r:1;
};
Members
b aob error
r arsb error
Writing s390 channel device drivers 4 / 33
2.1.4 struct sublog
struct sublog subchannel logout area
Synopsis
struct sublog {
__u32 res0:1;
__u32 esf:7;
__u32 lpum:8;
__u32 arep:1;
__u32 fvf:5;
__u32 sacc:2;
__u32 termc:2;
__u32 devsc:1;
__u32 serr:1;
__u32 ioerr:1;
__u32 seqc:3;
};
Members
res0 reserved
esf extended status ags
lpum last path used mask
arep ancillary report
fvf eld-validity ags
sacc storage access code
termc termination code
devsc device-status check
serr secondary error
ioerr i/o-error alert
seqc sequence code
2.1.5 struct esw0
struct esw0 Format 0 Extended Status Word (ESW)
Synopsis
struct esw0 {
struct sublog sublog;
struct erw erw;
__u32 faddr[2];
__u32 saddr;
};
Writing s390 channel device drivers 5 / 33
Members
sublog subchannel logout
erw extended report word
faddr[2] failing storage address
saddr secondary ccw address
2.1.6 struct esw1
struct esw1 Format 1 Extended Status Word (ESW)
Synopsis
struct esw1 {
__u8 zero0;
__u8 lpum;
__u16 zero16;
struct erw erw;
__u32 zeros[3];
};
Members
zero0 reserved zeros
lpum last path used mask
zero16 reserved zeros
erw extended report word
zeros[3] three fullwords of zeros
2.1.7 struct esw2
struct esw2 Format 2 Extended Status Word (ESW)
Synopsis
struct esw2 {
__u8 zero0;
__u8 lpum;
__u16 dcti;
struct erw erw;
__u32 zeros[3];
};
Writing s390 channel device drivers 6 / 33
Members
zero0 reserved zeros
lpum last path used mask
dcti device-connect-time interval
erw extended report word
zeros[3] three fullwords of zeros
2.1.8 struct esw3
struct esw3 Format 3 Extended Status Word (ESW)
Synopsis
struct esw3 {
__u8 zero0;
__u8 lpum;
__u16 res;
struct erw erw;
__u32 zeros[3];
};
Members
zero0 reserved zeros
lpum last path used mask
res reserved
erw extended report word
zeros[3] three fullwords of zeros
2.1.9 struct esw_eadm
struct esw_eadm EADM Subchannel Extended Status Word (ESW)
Synopsis
struct esw_eadm {
__u32 sublog;
struct erw_eadm erw;
};
Members
sublog subchannel logout
erw extended report word
Writing s390 channel device drivers 7 / 33
2.1.10 struct irb
struct irb interruption response block
Synopsis
struct irb {
union scsw scsw;
union esw;
__u8 ecw[32];
};
Members
scsw subchannel status word
esw extended status word
ecw[32] extended control word
Description
The irb that is handed to the device driver when an interrupt occurs. For solicited interrupts, the common I/O layer already
performs checks whether a eld is valid; a eld not being valid is always passed as 0. If a unit check occurred, ecw may contain
sense data; this is retrieved by the common I/O layer itself if the device doesnt support concurrent sense (so that the device driver
never needs to perform basic sene itself). For unsolicited interrupts, the irb is passed as-is (expect for sense data, if applicable).
2.1.11 struct ciw
struct ciw command information word (CIW) layout
Synopsis
struct ciw {
__u32 et:2;
__u32 reserved:2;
__u32 ct:4;
__u32 cmd:8;
__u32 count:16;
};
Members
et entry type
reserved reserved bits
ct command type
cmd command code
count command count
Writing s390 channel device drivers 8 / 33
2.1.12 struct ccw_dev_id
struct ccw_dev_id unique identier for ccw devices
Synopsis
struct ccw_dev_id {
u8 ssid;
u16 devno;
};
Members
ssid subchannel set id
devno device number
Description
This structure is not directly based on any hardware structure. The hardware identies a device by its device number and its
subchannel, which is in turn identied by its id. In order to get a unique identier for ccw devices across subchannel sets,
struct ccw_dev_id has been introduced.
2.1.13 ccw_dev_id_is_equal
ccw_dev_id_is_equal compare two ccw_dev_ids
Synopsis
int ccw_dev_id_is_equal (struct ccw_dev_id * dev_id1, struct ccw_dev_id * dev_id2);
Arguments
dev_id1 a ccw_dev_id
dev_id2 another ccw_dev_id
Returns
1 if the two structures are equal eld-by-eld, 0 if not.
Context
any
2.2 ccw devices
Devices that want to initiate channel I/O need to attach to the ccw bus. Interaction with the driver core is done via the common
I/O layer, which provides the abstractions of ccw devices and ccw device drivers.
The functions that initiate or terminate channel I/O all act upon a ccw device structure. Device drivers must not bypass those
functions or strange side effects may happen.
Writing s390 channel device drivers 9 / 33
2.2.1 struct ccw_device
struct ccw_device channel attached device
Synopsis
struct ccw_device {
spinlock_t
*
ccwlock;
struct ccw_device_id id;
struct ccw_driver
*
drv;
struct device dev;
int online;
void (
*
handler) (struct ccw_device
*
, unsigned long, struct irb
*
);
};
Members
ccwlock pointer to device lock
id id of this device
drv ccw driver for this device
dev embedded device structure
online online status of device
handler interrupt handler
Description
handler is a member of the device rather than the driver since a driver can have different interrupt handlers for different ccw
devices (multi-subchannel drivers).
2.2.2 struct ccw_driver
struct ccw_driver device driver for channel attached devices
Synopsis
struct ccw_driver {
struct ccw_device_id
*
ids;
int (
*
probe) (struct ccw_device
*
);
void (
*
remove) (struct ccw_device
*
);
int (
*
set_online) (struct ccw_device
*
);
int (
*
set_offline) (struct ccw_device
*
);
int (
*
notify) (struct ccw_device
*
, int);
void (
*
path_event) (struct ccw_device
*
, int
*
);
void (
*
shutdown) (struct ccw_device
*
);
int (
*
prepare) (struct ccw_device
*
);
void (
*
complete) (struct ccw_device
*
);
int (
*
freeze) (struct ccw_device
*
);
int (
*
thaw) (struct ccw_device
*
);
int (
*
restore) (struct ccw_device
*
);
enum uc_todo (
*
uc_handler) (struct ccw_device
*
, struct irb
*
);
struct device_driver driver;
enum interruption_class int_class;
};
Writing s390 channel device drivers 10 / 33
Members
ids ids supported by this driver
probe function called on probe
remove function called on remove
set_online called when setting device online
set_ofine called when setting device ofine
notify notify driver of device state changes
path_event notify driver of channel path events
shutdown called at device shutdown
prepare prepare for pm state transition
complete undo work done in prepare
freeze callback for freezing during hibernation snapshotting
thaw undo work done in freeze
restore callback for restoring after hibernation
uc_handler callback for unit check handler
driver embedded device driver structure
int_class interruption class to use for accounting interrupts
2.2.3 ccw_device_set_ofine
ccw_device_set_ofine disable a ccw device for I/O
Synopsis
int ccw_device_set_ofine (struct ccw_device * cdev);
Arguments
cdev target ccw device
Description
This function calls the drivers set_offline function for cdev, if given, and then disables cdev.
Returns
0 on success and a negative error value on failure.
Context
enabled, ccw device lock not held
Writing s390 channel device drivers 11 / 33
2.2.4 ccw_device_set_online
ccw_device_set_online enable a ccw device for I/O
Synopsis
int ccw_device_set_online (struct ccw_device * cdev);
Arguments
cdev target ccw device
Description
This function rst enables cdev and then calls the drivers set_online function for cdev, if given. If set_online returns
an error, cdev is disabled again.
Returns
0 on success and a negative error value on failure.
Context
enabled, ccw device lock not held
2.2.5 get_ccwdev_by_dev_id
get_ccwdev_by_dev_id obtain device from a ccw device id
Synopsis
struct ccw_device * get_ccwdev_by_dev_id (struct ccw_dev_id * dev_id);
Arguments
dev_id id of the device to be searched
Description
This function searches all devices attached to the ccw bus for a device matching dev_id.
Returns
If a device is found its reference count is increased and returned; else NULL is returned.
2.2.6 get_ccwdev_by_busid
get_ccwdev_by_busid obtain device from a bus id
Writing s390 channel device drivers 12 / 33
Synopsis
struct ccw_device * get_ccwdev_by_busid (struct ccw_driver * cdrv, const char * bus_id);
Arguments
cdrv driver the device is owned by
bus_id bus id of the device to be searched
Description
This function searches all devices owned by cdrv for a device with a bus id matching bus_id.
Returns
If a match is found, its reference count of the found device is increased and it is returned; else NULL is returned.
2.2.7 ccw_driver_register
ccw_driver_register register a ccw driver
Synopsis
int ccw_driver_register (struct ccw_driver * cdriver);
Arguments
cdriver driver to be registered
Description
This function is mainly a wrapper around driver_register.
Returns
0 on success and a negative error value on failure.
2.2.8 ccw_driver_unregister
ccw_driver_unregister deregister a ccw driver
Synopsis
void ccw_driver_unregister (struct ccw_driver * cdriver);
Arguments
cdriver driver to be deregistered
Writing s390 channel device drivers 13 / 33
Description
This function is mainly a wrapper around driver_unregister.
2.2.9 ccw_device_siosl
ccw_device_siosl initiate logging
Synopsis
int ccw_device_siosl (struct ccw_device * cdev);
Arguments
cdev ccw device
Description
This function is used to invoke model-dependent logging within the channel subsystem.
2.2.10 ccw_device_set_options_mask
ccw_device_set_options_mask set some options and unset the rest
Synopsis
int ccw_device_set_options_mask (struct ccw_device * cdev, unsigned long ags);
Arguments
cdev device for which the options are to be set
flags options to be set
Description
All ags specied in flags are set, all ags not specied in flags are cleared.
Returns
0 on success, -EINVAL on an invalid ag combination.
2.2.11 ccw_device_set_options
ccw_device_set_options set some options
Synopsis
int ccw_device_set_options (struct ccw_device * cdev, unsigned long ags);
Writing s390 channel device drivers 14 / 33
Arguments
cdev device for which the options are to be set
flags options to be set
Description
All ags specied in flags are set, the remainder is left untouched.
Returns
0 on success, -EINVAL if an invalid ag combination would ensue.
2.2.12 ccw_device_clear_options
ccw_device_clear_options clear some options
Synopsis
void ccw_device_clear_options (struct ccw_device * cdev, unsigned long ags);
Arguments
cdev device for which the options are to be cleared
flags options to be cleared
Description
All ags specied in flags are cleared, the remainder is left untouched.
2.2.13 ccw_device_is_pathgroup
ccw_device_is_pathgroup determine if paths to this device are grouped
Synopsis
int ccw_device_is_pathgroup (struct ccw_device * cdev);
Arguments
cdev ccw device
Description
Return non-zero if there is a path group, zero otherwise.
Writing s390 channel device drivers 15 / 33
2.2.14 ccw_device_is_multipath
ccw_device_is_multipath determine if device is operating in multipath mode
Synopsis
int ccw_device_is_multipath (struct ccw_device * cdev);
Arguments
cdev ccw device
Description
Return non-zero if device is operating in multipath mode, zero otherwise.
2.2.15 ccw_device_clear
ccw_device_clear terminate I/O request processing
Synopsis
int ccw_device_clear (struct ccw_device * cdev, unsigned long intparm);
Arguments
cdev target ccw device
intparm interruption parameter; value is only used if no I/O is outstanding, otherwise the intparm associated with the I/O
request is returned
Description
ccw_device_clear calls csch on cdevs subchannel.
Returns
0 on success, -ENODEV on device not operational, -EINVAL on invalid device state.
Context
Interrupts disabled, ccw device lock held
2.2.16 ccw_device_start_key
ccw_device_start_key start a s390 channel program with key
Writing s390 channel device drivers 16 / 33
Synopsis
int ccw_device_start_key (struct ccw_device * cdev, struct ccw1 * cpa, unsigned long intparm, __u8 lpm, __u8 key, unsigned
long ags);
Arguments
cdev target ccw device
cpa logical start address of channel program
intparm user specic interruption parameter; will be presented back to cdevs interrupt handler. Allows a device driver to
associate the interrupt with a particular I/O request.
lpm denes the channel path to be used for a specic I/O request. A value of 0 will make cio use the opm.
key storage key to be used for the I/O
flags additional ags; denes the action to be performed for I/O processing.
Description
Start a S/390 channel program. When the interrupt arrives, the IRQ handler is called, either immediately, delayed (dev-end
missing, or sense required) or never (no IRQ handler registered).
Returns
0, if the operation was successful; -EBUSY, if the device is busy, or status pending; -EACCES, if no path specied in lpm is
operational; -ENODEV, if the device is not operational.
Context
Interrupts disabled, ccw device lock held
2.2.17 ccw_device_start_timeout_key
ccw_device_start_timeout_key start a s390 channel program with timeout and key
Synopsis
int ccw_device_start_timeout_key (struct ccw_device * cdev, struct ccw1 * cpa, unsigned long intparm, __u8 lpm, __u8 key,
unsigned long ags, int expires);
Arguments
cdev target ccw device
cpa logical start address of channel program
intparm user specic interruption parameter; will be presented back to cdevs interrupt handler. Allows a device driver to
associate the interrupt with a particular I/O request.
lpm denes the channel path to be used for a specic I/O request. A value of 0 will make cio use the opm.
key storage key to be used for the I/O
flags additional ags; denes the action to be performed for I/O processing.
expires timeout value in jifes
Writing s390 channel device drivers 17 / 33
Description
Start a S/390 channel program. When the interrupt arrives, the IRQ handler is called, either immediately, delayed (dev-end
missing, or sense required) or never (no IRQ handler registered). This function noties the device driver if the channel program
has not completed during the time specied by expires. If a timeout occurs, the channel program is terminated via xsch, hsch
or csch, and the devices interrupt handler will be called with an irb containing ERR_PTR(-ETIMEDOUT).
Returns
0, if the operation was successful; -EBUSY, if the device is busy, or status pending; -EACCES, if no path specied in lpm is
operational; -ENODEV, if the device is not operational.
Context
Interrupts disabled, ccw device lock held
2.2.18 ccw_device_start
ccw_device_start start a s390 channel program
Synopsis
int ccw_device_start (struct ccw_device * cdev, struct ccw1 * cpa, unsigned long intparm, __u8 lpm, unsigned long ags);
Arguments
cdev target ccw device
cpa logical start address of channel program
intparm user specic interruption parameter; will be presented back to cdevs interrupt handler. Allows a device driver to
associate the interrupt with a particular I/O request.
lpm denes the channel path to be used for a specic I/O request. A value of 0 will make cio use the opm.
flags additional ags; denes the action to be performed for I/O processing.
Description
Start a S/390 channel program. When the interrupt arrives, the IRQ handler is called, either immediately, delayed (dev-end
missing, or sense required) or never (no IRQ handler registered).
Returns
0, if the operation was successful; -EBUSY, if the device is busy, or status pending; -EACCES, if no path specied in lpm is
operational; -ENODEV, if the device is not operational.
Context
Interrupts disabled, ccw device lock held
Writing s390 channel device drivers 18 / 33
2.2.19 ccw_device_start_timeout
ccw_device_start_timeout start a s390 channel program with timeout
Synopsis
int ccw_device_start_timeout (struct ccw_device * cdev, struct ccw1 * cpa, unsigned long intparm, __u8 lpm, unsigned long
ags, int expires);
Arguments
cdev target ccw device
cpa logical start address of channel program
intparm user specic interruption parameter; will be presented back to cdevs interrupt handler. Allows a device driver to
associate the interrupt with a particular I/O request.
lpm denes the channel path to be used for a specic I/O request. A value of 0 will make cio use the opm.
flags additional ags; denes the action to be performed for I/O processing.
expires timeout value in jifes
Description
Start a S/390 channel program. When the interrupt arrives, the IRQ handler is called, either immediately, delayed (dev-end
missing, or sense required) or never (no IRQ handler registered). This function noties the device driver if the channel program
has not completed during the time specied by expires. If a timeout occurs, the channel program is terminated via xsch, hsch
or csch, and the devices interrupt handler will be called with an irb containing ERR_PTR(-ETIMEDOUT).
Returns
0, if the operation was successful; -EBUSY, if the device is busy, or status pending; -EACCES, if no path specied in lpm is
operational; -ENODEV, if the device is not operational.
Context
Interrupts disabled, ccw device lock held
2.2.20 ccw_device_halt
ccw_device_halt halt I/O request processing
Synopsis
int ccw_device_halt (struct ccw_device * cdev, unsigned long intparm);
Arguments
cdev target ccw device
intparm interruption parameter; value is only used if no I/O is outstanding, otherwise the intparm associated with the I/O
request is returned
Writing s390 channel device drivers 19 / 33
Description
ccw_device_halt calls hsch on cdevs subchannel.
Returns
0 on success, -ENODEV on device not operational, -EINVAL on invalid device state, -EBUSY on device busy or interrupt pending.
Context
Interrupts disabled, ccw device lock held
2.2.21 ccw_device_resume
ccw_device_resume resume channel program execution
Synopsis
int ccw_device_resume (struct ccw_device * cdev);
Arguments
cdev target ccw device
Description
ccw_device_resume calls rsch on cdevs subchannel.
Returns
0 on success, -ENODEV on device not operational, -EINVAL on invalid device state, -EBUSY on device busy or interrupt pending.
Context
Interrupts disabled, ccw device lock held
2.2.22 ccw_device_get_ciw
ccw_device_get_ciw Search for CIW command in extended sense data.
Synopsis
struct ciw * ccw_device_get_ciw (struct ccw_device * cdev, __u32 ct);
Arguments
cdev ccw device to inspect
ct command type to look for
Writing s390 channel device drivers 20 / 33
Description
During SenseID, command information words (CIWs) describing special commands available to the device may have been stored
in the extended sense data. This function searches for CIWs of a specied command type in the extended sense data.
Returns
NULL if no extended sense data has been stored or if no CIW of the specied command type could be found, else a pointer to the
CIW of the specied command type.
2.2.23 ccw_device_get_path_mask
ccw_device_get_path_mask get currently available paths
Synopsis
__u8 ccw_device_get_path_mask (struct ccw_device * cdev);
Arguments
cdev ccw device to be queried
Returns
0 if no subchannel for the device is available, else the mask of currently available paths for the ccw devices subchannel.
2.2.24 ccw_device_get_chp_desc
ccw_device_get_chp_desc return newly allocated channel-path descriptor
Synopsis
struct channel_path_desc * ccw_device_get_chp_desc (struct ccw_device * cdev, int chp_idx);
Arguments
cdev device to obtain the descriptor for
chp_idx index of the channel path
Description
On success return a newly allocated copy of the channel-path description data associated with the given channel path. Return
NULL on error.
2.2.25 ccw_device_get_id
ccw_device_get_id obtain a ccw device id
Writing s390 channel device drivers 21 / 33
Synopsis
void ccw_device_get_id (struct ccw_device * cdev, struct ccw_dev_id * dev_id);
Arguments
cdev device to obtain the id for
dev_id where to ll in the values
2.2.26 ccw_device_tm_start_key
ccw_device_tm_start_key perform start function
Synopsis
int ccw_device_tm_start_key (struct ccw_device * cdev, struct tcw * tcw, unsigned long intparm, u8 lpm, u8 key);
Arguments
cdev ccw device on which to perform the start function
tcw transport-command word to be started
intparm user dened parameter to be passed to the interrupt handler
lpm mask of paths to use
key storage key to use for storage access
Description
Start the tcw on the given ccw device. Return zero on success, non-zero otherwise.
2.2.27 ccw_device_tm_start_timeout_key
ccw_device_tm_start_timeout_key perform start function
Synopsis
int ccw_device_tm_start_timeout_key (struct ccw_device * cdev, struct tcw * tcw, unsigned long intparm, u8 lpm, u8 key, int
expires);
Arguments
cdev ccw device on which to perform the start function
tcw transport-command word to be started
intparm user dened parameter to be passed to the interrupt handler
lpm mask of paths to use
key storage key to use for storage access
expires time span in jifes after which to abort request
Writing s390 channel device drivers 22 / 33
Description
Start the tcw on the given ccw device. Return zero on success, non-zero otherwise.
2.2.28 ccw_device_tm_start
ccw_device_tm_start perform start function
Synopsis
int ccw_device_tm_start (struct ccw_device * cdev, struct tcw * tcw, unsigned long intparm, u8 lpm);
Arguments
cdev ccw device on which to perform the start function
tcw transport-command word to be started
intparm user dened parameter to be passed to the interrupt handler
lpm mask of paths to use
Description
Start the tcw on the given ccw device. Return zero on success, non-zero otherwise.
2.2.29 ccw_device_tm_start_timeout
ccw_device_tm_start_timeout perform start function
Synopsis
int ccw_device_tm_start_timeout (struct ccw_device * cdev, struct tcw * tcw, unsigned long intparm, u8 lpm, int expires);
Arguments
cdev ccw device on which to perform the start function
tcw transport-command word to be started
intparm user dened parameter to be passed to the interrupt handler
lpm mask of paths to use
expires time span in jifes after which to abort request
Description
Start the tcw on the given ccw device. Return zero on success, non-zero otherwise.
2.2.30 ccw_device_get_mdc
ccw_device_get_mdc accumulate max data count
Writing s390 channel device drivers 23 / 33
Synopsis
int ccw_device_get_mdc (struct ccw_device * cdev, u8 mask);
Arguments
cdev ccw device for which the max data count is accumulated
mask mask of paths to use
Description
Return the number of 64K-bytes blocks all paths at least support for a transport command. Return values <= 0 indicate failures.
2.2.31 ccw_device_tm_intrg
ccw_device_tm_intrg perform interrogate function
Synopsis
int ccw_device_tm_intrg (struct ccw_device * cdev);
Arguments
cdev ccw device on which to perform the interrogate function
Description
Perform an interrogate function on the given ccw device. Return zero on success, non-zero otherwise.
2.2.32 ccw_device_get_schid
ccw_device_get_schid obtain a subchannel id
Synopsis
void ccw_device_get_schid (struct ccw_device * cdev, struct subchannel_id * schid);
Arguments
cdev device to obtain the id for
schid where to ll in the values
2.3 The channel-measurement facility
The channel-measurement facility provides a means to collect measurement data which is made available by the channel subsys-
tem for each channel attached device.
Writing s390 channel device drivers 24 / 33
2.3.1 .//arch/s390/include/asm/cmb.h
.//arch/s390/include/asm/cmb.h Document generation inconsistency
Oops
Warning
The template for this document tried to insert the structured comment from the le .//arch/s390/include/
asm/cmb.h at this point, but none was found. This dummy section is inserted to allow generation to continue.
2.3.2 enable_cmf
enable_cmf switch on the channel measurement for a specic device
Synopsis
int enable_cmf (struct ccw_device * cdev);
Arguments
cdev The ccw device to be enabled
Description
Returns 0 for success or a negative error value.
Context
non-atomic
2.3.3 disable_cmf
disable_cmf switch off the channel measurement for a specic device
Synopsis
int disable_cmf (struct ccw_device * cdev);
Arguments
cdev The ccw device to be disabled
Description
Returns 0 for success or a negative error value.
Writing s390 channel device drivers 25 / 33
Context
non-atomic
2.3.4 cmf_read
cmf_read read one value from the current channel measurement block
Synopsis
u64 cmf_read (struct ccw_device * cdev, int index);
Arguments
cdev the channel to be read
index the index of the value to be read
Description
Returns the value read or 0 if the value cannot be read.
Context
any
2.3.5 cmf_readall
cmf_readall read the current channel measurement block
Synopsis
int cmf_readall (struct ccw_device * cdev, struct cmbdata * data);
Arguments
cdev the channel to be read
data a pointer to a data block that will be lled
Description
Returns 0 on success, a negative error value otherwise.
Context
any
Writing s390 channel device drivers 26 / 33
Chapter 3
The ccwgroup bus
The ccwgroup bus only contains articial devices, created by the user. Many networking devices (e.g. qeth) are in fact composed
of several ccw devices (like read, write and data channel for qeth). The ccwgroup bus provides a mechanism to create a meta-
device which contains those ccw devices as slave devices and can be associated with the netdevice.
3.1 ccw group devices
3.1.1 struct ccwgroup_device
struct ccwgroup_device ccw group device
Synopsis
struct ccwgroup_device {
enum state;
unsigned int count;
struct device dev;
struct work_struct ungroup_work;
struct ccw_device
*
cdev[0];
};
Members
state online/ofine state
count number of attached slave devices
dev embedded device structure
ungroup_work work to be done when a ccwgroup notier has action type BUS_NOTIFY_UNBIND_DRIVER
cdev[0] variable number of slave devices, allocated as needed
3.1.2 struct ccwgroup_driver
struct ccwgroup_driver driver for ccw group devices
Writing s390 channel device drivers 27 / 33
Synopsis
struct ccwgroup_driver {
int (
*
setup) (struct ccwgroup_device
*
);
void (
*
remove) (struct ccwgroup_device
*
);
int (
*
set_online) (struct ccwgroup_device
*
);
int (
*
set_offline) (struct ccwgroup_device
*
);
void (
*
shutdown) (struct ccwgroup_device
*
);
int (
*
prepare) (struct ccwgroup_device
*
);
void (
*
complete) (struct ccwgroup_device
*
);
int (
*
freeze) (struct ccwgroup_device
*
);
int (
*
thaw) (struct ccwgroup_device
*
);
int (
*
restore) (struct ccwgroup_device
*
);
struct device_driver driver;
};
Members
setup function called during device creation to setup the device
remove function called on remove
set_online function called when device is set online
set_ofine function called when device is set ofine
shutdown function called when device is shut down
prepare prepare for pm state transition
complete undo work done in prepare
freeze callback for freezing during hibernation snapshotting
thaw undo work done in freeze
restore callback for restoring after hibernation
driver embedded driver structure
3.1.3 ccwgroup_set_online
ccwgroup_set_online enable a ccwgroup device
Synopsis
int ccwgroup_set_online (struct ccwgroup_device * gdev);
Arguments
gdev target ccwgroup device
Description
This function attempts to put the ccwgroup device into the online state.
Writing s390 channel device drivers 28 / 33
Returns
0 on success and a negative error value on failure.
3.1.4 ccwgroup_set_ofine
ccwgroup_set_ofine disable a ccwgroup device
Synopsis
int ccwgroup_set_ofine (struct ccwgroup_device * gdev);
Arguments
gdev target ccwgroup device
Description
This function attempts to put the ccwgroup device into the ofine state.
Returns
0 on success and a negative error value on failure.
3.1.5 ccwgroup_create_dev
ccwgroup_create_dev create and register a ccw group device
Synopsis
int ccwgroup_create_dev (struct device * parent, struct ccwgroup_driver * gdrv, int num_devices, const char * buf);
Arguments
parent parent device for the new device
gdrv driver for the new group device
num_devices number of slave devices
buf buffer containing comma separated bus ids of slave devices
Description
Create and register a new ccw group device as a child of parent. Slave devices are obtained from the list of bus ids given in
buf.
Returns
0 on success and an error code on failure.
Writing s390 channel device drivers 29 / 33
Context
non-atomic
3.1.6 ccwgroup_driver_register
ccwgroup_driver_register register a ccw group driver
Synopsis
int ccwgroup_driver_register (struct ccwgroup_driver * cdriver);
Arguments
cdriver driver to be registered
Description
This function is mainly a wrapper around driver_register.
3.1.7 ccwgroup_driver_unregister
ccwgroup_driver_unregister deregister a ccw group driver
Synopsis
void ccwgroup_driver_unregister (struct ccwgroup_driver * cdriver);
Arguments
cdriver driver to be deregistered
Description
This function is mainly a wrapper around driver_unregister.
3.1.8 ccwgroup_probe_ccwdev
ccwgroup_probe_ccwdev probe function for slave devices
Synopsis
int ccwgroup_probe_ccwdev (struct ccw_device * cdev);
Arguments
cdev ccw device to be probed
Writing s390 channel device drivers 30 / 33
Description
This is a dummy probe function for ccw devices that are slave devices in a ccw group device.
Returns
always 0
3.1.9 ccwgroup_remove_ccwdev
ccwgroup_remove_ccwdev remove function for slave devices
Synopsis
void ccwgroup_remove_ccwdev (struct ccw_device * cdev);
Arguments
cdev ccw device to be removed
Description
This is a remove function for ccw devices that are slave devices in a ccw group device. It sets the ccw device ofine and also
deregisters the embedding ccw group device.
Writing s390 channel device drivers 31 / 33
Chapter 4
Generic interfaces
Some interfaces are available to other drivers that do not necessarily have anything to do with the busses described above, but
still are indirectly using basic infrastructure in the common I/O layer. One example is the support for adapter interrupts.
4.1 register_adapter_interrupt
register_adapter_interrupt register adapter interrupt handler
Synopsis
int register_adapter_interrupt (struct airq_struct * airq);
Arguments
airq pointer to adapter interrupt descriptor
Description
Returns 0 on success, or -EINVAL.
4.2 unregister_adapter_interrupt
unregister_adapter_interrupt unregister adapter interrupt handler
Synopsis
void unregister_adapter_interrupt (struct airq_struct * airq);
Arguments
airq pointer to adapter interrupt descriptor
Writing s390 channel device drivers 32 / 33
4.3 airq_iv_create
airq_iv_create create an interrupt vector
Synopsis
struct airq_iv * airq_iv_create (unsigned long bits, unsigned long ags);
Arguments
bits number of bits in the interrupt vector
flags allocation ags
Description
Returns a pointer to an interrupt vector structure
4.4 airq_iv_release
airq_iv_release release an interrupt vector
Synopsis
void airq_iv_release (struct airq_iv * iv);
Arguments
iv pointer to interrupt vector structure
4.5 airq_iv_alloc
airq_iv_alloc allocate irq bits from an interrupt vector
Synopsis
unsigned long airq_iv_alloc (struct airq_iv * iv, unsigned long num);
Arguments
iv pointer to an interrupt vector structure
num number of consecutive irq bits to allocate
Writing s390 channel device drivers 33 / 33
Description
Returns the bit number of the rst irq in the allocated block of irqs, or -1UL if no bit is available or the AIRQ_IV_ALLOC ag
has not been specied
4.6 airq_iv_free
airq_iv_free free irq bits of an interrupt vector
Synopsis
void airq_iv_free (struct airq_iv * iv, unsigned long bit, unsigned long num);
Arguments
iv pointer to interrupt vector structure
bit number of the rst irq bit to free
num number of consecutive irq bits to free
4.7 airq_iv_scan
airq_iv_scan scan interrupt vector for non-zero bits
Synopsis
unsigned long airq_iv_scan (struct airq_iv * iv, unsigned long start, unsigned long end);
Arguments
iv pointer to interrupt vector structure
start bit number to start the search
end bit number to end the search
Description
Returns the bit number of the next non-zero interrupt bit, or -1UL if the scan completed without nding any more any non-zero
bits.