cds.txt

嵌入式系统设计与实例开发实验教材二源码 多线程应用程序设计 串行端口程序设计 AD接口实验 CAN总线通信实验 GPS通信实验 Linux内核移植与编译实验 IC卡读写实验 SD驱动使

available in the sense area dev_id->ii.sense. No device sensing by the device
driver itself is required.

typedef struct {
   unsigned char res[32];       /* reserved   */
   unsigned char data[32];      /* sense data */
} sense_t;

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

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

The devi_id->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 dev_id->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.

In rare error situations the device driver may require access to the original
hardware interrupt data beyond the scope of above mentioned infromation. For
those situations the Linux/390 common device support provides the interrupt
response block (IRB) as part of the device status block in dev_id->ii.irb.

Usage Notes :

Prior to call do_IO() 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 __save_flags( flags). The current PSW
flags are preserved and can be restored by __restore_flags( 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 do_IO() 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)  s390irq_spin_lock( irq), or
(ii) s390irq_spin_lock_irqsave(irq, 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.
See the descriptions of s390irq_spin_lock() or s390irq_spin_lock_irqsave()
for more details.

The device driver is allowed to issue the next do_IO() 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 do_IO() or we end in a deadlock
situation ! Anyway, the device driver's interrupt handler must only call
do_IO() if the handler itself can be entered recursively if do_IO() e.g. finds
a status pending and needs to all the interrupt handler itself.

Device drivers shouldn't heavily rely on DOIO_WAIT_FOR_INTERRUPT synchronous
I/O request processing. All I/O devices, but the console device are driven
using a single shared interrupt subclass (ISC). For sync. processing the
device is temporarily mapped to a special ISC while the calling CPU waits for
I/O completion. As this special ISC is gated, all sync. requests in a SMP
environment are serialized which may cause other CPUs to spin. This service
is therewith primarily meant to be used during device driver initialization
for ease of device setup.

The lpm input parameter might be used for multipath devices shared among
multiple systems as the Linux/390 CDS isn't grouping channel paths. Therefore
its use might be required if multiple access paths to a device are available
and the device was reserved by means of a reserve device command (for devices
supporting this technique). When issuing this command the device driver needs
needs to extract the dev_id->lpum value and restrict all subsequent channel
programs to this channel path until the device is released by a device release
command. Otherwise a deadlock may occur.

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 interrups 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 do_IO() requests that have been
issued since the last secondary (final) status.

During interrupt processing the device specific interrupt handler should avoid
basing its processing decisions on the interruption response block (IRB) that
is part of the dev_id buffer area. The IRB area represents the interruption
parameters from the last interrupt received. Unless the device driver has
specified DOIO_REPORT_ALL or is called with a pending status
(DEVSTAT_STATUS_PENDING), the IRB information may or may not show the complete
interruption status, but the last interrupt only. Therefore the device driver
should usually base its processing decisions on the values of dev_id->cstat
and dev_id->dstat that represent the accumulated subchannel and device status
information gathered since do_IO() request initiation.


halt_IO() - 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 halt_IO() command
is provided.

int halt_IO( int          irq,     /* subchannel number */
             int          intparm, /* dummy intparm */
             unsigned int flag);   /* operation mode */

irq     : irq (subchannel) 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
flag    : 0 (zero) or DOIO_WAIT_FOR_INTERRUPT

The halt_IO() function returns :

      0 - successful completion or request successfully initiated
-EBUSY  - the device is currently performing a synchronous I/O
          operation : do_IO() with flag DOIO_WAIT_FOR_INTERRUPT
          or an error was encountered and the device is currently
          be sensed
-ENODEV - the irq specified doesn't specify a valid subchannel, the
          device is not operational (check dev_id.flags) or the irq
          is not owned.

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 halt_IO() is required
to end the pending operation.

We don't allow to stop sync. I/O requests by means of a halt_IO() call. The
function will return -EBUSY instead.


Miscellaneous Support Routines

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

s390irq_spin_lock() / s390irq_spin_unlock()

Those two macro definitions are required to obtain the device specific IRQ
lock. The lock needs to be obtained if the device driver intends to call
do_IO() or halt_IO() from anywhere but the device interrupt handler (where
the lock is already owned). Those routines must only be used if running
disabled for interrupts already. Otherwise use s390irq_spin_lock_irqsave()
and the corresponding unlock routine instead (see below).

s390irq_spin_lock( int irq);
s390irq_spin_unlock( int irq);


s390irq_spin_lock_irqsave() / s390_irq_spin_unlock_irqrestore()

Those two macro definitions are required to obtain the device specific IRQ
lock. The lock needs to be obtained if the device driver intends to call
do_IO() or halt_IO() from anywhere but the device interrupt handler (where
the lock is already owned). Those routines should only be used if running
enabled for interrupts. If running disabled already, the driver should use
s390irq_spin_lock() and the corresponding unlock routine instead (see above).

s390irq_spin_lock_irqsave( int irq, unsigned long flags);
s390irq_spin_unlock_irqrestore( int irq, unsigned long flags);




Special Console Interface Routines

This chapter describes the special interface routines required for system
console processing. Though they are an extension to the Linux/390 device
driver interface concept, they base on the same principles. It was necessary
to build those extensions to assure a deterministic behaviour in critical
situations e.g. printk() messages by other device drivers running disabled
for interrupts during I/O interrupt handling or in case of a panic() message
being raised.

set_cons_dev - Set Console Device

This routine allows to specify the system console device. This is necessary
as the console isn't driven by the same ESA/390 interrupt subclass as are
other devices, but it is assigned ist own interrupt subclass. Only one device
can act as system console. See wait_cons_dev() for details.

int set_cons_dev( int irq);

irq : subchannel identifying the system console device

The set_cons_dev() function returns

      0 - successful completion
-EIO    - an unhandled interrupt condition is pending for the
          specified subchannel (irq) - status pending
-ENODEV - irq doesn't specify a valid subchannel or the devive is
          not operational
-EBUSY  - the console device is already defined

reset_cons_dev - Reset Console Device

This routine allows for resetting the console device specification. See
set_cons_dev() for details.

int reset_cons_dev( int irq);

irq : subchannel identifying the system console device

The reset_cons_dev() function returns

      0 - successful completion
-EIO    - an unhandled interrupt condition is pending for the
          specified subchannel (irq) - status pending
-ENODEV - irq doesn't specify a valid subchannel or the devive is
          not operational

wait_cons_dev - Synchronously Wait for Console Processing

The wait_cons_dev() routine is used by the console device driver when its
buffer pool for intermediate request queuing is exhausted and a new output
request is received. In this case the console driver uses the wait_cons_dev()
routine to synchronously wait until enough buffer space is gained to enqueue
the current request. Any pending interrupt condition for the console device
found during wait_cons_dev() processing causes its interrupt handler to be
called.

int wait_cons_dev( int irq);

irq : subchannel identifying the system console device

The wait_cons_dev() function  returns :

      0 - successful completion
-EINVAL - the irq specified doesn't match the irq configured for
          the console device by set_cons_dev()

Usage Notes :

The function should be used carefully. Especially in a SMP environment the
wait_cons_dev() processing requires that all but the special console ISC are
disabled. In a SMP system this requires the other CPUs to be signaled to
disable/enable those ISCs.