Commit | Line | Data |
---|---|---|
3a2fbff2 CH |
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 | |
2fffc935 | 62 | drive s390 based channel attached I/O devices. This includes interfaces for |
3a2fbff2 CH |
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 | |
2fffc935 CH |
89 | so-called channel attached devices. They are addressed via I/O |
90 | subchannels, visible on the css bus. A device driver for | |
91 | channel-attached devices, however, will never interact with the | |
92 | subchannel directly, but only via the I/O device on the ccw bus, | |
3a2fbff2 CH |
93 | the ccw device. |
94 | </para> | |
95 | <sect1 id="channelIO"> | |
96 | <title>I/O functions for channel-attached devices</title> | |
97 | <para> | |
98 | Some hardware structures have been translated into C structures for use | |
99 | by the common I/O layer and device drivers. For more information on | |
100 | the hardware structures represented here, please consult the Principles | |
101 | of Operation. | |
102 | </para> | |
37193fb4 | 103 | !Iarch/s390/include/asm/cio.h |
3a2fbff2 CH |
104 | </sect1> |
105 | <sect1 id="ccwdev"> | |
106 | <title>ccw devices</title> | |
107 | <para> | |
108 | Devices that want to initiate channel I/O need to attach to the ccw bus. | |
109 | Interaction with the driver core is done via the common I/O layer, which | |
110 | provides the abstractions of ccw devices and ccw device drivers. | |
111 | </para> | |
112 | <para> | |
113 | The functions that initiate or terminate channel I/O all act upon a | |
114 | ccw device structure. Device drivers must not bypass those functions | |
115 | or strange side effects may happen. | |
116 | </para> | |
37193fb4 | 117 | !Iarch/s390/include/asm/ccwdev.h |
3a2fbff2 CH |
118 | !Edrivers/s390/cio/device.c |
119 | !Edrivers/s390/cio/device_ops.c | |
120 | </sect1> | |
121 | <sect1 id="cmf"> | |
122 | <title>The channel-measurement facility</title> | |
123 | <para> | |
124 | The channel-measurement facility provides a means to collect | |
125 | measurement data which is made available by the channel subsystem | |
126 | for each channel attached device. | |
127 | </para> | |
37193fb4 | 128 | !Iarch/s390/include/asm/cmb.h |
3a2fbff2 CH |
129 | !Edrivers/s390/cio/cmf.c |
130 | </sect1> | |
131 | </chapter> | |
132 | ||
133 | <chapter id="ccwgroup"> | |
134 | <title>The ccwgroup bus</title> | |
135 | <para> | |
136 | The ccwgroup bus only contains artificial devices, created by the user. | |
137 | Many networking devices (e.g. qeth) are in fact composed of several | |
138 | ccw devices (like read, write and data channel for qeth). The | |
139 | ccwgroup bus provides a mechanism to create a meta-device which | |
140 | contains those ccw devices as slave devices and can be associated | |
141 | with the netdevice. | |
142 | </para> | |
143 | <sect1 id="ccwgroupdevices"> | |
144 | <title>ccw group devices</title> | |
37193fb4 | 145 | !Iarch/s390/include/asm/ccwgroup.h |
3a2fbff2 CH |
146 | !Edrivers/s390/cio/ccwgroup.c |
147 | </sect1> | |
148 | </chapter> | |
149 | ||
2fffc935 CH |
150 | <chapter id="genericinterfaces"> |
151 | <title>Generic interfaces</title> | |
152 | <para> | |
153 | Some interfaces are available to other drivers that do not necessarily | |
154 | have anything to do with the busses described above, but still are | |
155 | indirectly using basic infrastructure in the common I/O layer. | |
156 | One example is the support for adapter interrupts. | |
157 | </para> | |
158 | !Edrivers/s390/cio/airq.c | |
159 | </chapter> | |
160 | ||
3a2fbff2 | 161 | </book> |