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 f0be389..05a2b4f 100644 (file)
--- 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
 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


@@ -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
 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.


@@ -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
 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, 


@@ -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.
 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


@@ -174,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.
 


@@ -325,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


@@ -342,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


@@ -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
 -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.
 
 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 :
 
 
 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


@@ -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.
 
 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


@@ -488,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


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


@@ -517,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.


@@ -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.
 
 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