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