[S390] cio: update documentation.

  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

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.

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.

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.

ccw_device_start() must be called disabled and with the ccw device lock held.

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

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

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);

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.

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

type - The physical type of the channel path.

shared - Whether the channel path is shared.

cmg - The channel measurement group.

3. System devices

-----------------