[patch 16/18] cio: Add s390-drivers book.

Martin Schwidefsky
2007-08-07T11:15:36Z

[-- Attachment #1: 105-cio-s390book.diff --]
[-- Type: text/plain, Size: 6529 bytes --]

From: Cornelia Huck <cornelia.huck@de.ibm.com>

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

Documentation/DocBook/Makefile | 2
Documentation/DocBook/s390-drivers.tmpl | 149 ++++++++++++++++++++++++++++++++
2 files changed, 150 insertions(+), 1 deletion(-)

Index: quilt-2.6/Documentation/DocBook/Makefile
===================================================================
--- quilt-2.6.orig/Documentation/DocBook/Makefile
+++ quilt-2.6/Documentation/DocBook/Makefile
@@ -11,7 +11,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mc
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):
Index: quilt-2.6/Documentation/DocBook/s390-drivers.tmpl
===================================================================
--- /dev/null
+++ quilt-2.6/Documentation/DocBook/s390-drivers.tmpl
@@ -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>
+ Writing s390 channel device drivers
+
+ <authorgroup>
+ <author>
+ <firstname>Cornelia</firstname>
+ <surname>Huck</surname>
+ <affiliation>
+
+ <email>cornelia.huck@de.ibm.com</email>
+
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>2007</year>
+ <holder>IBM Corp.</holder>
+ </copyright>
+
+ <legalnotice>
+
+ 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 file COPYING in the source
+ distribution of Linux.
+
+ </legalnotice>
+ </bookinfo>
+
+<toc></toc>
+
+ <chapter id="intro">
+ Introduction
+
+ 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.
+
+
+ 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.
+
+ </chapter>
+ <chapter id="ccw">
+ 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 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.
+
+ <sect1 id="channelIO">
+ 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.
+
+!Iinclude/asm-s390/cio.h
+ </sect1>
+ <sect1 id="ccwdev">
+ 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.
+
+!Iinclude/asm-s390/ccwdev.h
+!Edrivers/s390/cio/device.c
+!Edrivers/s390/cio/device_ops.c
+ </sect1>
+ <sect1 id="cmf">
+ 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.
+
+!Iinclude/asm-s390/cmb.h
+!Edrivers/s390/cio/cmf.c
+ </sect1>
+ </chapter>
+
+ <chapter id="ccwgroup">
+ 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.
+
+ <sect1 id="ccwgroupdevices">
+ ccw group devices
+!Iinclude/asm-s390/ccwgroup.h
+!Edrivers/s390/cio/ccwgroup.c
+ </sect1>
+ </chapter>
+
+</book>