fedora core 6 1.2949 + vserver 2.2.0

[linux-2.6.git] / Documentation / s390 / cds.txt

diff --git a/Documentation/s390/cds.txt b/Documentation/s390/cds.txt
index d939717..05a2b4f 100644 (file)
--- a/Documentation/s390/cds.txt
+++ b/Documentation/s390/cds.txt
@@ -56,12 +56,16 @@ read_dev_chars()
    read device characteristics
    
 read_conf_data()
    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()     
    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()
    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
 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
 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
 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.
 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
 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, 
 
 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.
 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
 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.
 
 
 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.
 
 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.
 
 
 The function may be called enabled or disabled.
 


@@ -197,19 +197,21 @@ The read_dev_chars() function returns :
           operational.
 
 
           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 
 
 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
 
 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
 
 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);
                     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
 
 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.
                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
 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 :
 
 
 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_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
 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
 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
           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
 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.
 
 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
 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.
 
 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 :
 
 
 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
 
 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
 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.
 
 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
 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
 
 
 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
 
         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.
 
 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);
 
 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 :
 
 
 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.
 -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.
 
 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
 
 
 Miscellaneous Support Routines