cds.txt

来自「Linux Kernel 2.6.9 for OMAP1710」· 文本 代码 · 共 514 行 · 第 1/2 页

driver's interrupt handler as this is related to the rules (flags) defined
with the associated I/O request when calling ccw_device_start().

int ccw_device_start(struct ccw_device *cdev,
		     struct ccw1 *cpa,
		     unsigned long intparm,
		     __u8 lpm,
		     unsigned long flags);

cdev         : ccw_device the I/O is destined for
cpa          : logical start address of channel program
user_intparm : user specific interrupt information; will be presented
	       back to the device driver's interrupt handler. Allows a
               device driver to associate the interrupt with a
               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.
flag         : defines the action to be performed for I/O processing

Possible flag values are :

DOIO_ALLOW_SUSPEND       - channel program may become suspended
DOIO_DENY_PREFETCH       - don't allow for CCW prefetch; usually
                           this implies the channel program might
                           become modified
DOIO_SUPPRESS_INTER     - don't call the handler on intermediate status

The cpa parameter points to the first format 1 CCW of a channel program :

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 incorrct 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 ther 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.
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.

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
available in the extended control word irb->scsw.ecw[0]. 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 :

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.

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
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 asynchronosly 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 resume_IO() 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.

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 - successful completion or 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.


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.