Lines Matching +full:device +full:- +full:specific
5 Common Device Support (CDS)
6 Device Driver I/O Support Routines
9 - Ingo Adlung
10 - Cornelia Huck
12 Copyright, IBM Corp. 1999-2002
17 This document describes the common device support routines for Linux/390.
19 I/O access method. This gives relief to the device drivers as they don't
21 processing, shared versus non-shared interrupt processing, DMA versus port
23 either every single device driver needs to implement the hardware I/O
26 every single device driver would have to provide itself.
30 Operation manual (IBM Form. No. SA22-7201).
32 In order to build common device support for ESA/390 I/O interfaces, a
36 The common device support layer comprises the I/O support routines defined
37 below. Some of them implement common Linux device driver interfaces, while
38 some of them are ESA/390 platform specific.
42 described in Documentation/arch/s390/driver-model.rst.
49 * All drivers must define a ccw_driver (see driver-model.txt) and the associated
56 * The channel device layer is gone.
73 terminate the current I/O request processed on the device.
78 routine determines the interrupt status and calls the device specific
84 first level interrupt handler only and does not comprise a device driver
86 describes the input to the device specific interrupt handler.
92 Common Device Support (CDS) for Linux/390 Device Drivers
96 -------------------
99 Linux/390 common device support (CDS) provides to allow for device specific
101 intend to provide the functionality required by every device driver
102 implementation to allow to drive a specific hardware device on the ESA/390
103 platform. Some of the interface routines are specific to Linux/390 and some
106 can be found in the architecture specific C header file
110 ----------------------------------
113 interrupt lines managed by a specific interrupt controller and bus systems
121 single device is uniquely identified to the system by a so called subchannel,
132 has to call every single device driver registered on this IRQ in order to
133 determine the device driver owning the device that raised the interrupt.
137 device drivers should use the new calling interface via the ccw_device only.
142 subchannel also takes a user defined attribute, the so called device number.
143 Both subchannel number and device number cannot exceed 65535. During sysfs
144 initialisation, the information about control unit type and device types that
145 imply specific I/O commands (channel command words - CCWs) in order to operate
146 the device are gathered. Device drivers can retrieve this set of hardware
151 applicable, the device drivers can use issue the READ DEVICE CHARACTERISTICS
152 ccw to retrieve device characteristics in its online routine.
155 ccw_device_start() interface that takes a device specific channel program (one
156 or more CCWs) as input sets up the required architecture specific control blocks
157 and initiates an I/O request on behalf of the device driver. The
159 to notify the device driver for every interrupt it observes, or with final status
160 only. See ccw_device_start() for more details. A device driver must never issue
169 get_ciw() - get command information word
171 This call enables a device driver to get information about supported commands
187 NULL No extended data available, invalid device or command not found.
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
200 This description also covers the status information passed to the device
234 user_intparm user specific interrupt information; will be presented
235 back to the device driver's interrupt handler. Allows a
236 device driver to associate the interrupt with a
238 lpm defines the channel path to be used for a specific I/O
245 with ERR_PTR(-ETIMEDOUT) as irb.
280 Via ccw_device_set_options(), the device driver may specify the following
281 options for the device:
293 -EBUSY The device is currently processing a previous I/O request, or there is
294 a status pending at the device.
295 -ENODEV cdev is invalid, the device is not operational or the ccw_device is
300 accumulate the status in a struct irb and then call the device interrupt handler.
301 The intparm field will contain the value the device driver has associated with a
302 particular I/O request. If a pending device status was recognized,
309 The irb may contain an error value, and the device driver should check for this
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
319 set, the field erw.scnt in the esw describes the number of device specific
320 sense bytes available in the extended control word irb->scsw.ecw[]. No device
321 sensing by the device driver itself is required.
323 The device interrupt handler can use the following definitions to investigate
336 Depending on the device status, multiple of those values may be set together.
337 Please refer to the device specific documentation for details.
339 The irb->scsw.cstat field provides the (accumulated) subchannel status :
352 The irb->scsw.dstat field provides the (accumulated) device status :
360 DEV_STAT_DEV_END device end
370 ccw_device_start() must be called disabled and with the ccw device lock held.
372 The device driver is allowed to issue the next ccw_device_start() call from
374 bottom-half, unless a non deterministically long running error recovery procedure
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
382 CCW_CMD_NOOP to the end of the submitted CCW chain. This will force Channel-End
383 and Device-End status to be presented together, with a single interrupt.
389 In order to minimize I/O overhead, a device driver should use the
390 DOIO_REPORT_ALL only if the device can report intermediate interrupt
391 information prior to device-end the device driver urgently relies on. In this
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
397 devices always report channel-end and device-end together, with a single
398 interrupt, others present primary status (channel-end) when the channel is
399 ready for the next I/O request and secondary status (device-end) when the data
400 transmission has been completed at the device.
407 presented to the device driver while overlapping I/O is performed. When a
418 ccw_device_resume() - Resume Channel Program Execution
420 If a device driver chooses to suspend the current channel program execution by
437 -EBUSY status pending
438 -ENODEV cdev invalid or not-operational subchannel
439 -EINVAL resume function not applicable
440 -ENOTCONN there is no I/O request pending for completion
448 ccw_device_halt() - Halt I/O Request Processing
450 Sometimes a device driver might need a possibility to stop the processing of
451 a long-running channel program or the device might require to initially issue
455 ccw_device_halt() must be called disabled and with the ccw device lock held.
473 -EBUSY the device is currently busy, or status pending.
474 -ENODEV cdev invalid.
475 -EINVAL The device is not operational or the ccw device is not online.
480 A device driver may write a never-ending channel program by writing a channel
483 device drivers by setting the PCI CCW flag (CCW_FLAG_PCI). Once this CCW is
484 executed a program controlled interrupt (PCI) is generated. The device driver
486 read to a network device (with or without PCI flag) a ccw_device_halt()
491 ccw_device_clear() - Terminage I/O Request Processing
496 ccw_device_clear() must be called disabled and with the ccw device lock held.
511 -ENODEV cdev invalid
512 -EINVAL The device is not operational or the ccw device is not online.
516 ------------------------------
518 This chapter describes various routines to be used in a Linux/390 device
523 Get the address of the device specific lock. This is then used in