[S390] cio: Add s390-drivers book.
s390-drivers is generated using the docbook comments. It should eventually supersede Documentation/s390/cds.txt. Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com> Signed-off-by: Martin Schwidefsky <schwidefsky@de.ibm.com> Signed-off-by: Heiko Carstens <heiko.carstens@de.ibm.com>
This commit is contained in:
Cornelia Huck
Martin Schwidefsky
parent
b2ffd8e9a7
commit
3a2fbff228
2 changed files with 150 additions and 1 deletions
|
|
@ -11,7 +11,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \
|
|||
procfs-guide.xml writing_usb_driver.xml \
|
||||
kernel-api.xml filesystems.xml lsm.xml usb.xml \
|
||||
gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
|
||||
genericirq.xml
|
||||
genericirq.xml s390-drivers.xml
|
||||
|
||||
###
|
||||
# The build process is as follows (targets):
|
||||
|
|
|
|||
149
Documentation/DocBook/s390-drivers.tmpl
Normal file
149
Documentation/DocBook/s390-drivers.tmpl
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
<?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 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 subchannels,
|
||||
visible on the css bus. A device driver, however, will never interact
|
||||
with the subchannel directly, but only via the 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>
|
||||
!Iinclude/asm-s390/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>
|
||||
!Iinclude/asm-s390/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>
|
||||
!Iinclude/asm-s390/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>
|
||||
!Iinclude/asm-s390/ccwgroup.h
|
||||
!Edrivers/s390/cio/ccwgroup.c
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
</book>
|
||||
Loading…
Reference in a new issue