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