요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
===================================
Writing s390 channel device drivers
===================================
:Author: Cornelia Huck
Introduction
============
This document describes the interfaces available for device drivers that
drive s390 based channel attached I/O devices. This includes interfaces
for interaction with the hardware and interfaces for interacting with
the common driver core. Those interfaces are provided by the s390 common
I/O layer.
The document assumes a familarity with the technical terms associated
with the s390 channel I/O architecture. For a description of this
architecture, please refer to the "z/Architecture: Principles of
Operation", IBM publication no. SA22-7832.
While most I/O devices on a s390 system are typically driven through the
channel I/O mechanism described here, there are various other methods
(like the diag interface). These are out of the scope of this document.
The s390 common I/O layer also provides access to some devices that are
not strictly considered I/O devices. They are considered here as well,
although they are not the focus of this document.
Some additional information can also be found in the kernel source under
Documentation/arch/s390/driver-model.rst.
The css bus
===========
The css bus contains the subchannels available on the system. They fall
into several categories:
* Standard I/O subchannels, for use by the system. They have a child
device on the ccw bus and are described below.
* I/O subchannels bound to the vfio-ccw driver. See
Documentation/arch/s390/vfio-ccw.rst.
* Message subchannels. No Linux driver currently exists.
* CHSC subchannels (at most one). The chsc subchannel driver can be used
to send asynchronous chsc commands.
* eADM subchannels. Used for talking to storage class memory.
The ccw bus
===========
The ccw bus typically contains the majority of devices available to a
s390 system. Named after the channel command word (ccw), the basic
command structure used to address its devices, the ccw bus contains
so-called channel attached devices. They are addressed via I/O
subchannels, visible on the css bus. A device driver for
channel-attached devices, however, will never interact with the
subchannel directly, but only via the I/O device on the ccw bus, the ccw
device.
I/O functions for channel-attached devices
------------------------------------------
Some hardware structures have been translated into C structures for use
by the common I/O layer and device drivers. For more information on the
hardware structures represented here, please consult the Principles of
Operation.
.. kernel-doc:: arch/s390/include/asm/cio.h
:internal:
ccw devices
-----------
Devices that want to initiate channel I/O need to attach to the ccw bus.
Interaction with the driver core is done via the common I/O layer, which
provides the abstractions of ccw devices and ccw device drivers.
The functions that initiate or terminate channel I/O all act upon a ccw
device structure. Device drivers must not bypass those functions or
strange side effects may happen.
.. kernel-doc:: arch/s390/include/asm/ccwdev.h
:internal:
.. kernel-doc:: drivers/s390/cio/device.c
:export:
.. kernel-doc:: drivers/s390/cio/device_ops.c
:export:
The channel-measurement facility
--------------------------------
The channel-measurement facility provides a means to collect measurement
data which is made available by the channel subsystem for each channel
attached device.
.. kernel-doc:: arch/s390/include/uapi/asm/cmb.h
:internal:
.. kernel-doc:: drivers/s390/cio/cmf.c
:export:
The ccwgroup bus
================
The ccwgroup bus only contains artificial devices, created by the user.
Many networking devices (e.g. qeth) are in fact composed of several ccw
devices (like read, write and data channel for qeth). The ccwgroup bus
provides a mechanism to create a meta-device which contains those ccw
devices as slave devices and can be associated with the netdevice.
ccw group devices
-----------------
.. kernel-doc:: arch/s390/include/asm/ccwgroup.h
:internal:
.. kernel-doc:: drivers/s390/cio/ccwgroup.c
:export:
Generic interfaces
==================
The following section contains interfaces in use not only by drivers
dealing with ccw devices, but drivers for various other s390 hardware
as well.
Adapter interrupts
------------------
The common I/O layer provides helper functions for dealing with adapter
interrupts and interrupt vectors.
.. kernel-doc:: drivers/s390/cio/airq.c
:export:
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
S390 channel device driver 문서 정보
1-6이 문서는 s390 channel device driver 작성 방법을 설명하며 저자는 Cornelia Huck입니다.
===================================
Writing s390 channel device drivers
===================================
:Author: Cornelia Huck
범위와 선행 지식
7-30이 문서는 s390 기반 channel-attached I/O device를 구동하는 driver가 사용할 수 있는 interface를 설명합니다. Hardware와 상호작용하는 interface와 common driver core와 상호작용하는 interface를 모두 포함하며, s390 common I/O layer가 이를 제공합니다.
독자는 s390 channel I/O architecture의 technical term에 익숙하다고 가정합니다. Architecture 설명은 IBM publication SA22-7832인 "z/Architecture: Principles of Operation"을 참조해야 합니다.
S390 system의 대다수 I/O device는 여기서 설명하는 channel I/O mechanism으로 구동되지만 diag interface 같은 다른 방식도 있으며 문서 범위 밖입니다.
S390 common I/O layer는 엄밀히 I/O device로 보지 않는 일부 device에도 access를 제공합니다. 이 문서에서도 다루지만 중심 대상은 아닙니다. 추가 정보는 kernel source의 `Documentation/arch/s390/driver-model.rst`에 있습니다.
Common I/O layer가 hardware channel interface와 Linux driver core abstraction을 연결합니다.
Introduction
============
This document describes the interfaces available for device drivers that
drive s390 based channel attached I/O devices. This includes interfaces
for interaction with the hardware and interfaces for interacting with
the common driver core. Those interfaces are provided by the s390 common
I/O layer.
The document assumes a familarity with the technical terms associated
with the s390 channel I/O architecture. For a description of this
architecture, please refer to the "z/Architecture: Principles of
Operation", IBM publication no. SA22-7832.
While most I/O devices on a s390 system are typically driven through the
channel I/O mechanism described here, there are various other methods
(like the diag interface). These are out of the scope of this document.
The s390 common I/O layer also provides access to some devices that are
not strictly considered I/O devices. They are considered here as well,
although they are not the focus of this document.
Some additional information can also be found in the kernel source under
Documentation/arch/s390/driver-model.rst.CSS bus와 subchannel 분류
31-46CSS bus에는 system에서 사용할 수 있는 subchannel이 들어 있으며 여러 category로 나뉩니다.
Standard I/O subchannel은 system이 사용하며 ccw bus에 child device를 둡니다. VFIO에 할당된 I/O subchannel은 `vfio-ccw` driver에 bind되고 `Documentation/arch/s390/vfio-ccw.rst`에서 설명합니다.
Message subchannel에는 현재 Linux driver가 없습니다. CHSC subchannel은 최대 하나이며 asynchronous CHSC command를 보내는 데 사용할 수 있습니다. eADM subchannel은 storage class memory와 통신합니다.
The css bus
===========
The css bus contains the subchannels available on the system. They fall
into several categories:
* Standard I/O subchannels, for use by the system. They have a child
device on the ccw bus and are described below.
* I/O subchannels bound to the vfio-ccw driver. See
Documentation/arch/s390/vfio-ccw.rst.
* Message subchannels. No Linux driver currently exists.
* CHSC subchannels (at most one). The chsc subchannel driver can be used
to send asynchronous chsc commands.
* eADM subchannels. Used for talking to storage class memory.
CCW bus와 device abstraction
47-58CCW bus에는 보통 s390 system에서 사용할 수 있는 device 대부분이 들어 있습니다. 이름은 device를 address하는 기본 command structure인 channel command word(CCW)에서 왔습니다.
CCW bus의 channel-attached device는 CSS bus에 보이는 I/O subchannel을 통해 address됩니다. 그러나 channel-attached device driver는 subchannel과 직접 상호작용하지 않고 CCW bus의 I/O device인 ccw device만 사용합니다.
Driver는 CSS subchannel을 직접 다루지 않고 CCW device abstraction을 통해 I/O를 수행합니다.
The ccw bus
===========
The ccw bus typically contains the majority of devices available to a
s390 system. Named after the channel command word (ccw), the basic
command structure used to address its devices, the ccw bus contains
so-called channel attached devices. They are addressed via I/O
subchannels, visible on the css bus. A device driver for
channel-attached devices, however, will never interact with the
subchannel directly, but only via the I/O device on the ccw bus, the ccw
device.
Channel I/O hardware structure
59-69Common I/O layer와 device driver에서 사용할 수 있도록 일부 hardware structure를 C structure로 옮겨 놓았습니다.
표현된 hardware structure의 자세한 의미는 Principles of Operation을 참조해야 합니다. Kernel-doc은 `arch/s390/include/asm/cio.h`의 internal interface를 가져옵니다.
I/O functions for channel-attached devices
------------------------------------------
Some hardware structures have been translated into C structures for use
by the common I/O layer and device drivers. For more information on the
hardware structures represented here, please consult the Principles of
Operation.
.. kernel-doc:: arch/s390/include/asm/cio.h
:internal:
CCW device와 I/O operation
70-89Channel I/O를 시작하려는 device는 CCW bus에 attach해야 합니다. Driver core와의 상호작용은 ccw device와 ccw device driver abstraction을 제공하는 common I/O layer를 통해 수행합니다.
Channel I/O를 시작하거나 종료하는 function은 모두 ccw device structure를 대상으로 동작합니다. Device driver가 이 function을 우회하면 예상하지 못한 side effect가 발생할 수 있으므로 절대 우회해서는 안 됩니다.
Kernel-doc은 `arch/s390/include/asm/ccwdev.h`의 internal declaration과 `drivers/s390/cio/device.c`, `drivers/s390/cio/device_ops.c`의 exported function을 가져옵니다.
Common I/O helper가 driver core와 channel operation 사이의 필수 경계를 이룹니다.
ccw devices
-----------
Devices that want to initiate channel I/O need to attach to the ccw bus.
Interaction with the driver core is done via the common I/O layer, which
provides the abstractions of ccw devices and ccw device drivers.
The functions that initiate or terminate channel I/O all act upon a ccw
device structure. Device drivers must not bypass those functions or
strange side effects may happen.
.. kernel-doc:: arch/s390/include/asm/ccwdev.h
:internal:
.. kernel-doc:: drivers/s390/cio/device.c
:export:
.. kernel-doc:: drivers/s390/cio/device_ops.c
:export:
Channel-measurement facility
90-102Channel-measurement facility는 channel subsystem이 각 channel-attached device에 대해 제공하는 measurement data를 수집하는 수단입니다.
Kernel-doc은 `arch/s390/include/uapi/asm/cmb.h`의 internal interface와 `drivers/s390/cio/cmf.c`의 exported function을 가져옵니다.
Channel subsystem의 device별 측정값을 CMF interface가 수집해 driver와 userspace API에 제공합니다.
The channel-measurement facility
--------------------------------
The channel-measurement facility provides a means to collect measurement
data which is made available by the channel subsystem for each channel
attached device.
.. kernel-doc:: arch/s390/include/uapi/asm/cmb.h
:internal:
.. kernel-doc:: drivers/s390/cio/cmf.c
:export:
CCW group meta-device
103-111CCWgroup bus에는 user가 만든 artificial device만 들어 있습니다.
Qeth 같은 많은 networking device는 read, write, data channel처럼 여러 ccw device로 구성됩니다. CCWgroup bus는 이 ccw device들을 slave device로 포함하고 netdevice와 연결할 수 있는 meta-device를 만드는 mechanism을 제공합니다.
여러 역할의 CCW device를 하나의 user-created logical network device로 묶습니다.
The ccwgroup bus
================
The ccwgroup bus only contains artificial devices, created by the user.
Many networking devices (e.g. qeth) are in fact composed of several ccw
devices (like read, write and data channel for qeth). The ccwgroup bus
provides a mechanism to create a meta-device which contains those ccw
devices as slave devices and can be associated with the netdevice.
CCW group device API
112-120CCW group device API의 kernel-doc은 `arch/s390/include/asm/ccwgroup.h`의 internal declaration과 `drivers/s390/cio/ccwgroup.c`의 exported function을 가져옵니다.
ccw group devices
-----------------
.. kernel-doc:: arch/s390/include/asm/ccwgroup.h
:internal:
.. kernel-doc:: drivers/s390/cio/ccwgroup.c
:export:
S390 generic interface
121-127이어지는 generic interface는 ccw device를 다루는 driver뿐 아니라 여러 다른 s390 hardware driver에서도 사용됩니다.
Generic interfaces
==================
The following section contains interfaces in use not only by drivers
dealing with ccw devices, but drivers for various other s390 hardware
as well.
Adapter interrupt helper
128-135Common I/O layer는 adapter interrupt와 interrupt vector를 처리하기 위한 helper function을 제공합니다.
Kernel-doc은 `drivers/s390/cio/airq.c`의 exported function을 가져옵니다.
Architecture-specific common I/O helper가 interrupt와 vector 관리를 driver에 제공합니다.
Adapter interrupts
------------------
The common I/O layer provides helper functions for dealing with adapter
interrupts and interrupt vectors.
.. kernel-doc:: drivers/s390/cio/airq.c
:export:
요약과 해설
s390-drivers.rst:1-135S390 common I/O layer는 CSS subchannel을 CCW device abstraction으로 감싸 driver core와 channel I/O를 연결합니다. Driver는 ccw helper를 우회하지 않아야 하며, CCWgroup은 여러 channel을 하나의 meta-device로 묶습니다. Measurement facility와 adapter interrupt helper의 kernel-doc source도 함께 정리합니다.