transport_class.c 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284
  1. // SPDX-License-Identifier: GPL-2.0
  2. /*
  3. * transport_class.c - implementation of generic transport classes
  4. * using attribute_containers
  5. *
  6. * Copyright (c) 2005 - James Bottomley <James.Bottomley@steeleye.com>
  7. *
  8. * The basic idea here is to allow any "device controller" (which
  9. * would most often be a Host Bus Adapter to use the services of one
  10. * or more tranport classes for performing transport specific
  11. * services. Transport specific services are things that the generic
  12. * command layer doesn't want to know about (speed settings, line
  13. * condidtioning, etc), but which the user might be interested in.
  14. * Thus, the HBA's use the routines exported by the transport classes
  15. * to perform these functions. The transport classes export certain
  16. * values to the user via sysfs using attribute containers.
  17. *
  18. * Note: because not every HBA will care about every transport
  19. * attribute, there's a many to one relationship that goes like this:
  20. *
  21. * transport class<-----attribute container<----class device
  22. *
  23. * Usually the attribute container is per-HBA, but the design doesn't
  24. * mandate that. Although most of the services will be specific to
  25. * the actual external storage connection used by the HBA, the generic
  26. * transport class is framed entirely in terms of generic devices to
  27. * allow it to be used by any physical HBA in the system.
  28. */
  29. #include <linux/export.h>
  30. #include <linux/attribute_container.h>
  31. #include <linux/transport_class.h>
  32. static int transport_remove_classdev(struct attribute_container *cont,
  33. struct device *dev,
  34. struct device *classdev);
  35. /**
  36. * transport_class_register - register an initial transport class
  37. *
  38. * @tclass: a pointer to the transport class structure to be initialised
  39. *
  40. * The transport class contains an embedded class which is used to
  41. * identify it. The caller should initialise this structure with
  42. * zeros and then generic class must have been initialised with the
  43. * actual transport class unique name. There's a macro
  44. * DECLARE_TRANSPORT_CLASS() to do this (declared classes still must
  45. * be registered).
  46. *
  47. * Returns 0 on success or error on failure.
  48. */
  49. int transport_class_register(struct transport_class *tclass)
  50. {
  51. return class_register(&tclass->class);
  52. }
  53. EXPORT_SYMBOL_GPL(transport_class_register);
  54. /**
  55. * transport_class_unregister - unregister a previously registered class
  56. *
  57. * @tclass: The transport class to unregister
  58. *
  59. * Must be called prior to deallocating the memory for the transport
  60. * class.
  61. */
  62. void transport_class_unregister(struct transport_class *tclass)
  63. {
  64. class_unregister(&tclass->class);
  65. }
  66. EXPORT_SYMBOL_GPL(transport_class_unregister);
  67. static int anon_transport_dummy_function(struct transport_container *tc,
  68. struct device *dev,
  69. struct device *cdev)
  70. {
  71. /* do nothing */
  72. return 0;
  73. }
  74. /**
  75. * anon_transport_class_register - register an anonymous class
  76. *
  77. * @atc: The anon transport class to register
  78. *
  79. * The anonymous transport class contains both a transport class and a
  80. * container. The idea of an anonymous class is that it never
  81. * actually has any device attributes associated with it (and thus
  82. * saves on container storage). So it can only be used for triggering
  83. * events. Use prezero and then use DECLARE_ANON_TRANSPORT_CLASS() to
  84. * initialise the anon transport class storage.
  85. */
  86. int anon_transport_class_register(struct anon_transport_class *atc)
  87. {
  88. int error;
  89. atc->container.class = &atc->tclass.class;
  90. attribute_container_set_no_classdevs(&atc->container);
  91. error = attribute_container_register(&atc->container);
  92. if (error)
  93. return error;
  94. atc->tclass.setup = anon_transport_dummy_function;
  95. atc->tclass.remove = anon_transport_dummy_function;
  96. return 0;
  97. }
  98. EXPORT_SYMBOL_GPL(anon_transport_class_register);
  99. /**
  100. * anon_transport_class_unregister - unregister an anon class
  101. *
  102. * @atc: Pointer to the anon transport class to unregister
  103. *
  104. * Must be called prior to deallocating the memory for the anon
  105. * transport class.
  106. */
  107. void anon_transport_class_unregister(struct anon_transport_class *atc)
  108. {
  109. if (unlikely(attribute_container_unregister(&atc->container)))
  110. BUG();
  111. }
  112. EXPORT_SYMBOL_GPL(anon_transport_class_unregister);
  113. static int transport_setup_classdev(struct attribute_container *cont,
  114. struct device *dev,
  115. struct device *classdev)
  116. {
  117. struct transport_class *tclass = class_to_transport_class(cont->class);
  118. struct transport_container *tcont = attribute_container_to_transport_container(cont);
  119. if (tclass->setup)
  120. tclass->setup(tcont, dev, classdev);
  121. return 0;
  122. }
  123. /**
  124. * transport_setup_device - declare a new dev for transport class association but don't make it visible yet.
  125. * @dev: the generic device representing the entity being added
  126. *
  127. * Usually, dev represents some component in the HBA system (either
  128. * the HBA itself or a device remote across the HBA bus). This
  129. * routine is simply a trigger point to see if any set of transport
  130. * classes wishes to associate with the added device. This allocates
  131. * storage for the class device and initialises it, but does not yet
  132. * add it to the system or add attributes to it (you do this with
  133. * transport_add_device). If you have no need for a separate setup
  134. * and add operations, use transport_register_device (see
  135. * transport_class.h).
  136. */
  137. void transport_setup_device(struct device *dev)
  138. {
  139. attribute_container_add_device(dev, transport_setup_classdev);
  140. }
  141. EXPORT_SYMBOL_GPL(transport_setup_device);
  142. static int transport_add_class_device(struct attribute_container *cont,
  143. struct device *dev,
  144. struct device *classdev)
  145. {
  146. int error = attribute_container_add_class_device(classdev);
  147. struct transport_container *tcont =
  148. attribute_container_to_transport_container(cont);
  149. if (!error && tcont->statistics)
  150. error = sysfs_create_group(&classdev->kobj, tcont->statistics);
  151. return error;
  152. }
  153. /**
  154. * transport_add_device - declare a new dev for transport class association
  155. *
  156. * @dev: the generic device representing the entity being added
  157. *
  158. * Usually, dev represents some component in the HBA system (either
  159. * the HBA itself or a device remote across the HBA bus). This
  160. * routine is simply a trigger point used to add the device to the
  161. * system and register attributes for it.
  162. */
  163. int transport_add_device(struct device *dev)
  164. {
  165. return attribute_container_device_trigger_safe(dev,
  166. transport_add_class_device,
  167. transport_remove_classdev);
  168. }
  169. EXPORT_SYMBOL_GPL(transport_add_device);
  170. static int transport_configure(struct attribute_container *cont,
  171. struct device *dev,
  172. struct device *cdev)
  173. {
  174. struct transport_class *tclass = class_to_transport_class(cont->class);
  175. struct transport_container *tcont = attribute_container_to_transport_container(cont);
  176. if (tclass->configure)
  177. tclass->configure(tcont, dev, cdev);
  178. return 0;
  179. }
  180. /**
  181. * transport_configure_device - configure an already set up device
  182. *
  183. * @dev: generic device representing device to be configured
  184. *
  185. * The idea of configure is simply to provide a point within the setup
  186. * process to allow the transport class to extract information from a
  187. * device after it has been setup. This is used in SCSI because we
  188. * have to have a setup device to begin using the HBA, but after we
  189. * send the initial inquiry, we use configure to extract the device
  190. * parameters. The device need not have been added to be configured.
  191. */
  192. void transport_configure_device(struct device *dev)
  193. {
  194. attribute_container_device_trigger(dev, transport_configure);
  195. }
  196. EXPORT_SYMBOL_GPL(transport_configure_device);
  197. static int transport_remove_classdev(struct attribute_container *cont,
  198. struct device *dev,
  199. struct device *classdev)
  200. {
  201. struct transport_container *tcont =
  202. attribute_container_to_transport_container(cont);
  203. struct transport_class *tclass = class_to_transport_class(cont->class);
  204. if (tclass->remove)
  205. tclass->remove(tcont, dev, classdev);
  206. if (tclass->remove != anon_transport_dummy_function) {
  207. if (tcont->statistics)
  208. sysfs_remove_group(&classdev->kobj, tcont->statistics);
  209. attribute_container_class_device_del(classdev);
  210. }
  211. return 0;
  212. }
  213. /**
  214. * transport_remove_device - remove the visibility of a device
  215. *
  216. * @dev: generic device to remove
  217. *
  218. * This call removes the visibility of the device (to the user from
  219. * sysfs), but does not destroy it. To eliminate a device entirely
  220. * you must also call transport_destroy_device. If you don't need to
  221. * do remove and destroy as separate operations, use
  222. * transport_unregister_device() (see transport_class.h) which will
  223. * perform both calls for you.
  224. */
  225. void transport_remove_device(struct device *dev)
  226. {
  227. attribute_container_device_trigger(dev, transport_remove_classdev);
  228. }
  229. EXPORT_SYMBOL_GPL(transport_remove_device);
  230. static void transport_destroy_classdev(struct attribute_container *cont,
  231. struct device *dev,
  232. struct device *classdev)
  233. {
  234. struct transport_class *tclass = class_to_transport_class(cont->class);
  235. if (tclass->remove != anon_transport_dummy_function)
  236. put_device(classdev);
  237. }
  238. /**
  239. * transport_destroy_device - destroy a removed device
  240. *
  241. * @dev: device to eliminate from the transport class.
  242. *
  243. * This call triggers the elimination of storage associated with the
  244. * transport classdev. Note: all it really does is relinquish a
  245. * reference to the classdev. The memory will not be freed until the
  246. * last reference goes to zero. Note also that the classdev retains a
  247. * reference count on dev, so dev too will remain for as long as the
  248. * transport class device remains around.
  249. */
  250. void transport_destroy_device(struct device *dev)
  251. {
  252. attribute_container_remove_device(dev, transport_destroy_classdev);
  253. }
  254. EXPORT_SYMBOL_GPL(transport_destroy_device);