1 ===========================
2 Linux for S/390 and zSeries
3 ===========================
4
5 Common Device Support (CDS)
6 Device Driver I/O Support Routines
7
8 Authors:
9 - Ingo Adlung
10 - Cornelia Huck
11
12 Copyright, IBM Corp. 1999-2002
13
14 Introduction
15 ============
16
17 This document describes the common device supp
18 Different than other hardware architectures, E
19 I/O access method. This gives relief to the de
20 have to deal with different bus types, polling
21 processing, shared versus non-shared interrupt
22 I/O (PIO), and other hardware features more. H
23 either every single device driver needs to imp
24 attachment functionality itself, or the operat
25 unified method to access the hardware, providi
26 every single device driver would have to provi
27
28 The document does not intend to explain the ES
29 every detail.This information can be obtained
30 Operation manual (IBM Form. No. SA22-7201).
31
32 In order to build common device support for ES
33 functional layer was introduced that provides
34 the hardware.
35
36 The common device support layer comprises the
37 below. Some of them implement common Linux dev
38 some of them are ESA/390 platform specific.
39
40 Note:
41 In order to write a driver for S/390, you al
42 described in Documentation/arch/s390/driver-
43
44 Note for porting drivers from 2.4:
45
46 The major changes are:
47
48 * The functions use a ccw_device instead of an
49 * All drivers must define a ccw_driver (see dr
50 functions.
51 * request_irq() and free_irq() are no longer d
52 * The oper_handler is (kindof) replaced by the
53 of the ccw_driver.
54 * The not_oper_handler is (kindof) replaced by
55 functions of the ccw_driver.
56 * The channel device layer is gone.
57 * The interrupt handlers must be adapted to us
58 Moreover, they don't return a devstat, but a
59 * Before initiating an io, the options must be
60 * Instead of calling read_dev_chars()/read_con
61 the channel program and handles the interrup
62
63 ccw_device_get_ciw()
64 get commands from extended sense data.
65
66 ccw_device_start(), ccw_device_start_timeout()
67 initiate an I/O request.
68
69 ccw_device_resume()
70 resume channel program execution.
71
72 ccw_device_halt()
73 terminate the current I/O request processed
74
75 do_IRQ()
76 generic interrupt routine. This function is
77 routine whenever an I/O interrupt is presen
78 routine determines the interrupt status and
79 interrupt handler according to the rules (f
80 initiation with do_IO().
81
82 The next chapters describe the functions other
83 The do_IRQ() interface is not described, as it
84 first level interrupt handler only and does no
85 callable interface. Instead, the functional de
86 describes the input to the device specific int
87
88 Note:
89 All explanations apply also to the 64
90
91
92 Common Device Support (CDS) for Linux/390 Devi
93 ==============================================
94
95 General Information
96 -------------------
97
98 The following chapters describe the I/O relate
99 Linux/390 common device support (CDS) provides
100 driver implementations on the IBM ESA/390 hard
101 intend to provide the functionality required b
102 implementation to allow to drive a specific ha
103 platform. Some of the interface routines are s
104 of them can be found on other Linux platforms
105 Miscellaneous function prototypes, data declar
106 can be found in the architecture specific C he
107 linux/arch/s390/include/asm/irq.h.
108
109 Overview of CDS interface concepts
110 ----------------------------------
111
112 Different to other hardware platforms, the ESA
113 interrupt lines managed by a specific interrup
114 that may or may not allow for shared interrupt
115 the ESA/390 architecture has implemented a so
116 provides a unified view of the devices physica
117 Though the ESA/390 hardware platform knows abo
118 peripheral attachments like disk devices (aka.
119 controllers, etc. they can all be accessed by
120 they are presenting I/O completion a unified w
121 single device is uniquely identified to the sy
122 where the ESA/390 architecture allows for 64k
123
124 Linux, however, was first built on the Intel P
125 cascaded 8259 programmable interrupt controlle
126 maximum of 15 different interrupt lines. All d
127 share those 15 interrupt levels. Devices attac
128 not share interrupt levels (aka. IRQs), as the
129 interrupts. MCA, EISA, PCI and other bus syste
130 interrupts, and therewith allow for shared IRQ
131 present their hardware status by the same (sha
132 has to call every single device driver registe
133 determine the device driver owning the device
134
135 Up to kernel 2.4, Linux/390 used to provide in
136 For internal use of the common I/O layer, thes
137 device drivers should use the new calling inte
138
139 During its startup the Linux/390 system checks
140 of those devices is uniquely defined by a so c
141 channel subsystem. While the subchannel number
142 subchannel also takes a user defined attribute
143 Both subchannel number and device number canno
144 initialisation, the information about control
145 imply specific I/O commands (channel command w
146 the device are gathered. Device drivers can re
147 information during their initialization step t
148 support using the information saved in the str
149 This methods implies that Linux/390 doesn't re
150 armed) interrupt request lines (IRQs) to drive
151 applicable, the device drivers can use issue t
152 ccw to retrieve device characteristics in its
153
154 In order to allow for easy I/O initiation the
155 ccw_device_start() interface that takes a devi
156 or more CCWs) as input sets up the required ar
157 and initiates an I/O request on behalf of the
158 ccw_device_start() routine allows to specify w
159 to notify the device driver for every interrup
160 only. See ccw_device_start() for more details.
161 ESA/390 I/O commands itself, but must use the
162
163 For long running I/O request to be canceled, t
164 ccw_device_halt() function. Some devices requi
165 SUBCHANNEL (HSCH) command without having pendi
166 also covered by ccw_device_halt().
167
168
169 get_ciw() - get command information word
170
171 This call enables a device driver to get infor
172 from the extended SenseID data.
173
174 ::
175
176 struct ciw *
177 ccw_device_get_ciw(struct ccw_device *cdev,
178
179 ==== ========================================
180 cdev The ccw_device for which the command is
181 cmd The command type to be retrieved.
182 ==== ========================================
183
184 ccw_device_get_ciw() returns:
185
186 ===== =======================================
187 NULL No extended data available, invalid dev
188 !NULL The command requested.
189 ===== =======================================
190
191 ::
192
193 ccw_device_start() - Initiate I/O Request
194
195 The ccw_device_start() routines is the I/O req
196 device driver I/O requests must be issued usin
197 must not issue ESA/390 I/O commands itself. In
198 routine provides all interfaces required to dr
199
200 This description also covers the status inform
201 driver's interrupt handler as this is related
202 with the associated I/O request when calling c
203
204 ::
205
206 int ccw_device_start(struct ccw_device *cdev
207 struct ccw1 *cpa,
208 unsigned long intparm,
209 __u8 lpm,
210 unsigned long flags);
211 int ccw_device_start_timeout(struct ccw_devi
212 struct ccw1 *cp
213 unsigned long i
214 __u8 lpm,
215 unsigned long f
216 int expires);
217 int ccw_device_start_key(struct ccw_device *
218 struct ccw1 *cpa,
219 unsigned long intpa
220 __u8 lpm,
221 __u8 key,
222 unsigned long flags
223 int ccw_device_start_key_timeout(struct ccw_
224 struct ccw1
225 unsigned lo
226 __u8 lpm,
227 __u8 key,
228 unsigned lo
229 int expires
230
231 ============= ================================
232 cdev ccw_device the I/O is destined f
233 cpa logical start address of channel
234 user_intparm user specific interrupt informat
235 back to the device driver's inte
236 device driver to associate the i
237 particular I/O request.
238 lpm defines the channel path to be u
239 request. A value of 0 will make
240 key the storage key to use for the I
241 storage with a storage key != de
242 flag defines the action to be perform
243 expires timeout value in jiffies. The co
244 the running program after this a
245 with ERR_PTR(-ETIMEDOUT) as irb.
246 ============= ================================
247
248 Possible flag values are:
249
250 ========================= ====================
251 DOIO_ALLOW_SUSPEND channel program may
252 DOIO_DENY_PREFETCH don't allow for CCW
253 this implies the cha
254 become modified
255 DOIO_SUPPRESS_INTER don't call the handl
256 ========================= ====================
257
258 The cpa parameter points to the first format 1
259
260 struct ccw1 {
261 __u8 cmd_code;/* command code */
262 __u8 flags; /* flags, like IDA addr
263 __u16 count; /* byte count */
264 __u32 cda; /* data address */
265 } __attribute__ ((packed,aligned(8)));
266
267 with the following CCW flags values defined:
268
269 =================== =========================
270 CCW_FLAG_DC data chaining
271 CCW_FLAG_CC command chaining
272 CCW_FLAG_SLI suppress incorrect length
273 CCW_FLAG_SKIP skip
274 CCW_FLAG_PCI PCI
275 CCW_FLAG_IDA indirect addressing
276 CCW_FLAG_SUSPEND suspend
277 =================== =========================
278
279
280 Via ccw_device_set_options(), the device drive
281 options for the device:
282
283 ========================= ====================
284 DOIO_EARLY_NOTIFICATION allow for early inte
285 DOIO_REPORT_ALL report all interrupt
286 ========================= ====================
287
288
289 The ccw_device_start() function returns:
290
291 ======== =====================================
292 0 successful completion or request succ
293 -EBUSY The device is currently processing a
294 a status pending at the device.
295 -ENODEV cdev is invalid, the device is not op
296 not online.
297 ======== =====================================
298
299 When the I/O request completes, the CDS first
300 accumulate the status in a struct irb and then
301 The intparm field will contain the value the d
302 particular I/O request. If a pending device st
303 intparm will be set to 0 (zero). This may happ
304 by an alert status notification. In any case t
305 current (last) I/O request. In case of a delay
306 interrupt will be presented to indicate I/O co
307 never started, even though ccw_device_start()
308
309 The irb may contain an error value, and the de
310 first:
311
312 ========== ===================================
313 -ETIMEDOUT the common I/O layer terminated the
314 timeout value
315 -EIO the common I/O layer terminated the
316 ========== ===================================
317
318 If the concurrent sense flag in the extended s
319 set, the field erw.scnt in the esw describes t
320 sense bytes available in the extended control
321 sensing by the device driver itself is require
322
323 The device interrupt handler can use the follo
324 the primary unit check source coded in sense b
325
326 ======================= ====
327 SNS0_CMD_REJECT 0x80
328 SNS0_INTERVENTION_REQ 0x40
329 SNS0_BUS_OUT_CHECK 0x20
330 SNS0_EQUIPMENT_CHECK 0x10
331 SNS0_DATA_CHECK 0x08
332 SNS0_OVERRUN 0x04
333 SNS0_INCOMPL_DOMAIN 0x01
334 ======================= ====
335
336 Depending on the device status, multiple of th
337 Please refer to the device specific documentat
338
339 The irb->scsw.cstat field provides the (accumu
340
341 ========================= ====================
342 SCHN_STAT_PCI program controlled i
343 SCHN_STAT_INCORR_LEN incorrect length
344 SCHN_STAT_PROG_CHECK program check
345 SCHN_STAT_PROT_CHECK protection check
346 SCHN_STAT_CHN_DATA_CHK channel data check
347 SCHN_STAT_CHN_CTRL_CHK channel control chec
348 SCHN_STAT_INTF_CTRL_CHK interface control ch
349 SCHN_STAT_CHAIN_CHECK chaining check
350 ========================= ====================
351
352 The irb->scsw.dstat field provides the (accumu
353
354 ===================== =================
355 DEV_STAT_ATTENTION attention
356 DEV_STAT_STAT_MOD status modifier
357 DEV_STAT_CU_END control unit end
358 DEV_STAT_BUSY busy
359 DEV_STAT_CHN_END channel end
360 DEV_STAT_DEV_END device end
361 DEV_STAT_UNIT_CHECK unit check
362 DEV_STAT_UNIT_EXCEP unit exception
363 ===================== =================
364
365 Please see the ESA/390 Principles of Operation
366 individual flag meanings.
367
368 Usage Notes:
369
370 ccw_device_start() must be called disabled and
371
372 The device driver is allowed to issue the next
373 within its interrupt handler already. It is no
374 bottom-half, unless a non deterministically lo
375 or similar needs to be scheduled. During I/O p
376 I/O device driver support has already obtained
377 must not try to obtain it again when calling c
378 deadlock situation!
379
380 If a device driver relies on an I/O request to
381 next it can reduce I/O processing overhead by
382 CCW_CMD_NOOP to the end of the submitted CCW c
383 and Device-End status to be presented together
384 However, this should be used with care as it i
385 busy, not being able to process I/O requests f
386 channel. Therefore e.g. read commands should n
387 result will be presented by a single interrupt
388
389 In order to minimize I/O overhead, a device dr
390 DOIO_REPORT_ALL only if the device can report
391 information prior to device-end the device dri
392 case all I/O interruptions are presented to th
393 status is recognized.
394
395 If a device is able to recover from asynchrono
396 perform overlapping I/O using the DOIO_EARLY_N
397 devices always report channel-end and device-e
398 interrupt, others present primary status (chan
399 ready for the next I/O request and secondary s
400 transmission has been completed at the device.
401
402 Above flag allows to exploit this feature, e.g
403 can handle lost data on the network to allow f
404
405 Unless the channel subsystem at any time prese
406 exploiting this feature will cause only primar
407 presented to the device driver while overlappi
408 secondary status without error (alert status)
409 successful completion for all overlapping ccw_
410 been issued since the last secondary (final) s
411
412 Channel programs that intend to set the suspen
413 (CCW) must start the I/O operation with the D
414 suspend flag will cause a channel program chec
415 becomes suspended an intermediate interrupt wi
416 subsystem.
417
418 ccw_device_resume() - Resume Channel Program E
419
420 If a device driver chooses to suspend the curr
421 setting the CCW suspend flag on a particular C
422 is suspended. In order to resume channel progr
423 provides the ccw_device_resume() routine.
424
425 ::
426
427 int ccw_device_resume(struct ccw_device *cde
428
429 ==== ========================================
430 cdev ccw_device the resume operation is reque
431 ==== ========================================
432
433 The ccw_device_resume() function returns:
434
435 ========= ==================================
436 0 suspended channel program is resum
437 -EBUSY status pending
438 -ENODEV cdev invalid or not-operational su
439 -EINVAL resume function not applicable
440 -ENOTCONN there is no I/O request pending fo
441 ========= ==================================
442
443 Usage Notes:
444
445 Please have a look at the ccw_device_start() u
446 suspended channel programs.
447
448 ccw_device_halt() - Halt I/O Request Processin
449
450 Sometimes a device driver might need a possibi
451 a long-running channel program or the device m
452 a halt subchannel (HSCH) I/O command. For thos
453 command is provided.
454
455 ccw_device_halt() must be called disabled and
456
457 ::
458
459 int ccw_device_halt(struct ccw_device *cdev,
460 unsigned long intparm);
461
462 ======= =====================================
463 cdev ccw_device the halt operation is requ
464 intparm interruption parameter; value is only
465 is outstanding, otherwise the intparm
466 the I/O request is returned
467 ======= =====================================
468
469 The ccw_device_halt() function returns:
470
471 ======= =====================================
472 0 request successfully initiated
473 -EBUSY the device is currently busy, or stat
474 -ENODEV cdev invalid.
475 -EINVAL The device is not operational or the
476 ======= =====================================
477
478 Usage Notes:
479
480 A device driver may write a never-ending chann
481 program that at its end loops back to its begi
482 channel (TIC) command (CCW_CMD_TIC). Usually
483 device drivers by setting the PCI CCW flag (CC
484 executed a program controlled interrupt (PCI)
485 can then perform an appropriate action. Prior
486 read to a network device (with or without PCI
487 is required to end the pending operation.
488
489 ::
490
491 ccw_device_clear() - Terminage I/O Request P
492
493 In order to terminate all I/O processing at th
494 (CSCH) command is used. It can be issued via c
495
496 ccw_device_clear() must be called disabled and
497
498 ::
499
500 int ccw_device_clear(struct ccw_device *cdev
501
502 ======= ======================================
503 cdev ccw_device the clear operation is requ
504 intparm interruption parameter (see ccw_device
505 ======= ======================================
506
507 The ccw_device_clear() function returns:
508
509 ======= =====================================
510 0 request successfully initiated
511 -ENODEV cdev invalid
512 -EINVAL The device is not operational or the
513 ======= =====================================
514
515 Miscellaneous Support Routines
516 ------------------------------
517
518 This chapter describes various routines to be
519 driver programming environment.
520
521 get_ccwdev_lock()
522
523 Get the address of the device specific lock. T
524 spin_lock() / spin_unlock() calls.
525
526 ::
527
528 __u8 ccw_device_get_path_mask(struct ccw_dev
529
530 Get the mask of the path currently available f
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.