X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=Documentation%2Fs390%2Fcds.txt;h=05a2b4f7e38f7ea17256d3f59461e68a04c485f7;hb=97bf2856c6014879bd04983a3e9dfcdac1e7fe85;hp=f0be389c7116934b6c1e43b97d70dab486aedf2a;hpb=76828883507a47dae78837ab5dec5a5b4513c667;p=linux-2.6.git diff --git a/Documentation/s390/cds.txt b/Documentation/s390/cds.txt index f0be389c7..05a2b4f7e 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. @@ -133,7 +133,7 @@ determine the device driver owning the device that raised the interrupt. In order not to introduce a new I/O concept to the common Linux code, Linux/390 preserves the IRQ concept and semantically maps the ESA/390 subchannels to Linux as IRQs. This allows Linux/390 to support up to 64k -different IRQs, uniquely representig a single device each. +different IRQs, uniquely representing a single device each. Up to kernel 2.4, Linux/390 used to provide interfaces via the IRQ (subchannel). For internal use of the common I/O layer, these are still there. However, @@ -143,7 +143,7 @@ During its startup the Linux/390 system checks for peripheral devices. Each of those devices is uniquely defined by a so called subchannel by the ESA/390 channel subsystem. While the subchannel numbers are system generated, each subchannel also takes a user defined attribute, the so called device number. -Both subchannel number and device number can not exceed 65535. During driverfs +Both subchannel number and device number cannot exceed 65535. During driverfs initialisation, the information about control unit type and device types that imply specific I/O commands (channel command words - CCWs) in order to operate the device are gathered. Device drivers can retrieve this set of hardware @@ -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 procesed 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. @@ -325,7 +321,7 @@ with the following CCW flags values defined : CCW_FLAG_DC - data chaining CCW_FLAG_CC - command chaining -CCW_FLAG_SLI - suppress incorrct length +CCW_FLAG_SLI - suppress incorrect length CCW_FLAG_SKIP - skip CCW_FLAG_PCI - PCI CCW_FLAG_IDA - indirect addressing @@ -342,13 +338,13 @@ 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. When the I/O request completes, the CDS first level interrupt handler will -accumalate the status in a struct irb and then call the device interrupt handler. +accumulate the status in a struct irb and then call the device interrupt handler. The intparm field will contain the value the device driver has associated with a particular I/O request. If a pending device status was recognized, intparm will be set to 0 (zero). This may happen during I/O initiation or delayed @@ -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 deterministicly 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