You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
161 lines
5.4 KiB
161 lines
5.4 KiB
<?xml version="1.0" encoding="UTF-8"?> |
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> |
|
|
|
<book id="s390drivers"> |
|
<bookinfo> |
|
<title>Writing s390 channel device drivers</title> |
|
|
|
<authorgroup> |
|
<author> |
|
<firstname>Cornelia</firstname> |
|
<surname>Huck</surname> |
|
<affiliation> |
|
<address> |
|
<email>cornelia.huck@de.ibm.com</email> |
|
</address> |
|
</affiliation> |
|
</author> |
|
</authorgroup> |
|
|
|
<copyright> |
|
<year>2007</year> |
|
<holder>IBM Corp.</holder> |
|
</copyright> |
|
|
|
<legalnotice> |
|
<para> |
|
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. |
|
</para> |
|
|
|
<para> |
|
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. |
|
</para> |
|
|
|
<para> |
|
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 |
|
</para> |
|
|
|
<para> |
|
For more details see the file COPYING in the source |
|
distribution of Linux. |
|
</para> |
|
</legalnotice> |
|
</bookinfo> |
|
|
|
<toc></toc> |
|
|
|
<chapter id="intro"> |
|
<title>Introduction</title> |
|
<para> |
|
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. |
|
</para> |
|
<para> |
|
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. |
|
</para> |
|
<para> |
|
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. |
|
</para> |
|
<para> |
|
Some additional information can also be found in the kernel source |
|
under Documentation/s390/driver-model.txt. |
|
</para> |
|
</chapter> |
|
<chapter id="ccw"> |
|
<title>The ccw bus</title> |
|
<para> |
|
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. |
|
</para> |
|
<sect1 id="channelIO"> |
|
<title>I/O functions for channel-attached devices</title> |
|
<para> |
|
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. |
|
</para> |
|
!Iarch/s390/include/asm/cio.h |
|
</sect1> |
|
<sect1 id="ccwdev"> |
|
<title>ccw devices</title> |
|
<para> |
|
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. |
|
</para> |
|
<para> |
|
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. |
|
</para> |
|
!Iarch/s390/include/asm/ccwdev.h |
|
!Edrivers/s390/cio/device.c |
|
!Edrivers/s390/cio/device_ops.c |
|
</sect1> |
|
<sect1 id="cmf"> |
|
<title>The channel-measurement facility</title> |
|
<para> |
|
The channel-measurement facility provides a means to collect |
|
measurement data which is made available by the channel subsystem |
|
for each channel attached device. |
|
</para> |
|
!Iarch/s390/include/asm/cmb.h |
|
!Edrivers/s390/cio/cmf.c |
|
</sect1> |
|
</chapter> |
|
|
|
<chapter id="ccwgroup"> |
|
<title>The ccwgroup bus</title> |
|
<para> |
|
The ccwgroup bus only contains artificial 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. |
|
</para> |
|
<sect1 id="ccwgroupdevices"> |
|
<title>ccw group devices</title> |
|
!Iarch/s390/include/asm/ccwgroup.h |
|
!Edrivers/s390/cio/ccwgroup.c |
|
</sect1> |
|
</chapter> |
|
|
|
<chapter id="genericinterfaces"> |
|
<title>Generic interfaces</title> |
|
<para> |
|
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. |
|
</para> |
|
!Edrivers/s390/cio/airq.c |
|
</chapter> |
|
|
|
</book>
|
|
|