cds.txt

linux 内核源代码

struct ccw1 {
      __u8  cmd_code;/* command code */
      __u8  flags;   /* flags, like IDA addressing, etc. */
      __u16 count;   /* byte count */
      __u32 cda;     /* data address */
} __attribute__ ((packed,aligned(8)));

with the following CCW flags values defined :

CCW_FLAG_DC        - data chaining
CCW_FLAG_CC        - command chaining
CCW_FLAG_SLI       - suppress incorrect length
CCW_FLAG_SKIP      - skip
CCW_FLAG_PCI       - PCI
CCW_FLAG_IDA       - indirect addressing
CCW_FLAG_SUSPEND   - suspend


Via ccw_device_set_options(), the device driver may specify the following
options for the device:

DOIO_EARLY_NOTIFICATION  - allow for early interrupt notification
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 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
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
by an alert status notification. In any case this status is not related to the
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 (esw) in the irb is
set, the field erw.scnt in the esw describes the number of device specific
sense bytes available in the extended control word irb->scsw.ecw[]. No device
sensing by the device driver itself is required.

The device interrupt handler can use the following definitions to investigate
the primary unit check source coded in sense byte 0 :

SNS0_CMD_REJECT         0x80
SNS0_INTERVENTION_REQ   0x40
SNS0_BUS_OUT_CHECK      0x20
SNS0_EQUIPMENT_CHECK    0x10
SNS0_DATA_CHECK         0x08
SNS0_OVERRUN            0x04
SNS0_INCOMPL_DOMAIN     0x01

Depending on the device status, multiple of those values may be set together.
Please refer to the device specific documentation for details.

The irb->scsw.cstat field provides the (accumulated) subchannel status :

SCHN_STAT_PCI            - program controlled interrupt
SCHN_STAT_INCORR_LEN     - incorrect length
SCHN_STAT_PROG_CHECK     - program check
SCHN_STAT_PROT_CHECK     - protection check
SCHN_STAT_CHN_DATA_CHK   - channel data check
SCHN_STAT_CHN_CTRL_CHK   - channel control check
SCHN_STAT_INTF_CTRL_CHK  - interface control check
SCHN_STAT_CHAIN_CHECK    - chaining check

The irb->scsw.dstat field provides the (accumulated) device status :

DEV_STAT_ATTENTION   - attention
DEV_STAT_STAT_MOD    - status modifier
DEV_STAT_CU_END      - control unit end
DEV_STAT_BUSY        - busy
DEV_STAT_CHN_END     - channel end
DEV_STAT_DEV_END     - device end
DEV_STAT_UNIT_CHECK  - unit check
DEV_STAT_UNIT_EXCEP  - unit exception

Please see the ESA/390 Principles of Operation manual for details on the
individual flag meanings.

Usage Notes :

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 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
deadlock situation!

If a device driver relies on an I/O request to be completed prior to start the
next it can reduce I/O processing overhead by chaining a NoOp I/O command
CCW_CMD_NOOP to the end of the submitted CCW chain. This will force Channel-End
and Device-End status to be presented together, with a single interrupt.
However, this should be used with care as it implies the channel will remain
busy, not being able to process I/O requests for other devices on the same
channel. Therefore e.g. read commands should never use this technique, as the
result will be presented by a single interrupt anyway.

In order to minimize I/O overhead, a device driver should use the
DOIO_REPORT_ALL  only if the device can report intermediate interrupt
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 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
ready for the next I/O request and secondary status (device-end) when the data
transmission has been completed at the device.

Above flag allows to exploit this feature, e.g. for communication devices that
can handle lost data on the network to allow for enhanced I/O processing.

Unless the channel subsystem at any time presents a secondary status interrupt,
exploiting this feature will cause only primary status interrupts to be
presented to the device driver while overlapping I/O is performed. When a
secondary status without error (alert status) is presented, this indicates
successful completion for all overlapping ccw_device_start() requests that have
been issued since the last secondary (final) status.

Channel programs that intend to set the suspend flag on a channel command word 
(CCW)  must start the I/O operation with the DOIO_ALLOW_SUSPEND option or the 
suspend flag will cause a channel program check. At the time the channel program 
becomes suspended an intermediate interrupt will be generated by the channel 
subsystem.

ccw_device_resume() - Resume Channel Program Execution 

If a device driver chooses to suspend the current channel program execution by 
setting the CCW suspend flag on a particular CCW, the channel program execution 
is suspended. In order to resume channel program execution the CIO layer 
provides the ccw_device_resume() routine. 

int ccw_device_resume(struct ccw_device *cdev);

cdev - ccw_device the resume operation is requested for

The ccw_device_resume() function returns:

        0  - suspended channel program is resumed
-EBUSY     - status pending
-ENODEV    - cdev invalid or not-operational subchannel 
-EINVAL    - resume function not applicable  
-ENOTCONN  - there is no I/O request pending for completion 

Usage Notes:
Please have a look at the ccw_device_start() usage notes for more details on
suspended channel programs.

ccw_device_halt() - Halt I/O Request Processing

Sometimes a device driver might need a possibility to stop the processing of
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);

cdev    : ccw_device the halt operation is requested for
intparm : interruption parameter; value is only used if no I/O
          is outstanding, otherwise the intparm associated with
          the I/O request is returned

The ccw_device_halt() function returns :

      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.

Usage Notes :

A device driver may write a never-ending channel program by writing a channel
program that at its end loops back to its beginning by means of a transfer in
channel (TIC)   command (CCW_CMD_TIC). Usually this is performed by network
device drivers by setting the PCI CCW flag (CCW_FLAG_PCI). Once this CCW is
executed a program controlled interrupt (PCI) is generated. The device driver
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

This chapter describes various routines to be used in a Linux/390 device
driver programming environment.

get_ccwdev_lock()

Get the address of the device specific lock. This is then used in
spin_lock() / spin_unlock() calls.


__u8 ccw_device_get_path_mask(struct ccw_device *cdev);

Get the mask of the path currently available for cdev.