Loading...
1// SPDX-License-Identifier: GPL-2.0+
2/*
3 * Surface System Aggregator Module bus and device integration.
4 *
5 * Copyright (C) 2019-2022 Maximilian Luz <luzmaximilian@gmail.com>
6 */
7
8#include <linux/device.h>
9#include <linux/of.h>
10#include <linux/property.h>
11#include <linux/slab.h>
12
13#include <linux/surface_aggregator/controller.h>
14#include <linux/surface_aggregator/device.h>
15
16#include "bus.h"
17#include "controller.h"
18
19
20/* -- Device and bus functions. --------------------------------------------- */
21
22static ssize_t modalias_show(struct device *dev, struct device_attribute *attr,
23 char *buf)
24{
25 struct ssam_device *sdev = to_ssam_device(dev);
26
27 return sysfs_emit(buf, "ssam:d%02Xc%02Xt%02Xi%02Xf%02X\n",
28 sdev->uid.domain, sdev->uid.category, sdev->uid.target,
29 sdev->uid.instance, sdev->uid.function);
30}
31static DEVICE_ATTR_RO(modalias);
32
33static struct attribute *ssam_device_attrs[] = {
34 &dev_attr_modalias.attr,
35 NULL,
36};
37ATTRIBUTE_GROUPS(ssam_device);
38
39static const struct bus_type ssam_bus_type;
40
41static int ssam_device_uevent(const struct device *dev, struct kobj_uevent_env *env)
42{
43 const struct ssam_device *sdev = to_ssam_device(dev);
44
45 return add_uevent_var(env, "MODALIAS=ssam:d%02Xc%02Xt%02Xi%02Xf%02X",
46 sdev->uid.domain, sdev->uid.category,
47 sdev->uid.target, sdev->uid.instance,
48 sdev->uid.function);
49}
50
51static void ssam_device_release(struct device *dev)
52{
53 struct ssam_device *sdev = to_ssam_device(dev);
54
55 ssam_controller_put(sdev->ctrl);
56 fwnode_handle_put(sdev->dev.fwnode);
57 kfree(sdev);
58}
59
60const struct device_type ssam_device_type = {
61 .name = "surface_aggregator_device",
62 .groups = ssam_device_groups,
63 .uevent = ssam_device_uevent,
64 .release = ssam_device_release,
65};
66EXPORT_SYMBOL_GPL(ssam_device_type);
67
68/**
69 * ssam_device_alloc() - Allocate and initialize a SSAM client device.
70 * @ctrl: The controller under which the device should be added.
71 * @uid: The UID of the device to be added.
72 *
73 * Allocates and initializes a new client device. The parent of the device
74 * will be set to the controller device and the name will be set based on the
75 * UID. Note that the device still has to be added via ssam_device_add().
76 * Refer to that function for more details.
77 *
78 * Return: Returns the newly allocated and initialized SSAM client device, or
79 * %NULL if it could not be allocated.
80 */
81struct ssam_device *ssam_device_alloc(struct ssam_controller *ctrl,
82 struct ssam_device_uid uid)
83{
84 struct ssam_device *sdev;
85
86 sdev = kzalloc(sizeof(*sdev), GFP_KERNEL);
87 if (!sdev)
88 return NULL;
89
90 device_initialize(&sdev->dev);
91 sdev->dev.bus = &ssam_bus_type;
92 sdev->dev.type = &ssam_device_type;
93 sdev->dev.parent = ssam_controller_device(ctrl);
94 sdev->ctrl = ssam_controller_get(ctrl);
95 sdev->uid = uid;
96
97 dev_set_name(&sdev->dev, "%02x:%02x:%02x:%02x:%02x",
98 sdev->uid.domain, sdev->uid.category, sdev->uid.target,
99 sdev->uid.instance, sdev->uid.function);
100
101 return sdev;
102}
103EXPORT_SYMBOL_GPL(ssam_device_alloc);
104
105/**
106 * ssam_device_add() - Add a SSAM client device.
107 * @sdev: The SSAM client device to be added.
108 *
109 * Added client devices must be guaranteed to always have a valid and active
110 * controller. Thus, this function will fail with %-ENODEV if the controller
111 * of the device has not been initialized yet, has been suspended, or has been
112 * shut down.
113 *
114 * The caller of this function should ensure that the corresponding call to
115 * ssam_device_remove() is issued before the controller is shut down. If the
116 * added device is a direct child of the controller device (default), it will
117 * be automatically removed when the controller is shut down.
118 *
119 * By default, the controller device will become the parent of the newly
120 * created client device. The parent may be changed before ssam_device_add is
121 * called, but care must be taken that a) the correct suspend/resume ordering
122 * is guaranteed and b) the client device does not outlive the controller,
123 * i.e. that the device is removed before the controller is being shut down.
124 * In case these guarantees have to be manually enforced, please refer to the
125 * ssam_client_link() and ssam_client_bind() functions, which are intended to
126 * set up device-links for this purpose.
127 *
128 * Return: Returns zero on success, a negative error code on failure.
129 */
130int ssam_device_add(struct ssam_device *sdev)
131{
132 int status;
133
134 /*
135 * Ensure that we can only add new devices to a controller if it has
136 * been started and is not going away soon. This works in combination
137 * with ssam_controller_remove_clients to ensure driver presence for the
138 * controller device, i.e. it ensures that the controller (sdev->ctrl)
139 * is always valid and can be used for requests as long as the client
140 * device we add here is registered as child under it. This essentially
141 * guarantees that the client driver can always expect the preconditions
142 * for functions like ssam_request_do_sync() (controller has to be
143 * started and is not suspended) to hold and thus does not have to check
144 * for them.
145 *
146 * Note that for this to work, the controller has to be a parent device.
147 * If it is not a direct parent, care has to be taken that the device is
148 * removed via ssam_device_remove(), as device_unregister does not
149 * remove child devices recursively.
150 */
151 ssam_controller_statelock(sdev->ctrl);
152
153 if (sdev->ctrl->state != SSAM_CONTROLLER_STARTED) {
154 ssam_controller_stateunlock(sdev->ctrl);
155 return -ENODEV;
156 }
157
158 status = device_add(&sdev->dev);
159
160 ssam_controller_stateunlock(sdev->ctrl);
161 return status;
162}
163EXPORT_SYMBOL_GPL(ssam_device_add);
164
165/**
166 * ssam_device_remove() - Remove a SSAM client device.
167 * @sdev: The device to remove.
168 *
169 * Removes and unregisters the provided SSAM client device.
170 */
171void ssam_device_remove(struct ssam_device *sdev)
172{
173 device_unregister(&sdev->dev);
174}
175EXPORT_SYMBOL_GPL(ssam_device_remove);
176
177/**
178 * ssam_device_id_compatible() - Check if a device ID matches a UID.
179 * @id: The device ID as potential match.
180 * @uid: The device UID matching against.
181 *
182 * Check if the given ID is a match for the given UID, i.e. if a device with
183 * the provided UID is compatible to the given ID following the match rules
184 * described in its &ssam_device_id.match_flags member.
185 *
186 * Return: Returns %true if the given UID is compatible to the match rule
187 * described by the given ID, %false otherwise.
188 */
189static bool ssam_device_id_compatible(const struct ssam_device_id *id,
190 struct ssam_device_uid uid)
191{
192 if (id->domain != uid.domain || id->category != uid.category)
193 return false;
194
195 if ((id->match_flags & SSAM_MATCH_TARGET) && id->target != uid.target)
196 return false;
197
198 if ((id->match_flags & SSAM_MATCH_INSTANCE) && id->instance != uid.instance)
199 return false;
200
201 if ((id->match_flags & SSAM_MATCH_FUNCTION) && id->function != uid.function)
202 return false;
203
204 return true;
205}
206
207/**
208 * ssam_device_id_is_null() - Check if a device ID is null.
209 * @id: The device ID to check.
210 *
211 * Check if a given device ID is null, i.e. all zeros. Used to check for the
212 * end of ``MODULE_DEVICE_TABLE(ssam, ...)`` or similar lists.
213 *
214 * Return: Returns %true if the given ID represents a null ID, %false
215 * otherwise.
216 */
217static bool ssam_device_id_is_null(const struct ssam_device_id *id)
218{
219 return id->match_flags == 0 &&
220 id->domain == 0 &&
221 id->category == 0 &&
222 id->target == 0 &&
223 id->instance == 0 &&
224 id->function == 0 &&
225 id->driver_data == 0;
226}
227
228/**
229 * ssam_device_id_match() - Find the matching ID table entry for the given UID.
230 * @table: The table to search in.
231 * @uid: The UID to matched against the individual table entries.
232 *
233 * Find the first match for the provided device UID in the provided ID table
234 * and return it. Returns %NULL if no match could be found.
235 */
236const struct ssam_device_id *ssam_device_id_match(const struct ssam_device_id *table,
237 const struct ssam_device_uid uid)
238{
239 const struct ssam_device_id *id;
240
241 for (id = table; !ssam_device_id_is_null(id); ++id)
242 if (ssam_device_id_compatible(id, uid))
243 return id;
244
245 return NULL;
246}
247EXPORT_SYMBOL_GPL(ssam_device_id_match);
248
249/**
250 * ssam_device_get_match() - Find and return the ID matching the device in the
251 * ID table of the bound driver.
252 * @dev: The device for which to get the matching ID table entry.
253 *
254 * Find the fist match for the UID of the device in the ID table of the
255 * currently bound driver and return it. Returns %NULL if the device does not
256 * have a driver bound to it, the driver does not have match_table (i.e. it is
257 * %NULL), or there is no match in the driver's match_table.
258 *
259 * This function essentially calls ssam_device_id_match() with the ID table of
260 * the bound device driver and the UID of the device.
261 *
262 * Return: Returns the first match for the UID of the device in the device
263 * driver's match table, or %NULL if no such match could be found.
264 */
265const struct ssam_device_id *ssam_device_get_match(const struct ssam_device *dev)
266{
267 const struct ssam_device_driver *sdrv;
268
269 sdrv = to_ssam_device_driver(dev->dev.driver);
270 if (!sdrv)
271 return NULL;
272
273 if (!sdrv->match_table)
274 return NULL;
275
276 return ssam_device_id_match(sdrv->match_table, dev->uid);
277}
278EXPORT_SYMBOL_GPL(ssam_device_get_match);
279
280/**
281 * ssam_device_get_match_data() - Find the ID matching the device in the
282 * ID table of the bound driver and return its ``driver_data`` member.
283 * @dev: The device for which to get the match data.
284 *
285 * Find the fist match for the UID of the device in the ID table of the
286 * corresponding driver and return its driver_data. Returns %NULL if the
287 * device does not have a driver bound to it, the driver does not have
288 * match_table (i.e. it is %NULL), there is no match in the driver's
289 * match_table, or the match does not have any driver_data.
290 *
291 * This function essentially calls ssam_device_get_match() and, if any match
292 * could be found, returns its ``struct ssam_device_id.driver_data`` member.
293 *
294 * Return: Returns the driver data associated with the first match for the UID
295 * of the device in the device driver's match table, or %NULL if no such match
296 * could be found.
297 */
298const void *ssam_device_get_match_data(const struct ssam_device *dev)
299{
300 const struct ssam_device_id *id;
301
302 id = ssam_device_get_match(dev);
303 if (!id)
304 return NULL;
305
306 return (const void *)id->driver_data;
307}
308EXPORT_SYMBOL_GPL(ssam_device_get_match_data);
309
310static int ssam_bus_match(struct device *dev, const struct device_driver *drv)
311{
312 const struct ssam_device_driver *sdrv = to_ssam_device_driver(drv);
313 struct ssam_device *sdev = to_ssam_device(dev);
314
315 if (!is_ssam_device(dev))
316 return 0;
317
318 return !!ssam_device_id_match(sdrv->match_table, sdev->uid);
319}
320
321static int ssam_bus_probe(struct device *dev)
322{
323 return to_ssam_device_driver(dev->driver)
324 ->probe(to_ssam_device(dev));
325}
326
327static void ssam_bus_remove(struct device *dev)
328{
329 struct ssam_device_driver *sdrv = to_ssam_device_driver(dev->driver);
330
331 if (sdrv->remove)
332 sdrv->remove(to_ssam_device(dev));
333}
334
335static const struct bus_type ssam_bus_type = {
336 .name = "surface_aggregator",
337 .match = ssam_bus_match,
338 .probe = ssam_bus_probe,
339 .remove = ssam_bus_remove,
340};
341
342/**
343 * __ssam_device_driver_register() - Register a SSAM client device driver.
344 * @sdrv: The driver to register.
345 * @owner: The module owning the provided driver.
346 *
347 * Please refer to the ssam_device_driver_register() macro for the normal way
348 * to register a driver from inside its owning module.
349 */
350int __ssam_device_driver_register(struct ssam_device_driver *sdrv,
351 struct module *owner)
352{
353 sdrv->driver.owner = owner;
354 sdrv->driver.bus = &ssam_bus_type;
355
356 /* force drivers to async probe so I/O is possible in probe */
357 sdrv->driver.probe_type = PROBE_PREFER_ASYNCHRONOUS;
358
359 return driver_register(&sdrv->driver);
360}
361EXPORT_SYMBOL_GPL(__ssam_device_driver_register);
362
363/**
364 * ssam_device_driver_unregister - Unregister a SSAM device driver.
365 * @sdrv: The driver to unregister.
366 */
367void ssam_device_driver_unregister(struct ssam_device_driver *sdrv)
368{
369 driver_unregister(&sdrv->driver);
370}
371EXPORT_SYMBOL_GPL(ssam_device_driver_unregister);
372
373
374/* -- Bus registration. ----------------------------------------------------- */
375
376/**
377 * ssam_bus_register() - Register and set-up the SSAM client device bus.
378 */
379int ssam_bus_register(void)
380{
381 return bus_register(&ssam_bus_type);
382}
383
384/**
385 * ssam_bus_unregister() - Unregister the SSAM client device bus.
386 */
387void ssam_bus_unregister(void)
388{
389 return bus_unregister(&ssam_bus_type);
390}
391
392
393/* -- Helpers for controller and hub devices. ------------------------------- */
394
395static int ssam_device_uid_from_string(const char *str, struct ssam_device_uid *uid)
396{
397 u8 d, tc, tid, iid, fn;
398 int n;
399
400 n = sscanf(str, "%hhx:%hhx:%hhx:%hhx:%hhx", &d, &tc, &tid, &iid, &fn);
401 if (n != 5)
402 return -EINVAL;
403
404 uid->domain = d;
405 uid->category = tc;
406 uid->target = tid;
407 uid->instance = iid;
408 uid->function = fn;
409
410 return 0;
411}
412
413static int ssam_get_uid_for_node(struct fwnode_handle *node, struct ssam_device_uid *uid)
414{
415 const char *str = fwnode_get_name(node);
416
417 /*
418 * To simplify definitions of firmware nodes, we set the device name
419 * based on the UID of the device, prefixed with "ssam:".
420 */
421 if (strncmp(str, "ssam:", strlen("ssam:")) != 0)
422 return -ENODEV;
423
424 str += strlen("ssam:");
425 return ssam_device_uid_from_string(str, uid);
426}
427
428static int ssam_add_client_device(struct device *parent, struct ssam_controller *ctrl,
429 struct fwnode_handle *node)
430{
431 struct ssam_device_uid uid;
432 struct ssam_device *sdev;
433 int status;
434
435 status = ssam_get_uid_for_node(node, &uid);
436 if (status)
437 return status;
438
439 sdev = ssam_device_alloc(ctrl, uid);
440 if (!sdev)
441 return -ENOMEM;
442
443 sdev->dev.parent = parent;
444 sdev->dev.fwnode = fwnode_handle_get(node);
445 sdev->dev.of_node = to_of_node(node);
446
447 status = ssam_device_add(sdev);
448 if (status)
449 ssam_device_put(sdev);
450
451 return status;
452}
453
454/**
455 * __ssam_register_clients() - Register client devices defined under the
456 * given firmware node as children of the given device.
457 * @parent: The parent device under which clients should be registered.
458 * @ctrl: The controller with which client should be registered.
459 * @node: The firmware node holding definitions of the devices to be added.
460 *
461 * Register all clients that have been defined as children of the given root
462 * firmware node as children of the given parent device. The respective child
463 * firmware nodes will be associated with the correspondingly created child
464 * devices.
465 *
466 * The given controller will be used to instantiate the new devices. See
467 * ssam_device_add() for details.
468 *
469 * Note that, generally, the use of either ssam_device_register_clients() or
470 * ssam_register_clients() should be preferred as they directly use the
471 * firmware node and/or controller associated with the given device. This
472 * function is only intended for use when different device specifications (e.g.
473 * ACPI and firmware nodes) need to be combined (as is done in the platform hub
474 * of the device registry).
475 *
476 * Return: Returns zero on success, nonzero on failure.
477 */
478int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl,
479 struct fwnode_handle *node)
480{
481 struct fwnode_handle *child;
482 int status;
483
484 fwnode_for_each_child_node(node, child) {
485 /*
486 * Try to add the device specified in the firmware node. If
487 * this fails with -ENODEV, the node does not specify any SSAM
488 * device, so ignore it and continue with the next one.
489 */
490 status = ssam_add_client_device(parent, ctrl, child);
491 if (status && status != -ENODEV) {
492 fwnode_handle_put(child);
493 goto err;
494 }
495 }
496
497 return 0;
498err:
499 ssam_remove_clients(parent);
500 return status;
501}
502EXPORT_SYMBOL_GPL(__ssam_register_clients);
503
504static int ssam_remove_device(struct device *dev, void *_data)
505{
506 struct ssam_device *sdev = to_ssam_device(dev);
507
508 if (is_ssam_device(dev))
509 ssam_device_remove(sdev);
510
511 return 0;
512}
513
514/**
515 * ssam_remove_clients() - Remove SSAM client devices registered as direct
516 * children under the given parent device.
517 * @dev: The (parent) device to remove all direct clients for.
518 *
519 * Remove all SSAM client devices registered as direct children under the given
520 * device. Note that this only accounts for direct children of the device.
521 * Refer to ssam_device_add()/ssam_device_remove() for more details.
522 */
523void ssam_remove_clients(struct device *dev)
524{
525 device_for_each_child_reverse(dev, NULL, ssam_remove_device);
526}
527EXPORT_SYMBOL_GPL(ssam_remove_clients);
1// SPDX-License-Identifier: GPL-2.0+
2/*
3 * Surface System Aggregator Module bus and device integration.
4 *
5 * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com>
6 */
7
8#include <linux/device.h>
9#include <linux/slab.h>
10
11#include <linux/surface_aggregator/controller.h>
12#include <linux/surface_aggregator/device.h>
13
14#include "bus.h"
15#include "controller.h"
16
17static ssize_t modalias_show(struct device *dev, struct device_attribute *attr,
18 char *buf)
19{
20 struct ssam_device *sdev = to_ssam_device(dev);
21
22 return sysfs_emit(buf, "ssam:d%02Xc%02Xt%02Xi%02Xf%02X\n",
23 sdev->uid.domain, sdev->uid.category, sdev->uid.target,
24 sdev->uid.instance, sdev->uid.function);
25}
26static DEVICE_ATTR_RO(modalias);
27
28static struct attribute *ssam_device_attrs[] = {
29 &dev_attr_modalias.attr,
30 NULL,
31};
32ATTRIBUTE_GROUPS(ssam_device);
33
34static int ssam_device_uevent(struct device *dev, struct kobj_uevent_env *env)
35{
36 struct ssam_device *sdev = to_ssam_device(dev);
37
38 return add_uevent_var(env, "MODALIAS=ssam:d%02Xc%02Xt%02Xi%02Xf%02X",
39 sdev->uid.domain, sdev->uid.category,
40 sdev->uid.target, sdev->uid.instance,
41 sdev->uid.function);
42}
43
44static void ssam_device_release(struct device *dev)
45{
46 struct ssam_device *sdev = to_ssam_device(dev);
47
48 ssam_controller_put(sdev->ctrl);
49 kfree(sdev);
50}
51
52const struct device_type ssam_device_type = {
53 .name = "surface_aggregator_device",
54 .groups = ssam_device_groups,
55 .uevent = ssam_device_uevent,
56 .release = ssam_device_release,
57};
58EXPORT_SYMBOL_GPL(ssam_device_type);
59
60/**
61 * ssam_device_alloc() - Allocate and initialize a SSAM client device.
62 * @ctrl: The controller under which the device should be added.
63 * @uid: The UID of the device to be added.
64 *
65 * Allocates and initializes a new client device. The parent of the device
66 * will be set to the controller device and the name will be set based on the
67 * UID. Note that the device still has to be added via ssam_device_add().
68 * Refer to that function for more details.
69 *
70 * Return: Returns the newly allocated and initialized SSAM client device, or
71 * %NULL if it could not be allocated.
72 */
73struct ssam_device *ssam_device_alloc(struct ssam_controller *ctrl,
74 struct ssam_device_uid uid)
75{
76 struct ssam_device *sdev;
77
78 sdev = kzalloc(sizeof(*sdev), GFP_KERNEL);
79 if (!sdev)
80 return NULL;
81
82 device_initialize(&sdev->dev);
83 sdev->dev.bus = &ssam_bus_type;
84 sdev->dev.type = &ssam_device_type;
85 sdev->dev.parent = ssam_controller_device(ctrl);
86 sdev->ctrl = ssam_controller_get(ctrl);
87 sdev->uid = uid;
88
89 dev_set_name(&sdev->dev, "%02x:%02x:%02x:%02x:%02x",
90 sdev->uid.domain, sdev->uid.category, sdev->uid.target,
91 sdev->uid.instance, sdev->uid.function);
92
93 return sdev;
94}
95EXPORT_SYMBOL_GPL(ssam_device_alloc);
96
97/**
98 * ssam_device_add() - Add a SSAM client device.
99 * @sdev: The SSAM client device to be added.
100 *
101 * Added client devices must be guaranteed to always have a valid and active
102 * controller. Thus, this function will fail with %-ENODEV if the controller
103 * of the device has not been initialized yet, has been suspended, or has been
104 * shut down.
105 *
106 * The caller of this function should ensure that the corresponding call to
107 * ssam_device_remove() is issued before the controller is shut down. If the
108 * added device is a direct child of the controller device (default), it will
109 * be automatically removed when the controller is shut down.
110 *
111 * By default, the controller device will become the parent of the newly
112 * created client device. The parent may be changed before ssam_device_add is
113 * called, but care must be taken that a) the correct suspend/resume ordering
114 * is guaranteed and b) the client device does not outlive the controller,
115 * i.e. that the device is removed before the controller is being shut down.
116 * In case these guarantees have to be manually enforced, please refer to the
117 * ssam_client_link() and ssam_client_bind() functions, which are intended to
118 * set up device-links for this purpose.
119 *
120 * Return: Returns zero on success, a negative error code on failure.
121 */
122int ssam_device_add(struct ssam_device *sdev)
123{
124 int status;
125
126 /*
127 * Ensure that we can only add new devices to a controller if it has
128 * been started and is not going away soon. This works in combination
129 * with ssam_controller_remove_clients to ensure driver presence for the
130 * controller device, i.e. it ensures that the controller (sdev->ctrl)
131 * is always valid and can be used for requests as long as the client
132 * device we add here is registered as child under it. This essentially
133 * guarantees that the client driver can always expect the preconditions
134 * for functions like ssam_request_sync (controller has to be started
135 * and is not suspended) to hold and thus does not have to check for
136 * them.
137 *
138 * Note that for this to work, the controller has to be a parent device.
139 * If it is not a direct parent, care has to be taken that the device is
140 * removed via ssam_device_remove(), as device_unregister does not
141 * remove child devices recursively.
142 */
143 ssam_controller_statelock(sdev->ctrl);
144
145 if (sdev->ctrl->state != SSAM_CONTROLLER_STARTED) {
146 ssam_controller_stateunlock(sdev->ctrl);
147 return -ENODEV;
148 }
149
150 status = device_add(&sdev->dev);
151
152 ssam_controller_stateunlock(sdev->ctrl);
153 return status;
154}
155EXPORT_SYMBOL_GPL(ssam_device_add);
156
157/**
158 * ssam_device_remove() - Remove a SSAM client device.
159 * @sdev: The device to remove.
160 *
161 * Removes and unregisters the provided SSAM client device.
162 */
163void ssam_device_remove(struct ssam_device *sdev)
164{
165 device_unregister(&sdev->dev);
166}
167EXPORT_SYMBOL_GPL(ssam_device_remove);
168
169/**
170 * ssam_device_id_compatible() - Check if a device ID matches a UID.
171 * @id: The device ID as potential match.
172 * @uid: The device UID matching against.
173 *
174 * Check if the given ID is a match for the given UID, i.e. if a device with
175 * the provided UID is compatible to the given ID following the match rules
176 * described in its &ssam_device_id.match_flags member.
177 *
178 * Return: Returns %true if the given UID is compatible to the match rule
179 * described by the given ID, %false otherwise.
180 */
181static bool ssam_device_id_compatible(const struct ssam_device_id *id,
182 struct ssam_device_uid uid)
183{
184 if (id->domain != uid.domain || id->category != uid.category)
185 return false;
186
187 if ((id->match_flags & SSAM_MATCH_TARGET) && id->target != uid.target)
188 return false;
189
190 if ((id->match_flags & SSAM_MATCH_INSTANCE) && id->instance != uid.instance)
191 return false;
192
193 if ((id->match_flags & SSAM_MATCH_FUNCTION) && id->function != uid.function)
194 return false;
195
196 return true;
197}
198
199/**
200 * ssam_device_id_is_null() - Check if a device ID is null.
201 * @id: The device ID to check.
202 *
203 * Check if a given device ID is null, i.e. all zeros. Used to check for the
204 * end of ``MODULE_DEVICE_TABLE(ssam, ...)`` or similar lists.
205 *
206 * Return: Returns %true if the given ID represents a null ID, %false
207 * otherwise.
208 */
209static bool ssam_device_id_is_null(const struct ssam_device_id *id)
210{
211 return id->match_flags == 0 &&
212 id->domain == 0 &&
213 id->category == 0 &&
214 id->target == 0 &&
215 id->instance == 0 &&
216 id->function == 0 &&
217 id->driver_data == 0;
218}
219
220/**
221 * ssam_device_id_match() - Find the matching ID table entry for the given UID.
222 * @table: The table to search in.
223 * @uid: The UID to matched against the individual table entries.
224 *
225 * Find the first match for the provided device UID in the provided ID table
226 * and return it. Returns %NULL if no match could be found.
227 */
228const struct ssam_device_id *ssam_device_id_match(const struct ssam_device_id *table,
229 const struct ssam_device_uid uid)
230{
231 const struct ssam_device_id *id;
232
233 for (id = table; !ssam_device_id_is_null(id); ++id)
234 if (ssam_device_id_compatible(id, uid))
235 return id;
236
237 return NULL;
238}
239EXPORT_SYMBOL_GPL(ssam_device_id_match);
240
241/**
242 * ssam_device_get_match() - Find and return the ID matching the device in the
243 * ID table of the bound driver.
244 * @dev: The device for which to get the matching ID table entry.
245 *
246 * Find the fist match for the UID of the device in the ID table of the
247 * currently bound driver and return it. Returns %NULL if the device does not
248 * have a driver bound to it, the driver does not have match_table (i.e. it is
249 * %NULL), or there is no match in the driver's match_table.
250 *
251 * This function essentially calls ssam_device_id_match() with the ID table of
252 * the bound device driver and the UID of the device.
253 *
254 * Return: Returns the first match for the UID of the device in the device
255 * driver's match table, or %NULL if no such match could be found.
256 */
257const struct ssam_device_id *ssam_device_get_match(const struct ssam_device *dev)
258{
259 const struct ssam_device_driver *sdrv;
260
261 sdrv = to_ssam_device_driver(dev->dev.driver);
262 if (!sdrv)
263 return NULL;
264
265 if (!sdrv->match_table)
266 return NULL;
267
268 return ssam_device_id_match(sdrv->match_table, dev->uid);
269}
270EXPORT_SYMBOL_GPL(ssam_device_get_match);
271
272/**
273 * ssam_device_get_match_data() - Find the ID matching the device in the
274 * ID table of the bound driver and return its ``driver_data`` member.
275 * @dev: The device for which to get the match data.
276 *
277 * Find the fist match for the UID of the device in the ID table of the
278 * corresponding driver and return its driver_data. Returns %NULL if the
279 * device does not have a driver bound to it, the driver does not have
280 * match_table (i.e. it is %NULL), there is no match in the driver's
281 * match_table, or the match does not have any driver_data.
282 *
283 * This function essentially calls ssam_device_get_match() and, if any match
284 * could be found, returns its ``struct ssam_device_id.driver_data`` member.
285 *
286 * Return: Returns the driver data associated with the first match for the UID
287 * of the device in the device driver's match table, or %NULL if no such match
288 * could be found.
289 */
290const void *ssam_device_get_match_data(const struct ssam_device *dev)
291{
292 const struct ssam_device_id *id;
293
294 id = ssam_device_get_match(dev);
295 if (!id)
296 return NULL;
297
298 return (const void *)id->driver_data;
299}
300EXPORT_SYMBOL_GPL(ssam_device_get_match_data);
301
302static int ssam_bus_match(struct device *dev, struct device_driver *drv)
303{
304 struct ssam_device_driver *sdrv = to_ssam_device_driver(drv);
305 struct ssam_device *sdev = to_ssam_device(dev);
306
307 if (!is_ssam_device(dev))
308 return 0;
309
310 return !!ssam_device_id_match(sdrv->match_table, sdev->uid);
311}
312
313static int ssam_bus_probe(struct device *dev)
314{
315 return to_ssam_device_driver(dev->driver)
316 ->probe(to_ssam_device(dev));
317}
318
319static int ssam_bus_remove(struct device *dev)
320{
321 struct ssam_device_driver *sdrv = to_ssam_device_driver(dev->driver);
322
323 if (sdrv->remove)
324 sdrv->remove(to_ssam_device(dev));
325
326 return 0;
327}
328
329struct bus_type ssam_bus_type = {
330 .name = "surface_aggregator",
331 .match = ssam_bus_match,
332 .probe = ssam_bus_probe,
333 .remove = ssam_bus_remove,
334};
335EXPORT_SYMBOL_GPL(ssam_bus_type);
336
337/**
338 * __ssam_device_driver_register() - Register a SSAM client device driver.
339 * @sdrv: The driver to register.
340 * @owner: The module owning the provided driver.
341 *
342 * Please refer to the ssam_device_driver_register() macro for the normal way
343 * to register a driver from inside its owning module.
344 */
345int __ssam_device_driver_register(struct ssam_device_driver *sdrv,
346 struct module *owner)
347{
348 sdrv->driver.owner = owner;
349 sdrv->driver.bus = &ssam_bus_type;
350
351 /* force drivers to async probe so I/O is possible in probe */
352 sdrv->driver.probe_type = PROBE_PREFER_ASYNCHRONOUS;
353
354 return driver_register(&sdrv->driver);
355}
356EXPORT_SYMBOL_GPL(__ssam_device_driver_register);
357
358/**
359 * ssam_device_driver_unregister - Unregister a SSAM device driver.
360 * @sdrv: The driver to unregister.
361 */
362void ssam_device_driver_unregister(struct ssam_device_driver *sdrv)
363{
364 driver_unregister(&sdrv->driver);
365}
366EXPORT_SYMBOL_GPL(ssam_device_driver_unregister);
367
368static int ssam_remove_device(struct device *dev, void *_data)
369{
370 struct ssam_device *sdev = to_ssam_device(dev);
371
372 if (is_ssam_device(dev))
373 ssam_device_remove(sdev);
374
375 return 0;
376}
377
378/**
379 * ssam_controller_remove_clients() - Remove SSAM client devices registered as
380 * direct children under the given controller.
381 * @ctrl: The controller to remove all direct clients for.
382 *
383 * Remove all SSAM client devices registered as direct children under the
384 * given controller. Note that this only accounts for direct children of the
385 * controller device. This does not take care of any client devices where the
386 * parent device has been manually set before calling ssam_device_add. Refer
387 * to ssam_device_add()/ssam_device_remove() for more details on those cases.
388 *
389 * To avoid new devices being added in parallel to this call, the main
390 * controller lock (not statelock) must be held during this (and if
391 * necessary, any subsequent deinitialization) call.
392 */
393void ssam_controller_remove_clients(struct ssam_controller *ctrl)
394{
395 struct device *dev;
396
397 dev = ssam_controller_device(ctrl);
398 device_for_each_child_reverse(dev, NULL, ssam_remove_device);
399}
400
401/**
402 * ssam_bus_register() - Register and set-up the SSAM client device bus.
403 */
404int ssam_bus_register(void)
405{
406 return bus_register(&ssam_bus_type);
407}
408
409/**
410 * ssam_bus_unregister() - Unregister the SSAM client device bus.
411 */
412void ssam_bus_unregister(void)
413{
414 return bus_unregister(&ssam_bus_type);
415}