cds.rst 23 KB

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