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 <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(const struct device *dev, struct kobj_uevent_env *env)
  39 {
  40         const 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_sync (controller has to be started
 140          * and is not suspended) to hold and thus does not have to check for
 141          * 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);