drivers/platform/surface/aggregator/bus.c

   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 <[email protected]>
   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
  22 static 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 }
  31 static DEVICE_ATTR_RO(modalias);
  32
  33 static struct attribute *ssam_device_attrs[] = {
  34         &dev_attr_modalias.attr,
  35         NULL,
  36 };
  37 ATTRIBUTE_GROUPS(ssam_device);
  38
  39 static const struct bus_type ssam_bus_type;
  40
  41 static 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
  51 static 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
  60 const 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 };
  66 EXPORT_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  */
  81 struct 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 }
 103 EXPORT_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  */
 130 int 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 }
 163 EXPORT_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  */
 171 void ssam_device_remove(struct ssam_device *sdev)
 172 {
 173         device_unregister(&sdev->dev);
 174 }
 175 EXPORT_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  */
 189 static 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  */
 217 static 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  */
 236 const 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 }
 247 EXPORT_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  */
 265 const 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 }
 278 EXPORT_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  */
 298 const 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 }
 308 EXPORT_SYMBOL_GPL(ssam_device_get_match_data);
 309
 310 static 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
 321 static int ssam_bus_probe(struct device *dev)
 322 {
 323         return to_ssam_device_driver(dev->driver)
 324                 ->probe(to_ssam_device(dev));
 325 }
 326
 327 static 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
 335 static 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  */
 350 int __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 }
 361 EXPORT_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  */
 367 void ssam_device_driver_unregister(struct ssam_device_driver *sdrv)
 368 {
 369         driver_unregister(&sdrv->driver);
 370 }
 371 EXPORT_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  */
 379 int 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  */
 387 void ssam_bus_unregister(void)
 388 {
 389         return bus_unregister(&ssam_bus_type);
 390 }
 391
 392
 393 /* -- Helpers for controller and hub devices. ------------------------------- */
 394
 395 static 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
 413 static 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
 428 static 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  */
 478 int __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;
 498 err:
 499         ssam_remove_clients(parent);
 500         return status;
 501 }
 502 EXPORT_SYMBOL_GPL(__ssam_register_clients);
 503
 504 static 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  */
 523 void ssam_remove_clients(struct device *dev)
 524 {
 525         device_for_each_child_reverse(dev, NULL, ssam_remove_device);
 526 }
 527 EXPORT_SYMBOL_GPL(ssam_remove_clients);