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