path: root/Documentation/s390/cds.txt
diff options
Diffstat (limited to 'Documentation/s390/cds.txt')
1 files changed, 513 insertions, 0 deletions
diff --git a/Documentation/s390/cds.txt b/Documentation/s390/cds.txt
new file mode 100644
index 000000000000..d9397170fb36
--- /dev/null
+++ b/Documentation/s390/cds.txt
@@ -0,0 +1,513 @@
+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
+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.
+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().
+ read device characteristics
+ read configuration data.
+ get commands from extended sense data.
+ initiate an I/O request.
+ resume channel program execution.
+ terminate the current I/O request processed on the device.
+ 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
+implementaion 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
+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 by 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.
+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.
+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 can not 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 the read_dev_chars() to retrieve device
+characteristics. This can be done without having to request device ownership
+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().
+read_dev_chars() - Read Device Characteristics
+This routine returns the characteristics for the device specified.
+The function is meant to be called with an irq handler in place; that is,
+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 function may be called enabled or disabled.
+int read_dev_chars(struct ccw_device *cdev, void **buffer, int length );
+cdev - the ccw_device the information is requested for.
+buffer - pointer to a buffer pointer. The buffer pointer itself
+ must contain a valid buffer area.
+length - length of the buffer provided.
+The read_dev_chars() function returns :
+ 0 - successful completion
+-ENODEV - cdev invalid
+-EINVAL - an invalid parameter was detected, or the function was called early.
+-EBUSY - an irrecoverable I/O error occurred or the device is not
+ operational.
+read_conf_data() - Read Configuration Data
+Retrieve the device dependent configuration data. Please have a look at your
+device dependent I/O commands for the device specific layout of the node
+descriptor elements.
+The function is meant to be called with an irq handler in place; that is,
+at earliest during set_online() processing.
+The function may be called enabled or disabled, but the device must not be
+int read_conf_data(struct ccw_device, void **buffer, int *length, __u8 lpm);
+cdev - the ccw_device the data is requested for.
+buffer - Pointer to a buffer pointer. The read_conf_data() routine
+ will allocate a buffer and initialize the buffer pointer
+ accordingly. It's the device driver's responsibility to
+ release the kernel memory if no longer needed.
+length - Length of the buffer allocated and retrieved.
+lpm - Logical path mask to be used for retrieving the data. If
+ zero the data is retrieved on the next path available.
+The read_conf_data() function returns :
+ 0 - Successful completion
+-ENODEV - cdev invalid.
+-EINVAL - An invalid parameter was detected, or the function was called early.
+-EIO - An irrecoverable I/O error occurred or the device is
+ not operational.
+-ENOMEM - The read_conf_data() routine couldn't obtain storage.
+-EOPNOTSUPP - The device doesn't support the read configuration
+ data command.
+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);
+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_IDA - indirect addressing
+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 :
+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_STAT_MOD - status modifier
+DEV_STAT_CU_END - control unit end
+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
+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 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.