X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=Documentation%2Fs390%2Fcds.txt;h=05a2b4f7e38f7ea17256d3f59461e68a04c485f7;hb=refs%2Fheads%2Fvserver;hp=d9397170fb3657805fe30e59888e02d090a43183;hpb=5273a3df6485dc2ad6aa7ddd441b9a21970f003b;p=linux-2.6.git diff --git a/Documentation/s390/cds.txt b/Documentation/s390/cds.txt index d9397170f..05a2b4f7e 100644 --- a/Documentation/s390/cds.txt +++ b/Documentation/s390/cds.txt @@ -56,12 +56,16 @@ read_dev_chars() read device characteristics read_conf_data() +read_conf_data_lpm() read configuration data. ccw_device_get_ciw() get commands from extended sense data. ccw_device_start() +ccw_device_start_timeout() +ccw_device_start_key() +ccw_device_start_key_timeout() initiate an I/O request. ccw_device_resume() @@ -94,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 @@ -110,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. @@ -129,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, @@ -139,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 @@ -170,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. @@ -197,19 +197,21 @@ The read_dev_chars() function returns : operational. -read_conf_data() - Read Configuration Data +read_conf_data(), read_conf_data_lpm() - Read Configuration Data Retrieve the device dependent configuration data. Please have a look at your device dependent I/O commands for the device specific layout of the node -descriptor elements. +descriptor elements. read_conf_data_lpm() will retrieve the configuration data +for a specific path. -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. The function may be called enabled or disabled, but the device must not be locked -int read_conf_data(struct ccw_device, void **buffer, int *length, __u8 lpm); +int read_conf_data(struct ccw_device, void **buffer, int *length); +int read_conf_data_lpm(struct ccw_device, void **buffer, int *length, __u8 lpm); cdev - the ccw_device the data is requested for. buffer - Pointer to a buffer pointer. The read_conf_data() routine @@ -263,6 +265,25 @@ int ccw_device_start(struct ccw_device *cdev, unsigned long intparm, __u8 lpm, unsigned long flags); +int ccw_device_start_timeout(struct ccw_device *cdev, + struct ccw1 *cpa, + unsigned long intparm, + __u8 lpm, + unsigned long flags, + int expires); +int ccw_device_start_key(struct ccw_device *cdev, + struct ccw1 *cpa, + unsigned long intparm, + __u8 lpm, + __u8 key, + unsigned long flags); +int ccw_device_start_key_timeout(struct ccw_device *cdev, + struct ccw1 *cpa, + unsigned long intparm, + __u8 lpm, + __u8 key, + unsigned long flags, + int expires); cdev : ccw_device the I/O is destined for cpa : logical start address of channel program @@ -272,7 +293,12 @@ user_intparm : user specific interrupt information; will be presented particular I/O request. lpm : defines the channel path to be used for a specific I/O request. A value of 0 will make cio use the opm. +key : the storage key to use for the I/O (useful for operating on a + storage with a storage key != default key) flag : defines the action to be performed for I/O processing +expires : timeout value in jiffies. The common I/O layer will terminate + the running program after this and call the interrupt handler + with ERR_PTR(-ETIMEDOUT) as irb. Possible flag values are : @@ -295,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 @@ -312,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 @@ -327,8 +353,15 @@ current (last) I/O request. In case of a delayed status notification no special interrupt will be presented to indicate I/O completion as the I/O request was never started, even though ccw_device_start() returned with successful completion. +The irb may contain an error value, and the device driver should check for this +first: + +-ETIMEDOUT: the common I/O layer terminated the request after the specified + timeout value +-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. @@ -373,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 @@ -417,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 @@ -451,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 @@ -470,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); @@ -480,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. @@ -496,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