cds.txt

linux 内核源代码

Linux for S/390 and zSeries

Common Device Support (CDS)
Device Driver I/O Support Routines

Authors : Ingo Adlung
	  Cornelia Huck

Copyright, IBM Corp. 1999-2002

Introduction

This document describes the common device support routines for Linux/390.
Different than other hardware architectures, ESA/390 has defined a unified
I/O access method. This gives relief to the device drivers as they don't
have to deal with different bus types, polling versus interrupt
processing, shared versus non-shared interrupt processing, DMA versus port
I/O (PIO), and other hardware features more. However, this implies that
either every single device driver needs to implement the hardware I/O
attachment functionality itself, or the operating system provides for a
unified method to access the hardware, providing all the functionality that
every single device driver would have to provide itself.

The document does not intend to explain the ESA/390 hardware architecture in
every detail.This information can be obtained from the ESA/390 Principles of
Operation manual (IBM Form. No. SA22-7201).

In order to build common device support for ESA/390 I/O interfaces, a
functional layer was introduced that provides generic I/O access methods to
the hardware. 

The common device support layer comprises the I/O support routines defined 
below. Some of them implement common Linux device driver interfaces, while 
some of them are ESA/390 platform specific.

Note:
In order to write a driver for S/390, you also need to look into the interface
described in Documentation/s390/driver-model.txt.

Note for porting drivers from 2.4:
The major changes are:
* The functions use a ccw_device instead of an irq (subchannel).
* All drivers must define a ccw_driver (see driver-model.txt) and the associated
  functions.
* request_irq() and free_irq() are no longer done by the driver.
* The oper_handler is (kindof) replaced by the probe() and set_online() functions
  of the ccw_driver.
* The not_oper_handler is (kindof) replaced by the remove() and set_offline()
  functions of the ccw_driver.
* The channel device layer is gone.
* The interrupt handlers must be adapted to use a ccw_device as argument.
  Moreover, they don't return a devstat, but an irb.
* Before initiating an io, the options must be set via ccw_device_set_options().
* Instead of calling read_dev_chars()/read_conf_data(), the driver issues
  the channel program and handles the interrupt itself.

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()
   resume channel program execution.

ccw_device_halt()	
   terminate the current I/O request processed on the device.

do_IRQ()	
   generic interrupt routine. This function is called by the interrupt entry
   routine whenever an I/O interrupt is presented to the system. The do_IRQ()
   routine determines the interrupt status and calls the device specific
   interrupt handler according to the rules (flags) defined during I/O request
   initiation with do_IO().

The next chapters describe the functions other than do_IRQ() in more details.
The do_IRQ() interface is not described, as it is called from the Linux/390
first level interrupt handler only and does not comprise a device driver
callable interface. Instead, the functional description of do_IO() also
describes the input to the device specific interrupt handler.

Note: All explanations apply also to the 64 bit architecture s390x.


Common Device Support (CDS) for Linux/390 Device Drivers

General Information

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
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
can be found in the architecture specific C header file
linux/include/asm-s390/irq.h.

Overview of CDS interface concepts

Different to other hardware platforms, the ESA/390 architecture doesn't define
interrupt lines managed by a specific interrupt controller and bus systems
that may or may not allow for shared interrupts, DMA processing, etc.. Instead,
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
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.

Linux, however, was first built on the Intel PC architecture, with its two
cascaded 8259 programmable interrupt controllers (PICs), that allow for a
maximum of 15 different interrupt lines. All devices attached to such a system
share those 15 interrupt levels. Devices attached to the ISA bus system must
not share interrupt levels (aka. IRQs), as the ISA bus bases on edge triggered
interrupts. MCA, EISA, PCI and other bus systems base on level triggered
interrupts, and therewith allow for shared IRQs. However, if multiple devices
present their hardware status by the same (shared) IRQ, the operating system
has to call every single device driver registered on this IRQ in order to
determine the device driver owning the device that raised the interrupt.

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, 
device drivers should use the new calling interface via the ccw_device only.

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.
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
information during their initialization step to recognize the devices they
support using the information saved in the struct ccw_device given to them.
This methods implies that Linux/390 doesn't require to probe for free (not
armed) interrupt request lines (IRQs) to drive its devices with. Where
applicable, the device drivers can use issue the READ DEVICE CHARACTERISTICS
ccw to retrieve device characteristics in its online routine.

In order to allow for easy I/O initiation the CDS layer provides a
ccw_device_start() interface that takes a device specific channel program (one
or more CCWs) as input sets up the required architecture specific control blocks
and initiates an I/O request on behalf of the device driver. The
ccw_device_start() routine allows to specify whether it expects the CDS layer
to notify the device driver for every interrupt it observes, or with final status
only. See ccw_device_start() for more details. A device driver must never issue
ESA/390 I/O commands itself, but must use the Linux/390 CDS interfaces instead.

For long running I/O request to be canceled, the CDS layer provides the
ccw_device_halt() function. Some devices require to initially issue a HALT
SUBCHANNEL (HSCH) command without having pending I/O requests. This function is
also covered by ccw_device_halt().


get_ciw() - get command information word

This call enables a device driver to get information about supported commands
from the extended SenseID data.

struct ciw *
ccw_device_get_ciw(struct ccw_device *cdev, __u32 cmd);

cdev - The ccw_device for which the command is to be retrieved.
cmd  - The command type to be retrieved.

ccw_device_get_ciw() returns:
NULL    - No extended data available, invalid device or command not found.
!NULL   - The command requested.


ccw_device_start() - Initiate I/O Request

The ccw_device_start() routines is the I/O request front-end processor. All
device driver I/O requests must be issued using this routine. A device driver
must not issue ESA/390 I/O commands itself. Instead the ccw_device_start()
routine provides all interfaces required to drive arbitrary devices.

This description also covers the status information passed to the device
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);
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
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.
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
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 :

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 :