driver-model.rst 9.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328
  1. =============================
  2. S/390 driver model interfaces
  3. =============================
  4. 1. CCW devices
  5. --------------
  6. All devices which can be addressed by means of ccws are called 'CCW devices' -
  7. even if they aren't actually driven by ccws.
  8. All ccw devices are accessed via a subchannel, this is reflected in the
  9. structures under devices/::
  10. devices/
  11. - system/
  12. - css0/
  13. - 0.0.0000/0.0.0815/
  14. - 0.0.0001/0.0.4711/
  15. - 0.0.0002/
  16. - 0.1.0000/0.1.1234/
  17. ...
  18. - defunct/
  19. In this example, device 0815 is accessed via subchannel 0 in subchannel set 0,
  20. device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O
  21. subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1.
  22. The subchannel named 'defunct' does not represent any real subchannel on the
  23. system; it is a pseudo subchannel where disconnected ccw devices are moved to
  24. if they are displaced by another ccw device becoming operational on their
  25. former subchannel. The ccw devices will be moved again to a proper subchannel
  26. if they become operational again on that subchannel.
  27. You should address a ccw device via its bus id (e.g. 0.0.4711); the device can
  28. be found under bus/ccw/devices/.
  29. All ccw devices export some data via sysfs.
  30. cutype:
  31. The control unit type / model.
  32. devtype:
  33. The device type / model, if applicable.
  34. availability:
  35. Can be 'good' or 'boxed'; 'no path' or 'no device' for
  36. disconnected devices.
  37. online:
  38. An interface to set the device online and offline.
  39. In the special case of the device being disconnected (see the
  40. notify function under 1.2), piping 0 to online will forcibly delete
  41. the device.
  42. The device drivers can add entries to export per-device data and interfaces.
  43. There is also some data exported on a per-subchannel basis (see under
  44. bus/css/devices/):
  45. chpids:
  46. Via which chpids the device is connected.
  47. pimpampom:
  48. The path installed, path available and path operational masks.
  49. There also might be additional data, for example for block devices.
  50. 1.1 Bringing up a ccw device
  51. ----------------------------
  52. This is done in several steps.
  53. a. Each driver can provide one or more parameter interfaces where parameters can
  54. be specified. These interfaces are also in the driver's responsibility.
  55. b. After a. has been performed, if necessary, the device is finally brought up
  56. via the 'online' interface.
  57. 1.2 Writing a driver for ccw devices
  58. ------------------------------------
  59. The basic struct ccw_device and struct ccw_driver data structures can be found
  60. under include/asm/ccwdev.h::
  61. struct ccw_device {
  62. spinlock_t *ccwlock;
  63. struct ccw_device_private *private;
  64. struct ccw_device_id id;
  65. struct ccw_driver *drv;
  66. struct device dev;
  67. int online;
  68. void (*handler) (struct ccw_device *dev, unsigned long intparm,
  69. struct irb *irb);
  70. };
  71. struct ccw_driver {
  72. struct module *owner;
  73. struct ccw_device_id *ids;
  74. int (*probe) (struct ccw_device *);
  75. int (*remove) (struct ccw_device *);
  76. int (*set_online) (struct ccw_device *);
  77. int (*set_offline) (struct ccw_device *);
  78. int (*notify) (struct ccw_device *, int);
  79. struct device_driver driver;
  80. char *name;
  81. };
  82. The 'private' field contains data needed for internal i/o operation only, and
  83. is not available to the device driver.
  84. Each driver should declare in a MODULE_DEVICE_TABLE into which CU types/models
  85. and/or device types/models it is interested. This information can later be found
  86. in the struct ccw_device_id fields::
  87. struct ccw_device_id {
  88. __u16 match_flags;
  89. __u16 cu_type;
  90. __u16 dev_type;
  91. __u8 cu_model;
  92. __u8 dev_model;
  93. unsigned long driver_info;
  94. };
  95. The functions in ccw_driver should be used in the following way:
  96. probe:
  97. This function is called by the device layer for each device the driver
  98. is interested in. The driver should only allocate private structures
  99. to put in dev->driver_data and create attributes (if needed). Also,
  100. the interrupt handler (see below) should be set here.
  101. ::
  102. int (*probe) (struct ccw_device *cdev);
  103. Parameters:
  104. cdev
  105. - the device to be probed.
  106. remove:
  107. This function is called by the device layer upon removal of the driver,
  108. the device or the module. The driver should perform cleanups here.
  109. ::
  110. int (*remove) (struct ccw_device *cdev);
  111. Parameters:
  112. cdev
  113. - the device to be removed.
  114. set_online:
  115. This function is called by the common I/O layer when the device is
  116. activated via the 'online' attribute. The driver should finally
  117. setup and activate the device here.
  118. ::
  119. int (*set_online) (struct ccw_device *);
  120. Parameters:
  121. cdev
  122. - the device to be activated. The common layer has
  123. verified that the device is not already online.
  124. set_offline: This function is called by the common I/O layer when the device is
  125. de-activated via the 'online' attribute. The driver should shut
  126. down the device, but not de-allocate its private data.
  127. ::
  128. int (*set_offline) (struct ccw_device *);
  129. Parameters:
  130. cdev
  131. - the device to be deactivated. The common layer has
  132. verified that the device is online.
  133. notify:
  134. This function is called by the common I/O layer for some state changes
  135. of the device.
  136. Signalled to the driver are:
  137. * In online state, device detached (CIO_GONE) or last path gone
  138. (CIO_NO_PATH). The driver must return !0 to keep the device; for
  139. return code 0, the device will be deleted as usual (also when no
  140. notify function is registered). If the driver wants to keep the
  141. device, it is moved into disconnected state.
  142. * In disconnected state, device operational again (CIO_OPER). The
  143. common I/O layer performs some sanity checks on device number and
  144. Device / CU to be reasonably sure if it is still the same device.
  145. If not, the old device is removed and a new one registered. By the
  146. return code of the notify function the device driver signals if it
  147. wants the device back: !0 for keeping, 0 to make the device being
  148. removed and re-registered.
  149. ::
  150. int (*notify) (struct ccw_device *, int);
  151. Parameters:
  152. cdev
  153. - the device whose state changed.
  154. event
  155. - the event that happened. This can be one of CIO_GONE,
  156. CIO_NO_PATH or CIO_OPER.
  157. The handler field of the struct ccw_device is meant to be set to the interrupt
  158. handler for the device. In order to accommodate drivers which use several
  159. distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device
  160. instead of ccw_driver.
  161. The handler is registered with the common layer during set_online() processing
  162. before the driver is called, and is deregistered during set_offline() after the
  163. driver has been called. Also, after registering / before deregistering, path
  164. grouping resp. disbanding of the path group (if applicable) are performed.
  165. ::
  166. void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);
  167. Parameters: dev - the device the handler is called for
  168. intparm - the intparm which allows the device driver to identify
  169. the i/o the interrupt is associated with, or to recognize
  170. the interrupt as unsolicited.
  171. irb - interruption response block which contains the accumulated
  172. status.
  173. The device driver is called from the common ccw_device layer and can retrieve
  174. information about the interrupt from the irb parameter.
  175. 1.3 ccwgroup devices
  176. --------------------
  177. The ccwgroup mechanism is designed to handle devices consisting of multiple ccw
  178. devices, like lcs or ctc.
  179. The ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to
  180. this attributes creates a ccwgroup device consisting of these ccw devices (if
  181. possible). This ccwgroup device can be set online or offline just like a normal
  182. ccw device.
  183. Each ccwgroup device also provides an 'ungroup' attribute to destroy the device
  184. again (only when offline). This is a generic ccwgroup mechanism (the driver does
  185. not need to implement anything beyond normal removal routines).
  186. A ccw device which is a member of a ccwgroup device carries a pointer to the
  187. ccwgroup device in the driver_data of its device struct. This field must not be
  188. touched by the driver - it should use the ccwgroup device's driver_data for its
  189. private data.
  190. To implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in
  191. mind that most drivers will need to implement both a ccwgroup and a ccw
  192. driver.
  193. 2. Channel paths
  194. -----------------
  195. Channel paths show up, like subchannels, under the channel subsystem root (css0)
  196. and are called 'chp0.<chpid>'. They have no driver and do not belong to any bus.
  197. Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect
  198. only the logical state and not the physical state, since we cannot track the
  199. latter consistently due to lacking machine support (we don't need to be aware
  200. of it anyway).
  201. status
  202. - Can be 'online' or 'offline'.
  203. Piping 'on' or 'off' sets the chpid logically online/offline.
  204. Piping 'on' to an online chpid triggers path reprobing for all devices
  205. the chpid connects to. This can be used to force the kernel to re-use
  206. a channel path the user knows to be online, but the machine hasn't
  207. created a machine check for.
  208. type
  209. - The physical type of the channel path.
  210. shared
  211. - Whether the channel path is shared.
  212. cmg
  213. - The channel measurement group.
  214. 3. System devices
  215. -----------------
  216. 3.1 xpram
  217. ---------
  218. xpram shows up under devices/system/ as 'xpram'.
  219. 3.2 cpus
  220. --------
  221. For each cpu, a directory is created under devices/system/cpu/. Each cpu has an
  222. attribute 'online' which can be 0 or 1.
  223. 4. Other devices
  224. ----------------
  225. 4.1 Netiucv
  226. -----------
  227. The netiucv driver creates an attribute 'connection' under
  228. bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv
  229. connection to the specified host.
  230. Netiucv connections show up under devices/iucv/ as "netiucv<ifnum>". The interface
  231. number is assigned sequentially to the connections defined via the 'connection'
  232. attribute.
  233. user
  234. - shows the connection partner.
  235. buffer
  236. - maximum buffer size. Pipe to it to change buffer size.