blob: f0be389c7116934b6c1e43b97d70dab486aedf2a [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001Linux for S/390 and zSeries
2
3Common Device Support (CDS)
4Device Driver I/O Support Routines
5
6Authors : Ingo Adlung
7 Cornelia Huck
8
9Copyright, IBM Corp. 1999-2002
10
11Introduction
12
13This document describes the common device support routines for Linux/390.
14Different than other hardware architectures, ESA/390 has defined a unified
15I/O access method. This gives relief to the device drivers as they don't
16have to deal with different bus types, polling versus interrupt
17processing, shared versus non-shared interrupt processing, DMA versus port
18I/O (PIO), and other hardware features more. However, this implies that
19either every single device driver needs to implement the hardware I/O
20attachment functionality itself, or the operating system provides for a
21unified method to access the hardware, providing all the functionality that
22every single device driver would have to provide itself.
23
24The document does not intend to explain the ESA/390 hardware architecture in
25every detail.This information can be obtained from the ESA/390 Principles of
26Operation manual (IBM Form. No. SA22-7201).
27
28In order to build common device support for ESA/390 I/O interfaces, a
29functional layer was introduced that provides generic I/O access methods to
30the hardware.
31
32The common device support layer comprises the I/O support routines defined
33below. Some of them implement common Linux device driver interfaces, while
34some of them are ESA/390 platform specific.
35
36Note:
37In order to write a driver for S/390, you also need to look into the interface
38described in Documentation/s390/driver-model.txt.
39
40Note for porting drivers from 2.4:
41The major changes are:
42* The functions use a ccw_device instead of an irq (subchannel).
43* All drivers must define a ccw_driver (see driver-model.txt) and the associated
44 functions.
45* request_irq() and free_irq() are no longer done by the driver.
46* The oper_handler is (kindof) replaced by the probe() and set_online() functions
47 of the ccw_driver.
48* The not_oper_handler is (kindof) replaced by the remove() and set_offline()
49 functions of the ccw_driver.
50* The channel device layer is gone.
51* The interrupt handlers must be adapted to use a ccw_device as argument.
52 Moreover, they don't return a devstat, but an irb.
53* Before initiating an io, the options must be set via ccw_device_set_options().
54
55read_dev_chars()
56 read device characteristics
57
58read_conf_data()
Cornelia Huck9fc14272005-05-01 08:59:00 -070059read_conf_data_lpm()
Linus Torvalds1da177e2005-04-16 15:20:36 -070060 read configuration data.
61
62ccw_device_get_ciw()
63 get commands from extended sense data.
64
65ccw_device_start()
Cornelia Huck9fc14272005-05-01 08:59:00 -070066ccw_device_start_timeout()
67ccw_device_start_key()
68ccw_device_start_key_timeout()
Linus Torvalds1da177e2005-04-16 15:20:36 -070069 initiate an I/O request.
70
71ccw_device_resume()
72 resume channel program execution.
73
74ccw_device_halt()
75 terminate the current I/O request processed on the device.
76
77do_IRQ()
78 generic interrupt routine. This function is called by the interrupt entry
79 routine whenever an I/O interrupt is presented to the system. The do_IRQ()
80 routine determines the interrupt status and calls the device specific
81 interrupt handler according to the rules (flags) defined during I/O request
82 initiation with do_IO().
83
84The next chapters describe the functions other than do_IRQ() in more details.
85The do_IRQ() interface is not described, as it is called from the Linux/390
86first level interrupt handler only and does not comprise a device driver
87callable interface. Instead, the functional description of do_IO() also
88describes the input to the device specific interrupt handler.
89
90Note: All explanations apply also to the 64 bit architecture s390x.
91
92
93Common Device Support (CDS) for Linux/390 Device Drivers
94
95General Information
96
97The following chapters describe the I/O related interface routines the
98Linux/390 common device support (CDS) provides to allow for device specific
99driver implementations on the IBM ESA/390 hardware platform. Those interfaces
100intend to provide the functionality required by every device driver
101implementaion to allow to drive a specific hardware device on the ESA/390
102platform. Some of the interface routines are specific to Linux/390 and some
103of them can be found on other Linux platforms implementations too.
104Miscellaneous function prototypes, data declarations, and macro definitions
105can be found in the architecture specific C header file
106linux/include/asm-s390/irq.h.
107
108Overview of CDS interface concepts
109
110Different to other hardware platforms, the ESA/390 architecture doesn't define
111interrupt lines managed by a specific interrupt controller and bus systems
112that may or may not allow for shared interrupts, DMA processing, etc.. Instead,
113the ESA/390 architecture has implemented a so called channel subsystem, that
114provides a unified view of the devices physically attached to the systems.
115Though the ESA/390 hardware platform knows about a huge variety of different
116peripheral attachments like disk devices (aka. DASDs), tapes, communication
117controllers, etc. they can all by accessed by a well defined access method and
118they are presenting I/O completion a unified way : I/O interruptions. Every
119single device is uniquely identified to the system by a so called subchannel,
120where the ESA/390 architecture allows for 64k devices be attached.
121
122Linux, however, was first built on the Intel PC architecture, with its two
123cascaded 8259 programmable interrupt controllers (PICs), that allow for a
124maximum of 15 different interrupt lines. All devices attached to such a system
125share those 15 interrupt levels. Devices attached to the ISA bus system must
126not share interrupt levels (aka. IRQs), as the ISA bus bases on edge triggered
127interrupts. MCA, EISA, PCI and other bus systems base on level triggered
128interrupts, and therewith allow for shared IRQs. However, if multiple devices
129present their hardware status by the same (shared) IRQ, the operating system
130has to call every single device driver registered on this IRQ in order to
131determine the device driver owning the device that raised the interrupt.
132
133In order not to introduce a new I/O concept to the common Linux code,
134Linux/390 preserves the IRQ concept and semantically maps the ESA/390
135subchannels to Linux as IRQs. This allows Linux/390 to support up to 64k
136different IRQs, uniquely representig a single device each.
137
138Up to kernel 2.4, Linux/390 used to provide interfaces via the IRQ (subchannel).
139For internal use of the common I/O layer, these are still there. However,
140device drivers should use the new calling interface via the ccw_device only.
141
142During its startup the Linux/390 system checks for peripheral devices. Each
143of those devices is uniquely defined by a so called subchannel by the ESA/390
144channel subsystem. While the subchannel numbers are system generated, each
145subchannel also takes a user defined attribute, the so called device number.
146Both subchannel number and device number can not exceed 65535. During driverfs
147initialisation, the information about control unit type and device types that
148imply specific I/O commands (channel command words - CCWs) in order to operate
149the device are gathered. Device drivers can retrieve this set of hardware
150information during their initialization step to recognize the devices they
151support using the information saved in the struct ccw_device given to them.
152This methods implies that Linux/390 doesn't require to probe for free (not
153armed) interrupt request lines (IRQs) to drive its devices with. Where
154applicable, the device drivers can use the read_dev_chars() to retrieve device
155characteristics. This can be done without having to request device ownership
156previously.
157
158In order to allow for easy I/O initiation the CDS layer provides a
159ccw_device_start() interface that takes a device specific channel program (one
160or more CCWs) as input sets up the required architecture specific control blocks
161and initiates an I/O request on behalf of the device driver. The
162ccw_device_start() routine allows to specify whether it expects the CDS layer
163to notify the device driver for every interrupt it observes, or with final status
164only. See ccw_device_start() for more details. A device driver must never issue
165ESA/390 I/O commands itself, but must use the Linux/390 CDS interfaces instead.
166
167For long running I/O request to be canceled, the CDS layer provides the
168ccw_device_halt() function. Some devices require to initially issue a HALT
169SUBCHANNEL (HSCH) command without having pending I/O requests. This function is
170also covered by ccw_device_halt().
171
172
173read_dev_chars() - Read Device Characteristics
174
175This routine returns the characteristics for the device specified.
176
177The function is meant to be called with an irq handler in place; that is,
178at earliest during set_online() processing.
179
180While the request is procesed synchronously, the device interrupt
181handler is called for final ending status. In case of error situations the
182interrupt handler may recover appropriately. The device irq handler can
183recognize the corresponding interrupts by the interruption parameter be
1840x00524443.The ccw_device must not be locked prior to calling read_dev_chars().
185
186The function may be called enabled or disabled.
187
188int read_dev_chars(struct ccw_device *cdev, void **buffer, int length );
189
190cdev - the ccw_device the information is requested for.
191buffer - pointer to a buffer pointer. The buffer pointer itself
192 must contain a valid buffer area.
193length - length of the buffer provided.
194
195The read_dev_chars() function returns :
196
197 0 - successful completion
198-ENODEV - cdev invalid
199-EINVAL - an invalid parameter was detected, or the function was called early.
200-EBUSY - an irrecoverable I/O error occurred or the device is not
201 operational.
202
203
Cornelia Huck9fc14272005-05-01 08:59:00 -0700204read_conf_data(), read_conf_data_lpm() - Read Configuration Data
Linus Torvalds1da177e2005-04-16 15:20:36 -0700205
206Retrieve the device dependent configuration data. Please have a look at your
207device dependent I/O commands for the device specific layout of the node
Cornelia Huck9fc14272005-05-01 08:59:00 -0700208descriptor elements. read_conf_data_lpm() will retrieve the configuration data
209for a specific path.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700210
Cornelia Huck9fc14272005-05-01 08:59:00 -0700211The function is meant to be called with the device already enabled; that is,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700212at earliest during set_online() processing.
213
214The function may be called enabled or disabled, but the device must not be
215locked
216
Cornelia Huck9fc14272005-05-01 08:59:00 -0700217int read_conf_data(struct ccw_device, void **buffer, int *length);
218int read_conf_data_lpm(struct ccw_device, void **buffer, int *length, __u8 lpm);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700219
220cdev - the ccw_device the data is requested for.
221buffer - Pointer to a buffer pointer. The read_conf_data() routine
222 will allocate a buffer and initialize the buffer pointer
223 accordingly. It's the device driver's responsibility to
224 release the kernel memory if no longer needed.
225length - Length of the buffer allocated and retrieved.
226lpm - Logical path mask to be used for retrieving the data. If
227 zero the data is retrieved on the next path available.
228
229The read_conf_data() function returns :
230 0 - Successful completion
231-ENODEV - cdev invalid.
232-EINVAL - An invalid parameter was detected, or the function was called early.
233-EIO - An irrecoverable I/O error occurred or the device is
234 not operational.
235-ENOMEM - The read_conf_data() routine couldn't obtain storage.
236-EOPNOTSUPP - The device doesn't support the read configuration
237 data command.
238
239
240get_ciw() - get command information word
241
242This call enables a device driver to get information about supported commands
243from the extended SenseID data.
244
245struct ciw *
246ccw_device_get_ciw(struct ccw_device *cdev, __u32 cmd);
247
248cdev - The ccw_device for which the command is to be retrieved.
249cmd - The command type to be retrieved.
250
251ccw_device_get_ciw() returns:
252NULL - No extended data available, invalid device or command not found.
253!NULL - The command requested.
254
255
256ccw_device_start() - Initiate I/O Request
257
258The ccw_device_start() routines is the I/O request front-end processor. All
259device driver I/O requests must be issued using this routine. A device driver
260must not issue ESA/390 I/O commands itself. Instead the ccw_device_start()
261routine provides all interfaces required to drive arbitrary devices.
262
263This description also covers the status information passed to the device
264driver's interrupt handler as this is related to the rules (flags) defined
265with the associated I/O request when calling ccw_device_start().
266
267int ccw_device_start(struct ccw_device *cdev,
268 struct ccw1 *cpa,
269 unsigned long intparm,
270 __u8 lpm,
271 unsigned long flags);
Cornelia Huck9fc14272005-05-01 08:59:00 -0700272int ccw_device_start_timeout(struct ccw_device *cdev,
273 struct ccw1 *cpa,
274 unsigned long intparm,
275 __u8 lpm,
276 unsigned long flags,
277 int expires);
278int ccw_device_start_key(struct ccw_device *cdev,
279 struct ccw1 *cpa,
280 unsigned long intparm,
281 __u8 lpm,
282 __u8 key,
283 unsigned long flags);
284int ccw_device_start_key_timeout(struct ccw_device *cdev,
285 struct ccw1 *cpa,
286 unsigned long intparm,
287 __u8 lpm,
288 __u8 key,
289 unsigned long flags,
290 int expires);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700291
292cdev : ccw_device the I/O is destined for
293cpa : logical start address of channel program
294user_intparm : user specific interrupt information; will be presented
295 back to the device driver's interrupt handler. Allows a
296 device driver to associate the interrupt with a
297 particular I/O request.
298lpm : defines the channel path to be used for a specific I/O
299 request. A value of 0 will make cio use the opm.
Cornelia Huck9fc14272005-05-01 08:59:00 -0700300key : the storage key to use for the I/O (useful for operating on a
301 storage with a storage key != default key)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700302flag : defines the action to be performed for I/O processing
Cornelia Huck9fc14272005-05-01 08:59:00 -0700303expires : timeout value in jiffies. The common I/O layer will terminate
304 the running program after this and call the interrupt handler
305 with ERR_PTR(-ETIMEDOUT) as irb.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700306
307Possible flag values are :
308
309DOIO_ALLOW_SUSPEND - channel program may become suspended
310DOIO_DENY_PREFETCH - don't allow for CCW prefetch; usually
311 this implies the channel program might
312 become modified
313DOIO_SUPPRESS_INTER - don't call the handler on intermediate status
314
315The cpa parameter points to the first format 1 CCW of a channel program :
316
317struct ccw1 {
318 __u8 cmd_code;/* command code */
319 __u8 flags; /* flags, like IDA addressing, etc. */
320 __u16 count; /* byte count */
321 __u32 cda; /* data address */
322} __attribute__ ((packed,aligned(8)));
323
324with the following CCW flags values defined :
325
326CCW_FLAG_DC - data chaining
327CCW_FLAG_CC - command chaining
328CCW_FLAG_SLI - suppress incorrct length
329CCW_FLAG_SKIP - skip
330CCW_FLAG_PCI - PCI
331CCW_FLAG_IDA - indirect addressing
332CCW_FLAG_SUSPEND - suspend
333
334
335Via ccw_device_set_options(), the device driver may specify the following
336options for the device:
337
338DOIO_EARLY_NOTIFICATION - allow for early interrupt notification
339DOIO_REPORT_ALL - report all interrupt conditions
340
341
342The ccw_device_start() function returns :
343
344 0 - successful completion or request successfully initiated
345-EBUSY - The device is currently processing a previous I/O request, or ther is
346 a status pending at the device.
347-ENODEV - cdev is invalid, the device is not operational or the ccw_device is
348 not online.
349
350When the I/O request completes, the CDS first level interrupt handler will
351accumalate the status in a struct irb and then call the device interrupt handler.
352The intparm field will contain the value the device driver has associated with a
353particular I/O request. If a pending device status was recognized,
354intparm will be set to 0 (zero). This may happen during I/O initiation or delayed
355by an alert status notification. In any case this status is not related to the
356current (last) I/O request. In case of a delayed status notification no special
357interrupt will be presented to indicate I/O completion as the I/O request was
358never started, even though ccw_device_start() returned with successful completion.
359
Cornelia Huck9fc14272005-05-01 08:59:00 -0700360The irb may contain an error value, and the device driver should check for this
361first:
362
363-ETIMEDOUT: the common I/O layer terminated the request after the specified
364 timeout value
365-EIO: the common I/O layer terminated the request due to an error state
366
Linus Torvalds1da177e2005-04-16 15:20:36 -0700367If the concurrent sense flag in the extended status word in the irb is set, the
368field irb->scsw.count describes the numer of device specific sense bytes
369available in the extended control word irb->scsw.ecw[0]. No device sensing by
370the device driver itself is required.
371
372The device interrupt handler can use the following definitions to investigate
373the primary unit check source coded in sense byte 0 :
374
375SNS0_CMD_REJECT 0x80
376SNS0_INTERVENTION_REQ 0x40
377SNS0_BUS_OUT_CHECK 0x20
378SNS0_EQUIPMENT_CHECK 0x10
379SNS0_DATA_CHECK 0x08
380SNS0_OVERRUN 0x04
381SNS0_INCOMPL_DOMAIN 0x01
382
383Depending on the device status, multiple of those values may be set together.
384Please refer to the device specific documentation for details.
385
386The irb->scsw.cstat field provides the (accumulated) subchannel status :
387
388SCHN_STAT_PCI - program controlled interrupt
389SCHN_STAT_INCORR_LEN - incorrect length
390SCHN_STAT_PROG_CHECK - program check
391SCHN_STAT_PROT_CHECK - protection check
392SCHN_STAT_CHN_DATA_CHK - channel data check
393SCHN_STAT_CHN_CTRL_CHK - channel control check
394SCHN_STAT_INTF_CTRL_CHK - interface control check
395SCHN_STAT_CHAIN_CHECK - chaining check
396
397The irb->scsw.dstat field provides the (accumulated) device status :
398
399DEV_STAT_ATTENTION - attention
400DEV_STAT_STAT_MOD - status modifier
401DEV_STAT_CU_END - control unit end
402DEV_STAT_BUSY - busy
403DEV_STAT_CHN_END - channel end
404DEV_STAT_DEV_END - device end
405DEV_STAT_UNIT_CHECK - unit check
406DEV_STAT_UNIT_EXCEP - unit exception
407
408Please see the ESA/390 Principles of Operation manual for details on the
409individual flag meanings.
410
411Usage Notes :
412
413Prior to call ccw_device_start() the device driver must assure disabled state,
414i.e. the I/O mask value in the PSW must be disabled. This can be accomplished
415by calling local_save_flags( flags). The current PSW flags are preserved and
416can be restored by local_irq_restore( flags) at a later time.
417
418If the device driver violates this rule while running in a uni-processor
419environment an interrupt might be presented prior to the ccw_device_start()
420routine returning to the device driver main path. In this case we will end in a
421deadlock situation as the interrupt handler will try to obtain the irq
422lock the device driver still owns (see below) !
423
424The driver must assure to hold the device specific lock. This can be
425accomplished by
426
427(i) spin_lock(get_ccwdev_lock(cdev)), or
428(ii) spin_lock_irqsave(get_ccwdev_lock(cdev), flags)
429
430Option (i) should be used if the calling routine is running disabled for
431I/O interrupts (see above) already. Option (ii) obtains the device gate und
432puts the CPU into I/O disabled state by preserving the current PSW flags.
433
434The device driver is allowed to issue the next ccw_device_start() call from
435within its interrupt handler already. It is not required to schedule a
436bottom-half, unless an non deterministicly long running error recovery procedure
437or similar needs to be scheduled. During I/O processing the Linux/390 generic
438I/O device driver support has already obtained the IRQ lock, i.e. the handler
439must not try to obtain it again when calling ccw_device_start() or we end in a
440deadlock situation!
441
442If a device driver relies on an I/O request to be completed prior to start the
443next it can reduce I/O processing overhead by chaining a NoOp I/O command
444CCW_CMD_NOOP to the end of the submitted CCW chain. This will force Channel-End
445and Device-End status to be presented together, with a single interrupt.
446However, this should be used with care as it implies the channel will remain
447busy, not being able to process I/O requests for other devices on the same
448channel. Therefore e.g. read commands should never use this technique, as the
449result will be presented by a single interrupt anyway.
450
451In order to minimize I/O overhead, a device driver should use the
452DOIO_REPORT_ALL only if the device can report intermediate interrupt
453information prior to device-end the device driver urgently relies on. In this
454case all I/O interruptions are presented to the device driver until final
455status is recognized.
456
457If a device is able to recover from asynchronosly presented I/O errors, it can
458perform overlapping I/O using the DOIO_EARLY_NOTIFICATION flag. While some
459devices always report channel-end and device-end together, with a single
460interrupt, others present primary status (channel-end) when the channel is
461ready for the next I/O request and secondary status (device-end) when the data
462transmission has been completed at the device.
463
464Above flag allows to exploit this feature, e.g. for communication devices that
465can handle lost data on the network to allow for enhanced I/O processing.
466
467Unless the channel subsystem at any time presents a secondary status interrupt,
468exploiting this feature will cause only primary status interrupts to be
469presented to the device driver while overlapping I/O is performed. When a
470secondary status without error (alert status) is presented, this indicates
471successful completion for all overlapping ccw_device_start() requests that have
472been issued since the last secondary (final) status.
473
474Channel programs that intend to set the suspend flag on a channel command word
475(CCW) must start the I/O operation with the DOIO_ALLOW_SUSPEND option or the
476suspend flag will cause a channel program check. At the time the channel program
477becomes suspended an intermediate interrupt will be generated by the channel
478subsystem.
479
480ccw_device_resume() - Resume Channel Program Execution
481
482If a device driver chooses to suspend the current channel program execution by
483setting the CCW suspend flag on a particular CCW, the channel program execution
484is suspended. In order to resume channel program execution the CIO layer
485provides the ccw_device_resume() routine.
486
487int ccw_device_resume(struct ccw_device *cdev);
488
489cdev - ccw_device the resume operation is requested for
490
491The resume_IO() function returns:
492
493 0 - suspended channel program is resumed
494-EBUSY - status pending
495-ENODEV - cdev invalid or not-operational subchannel
496-EINVAL - resume function not applicable
497-ENOTCONN - there is no I/O request pending for completion
498
499Usage Notes:
500Please have a look at the ccw_device_start() usage notes for more details on
501suspended channel programs.
502
503ccw_device_halt() - Halt I/O Request Processing
504
505Sometimes a device driver might need a possibility to stop the processing of
506a long-running channel program or the device might require to initially issue
507a halt subchannel (HSCH) I/O command. For those purposes the ccw_device_halt()
508command is provided.
509
510int ccw_device_halt(struct ccw_device *cdev,
511 unsigned long intparm);
512
513cdev : ccw_device the halt operation is requested for
514intparm : interruption parameter; value is only used if no I/O
515 is outstanding, otherwise the intparm associated with
516 the I/O request is returned
517
518The ccw_device_halt() function returns :
519
520 0 - successful completion or request successfully initiated
521-EBUSY - the device is currently busy, or status pending.
522-ENODEV - cdev invalid.
523-EINVAL - The device is not operational or the ccw device is not online.
524
525Usage Notes :
526
527A device driver may write a never-ending channel program by writing a channel
528program that at its end loops back to its beginning by means of a transfer in
529channel (TIC) command (CCW_CMD_TIC). Usually this is performed by network
530device drivers by setting the PCI CCW flag (CCW_FLAG_PCI). Once this CCW is
531executed a program controlled interrupt (PCI) is generated. The device driver
532can then perform an appropriate action. Prior to interrupt of an outstanding
533read to a network device (with or without PCI flag) a ccw_device_halt()
534is required to end the pending operation.
535
536
537Miscellaneous Support Routines
538
539This chapter describes various routines to be used in a Linux/390 device
540driver programming environment.
541
542get_ccwdev_lock()
543
544Get the address of the device specific lock. This is then used in
545spin_lock() / spin_unlock() calls.
546
547
548__u8 ccw_device_get_path_mask(struct ccw_device *cdev);
549
550Get the mask of the path currently available for cdev.