^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Writing s390 channel device drivers
^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) :Author: Cornelia Huck
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) This document describes the interfaces available for device drivers that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) drive s390 based channel attached I/O devices. This includes interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) for interaction with the hardware and interfaces for interacting with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) the common driver core. Those interfaces are provided by the s390 common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) I/O layer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) The document assumes a familarity with the technical terms associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) with the s390 channel I/O architecture. For a description of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) architecture, please refer to the "z/Architecture: Principles of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Operation", IBM publication no. SA22-7832.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) While most I/O devices on a s390 system are typically driven through the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) channel I/O mechanism described here, there are various other methods
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) (like the diag interface). These are out of the scope of this document.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) The s390 common I/O layer also provides access to some devices that are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) not strictly considered I/O devices. They are considered here as well,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) although they are not the focus of this document.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Some additional information can also be found in the kernel source under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Documentation/s390/driver-model.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) The css bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) The css bus contains the subchannels available on the system. They fall
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) into several categories:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) * Standard I/O subchannels, for use by the system. They have a child
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) device on the ccw bus and are described below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) * I/O subchannels bound to the vfio-ccw driver. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) Documentation/s390/vfio-ccw.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) * Message subchannels. No Linux driver currently exists.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) * CHSC subchannels (at most one). The chsc subchannel driver can be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) to send asynchronous chsc commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) * eADM subchannels. Used for talking to storage class memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) The ccw bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) The ccw bus typically contains the majority of devices available to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) s390 system. Named after the channel command word (ccw), the basic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) command structure used to address its devices, the ccw bus contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) so-called channel attached devices. They are addressed via I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) subchannels, visible on the css bus. A device driver for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) channel-attached devices, however, will never interact with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) subchannel directly, but only via the I/O device on the ccw bus, the ccw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) I/O functions for channel-attached devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) ------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) Some hardware structures have been translated into C structures for use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) by the common I/O layer and device drivers. For more information on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) hardware structures represented here, please consult the Principles of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) Operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) .. kernel-doc:: arch/s390/include/asm/cio.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) ccw devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) Devices that want to initiate channel I/O need to attach to the ccw bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) Interaction with the driver core is done via the common I/O layer, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) provides the abstractions of ccw devices and ccw device drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) The functions that initiate or terminate channel I/O all act upon a ccw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) device structure. Device drivers must not bypass those functions or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) strange side effects may happen.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) .. kernel-doc:: arch/s390/include/asm/ccwdev.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) .. kernel-doc:: drivers/s390/cio/device.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) .. kernel-doc:: drivers/s390/cio/device_ops.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) The channel-measurement facility
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) The channel-measurement facility provides a means to collect measurement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) data which is made available by the channel subsystem for each channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) attached device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) .. kernel-doc:: arch/s390/include/uapi/asm/cmb.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) .. kernel-doc:: drivers/s390/cio/cmf.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) The ccwgroup bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) The ccwgroup bus only contains artificial devices, created by the user.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) Many networking devices (e.g. qeth) are in fact composed of several ccw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) devices (like read, write and data channel for qeth). The ccwgroup bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) provides a mechanism to create a meta-device which contains those ccw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) devices as slave devices and can be associated with the netdevice.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) ccw group devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) .. kernel-doc:: arch/s390/include/asm/ccwgroup.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) .. kernel-doc:: drivers/s390/cio/ccwgroup.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) Generic interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) The following section contains interfaces in use not only by drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) dealing with ccw devices, but drivers for various other s390 hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) Adapter interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) The common I/O layer provides helper functions for dealing with adapter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) interrupts and interrupt vectors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) .. kernel-doc:: drivers/s390/cio/airq.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) :export:
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags