arch/s390/cds.rst

6 Device Driver I/O Support Routines
19 I/O access method. This gives relief to the device drivers as they don't
22 I/O (PIO), and other hardware features more. However, this implies that
23 either every single device driver needs to implement the hardware I/O
32 In order to build common device support for ESA/390 I/O interfaces, a
33 functional layer was introduced that provides generic I/O access methods to
36 The common device support layer comprises the I/O support routines defined
67    initiate an I/O request.
73    terminate the current I/O request processed on the device.
77    routine whenever an I/O interrupt is presented to the system. The do_IRQ()
79    interrupt handler according to the rules (flags) defined during I/O request
98 The following chapters describe the I/O related interface routines the
120 they are presenting I/O completion a unified way : I/O interruptions. Every
136 For internal use of the common I/O layer, these are still there. However,
145 imply specific I/O commands (channel command words - CCWs) in order to operate
154 In order to allow for easy I/O initiation the CDS layer provides a
157 and initiates an I/O request on behalf of the device driver. The
161 ESA/390 I/O commands itself, but must use the Linux/390 CDS interfaces instead.
163 For long running I/O request to be canceled, the CDS layer provides the
165 SUBCHANNEL (HSCH) command without having pending I/O requests. This function is
193   ccw_device_start() - Initiate I/O Request
195 The ccw_device_start() routines is the I/O request front-end processor. All
196 device driver I/O requests must be issued using this routine. A device driver
197 must not issue ESA/390 I/O commands itself. Instead the ccw_device_start()
202 with the associated I/O request when calling ccw_device_start().
232 cdev          ccw_device the I/O is destined for
237 	      particular I/O request.
238 lpm           defines the channel path to be used for a specific I/O
240 key           the storage key to use for the I/O (useful for operating on a
242 flag          defines the action to be performed for I/O processing
243 expires       timeout value in jiffies. The common I/O layer will terminate
293  -EBUSY  The device is currently processing a previous I/O request, or there is
299 When the I/O request completes, the CDS first level interrupt handler will
302 particular I/O request. If a pending device status was recognized,
303 intparm will be set to 0 (zero). This may happen during I/O initiation or delayed
305 current (last) I/O request. In case of a delayed status notification no special
306 interrupt will be presented to indicate I/O completion as the I/O request was
313 -ETIMEDOUT the common I/O layer terminated the request after the specified
315 -EIO       the common I/O layer terminated the request due to an error state
375 or similar needs to be scheduled. During I/O processing the Linux/390 generic
376 I/O device driver support has already obtained the IRQ lock, i.e. the handler
380 If a device driver relies on an I/O request to be completed prior to start the
381 next it can reduce I/O processing overhead by chaining a NoOp I/O command
385 busy, not being able to process I/O requests for other devices on the same
389 In order to minimize I/O overhead, a device driver should use the
392 case all I/O interruptions are presented to the device driver until final
395 If a device is able to recover from asynchronously presented I/O errors, it can
396 perform overlapping I/O using the DOIO_EARLY_NOTIFICATION flag. While some
399 ready for the next I/O request and secondary status (device-end) when the data
403 can handle lost data on the network to allow for enhanced I/O processing.
407 presented to the device driver while overlapping I/O is performed. When a
413 (CCW)  must start the I/O operation with the DOIO_ALLOW_SUSPEND option or the
440 -ENOTCONN   there is no I/O request pending for completion
448 ccw_device_halt() - Halt I/O Request Processing
452 a halt subchannel (HSCH) I/O command. For those purposes the ccw_device_halt()
464 intparm  interruption parameter; value is only used if no I/O
466 	 the I/O request is returned
491   ccw_device_clear() - Terminage I/O Request Processing
493 In order to terminate all I/O processing at the subchannel, the clear subchannel