^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Linux for S/390 and zSeries
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Common Device Support (CDS)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Device Driver I/O Support Routines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) Authors:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) - Ingo Adlung
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) - Cornelia Huck
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) Copyright, IBM Corp. 1999-2002
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) This document describes the common device support routines for Linux/390.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) Different than other hardware architectures, ESA/390 has defined a unified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) I/O access method. This gives relief to the device drivers as they don't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) have to deal with different bus types, polling versus interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) processing, shared versus non-shared interrupt processing, DMA versus port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) I/O (PIO), and other hardware features more. However, this implies that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) either every single device driver needs to implement the hardware I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) attachment functionality itself, or the operating system provides for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) unified method to access the hardware, providing all the functionality that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) every single device driver would have to provide itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) The document does not intend to explain the ESA/390 hardware architecture in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) every detail.This information can be obtained from the ESA/390 Principles of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Operation manual (IBM Form. No. SA22-7201).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) In order to build common device support for ESA/390 I/O interfaces, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) functional layer was introduced that provides generic I/O access methods to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) the hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) The common device support layer comprises the I/O support routines defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) below. Some of them implement common Linux device driver interfaces, while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) some of them are ESA/390 platform specific.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) Note:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) In order to write a driver for S/390, you also need to look into the interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) described in Documentation/s390/driver-model.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) Note for porting drivers from 2.4:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) The major changes are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) * The functions use a ccw_device instead of an irq (subchannel).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) * All drivers must define a ccw_driver (see driver-model.txt) and the associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) * request_irq() and free_irq() are no longer done by the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) * The oper_handler is (kindof) replaced by the probe() and set_online() functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) of the ccw_driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) * The not_oper_handler is (kindof) replaced by the remove() and set_offline()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) functions of the ccw_driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) * The channel device layer is gone.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) * The interrupt handlers must be adapted to use a ccw_device as argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Moreover, they don't return a devstat, but an irb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) * Before initiating an io, the options must be set via ccw_device_set_options().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) * Instead of calling read_dev_chars()/read_conf_data(), the driver issues
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) the channel program and handles the interrupt itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) ccw_device_get_ciw()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) get commands from extended sense data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) ccw_device_start(), ccw_device_start_timeout(), ccw_device_start_key(), ccw_device_start_key_timeout()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) initiate an I/O request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) ccw_device_resume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) resume channel program execution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) ccw_device_halt()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) terminate the current I/O request processed on the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) do_IRQ()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) generic interrupt routine. This function is called by the interrupt entry
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) routine whenever an I/O interrupt is presented to the system. The do_IRQ()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) routine determines the interrupt status and calls the device specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) interrupt handler according to the rules (flags) defined during I/O request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) initiation with do_IO().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) The next chapters describe the functions other than do_IRQ() in more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) The do_IRQ() interface is not described, as it is called from the Linux/390
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) first level interrupt handler only and does not comprise a device driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) callable interface. Instead, the functional description of do_IO() also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) describes the input to the device specific interrupt handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) Note:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) All explanations apply also to the 64 bit architecture s390x.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) Common Device Support (CDS) for Linux/390 Device Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) ========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) General Information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) The following chapters describe the I/O related interface routines the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) Linux/390 common device support (CDS) provides to allow for device specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) driver implementations on the IBM ESA/390 hardware platform. Those interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) intend to provide the functionality required by every device driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) implementation to allow to drive a specific hardware device on the ESA/390
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) platform. Some of the interface routines are specific to Linux/390 and some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) of them can be found on other Linux platforms implementations too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) Miscellaneous function prototypes, data declarations, and macro definitions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) can be found in the architecture specific C header file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) linux/arch/s390/include/asm/irq.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Overview of CDS interface concepts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) Different to other hardware platforms, the ESA/390 architecture doesn't define
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) interrupt lines managed by a specific interrupt controller and bus systems
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) that may or may not allow for shared interrupts, DMA processing, etc.. Instead,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) the ESA/390 architecture has implemented a so called channel subsystem, that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) provides a unified view of the devices physically attached to the systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Though the ESA/390 hardware platform knows about a huge variety of different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) peripheral attachments like disk devices (aka. DASDs), tapes, communication
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) controllers, etc. they can all be accessed by a well defined access method and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) they are presenting I/O completion a unified way : I/O interruptions. Every
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) single device is uniquely identified to the system by a so called subchannel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) where the ESA/390 architecture allows for 64k devices be attached.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) Linux, however, was first built on the Intel PC architecture, with its two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) cascaded 8259 programmable interrupt controllers (PICs), that allow for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) maximum of 15 different interrupt lines. All devices attached to such a system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) share those 15 interrupt levels. Devices attached to the ISA bus system must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) not share interrupt levels (aka. IRQs), as the ISA bus bases on edge triggered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) interrupts. MCA, EISA, PCI and other bus systems base on level triggered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) interrupts, and therewith allow for shared IRQs. However, if multiple devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) present their hardware status by the same (shared) IRQ, the operating system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) has to call every single device driver registered on this IRQ in order to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) determine the device driver owning the device that raised the interrupt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) Up to kernel 2.4, Linux/390 used to provide interfaces via the IRQ (subchannel).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) For internal use of the common I/O layer, these are still there. However,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) device drivers should use the new calling interface via the ccw_device only.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) During its startup the Linux/390 system checks for peripheral devices. Each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) of those devices is uniquely defined by a so called subchannel by the ESA/390
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) channel subsystem. While the subchannel numbers are system generated, each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) subchannel also takes a user defined attribute, the so called device number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) Both subchannel number and device number cannot exceed 65535. During sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) initialisation, the information about control unit type and device types that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) imply specific I/O commands (channel command words - CCWs) in order to operate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) the device are gathered. Device drivers can retrieve this set of hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) information during their initialization step to recognize the devices they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) support using the information saved in the struct ccw_device given to them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) This methods implies that Linux/390 doesn't require to probe for free (not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) armed) interrupt request lines (IRQs) to drive its devices with. Where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) applicable, the device drivers can use issue the READ DEVICE CHARACTERISTICS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) ccw to retrieve device characteristics in its online routine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) In order to allow for easy I/O initiation the CDS layer provides a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) ccw_device_start() interface that takes a device specific channel program (one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) or more CCWs) as input sets up the required architecture specific control blocks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) and initiates an I/O request on behalf of the device driver. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) ccw_device_start() routine allows to specify whether it expects the CDS layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) to notify the device driver for every interrupt it observes, or with final status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) only. See ccw_device_start() for more details. A device driver must never issue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) ESA/390 I/O commands itself, but must use the Linux/390 CDS interfaces instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) For long running I/O request to be canceled, the CDS layer provides the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) ccw_device_halt() function. Some devices require to initially issue a HALT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) SUBCHANNEL (HSCH) command without having pending I/O requests. This function is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) also covered by ccw_device_halt().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) get_ciw() - get command information word
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) This call enables a device driver to get information about supported commands
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) from the extended SenseID data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) struct ciw *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) ccw_device_get_ciw(struct ccw_device *cdev, __u32 cmd);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) ==== ========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) cdev The ccw_device for which the command is to be retrieved.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) cmd The command type to be retrieved.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) ==== ========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) ccw_device_get_ciw() returns:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) ===== ================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) NULL No extended data available, invalid device or command not found.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) !NULL The command requested.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) ===== ================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) ccw_device_start() - Initiate I/O Request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) The ccw_device_start() routines is the I/O request front-end processor. All
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) device driver I/O requests must be issued using this routine. A device driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) must not issue ESA/390 I/O commands itself. Instead the ccw_device_start()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) routine provides all interfaces required to drive arbitrary devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) This description also covers the status information passed to the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) driver's interrupt handler as this is related to the rules (flags) defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) with the associated I/O request when calling ccw_device_start().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) int ccw_device_start(struct ccw_device *cdev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) struct ccw1 *cpa,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) unsigned long intparm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) __u8 lpm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) unsigned long flags);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) int ccw_device_start_timeout(struct ccw_device *cdev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) struct ccw1 *cpa,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) unsigned long intparm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) __u8 lpm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) unsigned long flags,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) int expires);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) int ccw_device_start_key(struct ccw_device *cdev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) struct ccw1 *cpa,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) unsigned long intparm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) __u8 lpm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) __u8 key,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) unsigned long flags);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) int ccw_device_start_key_timeout(struct ccw_device *cdev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) struct ccw1 *cpa,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) unsigned long intparm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) __u8 lpm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) __u8 key,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) unsigned long flags,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) int expires);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) ============= =============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) cdev ccw_device the I/O is destined for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) cpa logical start address of channel program
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) user_intparm user specific interrupt information; will be presented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) back to the device driver's interrupt handler. Allows a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) device driver to associate the interrupt with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) particular I/O request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) lpm defines the channel path to be used for a specific I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) request. A value of 0 will make cio use the opm.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) key the storage key to use for the I/O (useful for operating on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) storage with a storage key != default key)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) flag defines the action to be performed for I/O processing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) expires timeout value in jiffies. The common I/O layer will terminate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) the running program after this and call the interrupt handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) with ERR_PTR(-ETIMEDOUT) as irb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) ============= =============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) Possible flag values are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) ========================= =============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) DOIO_ALLOW_SUSPEND channel program may become suspended
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) DOIO_DENY_PREFETCH don't allow for CCW prefetch; usually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) this implies the channel program might
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) become modified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) DOIO_SUPPRESS_INTER don't call the handler on intermediate status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) ========================= =============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) The cpa parameter points to the first format 1 CCW of a channel program::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) struct ccw1 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) __u8 cmd_code;/* command code */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) __u8 flags; /* flags, like IDA addressing, etc. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) __u16 count; /* byte count */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) __u32 cda; /* data address */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) } __attribute__ ((packed,aligned(8)));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) with the following CCW flags values defined:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) =================== =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) CCW_FLAG_DC data chaining
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) CCW_FLAG_CC command chaining
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) CCW_FLAG_SLI suppress incorrect length
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) CCW_FLAG_SKIP skip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) CCW_FLAG_PCI PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) CCW_FLAG_IDA indirect addressing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) CCW_FLAG_SUSPEND suspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) =================== =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) Via ccw_device_set_options(), the device driver may specify the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) options for the device:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) ========================= ======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) DOIO_EARLY_NOTIFICATION allow for early interrupt notification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) DOIO_REPORT_ALL report all interrupt conditions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) ========================= ======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) The ccw_device_start() function returns:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) ======== ======================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) 0 successful completion or request successfully initiated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) -EBUSY The device is currently processing a previous I/O request, or there is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) a status pending at the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) -ENODEV cdev is invalid, the device is not operational or the ccw_device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) not online.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) ======== ======================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) When the I/O request completes, the CDS first level interrupt handler will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) accumulate the status in a struct irb and then call the device interrupt handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) The intparm field will contain the value the device driver has associated with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) particular I/O request. If a pending device status was recognized,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) intparm will be set to 0 (zero). This may happen during I/O initiation or delayed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) by an alert status notification. In any case this status is not related to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) current (last) I/O request. In case of a delayed status notification no special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) interrupt will be presented to indicate I/O completion as the I/O request was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) never started, even though ccw_device_start() returned with successful completion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) The irb may contain an error value, and the device driver should check for this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) first:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) ========== =================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) -ETIMEDOUT the common I/O layer terminated the request after the specified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) timeout value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) -EIO the common I/O layer terminated the request due to an error state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) ========== =================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) If the concurrent sense flag in the extended status word (esw) in the irb is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) set, the field erw.scnt in the esw describes the number of device specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) sense bytes available in the extended control word irb->scsw.ecw[]. No device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) sensing by the device driver itself is required.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) The device interrupt handler can use the following definitions to investigate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) the primary unit check source coded in sense byte 0 :
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) ======================= ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) SNS0_CMD_REJECT 0x80
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) SNS0_INTERVENTION_REQ 0x40
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) SNS0_BUS_OUT_CHECK 0x20
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) SNS0_EQUIPMENT_CHECK 0x10
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) SNS0_DATA_CHECK 0x08
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) SNS0_OVERRUN 0x04
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) SNS0_INCOMPL_DOMAIN 0x01
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) ======================= ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) Depending on the device status, multiple of those values may be set together.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) Please refer to the device specific documentation for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) The irb->scsw.cstat field provides the (accumulated) subchannel status :
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) ========================= ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) SCHN_STAT_PCI program controlled interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) SCHN_STAT_INCORR_LEN incorrect length
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) SCHN_STAT_PROG_CHECK program check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) SCHN_STAT_PROT_CHECK protection check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) SCHN_STAT_CHN_DATA_CHK channel data check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) SCHN_STAT_CHN_CTRL_CHK channel control check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) SCHN_STAT_INTF_CTRL_CHK interface control check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) SCHN_STAT_CHAIN_CHECK chaining check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) ========================= ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) The irb->scsw.dstat field provides the (accumulated) device status :
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) ===================== =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) DEV_STAT_ATTENTION attention
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) DEV_STAT_STAT_MOD status modifier
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) DEV_STAT_CU_END control unit end
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) DEV_STAT_BUSY busy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) DEV_STAT_CHN_END channel end
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) DEV_STAT_DEV_END device end
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) DEV_STAT_UNIT_CHECK unit check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) DEV_STAT_UNIT_EXCEP unit exception
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) ===================== =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) Please see the ESA/390 Principles of Operation manual for details on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) individual flag meanings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) Usage Notes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) ccw_device_start() must be called disabled and with the ccw device lock held.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) The device driver is allowed to issue the next ccw_device_start() call from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) within its interrupt handler already. It is not required to schedule a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) bottom-half, unless a non deterministically long running error recovery procedure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) or similar needs to be scheduled. During I/O processing the Linux/390 generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) I/O device driver support has already obtained the IRQ lock, i.e. the handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) must not try to obtain it again when calling ccw_device_start() or we end in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) deadlock situation!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) If a device driver relies on an I/O request to be completed prior to start the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) next it can reduce I/O processing overhead by chaining a NoOp I/O command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) CCW_CMD_NOOP to the end of the submitted CCW chain. This will force Channel-End
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) and Device-End status to be presented together, with a single interrupt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) However, this should be used with care as it implies the channel will remain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) busy, not being able to process I/O requests for other devices on the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) channel. Therefore e.g. read commands should never use this technique, as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) result will be presented by a single interrupt anyway.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) In order to minimize I/O overhead, a device driver should use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) DOIO_REPORT_ALL only if the device can report intermediate interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) information prior to device-end the device driver urgently relies on. In this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) case all I/O interruptions are presented to the device driver until final
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) status is recognized.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) If a device is able to recover from asynchronously presented I/O errors, it can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) perform overlapping I/O using the DOIO_EARLY_NOTIFICATION flag. While some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) devices always report channel-end and device-end together, with a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) interrupt, others present primary status (channel-end) when the channel is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) ready for the next I/O request and secondary status (device-end) when the data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) transmission has been completed at the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) Above flag allows to exploit this feature, e.g. for communication devices that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) can handle lost data on the network to allow for enhanced I/O processing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) Unless the channel subsystem at any time presents a secondary status interrupt,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) exploiting this feature will cause only primary status interrupts to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) presented to the device driver while overlapping I/O is performed. When a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) secondary status without error (alert status) is presented, this indicates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) successful completion for all overlapping ccw_device_start() requests that have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) been issued since the last secondary (final) status.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) Channel programs that intend to set the suspend flag on a channel command word
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) (CCW) must start the I/O operation with the DOIO_ALLOW_SUSPEND option or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) suspend flag will cause a channel program check. At the time the channel program
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) becomes suspended an intermediate interrupt will be generated by the channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) ccw_device_resume() - Resume Channel Program Execution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) If a device driver chooses to suspend the current channel program execution by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) setting the CCW suspend flag on a particular CCW, the channel program execution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) is suspended. In order to resume channel program execution the CIO layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) provides the ccw_device_resume() routine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) int ccw_device_resume(struct ccw_device *cdev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) ==== ================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) cdev ccw_device the resume operation is requested for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) ==== ================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) The ccw_device_resume() function returns:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) ========= ==============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) 0 suspended channel program is resumed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) -EBUSY status pending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) -ENODEV cdev invalid or not-operational subchannel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) -EINVAL resume function not applicable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) -ENOTCONN there is no I/O request pending for completion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) ========= ==============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) Usage Notes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) Please have a look at the ccw_device_start() usage notes for more details on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) suspended channel programs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) ccw_device_halt() - Halt I/O Request Processing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) Sometimes a device driver might need a possibility to stop the processing of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) a long-running channel program or the device might require to initially issue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) a halt subchannel (HSCH) I/O command. For those purposes the ccw_device_halt()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) command is provided.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) ccw_device_halt() must be called disabled and with the ccw device lock held.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) int ccw_device_halt(struct ccw_device *cdev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) unsigned long intparm);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) ======= =====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) cdev ccw_device the halt operation is requested for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) intparm interruption parameter; value is only used if no I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) is outstanding, otherwise the intparm associated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) the I/O request is returned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) ======= =====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) The ccw_device_halt() function returns:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) ======= ==============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) 0 request successfully initiated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) -EBUSY the device is currently busy, or status pending.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) -ENODEV cdev invalid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) -EINVAL The device is not operational or the ccw device is not online.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) ======= ==============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) Usage Notes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) A device driver may write a never-ending channel program by writing a channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) program that at its end loops back to its beginning by means of a transfer in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) channel (TIC) command (CCW_CMD_TIC). Usually this is performed by network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) device drivers by setting the PCI CCW flag (CCW_FLAG_PCI). Once this CCW is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) executed a program controlled interrupt (PCI) is generated. The device driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) can then perform an appropriate action. Prior to interrupt of an outstanding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) read to a network device (with or without PCI flag) a ccw_device_halt()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) is required to end the pending operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) ccw_device_clear() - Terminage I/O Request Processing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) In order to terminate all I/O processing at the subchannel, the clear subchannel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) (CSCH) command is used. It can be issued via ccw_device_clear().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) ccw_device_clear() must be called disabled and with the ccw device lock held.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) int ccw_device_clear(struct ccw_device *cdev, unsigned long intparm);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) ======= ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) cdev ccw_device the clear operation is requested for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) intparm interruption parameter (see ccw_device_halt())
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) ======= ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) The ccw_device_clear() function returns:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) ======= ==============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) 0 request successfully initiated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) -ENODEV cdev invalid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) -EINVAL The device is not operational or the ccw device is not online.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) ======= ==============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) Miscellaneous Support Routines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) This chapter describes various routines to be used in a Linux/390 device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) driver programming environment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) get_ccwdev_lock()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) Get the address of the device specific lock. This is then used in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) spin_lock() / spin_unlock() calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) __u8 ccw_device_get_path_mask(struct ccw_device *cdev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) Get the mask of the path currently available for cdev.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags