Lines Matching refs:the
13 This document describes the common device support routines for Linux/390.
15 I/O access method. This gives relief to the device drivers as they don't
19 either every single device driver needs to implement the hardware I/O
20 attachment functionality itself, or the operating system provides for a
21 unified method to access the hardware, providing all the functionality that
24 The document does not intend to explain the ESA/390 hardware architecture in
25 every detail.This information can be obtained from the ESA/390 Principles of
30 the hardware.
32 The common device support layer comprises the I/O support routines defined
37 In order to write a driver for S/390, you also need to look into the interface
43 * All drivers must define a ccw_driver (see driver-model.txt) and the associated
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.
53 * Before initiating an io, the options must be set via ccw_device_set_options().
54 * Instead of calling read_dev_chars()/read_conf_data(), the driver issues
55 the channel program and handles the interrupt itself.
70 terminate the current I/O request processed on the device.
73 generic interrupt routine. This function is called by the interrupt entry
74 routine whenever an I/O interrupt is presented to the system. The do_IRQ()
75 routine determines the interrupt status and calls the device specific
76 interrupt handler according to the rules (flags) defined during I/O request
79 The next chapters describe the functions other than do_IRQ() in more details.
80 The do_IRQ() interface is not described, as it is called from the Linux/390
82 callable interface. Instead, the functional description of do_IO() also
83 describes the input to the device specific interrupt handler.
85 Note: All explanations apply also to the 64 bit architecture s390x.
92 The following chapters describe the I/O related interface routines the
94 driver implementations on the IBM ESA/390 hardware platform. Those interfaces
95 intend to provide the functionality required by every device driver
96 implementation to allow to drive a specific hardware device on the ESA/390
97 platform. Some of the interface routines are specific to Linux/390 and some
100 can be found in the architecture specific C header file
105 Different to other hardware platforms, the ESA/390 architecture doesn't define
108 the ESA/390 architecture has implemented a so called channel subsystem, that
109 provides a unified view of the devices physically attached to the systems.
110 Though the ESA/390 hardware platform knows about a huge variety of different
114 single device is uniquely identified to the system by a so called subchannel,
115 where the ESA/390 architecture allows for 64k devices be attached.
117 Linux, however, was first built on the Intel PC architecture, with its two
120 share those 15 interrupt levels. Devices attached to the ISA bus system must
121 not share interrupt levels (aka. IRQs), as the ISA bus bases on edge triggered
124 present their hardware status by the same (shared) IRQ, the operating system
126 determine the device driver owning the device that raised the interrupt.
128 Up to kernel 2.4, Linux/390 used to provide interfaces via the IRQ (subchannel).
129 For internal use of the common I/O layer, these are still there. However,
130 device drivers should use the new calling interface via the ccw_device only.
132 During its startup the Linux/390 system checks for peripheral devices. Each
133 of those devices is uniquely defined by a so called subchannel by the ESA/390
134 channel subsystem. While the subchannel numbers are system generated, each
135 subchannel also takes a user defined attribute, the so called device number.
137 initialisation, the information about control unit type and device types that
139 the device are gathered. Device drivers can retrieve this set of hardware
140 information during their initialization step to recognize the devices they
141 support using the information saved in the struct ccw_device given to them.
144 applicable, the device drivers can use issue the READ DEVICE CHARACTERISTICS
147 In order to allow for easy I/O initiation the CDS layer provides a
149 or more CCWs) as input sets up the required architecture specific control blocks
150 and initiates an I/O request on behalf of the device driver. The
151 ccw_device_start() routine allows to specify whether it expects the CDS layer
152 to notify the device driver for every interrupt it observes, or with final status
154 ESA/390 I/O commands itself, but must use the Linux/390 CDS interfaces instead.
156 For long running I/O request to be canceled, the CDS layer provides the
165 from the extended SenseID data.
170 cdev - The ccw_device for which the command is to be retrieved.
180 The ccw_device_start() routines is the I/O request front-end processor. All
182 must not issue ESA/390 I/O commands itself. Instead the ccw_device_start()
185 This description also covers the status information passed to the device
186 driver's interrupt handler as this is related to the rules (flags) defined
187 with the associated I/O request when calling ccw_device_start().
214 cdev : ccw_device the I/O is destined for
217 back to the device driver's interrupt handler. Allows a
218 device driver to associate the interrupt with a
220 lpm : defines the channel path to be used for a specific I/O
221 request. A value of 0 will make cio use the opm.
222 key : the storage key to use for the I/O (useful for operating on a
224 flag : defines the action to be performed for I/O processing
226 the running program after this and call the interrupt handler
233 this implies the channel program might
235 DOIO_SUPPRESS_INTER - don't call the handler on intermediate status
237 The cpa parameter points to the first format 1 CCW of a channel program :
246 with the following CCW flags values defined :
257 Via ccw_device_set_options(), the device driver may specify the following
258 options for the device:
268 a status pending at the device.
269 -ENODEV - cdev is invalid, the device is not operational or the ccw_device is
272 When the I/O request completes, the CDS first level interrupt handler will
273 accumulate the status in a struct irb and then call the device interrupt handler.
274 The intparm field will contain the value the device driver has associated with a
277 by an alert status notification. In any case this status is not related to the
279 interrupt will be presented to indicate I/O completion as the I/O request was
282 The irb may contain an error value, and the device driver should check for this
285 -ETIMEDOUT: the common I/O layer terminated the request after the specified
287 -EIO: the common I/O layer terminated the request due to an error state
289 If the concurrent sense flag in the extended status word (esw) in the irb is
290 set, the field erw.scnt in the esw describes the number of device specific
291 sense bytes available in the extended control word irb->scsw.ecw[]. No device
292 sensing by the device driver itself is required.
294 The device interrupt handler can use the following definitions to investigate
295 the primary unit check source coded in sense byte 0 :
305 Depending on the device status, multiple of those values may be set together.
306 Please refer to the device specific documentation for details.
308 The irb->scsw.cstat field provides the (accumulated) subchannel status :
319 The irb->scsw.dstat field provides the (accumulated) device status :
330 Please see the ESA/390 Principles of Operation manual for details on the
335 ccw_device_start() must be called disabled and with the ccw device lock held.
337 The device driver is allowed to issue the next ccw_device_start() call from
340 or similar needs to be scheduled. During I/O processing the Linux/390 generic
341 I/O device driver support has already obtained the IRQ lock, i.e. the handler
345 If a device driver relies on an I/O request to be completed prior to start the
347 CCW_CMD_NOOP to the end of the submitted CCW chain. This will force Channel-End
349 However, this should be used with care as it implies the channel will remain
350 busy, not being able to process I/O requests for other devices on the same
351 channel. Therefore e.g. read commands should never use this technique, as the
354 In order to minimize I/O overhead, a device driver should use the
355 DOIO_REPORT_ALL only if the device can report intermediate interrupt
356 information prior to device-end the device driver urgently relies on. In this
357 case all I/O interruptions are presented to the device driver until final
361 perform overlapping I/O using the DOIO_EARLY_NOTIFICATION flag. While some
363 interrupt, others present primary status (channel-end) when the channel is
364 ready for the next I/O request and secondary status (device-end) when the data
365 transmission has been completed at the device.
368 can handle lost data on the network to allow for enhanced I/O processing.
370 Unless the channel subsystem at any time presents a secondary status interrupt,
372 presented to the device driver while overlapping I/O is performed. When a
375 been issued since the last secondary (final) status.
377 Channel programs that intend to set the suspend flag on a channel command word
378 (CCW) must start the I/O operation with the DOIO_ALLOW_SUSPEND option or the
379 suspend flag will cause a channel program check. At the time the channel program
380 becomes suspended an intermediate interrupt will be generated by the channel
385 If a device driver chooses to suspend the current channel program execution by
386 setting the CCW suspend flag on a particular CCW, the channel program execution
387 is suspended. In order to resume channel program execution the CIO layer
388 provides the ccw_device_resume() routine.
392 cdev - ccw_device the resume operation is requested for
403 Please have a look at the ccw_device_start() usage notes for more details on
408 Sometimes a device driver might need a possibility to stop the processing of
409 a long-running channel program or the device might require to initially issue
410 a halt subchannel (HSCH) I/O command. For those purposes the ccw_device_halt()
413 ccw_device_halt() must be called disabled and with the ccw device lock held.
418 cdev : ccw_device the halt operation is requested for
420 is outstanding, otherwise the intparm associated with
421 the I/O request is returned
426 -EBUSY - the device is currently busy, or status pending.
428 -EINVAL - The device is not operational or the ccw device is not online.
435 device drivers by setting the PCI CCW flag (CCW_FLAG_PCI). Once this CCW is
439 is required to end the pending operation.
443 In order to terminate all I/O processing at the subchannel, the clear subchannel
446 ccw_device_clear() must be called disabled and with the ccw device lock held.
450 cdev: ccw_device the clear operation is requested for
457 -EINVAL - The device is not operational or the ccw device is not online.
466 Get the address of the device specific lock. This is then used in
472 Get the mask of the path currently available for cdev.