docs-rst: convert s390-drivers DocBook to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Acked-by: Cornelia Huck <cornelia.huck@de.ibm.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
This commit is contained in:
Mauro Carvalho Chehab
parent
83af4e1f80
commit
bcb1a87a8b
|
|
@ -10,7 +10,7 @@ DOCBOOKS := z8530book.xml \
|
||||||
networking.xml \
|
networking.xml \
|
||||||
lsm.xml \
|
lsm.xml \
|
||||||
mtdnand.xml librs.xml rapidio.xml \
|
mtdnand.xml librs.xml rapidio.xml \
|
||||||
s390-drivers.xml scsi.xml \
|
scsi.xml \
|
||||||
sh.xml w1.xml
|
sh.xml w1.xml
|
||||||
|
|
||||||
ifeq ($(DOCBOOKS),)
|
ifeq ($(DOCBOOKS),)
|
||||||
|
|
|
||||||
|
|
@ -1,161 +0,0 @@
|
||||||
<?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>
|
|
||||||
|
|
@ -34,6 +34,7 @@ available subsections can be seen below.
|
||||||
edac
|
edac
|
||||||
libata
|
libata
|
||||||
miscellaneous
|
miscellaneous
|
||||||
|
s390-drivers
|
||||||
vme
|
vme
|
||||||
80211/index
|
80211/index
|
||||||
uio-howto
|
uio-howto
|
||||||
|
|
|
||||||
111
Documentation/driver-api/s390-drivers.rst
Normal file
111
Documentation/driver-api/s390-drivers.rst
Normal file
|
|
@ -0,0 +1,111 @@
|
||||||
|
===================================
|
||||||
|
Writing s390 channel device drivers
|
||||||
|
===================================
|
||||||
|
|
||||||
|
:Author: Cornelia Huck
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/s390/include/asm/cio.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/s390/include/asm/ccwdev.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/s390/cio/device.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/s390/cio/device_ops.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
The channel-measurement facility
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
The channel-measurement facility provides a means to collect measurement
|
||||||
|
data which is made available by the channel subsystem for each channel
|
||||||
|
attached device.
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/s390/include/asm/cmb.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/s390/cio/cmf.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
The ccwgroup bus
|
||||||
|
================
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
ccw group devices
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/s390/include/asm/ccwgroup.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/s390/cio/ccwgroup.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/s390/cio/airq.c
|
||||||
|
:export:
|
||||||
Loading…
Reference in New Issue
Block a user