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 | |
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 | |
4e8e56c6 | 119 | !Edrivers/s390/cio/airq.c |
3a2fbff2 CH |
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> | |
128 | !Iinclude/asm-s390/cmb.h | |
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> | |
145 | !Iinclude/asm-s390/ccwgroup.h | |
146 | !Edrivers/s390/cio/ccwgroup.c | |
147 | </sect1> | |
148 | </chapter> | |
149 | ||
150 | </book> |