diff options
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r-- | Documentation/DocBook/Makefile | 2 | ||||
-rw-r--r-- | Documentation/DocBook/s390-drivers.tmpl | 149 |
2 files changed, 150 insertions, 1 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 08687e45e19d..1a7f53068ec2 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile | |||
@@ -11,7 +11,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ | |||
11 | procfs-guide.xml writing_usb_driver.xml \ | 11 | procfs-guide.xml writing_usb_driver.xml \ |
12 | kernel-api.xml filesystems.xml lsm.xml usb.xml \ | 12 | kernel-api.xml filesystems.xml lsm.xml usb.xml \ |
13 | gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ | 13 | gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ |
14 | genericirq.xml | 14 | genericirq.xml s390-drivers.xml |
15 | 15 | ||
16 | ### | 16 | ### |
17 | # The build process is as follows (targets): | 17 | # The build process is as follows (targets): |
diff --git a/Documentation/DocBook/s390-drivers.tmpl b/Documentation/DocBook/s390-drivers.tmpl new file mode 100644 index 000000000000..254e769282a4 --- /dev/null +++ b/Documentation/DocBook/s390-drivers.tmpl | |||
@@ -0,0 +1,149 @@ | |||
1 | <?xml version="1.0" encoding="UTF-8"?> | ||
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | ||
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> | ||
4 | |||
5 | <book id="s390drivers"> | ||
6 | <bookinfo> | ||
7 | <title>Writing s390 channel device drivers</title> | ||
8 | |||
9 | <authorgroup> | ||
10 | <author> | ||
11 | <firstname>Cornelia</firstname> | ||
12 | <surname>Huck</surname> | ||
13 | <affiliation> | ||
14 | <address> | ||
15 | <email>cornelia.huck@de.ibm.com</email> | ||
16 | </address> | ||
17 | </affiliation> | ||
18 | </author> | ||
19 | </authorgroup> | ||
20 | |||
21 | <copyright> | ||
22 | <year>2007</year> | ||
23 | <holder>IBM Corp.</holder> | ||
24 | </copyright> | ||
25 | |||
26 | <legalnotice> | ||
27 | <para> | ||
28 | This documentation is free software; you can redistribute | ||
29 | it and/or modify it under the terms of the GNU General Public | ||
30 | License as published by the Free Software Foundation; either | ||
31 | version 2 of the License, or (at your option) any later | ||
32 | version. | ||
33 | </para> | ||
34 | |||
35 | <para> | ||
36 | This program is distributed in the hope that it will be | ||
37 | useful, but WITHOUT ANY WARRANTY; without even the implied | ||
38 | warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | ||
39 | See the GNU General Public License for more details. | ||
40 | </para> | ||
41 | |||
42 | <para> | ||
43 | You should have received a copy of the GNU General Public | ||
44 | License along with this program; if not, write to the Free | ||
45 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, | ||
46 | MA 02111-1307 USA | ||
47 | </para> | ||
48 | |||
49 | <para> | ||
50 | For more details see the file COPYING in the source | ||
51 | distribution of Linux. | ||
52 | </para> | ||
53 | </legalnotice> | ||
54 | </bookinfo> | ||
55 | |||
56 | <toc></toc> | ||
57 | |||
58 | <chapter id="intro"> | ||
59 | <title>Introduction</title> | ||
60 | <para> | ||
61 | This document describes the interfaces available for device drivers that | ||
62 | drive s390 based channel attached devices. This includes interfaces for | ||
63 | interaction with the hardware and interfaces for interacting with the | ||
64 | common driver core. Those interfaces are provided by the s390 common I/O | ||
65 | layer. | ||
66 | </para> | ||
67 | <para> | ||
68 | The document assumes a familarity with the technical terms associated | ||
69 | with the s390 channel I/O architecture. For a description of this | ||
70 | architecture, please refer to the "z/Architecture: Principles of | ||
71 | Operation", IBM publication no. SA22-7832. | ||
72 | </para> | ||
73 | <para> | ||
74 | While most I/O devices on a s390 system are typically driven through the | ||
75 | channel I/O mechanism described here, there are various other methods | ||
76 | (like the diag interface). These are out of the scope of this document. | ||
77 | </para> | ||
78 | <para> | ||
79 | Some additional information can also be found in the kernel source | ||
80 | under Documentation/s390/driver-model.txt. | ||
81 | </para> | ||
82 | </chapter> | ||
83 | <chapter id="ccw"> | ||
84 | <title>The ccw bus</title> | ||
85 | <para> | ||
86 | The ccw bus typically contains the majority of devices available to | ||
87 | a s390 system. Named after the channel command word (ccw), the basic | ||
88 | command structure used to address its devices, the ccw bus contains | ||
89 | so-called channel attached devices. They are addressed via subchannels, | ||
90 | visible on the css bus. A device driver, however, will never interact | ||
91 | with the subchannel directly, but only via the device on the ccw bus, | ||
92 | the ccw device. | ||
93 | </para> | ||
94 | <sect1 id="channelIO"> | ||
95 | <title>I/O functions for channel-attached devices</title> | ||
96 | <para> | ||
97 | Some hardware structures have been translated into C structures for use | ||
98 | by the common I/O layer and device drivers. For more information on | ||
99 | the hardware structures represented here, please consult the Principles | ||
100 | of Operation. | ||
101 | </para> | ||
102 | !Iinclude/asm-s390/cio.h | ||
103 | </sect1> | ||
104 | <sect1 id="ccwdev"> | ||
105 | <title>ccw devices</title> | ||
106 | <para> | ||
107 | Devices that want to initiate channel I/O need to attach to the ccw bus. | ||
108 | Interaction with the driver core is done via the common I/O layer, which | ||
109 | provides the abstractions of ccw devices and ccw device drivers. | ||
110 | </para> | ||
111 | <para> | ||
112 | The functions that initiate or terminate channel I/O all act upon a | ||
113 | ccw device structure. Device drivers must not bypass those functions | ||
114 | or strange side effects may happen. | ||
115 | </para> | ||
116 | !Iinclude/asm-s390/ccwdev.h | ||
117 | !Edrivers/s390/cio/device.c | ||
118 | !Edrivers/s390/cio/device_ops.c | ||
119 | </sect1> | ||
120 | <sect1 id="cmf"> | ||
121 | <title>The channel-measurement facility</title> | ||
122 | <para> | ||
123 | The channel-measurement facility provides a means to collect | ||
124 | measurement data which is made available by the channel subsystem | ||
125 | for each channel attached device. | ||
126 | </para> | ||
127 | !Iinclude/asm-s390/cmb.h | ||
128 | !Edrivers/s390/cio/cmf.c | ||
129 | </sect1> | ||
130 | </chapter> | ||
131 | |||
132 | <chapter id="ccwgroup"> | ||
133 | <title>The ccwgroup bus</title> | ||
134 | <para> | ||
135 | The ccwgroup bus only contains artificial devices, created by the user. | ||
136 | Many networking devices (e.g. qeth) are in fact composed of several | ||
137 | ccw devices (like read, write and data channel for qeth). The | ||
138 | ccwgroup bus provides a mechanism to create a meta-device which | ||
139 | contains those ccw devices as slave devices and can be associated | ||
140 | with the netdevice. | ||
141 | </para> | ||
142 | <sect1 id="ccwgroupdevices"> | ||
143 | <title>ccw group devices</title> | ||
144 | !Iinclude/asm-s390/ccwgroup.h | ||
145 | !Edrivers/s390/cio/ccwgroup.c | ||
146 | </sect1> | ||
147 | </chapter> | ||
148 | |||
149 | </book> | ||