1 |
1275 |
phoenix |
Linux/390
|
2 |
|
|
|
3 |
|
|
Common Device Support (CDS)
|
4 |
|
|
Device Driver I/O Support Routines
|
5 |
|
|
|
6 |
|
|
Author : Ingo Adlung
|
7 |
|
|
|
8 |
|
|
Copyright, IBM Corp. 1999-2002
|
9 |
|
|
|
10 |
|
|
ChangeLog: 02/01/2002 Cornelia Huck brought up-to-date
|
11 |
|
|
|
12 |
|
|
Introduction
|
13 |
|
|
|
14 |
|
|
This document describes the common device support routines for Linux/390.
|
15 |
|
|
Different than other hardware architectures, ESA/390 has defined a unified
|
16 |
|
|
I/O access method. This gives relief to the device drivers as they don't
|
17 |
|
|
have to deal with different bus types, polling versus interrupt
|
18 |
|
|
processing, shared versus non-shared interrupt processing, DMA versus port
|
19 |
|
|
I/O (PIO), and other hardware features more. However, this implies that
|
20 |
|
|
either every single device driver needs to implement the hardware I/O
|
21 |
|
|
attachment functionality itself, or the operating system provides for a
|
22 |
|
|
unified method to access the hardware, providing all the functionality that
|
23 |
|
|
every single device driver would have to provide itself.
|
24 |
|
|
|
25 |
|
|
The document does not intend to explain the ESA/390 hardware architecture in
|
26 |
|
|
every detail.This information can be obtained from the ESA/390 Principles of
|
27 |
|
|
Operation manual (IBM Form. No. SA22-7201).
|
28 |
|
|
|
29 |
|
|
In order to build common device support for ESA/390 I/O interfaces, a
|
30 |
|
|
functional layer was introduced that provides generic I/O access methods to
|
31 |
|
|
the hardware.
|
32 |
|
|
|
33 |
|
|
The common device support layer comprises the I/O support routines defined
|
34 |
|
|
below. Some of them implement common Linux device driver interfaces, while
|
35 |
|
|
some of them are ESA/390 platform specific.
|
36 |
|
|
|
37 |
|
|
get_dev_info_by_irq() / get_dev_info_by_devno()
|
38 |
|
|
allow a device driver to determine the devices attached (visible) to the
|
39 |
|
|
system and their current status.
|
40 |
|
|
|
41 |
|
|
get_irq_by_devno() / get_devno_by_irq()
|
42 |
|
|
get irq (subchannel) from device number and vice versa.
|
43 |
|
|
|
44 |
|
|
read_dev_chars()
|
45 |
|
|
read device characteristics
|
46 |
|
|
|
47 |
|
|
read_conf_data()
|
48 |
|
|
read configuration data.
|
49 |
|
|
|
50 |
|
|
request_irq()
|
51 |
|
|
obtain ownership for a specific device.
|
52 |
|
|
|
53 |
|
|
s390_request_irq_special()
|
54 |
|
|
obtain ownership for a specific device. Similar to request_irq(), but
|
55 |
|
|
allows for device not operational notification too.
|
56 |
|
|
|
57 |
|
|
free_irq()
|
58 |
|
|
release ownership for a specific device.
|
59 |
|
|
|
60 |
|
|
disable_irq()
|
61 |
|
|
disable a device from presenting interrupts.
|
62 |
|
|
|
63 |
|
|
enable_irq()
|
64 |
|
|
enable a device, allowing for I/O interrupts.
|
65 |
|
|
|
66 |
|
|
do_IO()
|
67 |
|
|
initiate an I/O request.
|
68 |
|
|
|
69 |
|
|
resume_IO()
|
70 |
|
|
resume channel program execution.
|
71 |
|
|
|
72 |
|
|
halt_IO()
|
73 |
|
|
terminate the current I/O request processed on the device.
|
74 |
|
|
|
75 |
|
|
do_IRQ()
|
76 |
|
|
generic interrupt routine. This function is called by the interrupt entry
|
77 |
|
|
routine whenever an I/O interrupt is presented to the system. The do_IRQ()
|
78 |
|
|
routine determines the interrupt status and calls the device specific
|
79 |
|
|
interrupt handler according to the rules (flags) defined during I/O request
|
80 |
|
|
initiation with do_IO().
|
81 |
|
|
|
82 |
|
|
The next chapters describe the functions other than do_IRQ() in more details.
|
83 |
|
|
The do_IRQ() interface is not described, as it is called from the Linux/390
|
84 |
|
|
first level interrupt handler only and does not comprise a device driver
|
85 |
|
|
callable interface. Instead, the functional description of do_IO() also
|
86 |
|
|
describes the input to the device specific interrupt handler.
|
87 |
|
|
|
88 |
|
|
Note: All explanations apply also to the 64 bit architecture s390x.
|
89 |
|
|
|
90 |
|
|
|
91 |
|
|
Common Device Support (CDS) for Linux/390 Device Drivers
|
92 |
|
|
|
93 |
|
|
General Information
|
94 |
|
|
|
95 |
|
|
The following chapters describe the I/O related interface routines the
|
96 |
|
|
Linux/390 common device support (CDS) provides to allow for device specific
|
97 |
|
|
driver implementations on the IBM ESA/390 hardware platform. Those interfaces
|
98 |
|
|
intend to provide the functionality required by every device driver
|
99 |
|
|
implementaion to allow to drive a specific hardware device on the ESA/390
|
100 |
|
|
platform. Some of the interface routines are specific to Linux/390 and some
|
101 |
|
|
of them can be found on other Linux platforms implementations too.
|
102 |
|
|
Miscellaneous function prototypes, data declarations, and macro definitions
|
103 |
|
|
can be found in the architecture specific C header file
|
104 |
|
|
linux/include/asm-s390/irq.h.
|
105 |
|
|
|
106 |
|
|
Overview of CDS interface concepts
|
107 |
|
|
|
108 |
|
|
Different to other hardware platforms, the ESA/390 architecture doesn't define
|
109 |
|
|
interrupt lines managed by a specific interrupt controller and bus systems
|
110 |
|
|
that may or may not allow for shared interrupts, DMA processing, etc.. Instead,
|
111 |
|
|
the ESA/390 architecture has implemented a so called channel subsystem, that
|
112 |
|
|
provides a unified view of the devices physically attached to the systems.
|
113 |
|
|
Though the ESA/390 hardware platform knows about a huge variety of different
|
114 |
|
|
peripheral attachments like disk devices (aka. DASDs), tapes, communication
|
115 |
|
|
controllers, etc. they can all by accessed by a well defined access method and
|
116 |
|
|
they are presenting I/O completion a unified way : I/O interruptions. Every
|
117 |
|
|
single device is uniquely identified to the system by a so called subchannel,
|
118 |
|
|
where the ESA/390 architecture allows for 64k devices be attached.
|
119 |
|
|
|
120 |
|
|
Linux, however, was first built on the Intel PC architecture, with its two
|
121 |
|
|
cascaded 8259 programmable interrupt controllers (PICs), that allow for a
|
122 |
|
|
maximum of 15 different interrupt lines. All devices attached to such a system
|
123 |
|
|
share those 15 interrupt levels. Devices attached to the ISA bus system must
|
124 |
|
|
not share interrupt levels (aka. IRQs), as the ISA bus bases on edge triggered
|
125 |
|
|
interrupts. MCA, EISA, PCI and other bus systems base on level triggered
|
126 |
|
|
interrupts, and therewith allow for shared IRQs. However, if multiple devices
|
127 |
|
|
present their hardware status by the same (shared) IRQ, the operating system
|
128 |
|
|
has to call every single device driver registered on this IRQ in order to
|
129 |
|
|
determine the device driver owning the device that raised the interrupt.
|
130 |
|
|
|
131 |
|
|
In order not to introduce a new I/O concept to the common Linux code,
|
132 |
|
|
Linux/390 preserves the IRQ concept and semantically maps the ESA/390
|
133 |
|
|
subchannels to Linux as IRQs. This allows Linux/390 to support up to 64k
|
134 |
|
|
different IRQs, uniquely representig a single device each.
|
135 |
|
|
|
136 |
|
|
During its startup the Linux/390 system checks for peripheral devices. Each
|
137 |
|
|
of those devices is uniquely defined by a so called subchannel by the ESA/390
|
138 |
|
|
channel subsystem. While the subchannel numbers are system generated, each
|
139 |
|
|
subchannel also takes a user defined attribute, the so called device number.
|
140 |
|
|
Both subchannel number and device number can not exceed 65535. The
|
141 |
|
|
init_IRQ() routine gathers the information about control unit type and device
|
142 |
|
|
types that imply specific I/O commands (channel command words - CCWs) in
|
143 |
|
|
order to operate the device. Device drivers can retrieve this set of hardware
|
144 |
|
|
information during their initialization step to recognize the devices they
|
145 |
|
|
support using get_dev_info_by_irq() or get_dev_info_by_devno() respectively.
|
146 |
|
|
This methods implies that Linux/390 doesn't require to probe for free (not
|
147 |
|
|
armed) interrupt request lines (IRQs) to drive its devices with. Where
|
148 |
|
|
applicable, the device drivers can use the read_dev_chars() to retrieve device
|
149 |
|
|
characteristics. This can be done without having to request device ownership
|
150 |
|
|
previously.
|
151 |
|
|
|
152 |
|
|
When a device driver has recognized a device it wants to claim ownership for,
|
153 |
|
|
it calls request_irq() with the device's subchannel id serving as pseudo irq
|
154 |
|
|
line. One of the required parameters it has to specify is dev_id, defining a
|
155 |
|
|
device status block which the CDS layer will use to notify the device driver's
|
156 |
|
|
interrupt handler about interrupt information observed. It depends on the
|
157 |
|
|
device driver to properly handle those interrupts.
|
158 |
|
|
|
159 |
|
|
In order to allow for easy I/O initiation the CDS layer provides a do_IO()
|
160 |
|
|
interface that takes a device specific channel program (one or more CCWs) as
|
161 |
|
|
input sets up the required architecture specific control blocks and initiates
|
162 |
|
|
an I/O request on behalf of the device driver. The do_IO() routine allows for
|
163 |
|
|
different I/O methods, synchronous and asynchronous, and allows to specify
|
164 |
|
|
whether it expects the CDS layer to notify the device driver for every
|
165 |
|
|
interrupt it observes, or with final status only. It also provides a scheme
|
166 |
|
|
to allow for overlapped I/O processing. See do_IO() for more details. A device
|
167 |
|
|
driver must never issue ESA/390 I/O commands itself, but must use the
|
168 |
|
|
Linux/390 CDS interfaces instead.
|
169 |
|
|
|
170 |
|
|
For long running I/O request to be canceled, the CDS layer provides the
|
171 |
|
|
halt_IO() function. Some devices require to initially issue a HALT SUBCHANNEL
|
172 |
|
|
(HSCH) command without having pending I/O requests. This function is also
|
173 |
|
|
covered by halt_IO().
|
174 |
|
|
|
175 |
|
|
When done with a device, the device driver calls free_irq() to release its
|
176 |
|
|
ownership for the device. During free_irq() processing the CDS layer also
|
177 |
|
|
disables the device from presenting further interrupts - the device driver
|
178 |
|
|
doesn't need to assure it. The device will be reenabled for interrupts with
|
179 |
|
|
the next call to request_irq().
|
180 |
|
|
|
181 |
|
|
|
182 |
|
|
|
183 |
|
|
get_irq_first() / get_irq_next() - Retrieve Information about available IRQs
|
184 |
|
|
|
185 |
|
|
A device driver can use those interface routines to retrieve information for
|
186 |
|
|
those IRQs only that have valid device information available. As
|
187 |
|
|
Linux for S/390 supports a maximum of 65535 subchannels (devices), it might
|
188 |
|
|
be a waste of CPU to scan for the max number of devices while a fraction is
|
189 |
|
|
available/usable only. get_irq_first() will retrieve the first usable IRQ.
|
190 |
|
|
Using this as input get_irq_next() will retrieve the next IRQ available, etc..
|
191 |
|
|
|
192 |
|
|
int get_irq_first( void );
|
193 |
|
|
int get_irq_next( int irq );
|
194 |
|
|
|
195 |
|
|
irq - defines the subchannel to start scanning with. This must be
|
196 |
|
|
a valid subchannel or an error is returned.
|
197 |
|
|
|
198 |
|
|
The get_irq_first() / get_irq_next() functions return:
|
199 |
|
|
|
200 |
|
|
non-negative value - next available IRQ
|
201 |
|
|
-ENODEV - no more IRQs available
|
202 |
|
|
|
203 |
|
|
Example :
|
204 |
|
|
|
205 |
|
|
irq = get_irq_first();
|
206 |
|
|
while ( irq != -ENODEV)
|
207 |
|
|
{
|
208 |
|
|
get_dev_info_by_irq( irq, &dinfo);
|
209 |
|
|
if ( dinfo.devno == devno_to_look_for
|
210 |
|
|
|| dinfo.sid_data.cu_type == cu_type_to_look_for )
|
211 |
|
|
{
|
212 |
|
|
do_some_action( irq, &dinfo );
|
213 |
|
|
} /* endif */
|
214 |
|
|
|
215 |
|
|
irq = get_irq_next(irq);
|
216 |
|
|
}
|
217 |
|
|
|
218 |
|
|
get_dev_info_by_irq() / get_dev_info_by_devno() - Retrieve Device Information
|
219 |
|
|
|
220 |
|
|
During system startup - init_IRQ() processing - the generic I/O device support
|
221 |
|
|
checks for the devices available. For all devices found it collects the
|
222 |
|
|
SenseID information. For those devices supporting the command it also obtains
|
223 |
|
|
extended SenseID information.
|
224 |
|
|
|
225 |
|
|
int get_dev_info_by_irq( int irq,
|
226 |
|
|
s390_dev_info_t *pdi);
|
227 |
|
|
|
228 |
|
|
int get_dev_info_by_devno( __u16 devno,
|
229 |
|
|
s390_dev_info_t *pdi);
|
230 |
|
|
|
231 |
|
|
irq - defines the subchannel status information is to be
|
232 |
|
|
returned for.
|
233 |
|
|
devno - device number.
|
234 |
|
|
pdi - pointer to a user buffer of type s390_dev_info_t that should
|
235 |
|
|
be filled with device specific information.
|
236 |
|
|
|
237 |
|
|
typedef struct {
|
238 |
|
|
int irq; /* irq, aka. subchannel */
|
239 |
|
|
__u16 devno; /* device number */
|
240 |
|
|
unsigned int status; /* device status */
|
241 |
|
|
senseid_t sid_data; /* senseID data */
|
242 |
|
|
} s390_dev_info_t;
|
243 |
|
|
|
244 |
|
|
irq - subchannel.
|
245 |
|
|
devno - device number as configured in the IOCDS.
|
246 |
|
|
status - device status
|
247 |
|
|
sid_data - data obtained by a SenseID call
|
248 |
|
|
|
249 |
|
|
Possible status values are :
|
250 |
|
|
|
251 |
|
|
DEVSTAT_NOT_OPER - device was found not-operational. In this case
|
252 |
|
|
the caller should disregard the sid_data
|
253 |
|
|
buffer content.
|
254 |
|
|
DEVSTAT_UNFRIENDLY_DEV - device is locked by someone else. The sid_data buffer
|
255 |
|
|
doesn't contain valid data.
|
256 |
|
|
DEVSTAT_UNKNOWN_DEV - The device is unknown, and the sid_data buffer doesn't
|
257 |
|
|
contain valid data.
|
258 |
|
|
DEVSTAT_DEVICE_OWNED - An interrupt handler is registered.
|
259 |
|
|
|
260 |
|
|
//
|
261 |
|
|
// sense-id response buffer layout
|
262 |
|
|
//
|
263 |
|
|
typedef struct {
|
264 |
|
|
/* common part */
|
265 |
|
|
__u8 reserved; /* always 0x'FF' */
|
266 |
|
|
__u16 cu_type; /* control unit type */
|
267 |
|
|
__u8 cu_model; /* control unit model */
|
268 |
|
|
__u16 dev_type; /* device type */
|
269 |
|
|
__u8 dev_model; /* device model */
|
270 |
|
|
__u8 unused; /* padding byte */
|
271 |
|
|
/* extended part */
|
272 |
|
|
ciw_t ciw[MAX_CIWS]; /* variable # of CIWs */
|
273 |
|
|
} __attribute__ ((packed,aligned(4))) senseid_t;
|
274 |
|
|
|
275 |
|
|
MAX_CIWS is currently defined as 8.
|
276 |
|
|
|
277 |
|
|
The ESA/390 I/O architecture defines certain device specific I/O functions.
|
278 |
|
|
The device returns the device specific command code together with the SenseID
|
279 |
|
|
data in so called Command Information Words (CIW) :
|
280 |
|
|
|
281 |
|
|
typedef struct _ciw {
|
282 |
|
|
__u32 et : 2; // entry type
|
283 |
|
|
__u32 reserved : 2; // reserved
|
284 |
|
|
__u32 ct : 4; // command type
|
285 |
|
|
__u32 cmd : 8; // command
|
286 |
|
|
__u32 count : 16; // count
|
287 |
|
|
} __attribute__ ((packed)) ciw_t;
|
288 |
|
|
|
289 |
|
|
Possible CIW entry types are :
|
290 |
|
|
|
291 |
|
|
#define CIW_TYPE_RDC 0x0; // read configuration data
|
292 |
|
|
#define CIW_TYPE_SII 0x1; // set interface identifier
|
293 |
|
|
#define CIW_TYPE_RNI 0x2; // read node identifier
|
294 |
|
|
|
295 |
|
|
The device driver may use these commands as appropriate.
|
296 |
|
|
|
297 |
|
|
The get_dev_info_by_irq() / get_dev_info_by_devno() functions return:
|
298 |
|
|
|
299 |
|
|
|
300 |
|
|
-ENODEV - irq or devno don't specify a known subchannel or device
|
301 |
|
|
number.
|
302 |
|
|
-EINVAL - invalid devinfo value.
|
303 |
|
|
-EUSERS - device is locked by someone else.
|
304 |
|
|
|
305 |
|
|
Usage Notes :
|
306 |
|
|
|
307 |
|
|
In order to scan for known devices a device driver should scan all irqs by
|
308 |
|
|
calling get_dev_info() until it returns -ENODEV as there aren't any more
|
309 |
|
|
available devices.
|
310 |
|
|
|
311 |
|
|
If a device driver wants to request ownership for a specific device, it must
|
312 |
|
|
call request_irq() prior to be able to issue any I/O request for it, including
|
313 |
|
|
above mentioned device dependent commands.
|
314 |
|
|
|
315 |
|
|
Please see the "ESA/390 Common I/O-Commandss and Self Description" manual,
|
316 |
|
|
with IBM form number SA22-7204 for more details on how to read the Sense-ID
|
317 |
|
|
output, CIWs and device independent commands.
|
318 |
|
|
|
319 |
|
|
|
320 |
|
|
|
321 |
|
|
get_irq_by_devno() / get_devno_by_irq() - Convert device identifiers
|
322 |
|
|
|
323 |
|
|
While some device drivers act on the irq (subchannel) only, others take user
|
324 |
|
|
defined device configurations on device number base, according to the device
|
325 |
|
|
numbers configured in the IOCDS. The following routines serve the purpose to
|
326 |
|
|
convert irq values into device numbers and vice versa.
|
327 |
|
|
|
328 |
|
|
int get_irq_by_devno( __u16 devno );
|
329 |
|
|
|
330 |
|
|
unsigned int get_devno_by_irq( int irq );
|
331 |
|
|
|
332 |
|
|
The functions return :
|
333 |
|
|
|
334 |
|
|
the requested irq/devno values
|
335 |
|
|
-1 if the requested conversion can't be accomplished.
|
336 |
|
|
|
337 |
|
|
This could either be caused by irq/devno be outside the valid range
|
338 |
|
|
( value > 0xffff or value < 0 ) or not identifying a known device.
|
339 |
|
|
|
340 |
|
|
|
341 |
|
|
read_dev_chars() - Read Device Characteristics
|
342 |
|
|
|
343 |
|
|
This routine returns the characteristics for the device specified.
|
344 |
|
|
|
345 |
|
|
The function is meant to be called without an irq handler be in place.
|
346 |
|
|
However, the irq for the requested device must not be locked or this will
|
347 |
|
|
cause a deadlock situation ! Further, the driver must assure that nobody
|
348 |
|
|
else has claimed ownership for the requested irq yet or the owning device
|
349 |
|
|
driver's internal accounting may be affected.
|
350 |
|
|
|
351 |
|
|
In case of a registered interrupt handler, the interrupt handler must be
|
352 |
|
|
able to properly react on interrupts related to the read_dev_chars() I/O
|
353 |
|
|
commands. While the request is procesed synchronously, the device interrupt
|
354 |
|
|
handler is called for final ending status. In case of error situations the
|
355 |
|
|
interrupt handler may recover appropriately. The device irq handler can
|
356 |
|
|
recognize the corresponding interrupts by the interruption parameter be
|
357 |
|
|
0x00524443. If using the function with an existing device interrupt handler
|
358 |
|
|
in place, the irq must be locked prior to call read_dev_chars().
|
359 |
|
|
|
360 |
|
|
The function may be called enabled or disabled.
|
361 |
|
|
|
362 |
|
|
int read_dev_chars( int irq, void **buffer, int length );
|
363 |
|
|
|
364 |
|
|
irq - specifies the subchannel the device characteristic
|
365 |
|
|
retrieval is requested for
|
366 |
|
|
buffer - pointer to a buffer pointer. The buffer pointer itself
|
367 |
|
|
may be NULL to have the function allocate a buffer or
|
368 |
|
|
must contain a valid buffer area.
|
369 |
|
|
length - length of the buffer provided or to be allocated.
|
370 |
|
|
|
371 |
|
|
The read_dev_chars() function returns :
|
372 |
|
|
|
373 |
|
|
|
374 |
|
|
-ENODEV - irq doesn't specify a valid subchannel number
|
375 |
|
|
-EINVAL - an invalid parameter was detected
|
376 |
|
|
-EBUSY - an irrecoverable I/O error occurred or the device is not
|
377 |
|
|
operational.
|
378 |
|
|
|
379 |
|
|
Usage Notes :
|
380 |
|
|
|
381 |
|
|
The function can be used in two ways :
|
382 |
|
|
|
383 |
|
|
If the caller doesn't provide a data buffer, read_dev_chars() allocates a
|
384 |
|
|
data buffer and provides the device characteristics together. It's the
|
385 |
|
|
caller's responsability to release the kernel memory if not longer needed.
|
386 |
|
|
This behaviour is triggered by specifying a NULL buffer area (*buffer == NULL).
|
387 |
|
|
|
388 |
|
|
Alternatively, if the user specifies a buffer area himself, nothing is
|
389 |
|
|
allocated.
|
390 |
|
|
|
391 |
|
|
In either case the caller must provide the data area length - for the buffer
|
392 |
|
|
he specifies, or the buffer he wants to be allocated.
|
393 |
|
|
|
394 |
|
|
|
395 |
|
|
read_conf_data() - Read Configuration Data
|
396 |
|
|
|
397 |
|
|
Retrieve the device dependent configuration data. Please have a look at your
|
398 |
|
|
device dependent I/O commands for the device specific layout of the node
|
399 |
|
|
descriptor elements.
|
400 |
|
|
|
401 |
|
|
The function is meant to be called without an irq handler be in place. However,
|
402 |
|
|
the irq for the requested device must not be locked or this will cause a
|
403 |
|
|
deadlock situation !
|
404 |
|
|
|
405 |
|
|
The function may be called enabled or disabled.
|
406 |
|
|
|
407 |
|
|
int read_conf_data( int irq, void **buffer, int *length, __u8 lpm);
|
408 |
|
|
|
409 |
|
|
irq - Specifies the subchannel the configuration data is to be
|
410 |
|
|
retrieved for.
|
411 |
|
|
buffer - Pointer to a buffer pointer. The read_conf_data() routine
|
412 |
|
|
will allocate a buffer and initialize the buffer pointer
|
413 |
|
|
accordingly. It's the device driver's responsability to
|
414 |
|
|
release the kernel memory if no longer needed.
|
415 |
|
|
length - Length of the buffer allocated and retrieved.
|
416 |
|
|
lpm - Logical path mask to be used for retrieving the data. If
|
417 |
|
|
zero the data is retrieved on the next path available.
|
418 |
|
|
|
419 |
|
|
The read_conf_data() function returns :
|
420 |
|
|
|
421 |
|
|
-ENODEV - irq doesn't specify a valid subchannel number
|
422 |
|
|
-EINVAL - An invalid parameter was detected
|
423 |
|
|
-EIO - An irrecoverable I/O error occured or the device is
|
424 |
|
|
not operational.
|
425 |
|
|
-ENOMEM - The read_conf_data() routine couldn't obtain storage.
|
426 |
|
|
-EOPNOTSUPP - The device doesn't support the read configuration
|
427 |
|
|
data command.
|
428 |
|
|
|
429 |
|
|
|
430 |
|
|
request_irq() - Request Device Ownership
|
431 |
|
|
|
432 |
|
|
As previously discussed a device driver will scan for the devices its supports
|
433 |
|
|
by calling get_dev_info(). Once it has found a device it will call
|
434 |
|
|
request_irq() to request ownership for it. This call causes the subchannel to
|
435 |
|
|
be enabled for interrupts if it was found operational.
|
436 |
|
|
|
437 |
|
|
Note: This function is obsolete and provided for compatibility purposes only.
|
438 |
|
|
Device drivers should use s390_request_irq_special() instead.
|
439 |
|
|
|
440 |
|
|
int request_irq( unsigned int irq,
|
441 |
|
|
int (*handler)( int,
|
442 |
|
|
void *,
|
443 |
|
|
struct pt_regs *),
|
444 |
|
|
unsigned long irqflags,
|
445 |
|
|
const char *devname,
|
446 |
|
|
void *dev_id);
|
447 |
|
|
|
448 |
|
|
irq : specifies the subchannel the ownership is requested for
|
449 |
|
|
handler : specifies the device driver's interrupt handler to be
|
450 |
|
|
called for interrupt processing
|
451 |
|
|
irqflags : IRQ flags, currently ignored
|
452 |
|
|
devname : device name
|
453 |
|
|
dev_id : required pointer to a device specific buffer of type
|
454 |
|
|
devstat_t
|
455 |
|
|
|
456 |
|
|
typedef struct {
|
457 |
|
|
__u16 devno; /* device number, aka. "cuu" from irb */
|
458 |
|
|
unsigned long intparm; /* interrupt parameter */
|
459 |
|
|
__u8 cstat; /* channel status - accumulated */
|
460 |
|
|
__u8 dstat; /* device status - accumulated */
|
461 |
|
|
__u8 lpum; /* last path used mask from irb */
|
462 |
|
|
__u8 unused; /* not used - reserved */
|
463 |
|
|
unsigned int flag; /* flag : see below */
|
464 |
|
|
__u32 cpa; /* CCW address from irb at primary status */
|
465 |
|
|
__u32 rescnt; /* res. count from irb at primary status */
|
466 |
|
|
__u32 scnt; /* sense count, if DEVSTAT_FLAG_SENSE_AVAIL */
|
467 |
|
|
union {
|
468 |
|
|
irb_t irb; /* interruption response block */
|
469 |
|
|
sense_t sense; /* sense information */
|
470 |
|
|
} ii; /* interrupt information */
|
471 |
|
|
} devstat_t;
|
472 |
|
|
|
473 |
|
|
|
474 |
|
|
During request_irq() processing, the devstat_t layout does not matter as it
|
475 |
|
|
won't be used during request_irq() processing. See do_IO() for a functional
|
476 |
|
|
description of its usage.
|
477 |
|
|
|
478 |
|
|
The request_irq() function returns :
|
479 |
|
|
|
480 |
|
|
|
481 |
|
|
-EINVAL - an invalid parameter was detected
|
482 |
|
|
-EBUSY - device (subchannel) already owned
|
483 |
|
|
-ENODEV - the device is not-operational
|
484 |
|
|
-ENOMEM - not enough kernel memory to process request
|
485 |
|
|
|
486 |
|
|
Usage Notes :
|
487 |
|
|
|
488 |
|
|
While Linux for Intel defines dev_id as a unique identifier for shared
|
489 |
|
|
interrupt lines it has a totally different purpose on Linux/390. Here it
|
490 |
|
|
serves as a shared interrupt status area between the generic device support
|
491 |
|
|
layer, and the device specific driver. The value passed to request_irq()
|
492 |
|
|
must therefore point to a valid devstat_t type buffer area the device driver
|
493 |
|
|
must preserve for later usage. I.e. it must not be released prior to a call
|
494 |
|
|
to free_irq().
|
495 |
|
|
|
496 |
|
|
Irqflags are currently ignored by the cds layer.
|
497 |
|
|
The Linux/390 kernel does neither know about "fast" interrupt handlers, nor
|
498 |
|
|
does it allow for interrupt sharing. Remember, the term interrupt level (irq),
|
499 |
|
|
device, and subchannel are used interchangeably in Linux/390.
|
500 |
|
|
|
501 |
|
|
If request_irq() was called in enabled state, or if multiple CPUs are present,
|
502 |
|
|
the device may present an interrupt to the specified handler prior to
|
503 |
|
|
request_irq() return to the caller already ! This includes the possibility
|
504 |
|
|
of unsolicited interrupts or a pending interrupt status from an earlier
|
505 |
|
|
solicited I/O request. The device driver must be able to handle this situation
|
506 |
|
|
properly or the device may become unoperational otherwise !
|
507 |
|
|
|
508 |
|
|
Although the interrupt handler is defined to be called with a pointer to a
|
509 |
|
|
struct pt_regs buffer area, this is not implemented by the Linux/390 generic
|
510 |
|
|
I/O device driver support layer. The device driver's interrupt handler must
|
511 |
|
|
therefore not rely on this parameter on function entry.
|
512 |
|
|
|
513 |
|
|
|
514 |
|
|
s390_request_irq_special() - Request Device Ownership
|
515 |
|
|
|
516 |
|
|
As previously discussed a device driver will scan for the devices its supports
|
517 |
|
|
by calling get_dev_info(). Once it has found a device it will call
|
518 |
|
|
request_irq() to request ownership.
|
519 |
|
|
|
520 |
|
|
Note: This function replaces request_irq() described previously.
|
521 |
|
|
|
522 |
|
|
int s390_request_irq_special(
|
523 |
|
|
int irq,
|
524 |
|
|
io_handler_func_t io_handler,
|
525 |
|
|
not_oper_handler_func_t not_oper_handler,
|
526 |
|
|
unsigned long irqflags,
|
527 |
|
|
const char *devname,
|
528 |
|
|
void *dev_id);
|
529 |
|
|
|
530 |
|
|
irq : specifies the subchannel the ownership is
|
531 |
|
|
requested for
|
532 |
|
|
io_handler : specifies the device driver's interrupt handler
|
533 |
|
|
to be called for interrupt processing
|
534 |
|
|
not_oper_handler : specifies a device driver "not operational" handler
|
535 |
|
|
irqflags : IRQ flags, currently ignored
|
536 |
|
|
devname : device name
|
537 |
|
|
dev_id : required pointer to a device specific buffer of
|
538 |
|
|
type devstat_t
|
539 |
|
|
|
540 |
|
|
|
541 |
|
|
typedef struct {
|
542 |
|
|
__u16 devno; /* device number, aka. "cuu" from irb */
|
543 |
|
|
unsigned long intparm; /* interrupt parameter */
|
544 |
|
|
__u8 cstat; /* channel status - accumulated */
|
545 |
|
|
__u8 dstat; /* device status - accumulated */
|
546 |
|
|
__u8 lpum; /* last path used mask from irb */
|
547 |
|
|
__u8 unused; /* not used - reserved */
|
548 |
|
|
unsigned int flag; /* flag : see below */
|
549 |
|
|
__u32 cpa; /* CCW address from irb at primary status */
|
550 |
|
|
__u32 rescnt; /* res. count from irb at primary status */
|
551 |
|
|
__u32 scnt; /* sense count, if DEVSTAT_FLAG_SENSE_AVAIL */
|
552 |
|
|
union {
|
553 |
|
|
irb_t irb; /* interruption response block */
|
554 |
|
|
sense_t sense; /* sense information */
|
555 |
|
|
} ii; /* interrupt information */
|
556 |
|
|
} devstat_t;
|
557 |
|
|
|
558 |
|
|
During request_irq() processing, the devstat_t layout does not matter as it
|
559 |
|
|
won't be used during request_irq() processing. See do_IO() for a functional
|
560 |
|
|
description of its usage.
|
561 |
|
|
|
562 |
|
|
typedef void (* io_handler_func_t) ( int irq,
|
563 |
|
|
void *devstat,
|
564 |
|
|
struct pt_regs *rgs);
|
565 |
|
|
|
566 |
|
|
irq : IRQ the interrupt handler is called for
|
567 |
|
|
devstat : device status block
|
568 |
|
|
rgs : obsolete
|
569 |
|
|
|
570 |
|
|
typedef (void)(* not_oper_handler_func_t)( int irq,
|
571 |
|
|
int status );
|
572 |
|
|
|
573 |
|
|
irq : IRQ the not operational status has been encountered for
|
574 |
|
|
status : device status
|
575 |
|
|
DEVSTAT_NOT_OPER - device is not operational
|
576 |
|
|
DEVSTAT_REVALIDATE - revalidate device number
|
577 |
|
|
DEVSTAT_DEVICE_GONE - no such device (irq)
|
578 |
|
|
|
579 |
|
|
Note: Revalidate indicates that running under VM the device number has been
|
580 |
|
|
modified by means of a DEFINE xxxx [as] yyyy command. Therewith device number
|
581 |
|
|
xxxx was altered to yyyy. It's the device drivers responsibility to decide
|
582 |
|
|
whether device ownership can be retained.
|
583 |
|
|
|
584 |
|
|
Gone indicates that the device was detached under VM, or the device number
|
585 |
|
|
became invalid (native, LPAR). In order to prevent further I/O the IRQ was
|
586 |
|
|
implicitly freed on behalf of the device driver. The driver must not call
|
587 |
|
|
free_irq itself.
|
588 |
|
|
|
589 |
|
|
Not Oper indicates the device became not operational. It's the device driver's
|
590 |
|
|
responsibility whether it wants to maintain ownership for the IRQ, or not.
|
591 |
|
|
|
592 |
|
|
The s390_request_irq_special() function returns :
|
593 |
|
|
|
594 |
|
|
-EINVAL - an invalid parameter was detected
|
595 |
|
|
-EBUSY - device (subchannel) already owned
|
596 |
|
|
-ENODEV - the device is not-operational
|
597 |
|
|
-ENOMEM - not enough kernel memory to process request
|
598 |
|
|
|
599 |
|
|
Usage Notes :
|
600 |
|
|
|
601 |
|
|
While Linux for Intel defines dev_id as a unique identifier for shared
|
602 |
|
|
interrupt lines, it has a totally different purpose on Linux for S/390. Here
|
603 |
|
|
it serves as a shared interrupt status area between the generic device support
|
604 |
|
|
layer and the device specific driver. The value passed to request_irq() must
|
605 |
|
|
therefore point to a valid devstat_t type buffer area the device driver must
|
606 |
|
|
preserve for later usage. I.e. it must not be released prior to a call to
|
607 |
|
|
free_irq().
|
608 |
|
|
|
609 |
|
|
Currently, the value of irqflags is ignored. The Linux for S/390 kernel does
|
610 |
|
|
neither know about "fast" interrupt handlers, nor does it allow for interrupt
|
611 |
|
|
sharing. Remember, the term interrupt level (irq), device, and subchannel are
|
612 |
|
|
used interchangeably in Linux for S/390.
|
613 |
|
|
|
614 |
|
|
Other than request_irq(), this function does allow for a not operational
|
615 |
|
|
handler to be defined. This handler is called when a device either became not
|
616 |
|
|
operational, the last path to a device became not operational, or the device
|
617 |
|
|
was detached from the system. A detach could be a "detach" under VM or that
|
618 |
|
|
the device became unassigned by the Support Element (SE) or Hardware Management
|
619 |
|
|
Console (HMC).
|
620 |
|
|
|
621 |
|
|
If s390_request_irq_special() was called in enabled state, or if multiple CPUs
|
622 |
|
|
are present, the device may present an interrupt to the specified handler prior
|
623 |
|
|
to request_irq() return to the caller already ! This includes the possibility
|
624 |
|
|
of unsolicited interrupts or a pending interrupt status from an earlier
|
625 |
|
|
solicited I/O request. The device driver must be able to handle this situation
|
626 |
|
|
properly or the device may become unoperational otherwise !
|
627 |
|
|
|
628 |
|
|
Although the interrupt handler is defined to be called with a pointer to a
|
629 |
|
|
struct pt_regs buffer area, this is not implemented by the Linux for S/390
|
630 |
|
|
platform specific common I/O support layer. The device driver's interrupt
|
631 |
|
|
handler must therefore not rely on this parameter on function entry.
|
632 |
|
|
|
633 |
|
|
|
634 |
|
|
free_irq() - Release Device Ownership
|
635 |
|
|
|
636 |
|
|
A device driver may call free_irq() to release ownership of a previously
|
637 |
|
|
acquired device.
|
638 |
|
|
|
639 |
|
|
void free_irq( unsigned int irq,
|
640 |
|
|
void *dev_id);
|
641 |
|
|
|
642 |
|
|
irq : specifies the subchannel the ownership is requested for
|
643 |
|
|
dev_id : required pointer to a device specific buffer of type
|
644 |
|
|
devstat_t. This must be the same as the one specified
|
645 |
|
|
during a previous call to request_irq().
|
646 |
|
|
|
647 |
|
|
Usage Notes :
|
648 |
|
|
|
649 |
|
|
Unfortunately the free_irq() is defined not to return error codes. I.e. if
|
650 |
|
|
called with wrong parameters a device may still be operational although there
|
651 |
|
|
is no device driver available to handle its interrupts. Further, during
|
652 |
|
|
free_irq() processing we may possibly find pending interrupt conditions. As
|
653 |
|
|
those need to be processed, we have to delay free_irq() returning until a
|
654 |
|
|
clean device status is found by synchronously handling them.
|
655 |
|
|
|
656 |
|
|
The call to free_irq() will also cause the device (subchannel) be disabled for
|
657 |
|
|
interrupts. The device driver must not release any data areas required for
|
658 |
|
|
interrupt processing prior to free_irq() return to the caller as interrupts
|
659 |
|
|
can occur prior to free_irq() returning. This is also true when called in
|
660 |
|
|
disabled state if either multiple CPUs are presents or a pending interrupt
|
661 |
|
|
status was found during free_irq() processing.
|
662 |
|
|
|
663 |
|
|
|
664 |
|
|
disable_irq() - Disable Interrupts for a given Device
|
665 |
|
|
|
666 |
|
|
This function may be called at any time to disable interrupt processing for
|
667 |
|
|
the specified irq. However, as Linux/390 maps irqs to the device (subchannel)
|
668 |
|
|
one-to-one, this may require more extensive I/O processing than anticipated,
|
669 |
|
|
especially if an interrupt status is found pending on the subchannel that
|
670 |
|
|
requires synchronous error processing.
|
671 |
|
|
|
672 |
|
|
int disable_irq( unsigned int irq );
|
673 |
|
|
|
674 |
|
|
irq : specifies the subchannel to be disabled
|
675 |
|
|
|
676 |
|
|
The disable-irq() routine may return :
|
677 |
|
|
|
678 |
|
|
|
679 |
|
|
-EBUSY - device (subchannel) is currently processing an I/O
|
680 |
|
|
request
|
681 |
|
|
-ENODEV - the device is not-operational or irq doesn't specify a
|
682 |
|
|
valid subchannel
|
683 |
|
|
|
684 |
|
|
Usage Notes :
|
685 |
|
|
|
686 |
|
|
Unlike the Intel based hardware architecture the ESA/390 architecture does
|
687 |
|
|
not have a programmable interrupt controller (PIC) where a specific interrupt
|
688 |
|
|
line can be disabled. Instead the subchannel logically representing the device
|
689 |
|
|
in the channel subsystem must be disabled for interrupts. However, if there
|
690 |
|
|
are still inetrrupt conditions pending they must be processed first in order
|
691 |
|
|
to allow for proper processing after reenabling the device at a later time.
|
692 |
|
|
This may lead to delayed disable processing.
|
693 |
|
|
|
694 |
|
|
As described above the disable processing may require extensive processing.
|
695 |
|
|
Therefore disabling and re-enabling the device using disable_irq() /
|
696 |
|
|
enable_irq() should be avoided and is not suitable for high frequency
|
697 |
|
|
operations.
|
698 |
|
|
|
699 |
|
|
Linux for Intel defines this function
|
700 |
|
|
|
701 |
|
|
void disable_irq( int irq);
|
702 |
|
|
|
703 |
|
|
This is suitable for the Intel PC architecture as this only causes to mask
|
704 |
|
|
the requested irq line in the PIC which is not applicable for the ESA/390
|
705 |
|
|
architecture. Therefore we allow for returning error codes.
|
706 |
|
|
|
707 |
|
|
|
708 |
|
|
enable_irq() - Enable Interrupts for a given Device
|
709 |
|
|
|
710 |
|
|
This function is used to enable a previously disabled device (subchannel).
|
711 |
|
|
See disable_irq() for more details.
|
712 |
|
|
|
713 |
|
|
int enable_irq( unsigned int irq );
|
714 |
|
|
|
715 |
|
|
irq : specifies the subchannel to be enabled
|
716 |
|
|
|
717 |
|
|
The enable-irq() routine may return :
|
718 |
|
|
|
719 |
|
|
|
720 |
|
|
-EBUSY - device (subchannel) is currently processing an I/O
|
721 |
|
|
request. This implies the device is already in enabled
|
722 |
|
|
state
|
723 |
|
|
-ENODEV - the device is not-operational or irq doesn't specify a
|
724 |
|
|
valid subchannel
|
725 |
|
|
|
726 |
|
|
|
727 |
|
|
|
728 |
|
|
do_IO() - Initiate I/O Request
|
729 |
|
|
|
730 |
|
|
The do_IO() routines is the I/O request front-end processor. All device driver
|
731 |
|
|
I/O requests must be issued using this routine. A device driver must not issue
|
732 |
|
|
ESA/390 I/O commands itself. Instead the do_IO() routine provides all
|
733 |
|
|
interfaces required to drive arbitrary devices.
|
734 |
|
|
|
735 |
|
|
This description also covers the status information passed to the device
|
736 |
|
|
driver's interrupt handler as this is related to the rules (flags) defined
|
737 |
|
|
with the associated I/O request when calling do_IO().
|
738 |
|
|
|
739 |
|
|
int do_IO( int irq,
|
740 |
|
|
ccw1_t *cpa,
|
741 |
|
|
unsigned long user_intparm,
|
742 |
|
|
unsigned int lpm,
|
743 |
|
|
unsigned long flag);
|
744 |
|
|
|
745 |
|
|
irq : irq (subchannel) the I/O request is destined for
|
746 |
|
|
cpa : logical start address of channel program
|
747 |
|
|
user_intparm : user specific interrupt information; will be presented
|
748 |
|
|
back to the device driver's interrupt handler. Allows a
|
749 |
|
|
device driver to associate the interrupt with a
|
750 |
|
|
particular I/O request.
|
751 |
|
|
lpm : defines the channel path to be used for a specific I/O
|
752 |
|
|
request. Valid with flag value DOIO_VALID_LPM only.
|
753 |
|
|
flag : defines the action to e parformed for I/O processing
|
754 |
|
|
|
755 |
|
|
Possible flag values are :
|
756 |
|
|
|
757 |
|
|
DOIO_EARLY_NOTIFICATION - allow for early interrupt notification
|
758 |
|
|
DOIO_VALID_LPM - LPM input parameter is valid (see usage
|
759 |
|
|
notes below for details)
|
760 |
|
|
DOIO_WAIT_FOR_INTERRUPT - wait synchronously for final status
|
761 |
|
|
DOIO_TIMEOUT - perform a loop while waiting for final status
|
762 |
|
|
and fail after a timeout
|
763 |
|
|
DOIO_REPORT_ALL - report all interrupt conditions
|
764 |
|
|
DOIO_ALLOW_SUSPEND - channel program may become suspended
|
765 |
|
|
DOIO_DENY_PREFETCH - don't allow for CCW prefetch; usually
|
766 |
|
|
this implies the channel program might
|
767 |
|
|
become modified
|
768 |
|
|
DOIO_CANCEL_ON_TIMEOUT - do a cancel_IO if there is a timeout waiting
|
769 |
|
|
for the channel program to finish (see usage
|
770 |
|
|
notes below for details)
|
771 |
|
|
|
772 |
|
|
The cpa parameter points to the first format 1 CCW of a channel program :
|
773 |
|
|
|
774 |
|
|
typedef struct {
|
775 |
|
|
__u8 cmd_code;/* command code */
|
776 |
|
|
__u8 flags; /* flags, like IDA adressing, etc. */
|
777 |
|
|
__u16 count; /* byte count */
|
778 |
|
|
__u32 cda; /* data address */
|
779 |
|
|
} __attribute__ ((packed,aligned(8))) ccw1_t;
|
780 |
|
|
|
781 |
|
|
with the following CCW flags values defined :
|
782 |
|
|
|
783 |
|
|
CCW_FLAG_DC - data chaining
|
784 |
|
|
CCW_FLAG_CC - command chaining
|
785 |
|
|
CCW_FLAG_SLI - suppress incorrct length
|
786 |
|
|
CCW_FLAG_SKIP - skip
|
787 |
|
|
CCW_FLAG_PCI - PCI
|
788 |
|
|
CCW_FLAG_IDA - indirect addressing
|
789 |
|
|
CCW_FLAG_SUSPEND - suspend
|
790 |
|
|
|
791 |
|
|
|
792 |
|
|
|
793 |
|
|
The do_IO() function returns :
|
794 |
|
|
|
795 |
|
|
|
796 |
|
|
-EBUSY - the do_io() function was caled out of sequence. The
|
797 |
|
|
device is currently processing a previous I/O request
|
798 |
|
|
-ENODEV - irq doesn't specify a valid subchannel, the device is
|
799 |
|
|
not operational (check dev_id.flags) or the irq is not
|
800 |
|
|
owned.
|
801 |
|
|
-EINVAL - both, DOIO_EARLY_NOTIFICATION and DOIO_REORT_ALL flags
|
802 |
|
|
have been specified. The usage of those flags is mutual
|
803 |
|
|
exclusive.
|
804 |
|
|
|
805 |
|
|
When the I/O request completes, the CDS first level interrupt handler will
|
806 |
|
|
setup the dev_id buffer of type devstat_t defined during request_irq()
|
807 |
|
|
processing. See request_irq() for the devstat_t data layout. The
|
808 |
|
|
dev_id->intparm field in the device status area will contain the value the
|
809 |
|
|
device driver has associated with a particular I/O request. If a pending
|
810 |
|
|
device status was recognized dev_id->intparm will be set to 0 (zero). This
|
811 |
|
|
may happen during I/O initiation or delayed by an alert status notification.
|
812 |
|
|
In any case this status is not related to the current (last) I/O request. In
|
813 |
|
|
case of a delayed status notification no special interrupt will be presented
|
814 |
|
|
to indicate I/O completion as the I/O request was never started, even though
|
815 |
|
|
do_IO() returned with successful completion.
|
816 |
|
|
|
817 |
|
|
Possible dev_id->flag values are :
|
818 |
|
|
|
819 |
|
|
DEVSTAT_FLAG_SENSE_AVAIL - sense data is available
|
820 |
|
|
DEVSTAT_NOT_OPER - device is not-operational
|
821 |
|
|
DEVSTAT_START_FUNCTION - interrupt is presented as result of a
|
822 |
|
|
call to do_IO()
|
823 |
|
|
DEVSTAT_HALT_FUNCTION - interrupt is presented as result of a
|
824 |
|
|
call to halt_IO()
|
825 |
|
|
DEVSTAT_STATUS_PENDING - a pending status was found. The I/O
|
826 |
|
|
resquest (if any) was not initiated.
|
827 |
|
|
This status might have been presented
|
828 |
|
|
delayed, after do_IO() or halt_IO() have
|
829 |
|
|
successfully be started previously.
|
830 |
|
|
DEVSTAT_FINAL_STATUS - This is a final interrupt status for the
|
831 |
|
|
I/O requst identified by intparm.
|
832 |
|
|
DEVSTAT_PCI - A PCI was received.
|
833 |
|
|
DEVSTAT_SUSPENDED - A "suspended" intermediate status was
|
834 |
|
|
received.
|
835 |
|
|
|
836 |
|
|
If device status DEVSTAT_FLAG_SENSE_AVAIL is indicated in field dev_id->flag,
|
837 |
|
|
field dev_id->scnt describes the numer of device specific sense bytes
|
838 |
|
|
available in the sense area dev_id->ii.sense. No device sensing by the device
|
839 |
|
|
driver itself is required.
|
840 |
|
|
|
841 |
|
|
typedef struct {
|
842 |
|
|
__u8 res[32]; /* reserved */
|
843 |
|
|
__u8 data[32]; /* sense data */
|
844 |
|
|
} __attribute__ ((packed)) sense_t;
|
845 |
|
|
|
846 |
|
|
The device interrupt handler can use the following definitions to investigate
|
847 |
|
|
the primary unit check source coded in sense byte 0 :
|
848 |
|
|
|
849 |
|
|
SNS0_CMD_REJECT 0x80
|
850 |
|
|
SNS0_INTERVENTION_REQ 0x40
|
851 |
|
|
SNS0_BUS_OUT_CHECK 0x20
|
852 |
|
|
SNS0_EQUIPMENT_CHECK 0x10
|
853 |
|
|
SNS0_DATA_CHECK 0x08
|
854 |
|
|
SNS0_OVERRUN 0x04
|
855 |
|
|
SNS0_INCOMPL_DOMAIN 0x01
|
856 |
|
|
|
857 |
|
|
Depending on the device status, multiple of those values may be set together.
|
858 |
|
|
Please refer to the device specific documentation for details.
|
859 |
|
|
|
860 |
|
|
The devi_id->cstat field provides the (accumulated) subchannel status :
|
861 |
|
|
|
862 |
|
|
SCHN_STAT_PCI - program controlled interrupt
|
863 |
|
|
SCHN_STAT_INCORR_LEN - incorrect length
|
864 |
|
|
SCHN_STAT_PROG_CHECK - program check
|
865 |
|
|
SCHN_STAT_PROT_CHECK - protection check
|
866 |
|
|
SCHN_STAT_CHN_DATA_CHK - channel data check
|
867 |
|
|
SCHN_STAT_CHN_CTRL_CHK - channel control check
|
868 |
|
|
SCHN_STAT_INTF_CTRL_CHK - interface control check
|
869 |
|
|
SCHN_STAT_CHAIN_CHECK - chaining check
|
870 |
|
|
|
871 |
|
|
The dev_id->dstat field provides the (accumulated) device status :
|
872 |
|
|
|
873 |
|
|
DEV_STAT_ATTENTION - attention
|
874 |
|
|
DEV_STAT_STAT_MOD - status modifier
|
875 |
|
|
DEV_STAT_CU_END - control unit end
|
876 |
|
|
DEV_STAT_BUSY - busy
|
877 |
|
|
DEV_STAT_CHN_END - channel end
|
878 |
|
|
DEV_STAT_DEV_END - device end
|
879 |
|
|
DEV_STAT_UNIT_CHECK - unit check
|
880 |
|
|
DEV_STAT_UNIT_EXCEP - unit exception
|
881 |
|
|
|
882 |
|
|
Please see the ESA/390 Principles of Operation manual for details on the
|
883 |
|
|
individual flag meanings.
|
884 |
|
|
|
885 |
|
|
In rare error situations the device driver may require access to the original
|
886 |
|
|
hardware interrupt data beyond the scope of above mentioned infromation. For
|
887 |
|
|
those situations the Linux/390 common device support provides the interrupt
|
888 |
|
|
response block (IRB) as part of the device status block in dev_id->ii.irb.
|
889 |
|
|
|
890 |
|
|
Usage Notes :
|
891 |
|
|
|
892 |
|
|
Prior to call do_IO() the device driver must assure disabled state, i.e. the
|
893 |
|
|
I/O mask value in the PSW must be disabled. This can be accomplished by calling
|
894 |
|
|
__save_flags( flags). The current PSW flags are preserved and can be restored
|
895 |
|
|
by __restore_flags( flags) at a later time.
|
896 |
|
|
|
897 |
|
|
If the device driver violates this rule while running in a uni-processor
|
898 |
|
|
environment an interrupt might be presented prior to the do_IO() routine
|
899 |
|
|
returning to the device driver main path. In this case we will end in a
|
900 |
|
|
deadlock situation as the interrupt handler will try to obtain the irq
|
901 |
|
|
lock the device driver still owns (see below) !
|
902 |
|
|
|
903 |
|
|
The driver must assure to hold the device specific lock. This can be
|
904 |
|
|
accomplished by
|
905 |
|
|
|
906 |
|
|
(i) s390irq_spin_lock( irq), or
|
907 |
|
|
(ii) s390irq_spin_lock_irqsave(irq, flags)
|
908 |
|
|
|
909 |
|
|
Option (i) should be used if the calling routine is running disabled for
|
910 |
|
|
I/O interrupts (see above) already. Option (ii) obtains the device gate und
|
911 |
|
|
puts the CPU into I/O disabled state by preserving the current PSW flags.
|
912 |
|
|
See the descriptions of s390irq_spin_lock() or s390irq_spin_lock_irqsave()
|
913 |
|
|
for more details.
|
914 |
|
|
|
915 |
|
|
The device driver is allowed to issue the next do_IO() call from within its
|
916 |
|
|
interrupt handler already. It is not required to schedule a bottom-half,
|
917 |
|
|
unless an non deterministicly long running error recovery procedure or
|
918 |
|
|
similar needs to be scheduled. During I/O processing the Linux/390 generic
|
919 |
|
|
I/O device driver support has already obtained the IRQ lock, i.e. the handler
|
920 |
|
|
must not try to obtain it again when calling do_IO() or we end in a deadlock
|
921 |
|
|
situation ! Anyway, the device driver's interrupt handler must only call
|
922 |
|
|
do_IO() if the handler itself can be entered recursively if do_IO() e.g. finds
|
923 |
|
|
a status pending and needs to all the interrupt handler itself.
|
924 |
|
|
|
925 |
|
|
Device drivers shouldn't heavily rely on DOIO_WAIT_FOR_INTERRUPT synchronous
|
926 |
|
|
I/O request processing. All I/O devices, but the console device are driven
|
927 |
|
|
using a single shared interrupt subclass (ISC). For sync. processing the
|
928 |
|
|
device is temporarily mapped to a special ISC while the calling CPU waits for
|
929 |
|
|
I/O completion. As this special ISC is gated, all sync. requests in a SMP
|
930 |
|
|
environment are serialized which may cause other CPUs to spin. This service
|
931 |
|
|
is therewith primarily meant to be used during device driver initialization
|
932 |
|
|
for ease of device setup.
|
933 |
|
|
|
934 |
|
|
If the device driver is using the DOIO_TIMEOUT parameter, it is a good idea
|
935 |
|
|
also to specify DOIO_CANCEL_ON_TIMEOUT. Otherwise, the failing channel program
|
936 |
|
|
may prevent the execution of any other channel program at the subchannel.
|
937 |
|
|
|
938 |
|
|
The lpm input parameter might be used for multipath devices shared among
|
939 |
|
|
multiple systems as the Linux/390 CDS isn't grouping channel paths. Therefore
|
940 |
|
|
its use might be required if multiple access paths to a device are available
|
941 |
|
|
and the device was reserved by means of a reserve device command (for devices
|
942 |
|
|
supporting this technique). When issuing this command the device driver needs
|
943 |
|
|
needs to extract the dev_id->lpum value and restrict all subsequent channel
|
944 |
|
|
programs to this channel path until the device is released by a device release
|
945 |
|
|
command. Otherwise a deadlock may occur.
|
946 |
|
|
|
947 |
|
|
If a device driver relies on an I/O request to be completed prior to start the
|
948 |
|
|
next it can reduce I/O processing overhead by chaining a NoOp I/O command
|
949 |
|
|
CCW_CMD_NOOP to the end of the submitted CCW chain. This will force Channel-End
|
950 |
|
|
and Device-End status to be presented together, with a single interrupt.
|
951 |
|
|
However, this should be used with care as it implies the channel will remain
|
952 |
|
|
busy, not being able to process I/O requests for other devices on the same
|
953 |
|
|
channel. Therefore e.g. read commands should never use this technique, as the
|
954 |
|
|
result will be presented by a single interrupt anyway.
|
955 |
|
|
|
956 |
|
|
In order to minimize I/O overhead, a device driver should use the
|
957 |
|
|
DOIO_REPORT_ALL only if the device can report intermediate interrupt
|
958 |
|
|
information prior to device-end the device driver urgently relies on. In this
|
959 |
|
|
case all I/O interruptions are presented to the device driver until final
|
960 |
|
|
status is recognized.
|
961 |
|
|
|
962 |
|
|
If a device is able to recover from asynchronosly presented I/O errors, it can
|
963 |
|
|
perform overlapping I/O using the DOIO_EARLY_NOTIFICATION flag. While some
|
964 |
|
|
devices always report channel-end and device-end together, with a single
|
965 |
|
|
interrupt, others present primary status (channel-end) when the channel is
|
966 |
|
|
ready for the next I/O request and secondary status (device-end) when the data
|
967 |
|
|
transmission has been completed at the device.
|
968 |
|
|
|
969 |
|
|
Above flag allows to exploit this feature, e.g. for communication devices that
|
970 |
|
|
can handle lost data on the network to allow for enhanced I/O processing.
|
971 |
|
|
|
972 |
|
|
Unless the channel subsystem at any time presents a secondary status interrupt,
|
973 |
|
|
exploiting this feature will cause only primary status interrups to be
|
974 |
|
|
presented to the device driver while overlapping I/O is performed. When a
|
975 |
|
|
secondary status without error (alert status) is presented, this indicates
|
976 |
|
|
successful completion for all overlapping do_IO() requests that have been
|
977 |
|
|
issued since the last secondary (final) status.
|
978 |
|
|
|
979 |
|
|
During interrupt processing the device specific interrupt handler should avoid
|
980 |
|
|
basing its processing decisions on the interruption response block (IRB) that
|
981 |
|
|
is part of the dev_id buffer area. The IRB area represents the interruption
|
982 |
|
|
parameters from the last interrupt received. Unless the device driver has
|
983 |
|
|
specified DOIO_REPORT_ALL or is called with a pending status
|
984 |
|
|
(DEVSTAT_STATUS_PENDING), the IRB information may or may not show the complete
|
985 |
|
|
interruption status, but the last interrupt only. Therefore the device driver
|
986 |
|
|
should usually base its processing decisions on the values of dev_id->cstat
|
987 |
|
|
and dev_id->dstat that represent the accumulated subchannel and device status
|
988 |
|
|
information gathered since do_IO() request initiation.
|
989 |
|
|
|
990 |
|
|
Channel programs that intend to set the suspend flag on a channel command word
|
991 |
|
|
(CCW) must start the I/O operation with the DOIO_ALLOW_SUSPEND option or the
|
992 |
|
|
suspend flag will cause a channel program check. At the time the channel program
|
993 |
|
|
becomes suspended an intermediate interrupt will be generated by the channel
|
994 |
|
|
subsystem.
|
995 |
|
|
|
996 |
|
|
resume_IO() - Resume Channel Program Execution
|
997 |
|
|
|
998 |
|
|
If a device driver chooses to suspend the current channel program execution by
|
999 |
|
|
setting the CCW suspend flag on a particular CCW, the channel program execution
|
1000 |
|
|
is suspended. In order to resume channel program execution the CIO layer
|
1001 |
|
|
provides the resume_IO() routine.
|
1002 |
|
|
|
1003 |
|
|
int resume_IO( int irq);
|
1004 |
|
|
|
1005 |
|
|
irq : irq (subchannel) the halt operation is requested for
|
1006 |
|
|
|
1007 |
|
|
The resume_IO() function returns:
|
1008 |
|
|
|
1009 |
|
|
|
1010 |
|
|
-EBUSY - status pending
|
1011 |
|
|
-ENODEV - invalid or not-operational subchannel
|
1012 |
|
|
-EINVAL - resume function not applicable
|
1013 |
|
|
-ENOTCONN - there is no I/O request pending for completion
|
1014 |
|
|
|
1015 |
|
|
Usage Notes:
|
1016 |
|
|
Please have a look at the do_IO() usage notes for more details on suspended
|
1017 |
|
|
channel programs.
|
1018 |
|
|
|
1019 |
|
|
halt_IO() - Halt I/O Request Processing
|
1020 |
|
|
|
1021 |
|
|
Sometimes a device driver might need a possibility to stop the processing of
|
1022 |
|
|
a long-running channel program or the device might require to initially issue
|
1023 |
|
|
a halt subchannel (HSCH) I/O command. For those purposes the halt_IO() command
|
1024 |
|
|
is provided.
|
1025 |
|
|
|
1026 |
|
|
int halt_IO( int irq, /* subchannel number */
|
1027 |
|
|
unsigned long intparm, /* dummy intparm */
|
1028 |
|
|
unsigned long flag); /* operation mode */
|
1029 |
|
|
|
1030 |
|
|
irq : irq (subchannel) the halt operation is requested for
|
1031 |
|
|
intparm : interruption parameter; value is only used if no I/O
|
1032 |
|
|
is outstanding, otherwise the intparm associated with
|
1033 |
|
|
the I/O request is returned
|
1034 |
|
|
flag : 0 (zero) or DOIO_WAIT_FOR_INTERRUPT
|
1035 |
|
|
|
1036 |
|
|
The halt_IO() function returns :
|
1037 |
|
|
|
1038 |
|
|
|
1039 |
|
|
-EBUSY - the device is currently performing a synchronous I/O
|
1040 |
|
|
operation : do_IO() with flag DOIO_WAIT_FOR_INTERRUPT
|
1041 |
|
|
or an error was encountered and the device is currently
|
1042 |
|
|
be sensed
|
1043 |
|
|
-ENODEV - the irq specified doesn't specify a valid subchannel, the
|
1044 |
|
|
device is not operational (check dev_id.flags) or the irq
|
1045 |
|
|
is not owned.
|
1046 |
|
|
|
1047 |
|
|
Usage Notes :
|
1048 |
|
|
|
1049 |
|
|
A device driver may write a never-ending channel program by writing a channel
|
1050 |
|
|
program that at its end loops back to its beginning by means of a transfer in
|
1051 |
|
|
channel (TIC) command (CCW_CMD_TIC). Usually this is performed by network
|
1052 |
|
|
device drivers by setting the PCI CCW flag (CCW_FLAG_PCI). Once this CCW is
|
1053 |
|
|
executed a program controlled interrupt (PCI) is generated. The device driver
|
1054 |
|
|
can then perform an appropriate action. Prior to interrupt of an outstanding
|
1055 |
|
|
read to a network device (with or without PCI flag) a halt_IO() is required
|
1056 |
|
|
to end the pending operation.
|
1057 |
|
|
|
1058 |
|
|
We don't allow to stop sync. I/O requests by means of a halt_IO() call. The
|
1059 |
|
|
function will return -EBUSY instead.
|
1060 |
|
|
|
1061 |
|
|
|
1062 |
|
|
Miscellaneous Support Routines
|
1063 |
|
|
|
1064 |
|
|
This chapter describes various routines to be used in a Linux/390 device
|
1065 |
|
|
driver programming environment.
|
1066 |
|
|
|
1067 |
|
|
s390irq_spin_lock() / s390irq_spin_unlock()
|
1068 |
|
|
|
1069 |
|
|
Those two macro definitions are required to obtain the device specific IRQ
|
1070 |
|
|
lock. The lock needs to be obtained if the device driver intends to call
|
1071 |
|
|
do_IO() or halt_IO() from anywhere but the device interrupt handler (where
|
1072 |
|
|
the lock is already owned). Those routines must only be used if running
|
1073 |
|
|
disabled for interrupts already. Otherwise use s390irq_spin_lock_irqsave()
|
1074 |
|
|
and the corresponding unlock routine instead (see below).
|
1075 |
|
|
|
1076 |
|
|
s390irq_spin_lock( int irq);
|
1077 |
|
|
s390irq_spin_unlock( int irq);
|
1078 |
|
|
|
1079 |
|
|
|
1080 |
|
|
s390irq_spin_lock_irqsave() / s390_irq_spin_unlock_irqrestore()
|
1081 |
|
|
|
1082 |
|
|
Those two macro definitions are required to obtain the device specific IRQ
|
1083 |
|
|
lock. The lock needs to be obtained if the device driver intends to call
|
1084 |
|
|
do_IO() or halt_IO() from anywhere but the device interrupt handler (where
|
1085 |
|
|
the lock is already owned). Those routines should only be used if running
|
1086 |
|
|
enabled for interrupts. If running disabled already, the driver should use
|
1087 |
|
|
s390irq_spin_lock() and the corresponding unlock routine instead (see above).
|
1088 |
|
|
|
1089 |
|
|
s390irq_spin_lock_irqsave( int irq, unsigned long flags);
|
1090 |
|
|
s390irq_spin_unlock_irqrestore( int irq, unsigned long flags);
|
1091 |
|
|
|
1092 |
|
|
|
1093 |
|
|
|
1094 |
|
|
|
1095 |
|
|
Special Console Interface Routines
|
1096 |
|
|
|
1097 |
|
|
This chapter describes the special interface routines required for system
|
1098 |
|
|
console processing. Though they are an extension to the Linux/390 device
|
1099 |
|
|
driver interface concept, they base on the same principles. It was necessary
|
1100 |
|
|
to build those extensions to assure a deterministic behaviour in critical
|
1101 |
|
|
situations e.g. printk() messages by other device drivers running disabled
|
1102 |
|
|
for interrupts during I/O interrupt handling or in case of a panic() message
|
1103 |
|
|
being raised.
|
1104 |
|
|
|
1105 |
|
|
set_cons_dev - Set Console Device
|
1106 |
|
|
|
1107 |
|
|
This routine allows to specify the system console device. This is necessary
|
1108 |
|
|
as the console isn't driven by the same ESA/390 interrupt subclass as are
|
1109 |
|
|
other devices, but it is assigned ist own interrupt subclass. Only one device
|
1110 |
|
|
can act as system console. See wait_cons_dev() for details.
|
1111 |
|
|
|
1112 |
|
|
int set_cons_dev( int irq);
|
1113 |
|
|
|
1114 |
|
|
irq : subchannel identifying the system console device
|
1115 |
|
|
|
1116 |
|
|
The set_cons_dev() function returns
|
1117 |
|
|
|
1118 |
|
|
|
1119 |
|
|
-EIO - an unhandled interrupt condition is pending for the
|
1120 |
|
|
specified subchannel (irq) - status pending
|
1121 |
|
|
-ENODEV - irq doesn't specify a valid subchannel or the devive is
|
1122 |
|
|
not operational
|
1123 |
|
|
-EBUSY - the console device is already defined
|
1124 |
|
|
|
1125 |
|
|
wait_cons_dev - Synchronously Wait for Console Processing
|
1126 |
|
|
|
1127 |
|
|
The wait_cons_dev() routine is used by the console device driver when its
|
1128 |
|
|
buffer pool for intermediate request queuing is exhausted and a new output
|
1129 |
|
|
request is received. In this case the console driver uses the wait_cons_dev()
|
1130 |
|
|
routine to synchronously wait until enough buffer space is gained to enqueue
|
1131 |
|
|
the current request. Any pending interrupt condition for the console device
|
1132 |
|
|
found during wait_cons_dev() processing causes its interrupt handler to be
|
1133 |
|
|
called.
|
1134 |
|
|
|
1135 |
|
|
int wait_cons_dev( int irq);
|
1136 |
|
|
|
1137 |
|
|
irq : subchannel identifying the system console device
|
1138 |
|
|
|
1139 |
|
|
The wait_cons_dev() function returns :
|
1140 |
|
|
|
1141 |
|
|
|
1142 |
|
|
-EINVAL - the irq specified doesn't match the irq configured for
|
1143 |
|
|
the console device by set_cons_dev()
|
1144 |
|
|
|
1145 |
|
|
Usage Notes :
|
1146 |
|
|
|
1147 |
|
|
The function should be used carefully. Especially in a SMP environment the
|
1148 |
|
|
wait_cons_dev() processing requires that all but the special console ISC are
|
1149 |
|
|
disabled. In a SMP system this requires the other CPUs to be signaled to
|
1150 |
|
|
disable/enable those ISCs.
|
1151 |
|
|
|
1152 |
|
|
|
1153 |
|
|
|