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