0001 ===================================
0002 Writing s390 channel device drivers
0003 ===================================
0004
0005 :Author: Cornelia Huck
0006
0007 Introduction
0008 ============
0009
0010 This document describes the interfaces available for device drivers that
0011 drive s390 based channel attached I/O devices. This includes interfaces
0012 for interaction with the hardware and interfaces for interacting with
0013 the common driver core. Those interfaces are provided by the s390 common
0014 I/O layer.
0015
0016 The document assumes a familarity with the technical terms associated
0017 with the s390 channel I/O architecture. For a description of this
0018 architecture, please refer to the "z/Architecture: Principles of
0019 Operation", IBM publication no. SA22-7832.
0020
0021 While most I/O devices on a s390 system are typically driven through the
0022 channel I/O mechanism described here, there are various other methods
0023 (like the diag interface). These are out of the scope of this document.
0024
0025 The s390 common I/O layer also provides access to some devices that are
0026 not strictly considered I/O devices. They are considered here as well,
0027 although they are not the focus of this document.
0028
0029 Some additional information can also be found in the kernel source under
0030 Documentation/s390/driver-model.rst.
0031
0032 The css bus
0033 ===========
0034
0035 The css bus contains the subchannels available on the system. They fall
0036 into several categories:
0037
0038 * Standard I/O subchannels, for use by the system. They have a child
0039 device on the ccw bus and are described below.
0040 * I/O subchannels bound to the vfio-ccw driver. See
0041 Documentation/s390/vfio-ccw.rst.
0042 * Message subchannels. No Linux driver currently exists.
0043 * CHSC subchannels (at most one). The chsc subchannel driver can be used
0044 to send asynchronous chsc commands.
0045 * eADM subchannels. Used for talking to storage class memory.
0046
0047 The ccw bus
0048 ===========
0049
0050 The ccw bus typically contains the majority of devices available to a
0051 s390 system. Named after the channel command word (ccw), the basic
0052 command structure used to address its devices, the ccw bus contains
0053 so-called channel attached devices. They are addressed via I/O
0054 subchannels, visible on the css bus. A device driver for
0055 channel-attached devices, however, will never interact with the
0056 subchannel directly, but only via the I/O device on the ccw bus, the ccw
0057 device.
0058
0059 I/O functions for channel-attached devices
0060 ------------------------------------------
0061
0062 Some hardware structures have been translated into C structures for use
0063 by the common I/O layer and device drivers. For more information on the
0064 hardware structures represented here, please consult the Principles of
0065 Operation.
0066
0067 .. kernel-doc:: arch/s390/include/asm/cio.h
0068 :internal:
0069
0070 ccw devices
0071 -----------
0072
0073 Devices that want to initiate channel I/O need to attach to the ccw bus.
0074 Interaction with the driver core is done via the common I/O layer, which
0075 provides the abstractions of ccw devices and ccw device drivers.
0076
0077 The functions that initiate or terminate channel I/O all act upon a ccw
0078 device structure. Device drivers must not bypass those functions or
0079 strange side effects may happen.
0080
0081 .. kernel-doc:: arch/s390/include/asm/ccwdev.h
0082 :internal:
0083
0084 .. kernel-doc:: drivers/s390/cio/device.c
0085 :export:
0086
0087 .. kernel-doc:: drivers/s390/cio/device_ops.c
0088 :export:
0089
0090 The channel-measurement facility
0091 --------------------------------
0092
0093 The channel-measurement facility provides a means to collect measurement
0094 data which is made available by the channel subsystem for each channel
0095 attached device.
0096
0097 .. kernel-doc:: arch/s390/include/uapi/asm/cmb.h
0098 :internal:
0099
0100 .. kernel-doc:: drivers/s390/cio/cmf.c
0101 :export:
0102
0103 The ccwgroup bus
0104 ================
0105
0106 The ccwgroup bus only contains artificial devices, created by the user.
0107 Many networking devices (e.g. qeth) are in fact composed of several ccw
0108 devices (like read, write and data channel for qeth). The ccwgroup bus
0109 provides a mechanism to create a meta-device which contains those ccw
0110 devices as slave devices and can be associated with the netdevice.
0111
0112 ccw group devices
0113 -----------------
0114
0115 .. kernel-doc:: arch/s390/include/asm/ccwgroup.h
0116 :internal:
0117
0118 .. kernel-doc:: drivers/s390/cio/ccwgroup.c
0119 :export:
0120
0121 Generic interfaces
0122 ==================
0123
0124 The following section contains interfaces in use not only by drivers
0125 dealing with ccw devices, but drivers for various other s390 hardware
0126 as well.
0127
0128 Adapter interrupts
0129 ------------------
0130
0131 The common I/O layer provides helper functions for dealing with adapter
0132 interrupts and interrupt vectors.
0133
0134 .. kernel-doc:: drivers/s390/cio/airq.c
0135 :export:
