S/390 Driver Model Interfaces | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

driver-model.rst:1-307

S/390 드라이버 모델은 CCW 장치를 버스 ID와 서브채널 계층으로 표현하고 `ccw_driver`의 `probe`, `remove`, 온라인 전환, 상태 통지 콜백으로 수명 주기를 관리합니다. 인터럽트 핸들러는 다중 서브채널 구성을 위해 드라이버가 아니라 각 `ccw_device`에 속합니다.

여러 CCW 장치를 묶는 qeth·ctc 계열은 ccwgroup을 사용하며, 채널 경로는 `css0` 아래의 논리 객체로 별도 관리됩니다. sysfs의 속성은 구성뿐 아니라 장치 강제 삭제와 경로 재탐색도 수행하므로 콜백의 사전 조건과 private 데이터 소유권을 지켜야 합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 =============================

2 S/390 driver model interfaces

3 =============================

5 1. CCW devices

6 --------------

8 All devices which can be addressed by means of ccws are called 'CCW devices' -

9 even if they aren't actually driven by ccws.

11 All ccw devices are accessed via a subchannel, this is reflected in the

12 structures under devices/::

14 devices/

15 - system/

16 - css0/

17 - 0.0.0000/0.0.0815/

18 - 0.0.0001/0.0.4711/

19 - 0.0.0002/

20 - 0.1.0000/0.1.1234/

21 ...

22 - defunct/

24 In this example, device 0815 is accessed via subchannel 0 in subchannel set 0,

25 device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O

26 subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1.

28 The subchannel named 'defunct' does not represent any real subchannel on the

29 system; it is a pseudo subchannel where disconnected ccw devices are moved to

30 if they are displaced by another ccw device becoming operational on their

31 former subchannel. The ccw devices will be moved again to a proper subchannel

32 if they become operational again on that subchannel.

34 You should address a ccw device via its bus id (e.g. 0.0.4711); the device can

35 be found under bus/ccw/devices/.

37 All ccw devices export some data via sysfs.

39 cutype:

40 The control unit type / model.

42 devtype:

43 The device type / model, if applicable.

45 availability:

46 Can be 'good' or 'boxed'; 'no path' or 'no device' for

47 disconnected devices.

49 online:

50 An interface to set the device online and offline.

51 In the special case of the device being disconnected (see the

52 notify function under 1.2), piping 0 to online will forcibly delete

53 the device.

55 The device drivers can add entries to export per-device data and interfaces.

57 There is also some data exported on a per-subchannel basis (see under

58 bus/css/devices/):

60 chpids:

61 Via which chpids the device is connected.

63 pimpampom:

64 The path installed, path available and path operational masks.

66 There also might be additional data, for example for block devices.

69 1.1 Bringing up a ccw device

70 ----------------------------

72 This is done in several steps.

74 a. Each driver can provide one or more parameter interfaces where parameters can

75 be specified. These interfaces are also in the driver's responsibility.

76 b. After a. has been performed, if necessary, the device is finally brought up

77 via the 'online' interface.

80 1.2 Writing a driver for ccw devices

81 ------------------------------------

83 The basic struct ccw_device and struct ccw_driver data structures can be found

84 under include/asm/ccwdev.h::

86 struct ccw_device {

87 spinlock_t *ccwlock;

88 struct ccw_device_private *private;

89 struct ccw_device_id id;

91 struct ccw_driver *drv;

92 struct device dev;

93 int online;

95 void (*handler) (struct ccw_device *dev, unsigned long intparm,

96 struct irb *irb);

97 };

99 struct ccw_driver {

100 struct module *owner;

101 struct ccw_device_id *ids;

102 int (*probe) (struct ccw_device *);

103 int (*remove) (struct ccw_device *);

104 int (*set_online) (struct ccw_device *);

105 int (*set_offline) (struct ccw_device *);

106 int (*notify) (struct ccw_device *, int);

107 struct device_driver driver;

108 char *name;

109 };

110

111 The 'private' field contains data needed for internal i/o operation only, and

112 is not available to the device driver.

113

114 Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models

115 and/or device types/models it is interested. This information can later be found

116 in the struct ccw_device_id fields::

117

118 struct ccw_device_id {

119 __u16 match_flags;

120

121 __u16 cu_type;

122 __u16 dev_type;

123 __u8 cu_model;

124 __u8 dev_model;

125

126 unsigned long driver_info;

127 };

128

129 The functions in ccw_driver should be used in the following way:

130

131 probe:

132 This function is called by the device layer for each device the driver

133 is interested in. The driver should only allocate private structures

134 to put in dev->driver_data and create attributes (if needed). Also,

135 the interrupt handler (see below) should be set here.

136

137 ::

138

139 int (*probe) (struct ccw_device *cdev);

140

141 Parameters:

142 cdev

143 - the device to be probed.

144

145

146 remove:

147 This function is called by the device layer upon removal of the driver,

148 the device or the module. The driver should perform cleanups here.

149

150 ::

151

152 int (*remove) (struct ccw_device *cdev);

153

154 Parameters:

155 cdev

156 - the device to be removed.

157

158

159 set_online:

160 This function is called by the common I/O layer when the device is

161 activated via the 'online' attribute. The driver should finally

162 setup and activate the device here.

163

164 ::

165

166 int (*set_online) (struct ccw_device *);

167

168 Parameters:

169 cdev

170 - the device to be activated. The common layer has

171 verified that the device is not already online.

172

173

174 set_offline: This function is called by the common I/O layer when the device is

175 de-activated via the 'online' attribute. The driver should shut

176 down the device, but not de-allocate its private data.

177

178 ::

179

180 int (*set_offline) (struct ccw_device *);

181

182 Parameters:

183 cdev

184 - the device to be deactivated. The common layer has

185 verified that the device is online.

186

187

188 notify:

189 This function is called by the common I/O layer for some state changes

190 of the device.

191

192 Signalled to the driver are:

193

194 * In online state, device detached (CIO_GONE) or last path gone

195 (CIO_NO_PATH). The driver must return !0 to keep the device; for

196 return code 0, the device will be deleted as usual (also when no

197 notify function is registered). If the driver wants to keep the

198 device, it is moved into disconnected state.

199 * In disconnected state, device operational again (CIO_OPER). The

200 common I/O layer performs some sanity checks on device number and

201 Device / CU to be reasonably sure if it is still the same device.

202 If not, the old device is removed and a new one registered. By the

203 return code of the notify function the device driver signals if it

204 wants the device back: !0 for keeping, 0 to make the device being

205 removed and re-registered.

206

207 ::

208

209 int (*notify) (struct ccw_device *, int);

210

211 Parameters:

212 cdev

213 - the device whose state changed.

214

215 event

216 - the event that happened. This can be one of CIO_GONE,

217 CIO_NO_PATH or CIO_OPER.

218

219 The handler field of the struct ccw_device is meant to be set to the interrupt

220 handler for the device. In order to accommodate drivers which use several

221 distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device

222 instead of ccw_driver.

223 The handler is registered with the common layer during set_online() processing

224 before the driver is called, and is deregistered during set_offline() after the

225 driver has been called. Also, after registering / before deregistering, path

226 grouping resp. disbanding of the path group (if applicable) are performed.

227

228 ::

229

230 void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);

231

232 Parameters: dev - the device the handler is called for

233 intparm - the intparm which allows the device driver to identify

234 the i/o the interrupt is associated with, or to recognize

235 the interrupt as unsolicited.

236 irb - interruption response block which contains the accumulated

237 status.

238

239 The device driver is called from the common ccw_device layer and can retrieve

240 information about the interrupt from the irb parameter.

241

242

243 1.3 ccwgroup devices

244 --------------------

245

246 The ccwgroup mechanism is designed to handle devices consisting of multiple ccw

247 devices, like qeth or ctc.

248

249 The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to

250 this attributes creates a ccwgroup device consisting of these ccw devices (if

251 possible). This ccwgroup device can be set online or offline just like a normal

252 ccw device.

253

254 Each ccwgroup device also provides an 'ungroup' attribute to destroy the device

255 again (only when offline). This is a generic ccwgroup mechanism (the driver does

256 not need to implement anything beyond normal removal routines).

257

258 A ccw device which is a member of a ccwgroup device carries a pointer to the

259 ccwgroup device in the driver_data of its device struct. This field must not be

260 touched by the driver - it should use the ccwgroup device's driver_data for its

261 private data.

262

263 To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in

264 mind that most drivers will need to implement both a ccwgroup and a ccw

265 driver.

266

267

268 2. Channel paths

269 -----------------

270

271 Channel paths show up, like subchannels, under the channel subsystem root (css0)

272 and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus.

273 Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect

274 only the logical state and not the physical state, since we cannot track the

275 latter consistently due to lacking machine support (we don't need to be aware

276 of it anyway).

277

278 status

279 - Can be 'online' or 'offline'.

280 Piping 'on' or 'off' sets the chpid logically online/offline.

281 Piping 'on' to an online chpid triggers path reprobing for all devices

282 the chpid connects to. This can be used to force the kernel to re-use

283 a channel path the user knows to be online, but the machine hasn't

284 created a machine check for.

285

286 type

287 - The physical type of the channel path.

288

289 shared

290 - Whether the channel path is shared.

291

292 cmg

293 - The channel measurement group.

294

295 3. System devices

296 -----------------

297

298 3.1 xpram

299 ---------

300

301 xpram shows up under devices/system/ as 'xpram'.

302

303 3.2 cpus

304 --------

305

306 For each cpu, a directory is created under devices/system/cpu/. Each cpu has an

307 attribute 'online' which can be 0 or 1.

308

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

S/390 드라이버 모델 인터페이스

1-4

이 문서는 S/390 드라이버 모델의 CCW 장치, 채널 경로, 시스템 장치 인터페이스를 설명합니다.

CCW 장치와 sysfs 계층

5-36

CCW로 주소를 지정할 수 있는 모든 장치를 실제로 CCW가 구동하는지와 관계없이 CCW 장치라고 부릅니다. 모든 CCW 장치는 서브채널을 통해 접근하며, 이는 `devices/` 아래의 계층 구조에 반영됩니다.

S/390 CCW 장치 계층

상위 경로항목의미

`devices/``system/`시스템 장치 루트

`devices/``css0/`채널 서브시스템 루트

`css0/``0.0.0000/0.0.0815/`서브채널 0, 장치 0815

`css0/``0.0.0001/0.0.4711/`서브채널 1, 장치 4711

`css0/``0.0.0002/`비 I/O 서브채널 2

`css0/``0.1.0000/0.1.1234/`서브채널 집합 1의 서브채널 0, 장치 1234

`css0/``defunct/`연결이 끊긴 CCW 장치를 위한 의사 서브채널

원문의 ASCII 디렉터리 트리를 같은 부모·자식 관계의 구조화 표로 옮겼습니다.

예제에서 장치 0815는 서브채널 집합 0의 서브채널 0을 통해, 장치 4711은 같은 집합의 서브채널 1을 통해 접근합니다. 서브채널 2는 비 I/O 서브채널이고 장치 1234는 서브채널 집합 1의 서브채널 0을 통해 접근합니다.

`defunct`는 실제 서브채널이 아닙니다. 연결이 끊긴 CCW 장치의 이전 서브채널에서 다른 CCW 장치가 작동하면서 기존 장치를 밀어냈을 때 옮겨 두는 의사 서브채널입니다. 장치가 그 서브채널에서 다시 작동하면 적절한 서브채널로 되돌아갑니다.

CCW 장치는 `0.0.4711` 같은 버스 ID로 지정해야 하며 `bus/ccw/devices/` 아래에서 찾을 수 있습니다.

장치 및 서브채널 속성

37-68

모든 CCW 장치는 sysfs를 통해 다음 데이터를 내보냅니다.

범위	속성	내용
CCW 장치	`cutype`	제어 장치 유형과 모델
CCW 장치	`devtype`	해당하는 경우 장치 유형과 모델
CCW 장치	`availability`	`good`, `boxed` 또는 연결이 끊긴 장치의 `no path`, `no device` 상태
CCW 장치	`online`	장치를 온라인·오프라인으로 전환합니다. 연결이 끊긴 장치에 0을 쓰면 장치를 강제로 삭제합니다.
서브채널	`chpids`	`bus/css/devices/` 아래에서 장치가 연결된 CHPID를 표시합니다.
서브채널	`pimpampom`	설치된 경로, 사용 가능한 경로, 작동 중인 경로의 마스크입니다.

장치 드라이버는 장치별 데이터와 인터페이스를 내보내는 항목을 추가할 수 있습니다. 블록 장치처럼 장치 유형에 따라 추가 데이터가 존재할 수도 있습니다.

CCW 장치 활성화

69-79

CCW 장치를 활성화하는 순서는 다음과 같습니다.

각 드라이버가 필요하면 매개변수를 지정할 하나 이상의 인터페이스를 제공합니다. 이 인터페이스의 구현도 드라이버 책임입니다.
필요한 매개변수 설정을 마친 뒤 `online` 인터페이스로 장치를 최종 활성화합니다.

CCW 장치 활성화 수명 주기

드라이버 매개변수 설정`online=1`공통 I/O 계층 검증

`set_online()`핸들러·경로 그룹 준비장치 온라인

`online=0``set_offline()`장치 오프라인

매개변수 구성부터 공통 계층과 드라이버 콜백을 거쳐 온라인 상태에 도달하는 흐름입니다.

ccw_device와 ccw_driver 구조

80-130

기본 `struct ccw_device`와 `struct ccw_driver`는 `include/asm/ccwdev.h`에 정의됩니다.

struct ccw_device {
      spinlock_t *ccwlock;
      struct ccw_device_private *private;
      struct ccw_device_id id;

      struct ccw_driver *drv;
      struct device dev;
      int online;

      void (*handler) (struct ccw_device *dev, unsigned long intparm,
                       struct irb *irb);
};

struct ccw_driver {
      struct module *owner;
      struct ccw_device_id *ids;
      int (*probe) (struct ccw_device *);
      int (*remove) (struct ccw_device *);
      int (*set_online) (struct ccw_device *);
      int (*set_offline) (struct ccw_device *);
      int (*notify) (struct ccw_device *, int);
      struct device_driver driver;
      char *name;
};

`private` 필드는 내부 I/O 동작에 필요한 데이터만 담으며 장치 드라이버에는 공개되지 않습니다.

각 드라이버는 관심 있는 제어 장치(CU) 유형·모델과 장치 유형·모델을 `MODULE_DEVICE_TABLE`로 선언해야 합니다. 이 정보는 이후 `struct ccw_device_id` 필드에서 확인할 수 있습니다.

struct ccw_device_id {
      __u16   match_flags;

      __u16   cu_type;
      __u16   dev_type;
      __u8    cu_model;
      __u8    dev_model;

      unsigned long driver_info;
};

구조체 요소	역할
`ccw_device`	장치 ID, 상태, 드라이버 연결, 장치별 인터럽트 핸들러를 보유합니다.
`ccw_driver`	ID 표와 probe·remove·온라인 전환·notify 콜백을 보유합니다.
`ccw_device_id`	CU와 장치의 유형·모델 매칭 정보 및 `driver_info`를 보유합니다.

probe()와 remove()

131-158

`probe()`는 드라이버가 관심을 표시한 각 장치에 대해 장치 계층이 호출합니다. 드라이버는 여기서 `dev->driver_data`에 둘 private 구조만 할당하고 필요한 속성을 생성해야 합니다. 아래의 장치 인터럽트 핸들러도 여기서 설정합니다.

int (*probe) (struct ccw_device *cdev);

콜백	`cdev` 의미	드라이버 책임
`probe()`	탐색할 장치	private 구조 할당, 속성 생성, 핸들러 설정
`remove()`	제거할 장치	드라이버·장치·모듈 제거 시 필요한 정리 수행

`remove()`는 드라이버, 장치 또는 모듈이 제거될 때 장치 계층이 호출합니다.

int (*remove) (struct ccw_device *cdev);

set_online()과 set_offline()

159-187

`set_online()`은 `online` 속성으로 장치를 활성화할 때 공통 I/O 계층이 호출합니다. 드라이버는 여기서 장치를 최종 설정하고 활성화합니다. 공통 계층은 장치가 아직 온라인이 아님을 미리 검증합니다.

int (*set_online) (struct ccw_device *);

`set_offline()`은 `online` 속성으로 장치를 비활성화할 때 호출합니다. 드라이버는 장치를 종료하되 private 데이터는 해제하지 않아야 합니다. 공통 계층은 장치가 온라인임을 미리 검증합니다.

int (*set_offline) (struct ccw_device *);

콜백	사전 조건	결과
`set_online()`	`cdev`가 아직 오프라인	장치 설정과 활성화
`set_offline()`	`cdev`가 온라인	private 데이터는 유지하고 장치만 종료

notify() 상태 변경 콜백

188-218

`notify()`는 장치의 특정 상태 변화가 발생할 때 공통 I/O 계층이 호출합니다.

현재 상태와 이벤트	공통 계층 동작과 반환 계약
온라인에서 `CIO_GONE` 또는 `CIO_NO_PATH`	장치를 유지하려면 0이 아닌 값을 반환합니다. 0 또는 미등록 콜백이면 장치를 삭제합니다. 유지하는 장치는 disconnected 상태로 이동합니다.
disconnected에서 `CIO_OPER`	장치 번호와 Device/CU를 검사해 같은 장치인지 확인합니다. 다르면 기존 장치를 제거하고 새로 등록합니다. 되찾으려면 0이 아닌 값을, 제거 후 재등록하려면 0을 반환합니다.

int (*notify) (struct ccw_device *, int);

매개변수	설명
`cdev`	상태가 바뀐 장치
`event`	`CIO_GONE`, `CIO_NO_PATH`, `CIO_OPER` 가운데 발생한 이벤트

장치 인터럽트 핸들러

219-242

`struct ccw_device`의 `handler` 필드는 장치 인터럽트 핸들러를 가리킵니다. 다중 서브채널 장치처럼 여러 핸들러를 사용하는 드라이버를 지원하기 위해 `ccw_driver`가 아니라 `ccw_device`의 멤버입니다.

공통 계층은 `set_online()` 처리 중 드라이버를 호출하기 전에 핸들러를 등록하고, `set_offline()` 처리 중 드라이버를 호출한 뒤 핸들러를 등록 해제합니다. 해당되는 경우 등록 뒤 경로 그룹을 만들고 등록 해제 전에 경로 그룹을 해체합니다.

void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);

매개변수	설명
`dev`	핸들러가 호출된 장치
`intparm`	인터럽트와 연결된 I/O를 식별하거나 unsolicited 인터럽트임을 판별하는 값
`irb`	누적 상태를 포함한 interruption response block

장치 드라이버는 공통 `ccw_device` 계층에서 호출되며 `irb` 매개변수로 인터럽트 정보를 가져올 수 있습니다.

ccwgroup 장치

243-267

ccwgroup 메커니즘은 qeth나 ctc처럼 여러 CCW 장치로 구성된 장치를 처리합니다.

속성 또는 데이터	동작과 제약
`group`	CCW 장치 버스 ID를 쓰면 가능한 경우 그 장치들로 ccwgroup 장치를 만듭니다. 일반 CCW 장치처럼 온라인·오프라인 전환할 수 있습니다.
`ungroup`	오프라인일 때만 ccwgroup 장치를 다시 파괴합니다. 일반 remove 루틴 외에 드라이버의 추가 구현은 필요하지 않습니다.
멤버의 `driver_data`	ccwgroup 장치 포인터를 담으므로 드라이버가 건드리면 안 됩니다. private 데이터는 ccwgroup 장치의 `driver_data`를 사용합니다.

ccwgroup 드라이버 구현은 `include/asm/ccwgroup.h`를 참조하십시오. 대부분의 드라이버는 ccwgroup 드라이버와 CCW 드라이버를 모두 구현해야 합니다.

채널 경로

268-294

채널 경로는 서브채널과 마찬가지로 채널 서브시스템 루트 `css0` 아래에 나타나며 이름은 `chp0.<chpid>`입니다. 드라이버가 없고 어떤 버스에도 속하지 않습니다.

Linux 2.4의 `/proc/chpids`와 달리 채널 경로 객체는 물리 상태가 아니라 논리 상태만 반영합니다. 머신 지원이 부족해 물리 상태를 일관되게 추적할 수 없으며 실제로 그럴 필요도 없습니다.

속성	내용
`status`	`online` 또는 `offline`입니다. `on`과 `off`를 써서 CHPID를 논리적으로 전환합니다. 이미 온라인인 CHPID에 `on`을 쓰면 연결된 모든 장치의 경로를 다시 탐색합니다.
`type`	채널 경로의 물리 유형
`shared`	채널 경로의 공유 여부
`cmg`	채널 측정 그룹

온라인임을 사용자가 알고 있지만 머신이 machine check를 만들지 않은 채널 경로를 커널이 다시 사용하도록 강제할 때 온라인 CHPID에 `on`을 다시 쓰는 재탐색 기능을 사용할 수 있습니다.

시스템 장치

295-307

장치	sysfs 표현
`xpram`	`devices/system/` 아래에 `xpram`으로 나타납니다.
CPU	각 CPU마다 `devices/system/cpu/` 아래에 디렉터리를 만들며 `online` 속성 값은 0 또는 1입니다.