diff options
Diffstat (limited to 'Documentation/s390/cds.txt')
| -rw-r--r-- | Documentation/s390/cds.txt | 64 |
1 files changed, 30 insertions, 34 deletions
diff --git a/Documentation/s390/cds.txt b/Documentation/s390/cds.txt index d80e5733827..05a2b4f7e38 100644 --- a/Documentation/s390/cds.txt +++ b/Documentation/s390/cds.txt @@ -98,7 +98,7 @@ The following chapters describe the I/O related interface routines the Linux/390 common device support (CDS) provides to allow for device specific driver implementations on the IBM ESA/390 hardware platform. Those interfaces intend to provide the functionality required by every device driver -implementaion to allow to drive a specific hardware device on the ESA/390 +implementation to allow to drive a specific hardware device on the ESA/390 platform. Some of the interface routines are specific to Linux/390 and some of them can be found on other Linux platforms implementations too. Miscellaneous function prototypes, data declarations, and macro definitions @@ -114,7 +114,7 @@ the ESA/390 architecture has implemented a so called channel subsystem, that provides a unified view of the devices physically attached to the systems. Though the ESA/390 hardware platform knows about a huge variety of different peripheral attachments like disk devices (aka. DASDs), tapes, communication -controllers, etc. they can all by accessed by a well defined access method and +controllers, etc. they can all be accessed by a well defined access method and they are presenting I/O completion a unified way : I/O interruptions. Every single device is uniquely identified to the system by a so called subchannel, where the ESA/390 architecture allows for 64k devices be attached. @@ -174,14 +174,10 @@ read_dev_chars() - Read Device Characteristics 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. @@ -342,7 +338,7 @@ DOIO_REPORT_ALL - report all interrupt conditions The ccw_device_start() function returns : 0 - successful completion or request successfully initiated --EBUSY - The device is currently processing a previous I/O request, or ther is +-EBUSY - The device is currently processing a previous I/O request, or there is a status pending at the device. -ENODEV - cdev is invalid, the device is not operational or the ccw_device is not online. @@ -365,7 +361,7 @@ first: -EIO: the common I/O layer terminated the request due to an error state If the concurrent sense flag in the extended status word in the irb is set, the -field irb->scsw.count describes the numer of device specific sense bytes +field irb->scsw.count describes the number of device specific sense bytes available in the extended control word irb->scsw.ecw[0]. No device sensing by the device driver itself is required. @@ -410,30 +406,11 @@ individual flag meanings. 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 -bottom-half, unless an non deterministically long running error recovery procedure +bottom-half, unless a non deterministically long running error recovery procedure or similar needs to be scheduled. During I/O processing the Linux/390 generic I/O device driver support has already obtained the IRQ lock, i.e. the handler must not try to obtain it again when calling ccw_device_start() or we end in a @@ -454,7 +431,7 @@ information prior to device-end the device driver urgently relies on. In this case all I/O interruptions are presented to the device driver until final status is recognized. -If a device is able to recover from asynchronosly presented I/O errors, it can +If a device is able to recover from asynchronously presented I/O errors, it can perform overlapping I/O using the DOIO_EARLY_NOTIFICATION flag. While some devices always report channel-end and device-end together, with a single interrupt, others present primary status (channel-end) when the channel is @@ -488,7 +465,7 @@ int ccw_device_resume(struct ccw_device *cdev); 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 long-running channel program or the device might require to initially issue 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 @@ intparm : interruption parameter; value is only used if no I/O 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 @@ can then perform an appropriate action. Prior to interrupt of an outstanding 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 |