[S390] cio: update documentation.

Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com> Signed-off-by: Martin Schwidefsky <schwidefsky@de.ibm.com>

[S390] cio: update documentation.
Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com> Signed-off-by: Martin Schwidefsky <schwidefsky@de.ibm.com>
Cornelia Huck · Martin Schwidefsky
1 parent 867dcd0f32
Showing 3 changed files with 28 additions and 29 deletions Side-by-side Diff
Documentation/s390/CommonIO
Documentation/s390/cds.txt
Documentation/s390/driver-model.txt
@@ -66,7 +66,7 @@
  
   When a device is un-ignored, device recognition and sensing is performed and 
   the device driver will be notified if possible, so the device will become
-  available to the system.
+  available to the system. Note that un-ignoring is performed asynchronously.
  
   You can also add ranges of devices to be ignored by piping to 
   /proc/cio_ignore; "add <device range>, <device range>, ..." will ignore the
@@ -174,14 +174,10 @@
  
 This routine returns the characteristics for the device specified.
  
-The function is meant to be called with an irq handler in place; that is,
+The function is meant to be called with the device already enabled; that is,
 at earliest during set_online() processing.
  
-While the request is processed synchronously, the device interrupt
-handler is called for final ending status. In case of error situations the
-interrupt handler may recover appropriately. The device irq handler can
-recognize the corresponding interrupts by the interruption parameter be
-0x00524443. The ccw_device must not be locked prior to calling read_dev_chars().
+The ccw_device must not be locked prior to calling read_dev_chars().
  
 The function may be called enabled or disabled.
  
  
@@ -410,27 +406,8 @@
  
 Usage Notes :
  
-Prior to call ccw_device_start() the device driver must assure disabled state,
-i.e. the I/O mask value in the PSW must be disabled. This can be accomplished
-by calling local_save_flags( flags). The current PSW flags are preserved and
-can be restored by local_irq_restore( flags) at a later time.
+ccw_device_start() must be called disabled and with the ccw device lock held.
  
-If the device driver violates this rule while running in a uni-processor
-environment an interrupt might be presented prior to the ccw_device_start()
-routine returning to the device driver main path. In this case we will end in a
-deadlock situation as the interrupt handler will try to obtain the irq
-lock the device driver still owns (see below) !
-
-The driver must assure to hold the device specific lock. This can be
-accomplished by
-
-(i)  spin_lock(get_ccwdev_lock(cdev)), or
-(ii) spin_lock_irqsave(get_ccwdev_lock(cdev), flags)
-
-Option (i) should be used if the calling routine is running disabled for
-I/O interrupts (see above) already. Option (ii) obtains the device gate und
-puts the CPU into I/O disabled state by preserving the current PSW flags.
-
 The device driver is allowed to issue the next ccw_device_start() call from
 within its interrupt handler already. It is not required to schedule a
 bottom-half, unless an non deterministically long running error recovery procedure
@@ -488,7 +465,7 @@
  
 cdev - ccw_device the resume operation is requested for
  
-The resume_IO() function returns:
+The ccw_device_resume() function returns:
  
         0  - suspended channel program is resumed
 -EBUSY     - status pending
@@ -507,6 +484,8 @@
 a halt subchannel (HSCH) I/O command. For those purposes the ccw_device_halt()
 command is provided.
  
+ccw_device_halt() must be called disabled and with the ccw device lock held.
+
 int ccw_device_halt(struct ccw_device *cdev,
                     unsigned long intparm);
  
@@ -517,7 +496,7 @@
  
 The ccw_device_halt() function returns :
  
-      0 - successful completion or request successfully initiated
+      0 - request successfully initiated
 -EBUSY  - the device is currently busy, or status pending.
 -ENODEV - cdev invalid.
 -EINVAL - The device is not operational or the ccw device is not online.
@@ -533,6 +512,23 @@
 read to a network device (with or without PCI flag) a ccw_device_halt()
 is required to end the pending operation.
  
+ccw_device_clear() - Terminage I/O Request Processing
+
+In order to terminate all I/O processing at the subchannel, the clear subchannel
+(CSCH) command is used. It can be issued via ccw_device_clear().
+
+ccw_device_clear() must be called disabled and with the ccw device lock held.
+
+int ccw_device_clear(struct ccw_device *cdev, unsigned long intparm);
+
+cdev:	 ccw_device the clear operation is requested for
+intparm: interruption parameter (see ccw_device_halt())
+
+The ccw_device_clear() function returns:
+
+      0 - request successfully initiated
+-ENODEV - cdev invalid
+-EINVAL - The device is not operational or the ccw device is not online.
  
 Miscellaneous Support Routines
  
@@ -239,6 +239,9 @@
  
 type - The physical type of the channel path.
  
+shared - Whether the channel path is shared.
+
+cmg - The channel measurement group.
  
 3. System devices
 -----------------
...	...	@@ -66,7 +66,7 @@
66	66
67	67	When a device is un-ignored, device recognition and sensing is performed and
68	68	the device driver will be notified if possible, so the device will become
69		- available to the system.
	69	+ available to the system. Note that un-ignoring is performed asynchronously.
70	70
71	71	You can also add ranges of devices to be ignored by piping to
72	72	/proc/cio_ignore; "add <device range>, <device range>, ..." will ignore the
...	...	@@ -174,14 +174,10 @@
174	174
175	175	This routine returns the characteristics for the device specified.
176	176
177		-The function is meant to be called with an irq handler in place; that is,
	177	+The function is meant to be called with the device already enabled; that is,
178	178	at earliest during set_online() processing.
179	179
180		-While the request is processed synchronously, the device interrupt
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
184		-0x00524443. The ccw_device must not be locked prior to calling read_dev_chars().
	180	+The ccw_device must not be locked prior to calling read_dev_chars().
185	181
186	182	The function may be called enabled or disabled.
187	183
188	184
...	...	@@ -410,27 +406,8 @@
410	406
411	407	Usage Notes :
412	408
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.
	409	+ccw_device_start() must be called disabled and with the ccw device lock held.
417	410
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	411	The device driver is allowed to issue the next ccw_device_start() call from
435	412	within its interrupt handler already. It is not required to schedule a
436	413	bottom-half, unless an non deterministically long running error recovery procedure
...	...	@@ -488,7 +465,7 @@
488	465
489	466	cdev - ccw_device the resume operation is requested for
490	467
491		-The resume_IO() function returns:
	468	+The ccw_device_resume() function returns:
492	469
493	470	0 - suspended channel program is resumed
494	471	-EBUSY - status pending
...	...	@@ -507,6 +484,8 @@
507	484	a halt subchannel (HSCH) I/O command. For those purposes the ccw_device_halt()
508	485	command is provided.
509	486
	487	+ccw_device_halt() must be called disabled and with the ccw device lock held.
	488	+
510	489	int ccw_device_halt(struct ccw_device *cdev,
511	490	unsigned long intparm);
512	491
...	...	@@ -517,7 +496,7 @@
517	496
518	497	The ccw_device_halt() function returns :
519	498
520		- 0 - successful completion or request successfully initiated
	499	+ 0 - request successfully initiated
521	500	-EBUSY - the device is currently busy, or status pending.
522	501	-ENODEV - cdev invalid.
523	502	-EINVAL - The device is not operational or the ccw device is not online.
...	...	@@ -533,6 +512,23 @@
533	512	read to a network device (with or without PCI flag) a ccw_device_halt()
534	513	is required to end the pending operation.
535	514
	515	+ccw_device_clear() - Terminage I/O Request Processing
	516	+
	517	+In order to terminate all I/O processing at the subchannel, the clear subchannel
	518	+(CSCH) command is used. It can be issued via ccw_device_clear().
	519	+
	520	+ccw_device_clear() must be called disabled and with the ccw device lock held.
	521	+
	522	+int ccw_device_clear(struct ccw_device *cdev, unsigned long intparm);
	523	+
	524	+cdev: ccw_device the clear operation is requested for
	525	+intparm: interruption parameter (see ccw_device_halt())
	526	+
	527	+The ccw_device_clear() function returns:
	528	+
	529	+ 0 - request successfully initiated
	530	+-ENODEV - cdev invalid
	531	+-EINVAL - The device is not operational or the ccw device is not online.
536	532
537	533	Miscellaneous Support Routines
538	534
...	...	@@ -239,6 +239,9 @@
239	239
240	240	type - The physical type of the channel path.
241	241
	242	+shared - Whether the channel path is shared.
	243	+
	244	+cmg - The channel measurement group.
242	245
243	246	3. System devices
244	247	-----------------