1 // SPDX-License-Identifier: GPL-2.0+ 2 /* 3 * Surface System Aggregator Module (SSAM) client device registry. 4 * 5 * Registry for non-platform/non-ACPI SSAM client devices, i.e. devices that 6 * cannot be auto-detected. Provides device-hubs and performs instantiation 7 * for these devices. 8 * 9 * Copyright (C) 2020-2021 Maximilian Luz <luzmaximilian@gmail.com> 10 */ 11 12 #include <linux/acpi.h> 13 #include <linux/kernel.h> 14 #include <linux/limits.h> 15 #include <linux/module.h> 16 #include <linux/platform_device.h> 17 #include <linux/property.h> 18 #include <linux/types.h> 19 #include <linux/workqueue.h> 20 21 #include <linux/surface_aggregator/controller.h> 22 #include <linux/surface_aggregator/device.h> 23 24 25 /* -- Device registry. ------------------------------------------------------ */ 26 27 /* 28 * SSAM device names follow the SSAM module alias, meaning they are prefixed 29 * with 'ssam:', followed by domain, category, target ID, instance ID, and 30 * function, each encoded as two-digit hexadecimal, separated by ':'. In other 31 * words, it follows the scheme 32 * 33 * ssam:dd:cc:tt:ii:ff 34 * 35 * Where, 'dd', 'cc', 'tt', 'ii', and 'ff' are the two-digit hexadecimal 36 * values mentioned above, respectively. 37 */ 38 39 /* Root node. */ 40 static const struct software_node ssam_node_root = { 41 .name = "ssam_platform_hub", 42 }; 43 44 /* Base device hub (devices attached to Surface Book 3 base). */ 45 static const struct software_node ssam_node_hub_base = { 46 .name = "ssam:00:00:02:00:00", 47 .parent = &ssam_node_root, 48 }; 49 50 /* AC adapter. */ 51 static const struct software_node ssam_node_bat_ac = { 52 .name = "ssam:01:02:01:01:01", 53 .parent = &ssam_node_root, 54 }; 55 56 /* Primary battery. */ 57 static const struct software_node ssam_node_bat_main = { 58 .name = "ssam:01:02:01:01:00", 59 .parent = &ssam_node_root, 60 }; 61 62 /* Secondary battery (Surface Book 3). */ 63 static const struct software_node ssam_node_bat_sb3base = { 64 .name = "ssam:01:02:02:01:00", 65 .parent = &ssam_node_hub_base, 66 }; 67 68 /* Platform profile / performance-mode device. */ 69 static const struct software_node ssam_node_tmp_pprof = { 70 .name = "ssam:01:03:01:00:01", 71 .parent = &ssam_node_root, 72 }; 73 74 /* DTX / detachment-system device (Surface Book 3). */ 75 static const struct software_node ssam_node_bas_dtx = { 76 .name = "ssam:01:11:01:00:00", 77 .parent = &ssam_node_root, 78 }; 79 80 /* HID keyboard (TID1). */ 81 static const struct software_node ssam_node_hid_tid1_keyboard = { 82 .name = "ssam:01:15:01:01:00", 83 .parent = &ssam_node_root, 84 }; 85 86 /* HID pen stash (TID1; pen taken / stashed away evens). */ 87 static const struct software_node ssam_node_hid_tid1_penstash = { 88 .name = "ssam:01:15:01:02:00", 89 .parent = &ssam_node_root, 90 }; 91 92 /* HID touchpad (TID1). */ 93 static const struct software_node ssam_node_hid_tid1_touchpad = { 94 .name = "ssam:01:15:01:03:00", 95 .parent = &ssam_node_root, 96 }; 97 98 /* HID device instance 6 (TID1, unknown HID device). */ 99 static const struct software_node ssam_node_hid_tid1_iid6 = { 100 .name = "ssam:01:15:01:06:00", 101 .parent = &ssam_node_root, 102 }; 103 104 /* HID device instance 7 (TID1, unknown HID device). */ 105 static const struct software_node ssam_node_hid_tid1_iid7 = { 106 .name = "ssam:01:15:01:07:00", 107 .parent = &ssam_node_root, 108 }; 109 110 /* HID system controls (TID1). */ 111 static const struct software_node ssam_node_hid_tid1_sysctrl = { 112 .name = "ssam:01:15:01:08:00", 113 .parent = &ssam_node_root, 114 }; 115 116 /* HID keyboard. */ 117 static const struct software_node ssam_node_hid_main_keyboard = { 118 .name = "ssam:01:15:02:01:00", 119 .parent = &ssam_node_root, 120 }; 121 122 /* HID touchpad. */ 123 static const struct software_node ssam_node_hid_main_touchpad = { 124 .name = "ssam:01:15:02:03:00", 125 .parent = &ssam_node_root, 126 }; 127 128 /* HID device instance 5 (unknown HID device). */ 129 static const struct software_node ssam_node_hid_main_iid5 = { 130 .name = "ssam:01:15:02:05:00", 131 .parent = &ssam_node_root, 132 }; 133 134 /* HID keyboard (base hub). */ 135 static const struct software_node ssam_node_hid_base_keyboard = { 136 .name = "ssam:01:15:02:01:00", 137 .parent = &ssam_node_hub_base, 138 }; 139 140 /* HID touchpad (base hub). */ 141 static const struct software_node ssam_node_hid_base_touchpad = { 142 .name = "ssam:01:15:02:03:00", 143 .parent = &ssam_node_hub_base, 144 }; 145 146 /* HID device instance 5 (unknown HID device, base hub). */ 147 static const struct software_node ssam_node_hid_base_iid5 = { 148 .name = "ssam:01:15:02:05:00", 149 .parent = &ssam_node_hub_base, 150 }; 151 152 /* HID device instance 6 (unknown HID device, base hub). */ 153 static const struct software_node ssam_node_hid_base_iid6 = { 154 .name = "ssam:01:15:02:06:00", 155 .parent = &ssam_node_hub_base, 156 }; 157 158 /* 159 * Devices for 5th- and 6th-generations models: 160 * - Surface Book 2, 161 * - Surface Laptop 1 and 2, 162 * - Surface Pro 5 and 6. 163 */ 164 static const struct software_node *ssam_node_group_gen5[] = { 165 &ssam_node_root, 166 &ssam_node_tmp_pprof, 167 NULL, 168 }; 169 170 /* Devices for Surface Book 3. */ 171 static const struct software_node *ssam_node_group_sb3[] = { 172 &ssam_node_root, 173 &ssam_node_hub_base, 174 &ssam_node_bat_ac, 175 &ssam_node_bat_main, 176 &ssam_node_bat_sb3base, 177 &ssam_node_tmp_pprof, 178 &ssam_node_bas_dtx, 179 &ssam_node_hid_base_keyboard, 180 &ssam_node_hid_base_touchpad, 181 &ssam_node_hid_base_iid5, 182 &ssam_node_hid_base_iid6, 183 NULL, 184 }; 185 186 /* Devices for Surface Laptop 3 and 4. */ 187 static const struct software_node *ssam_node_group_sl3[] = { 188 &ssam_node_root, 189 &ssam_node_bat_ac, 190 &ssam_node_bat_main, 191 &ssam_node_tmp_pprof, 192 &ssam_node_hid_main_keyboard, 193 &ssam_node_hid_main_touchpad, 194 &ssam_node_hid_main_iid5, 195 NULL, 196 }; 197 198 /* Devices for Surface Laptop Studio. */ 199 static const struct software_node *ssam_node_group_sls[] = { 200 &ssam_node_root, 201 &ssam_node_bat_ac, 202 &ssam_node_bat_main, 203 &ssam_node_tmp_pprof, 204 &ssam_node_hid_tid1_keyboard, 205 &ssam_node_hid_tid1_penstash, 206 &ssam_node_hid_tid1_touchpad, 207 &ssam_node_hid_tid1_iid6, 208 &ssam_node_hid_tid1_iid7, 209 &ssam_node_hid_tid1_sysctrl, 210 NULL, 211 }; 212 213 /* Devices for Surface Laptop Go. */ 214 static const struct software_node *ssam_node_group_slg1[] = { 215 &ssam_node_root, 216 &ssam_node_bat_ac, 217 &ssam_node_bat_main, 218 &ssam_node_tmp_pprof, 219 NULL, 220 }; 221 222 /* Devices for Surface Pro 7 and Surface Pro 7+. */ 223 static const struct software_node *ssam_node_group_sp7[] = { 224 &ssam_node_root, 225 &ssam_node_bat_ac, 226 &ssam_node_bat_main, 227 &ssam_node_tmp_pprof, 228 NULL, 229 }; 230 231 static const struct software_node *ssam_node_group_sp8[] = { 232 &ssam_node_root, 233 &ssam_node_bat_ac, 234 &ssam_node_bat_main, 235 &ssam_node_tmp_pprof, 236 /* TODO: Add support for keyboard cover. */ 237 NULL, 238 }; 239 240 241 /* -- Device registry helper functions. ------------------------------------- */ 242 243 static int ssam_uid_from_string(const char *str, struct ssam_device_uid *uid) 244 { 245 u8 d, tc, tid, iid, fn; 246 int n; 247 248 n = sscanf(str, "ssam:%hhx:%hhx:%hhx:%hhx:%hhx", &d, &tc, &tid, &iid, &fn); 249 if (n != 5) 250 return -EINVAL; 251 252 uid->domain = d; 253 uid->category = tc; 254 uid->target = tid; 255 uid->instance = iid; 256 uid->function = fn; 257 258 return 0; 259 } 260 261 static int ssam_hub_remove_devices_fn(struct device *dev, void *data) 262 { 263 if (!is_ssam_device(dev)) 264 return 0; 265 266 ssam_device_remove(to_ssam_device(dev)); 267 return 0; 268 } 269 270 static void ssam_hub_remove_devices(struct device *parent) 271 { 272 device_for_each_child_reverse(parent, NULL, ssam_hub_remove_devices_fn); 273 } 274 275 static int ssam_hub_add_device(struct device *parent, struct ssam_controller *ctrl, 276 struct fwnode_handle *node) 277 { 278 struct ssam_device_uid uid; 279 struct ssam_device *sdev; 280 int status; 281 282 status = ssam_uid_from_string(fwnode_get_name(node), &uid); 283 if (status) 284 return status; 285 286 sdev = ssam_device_alloc(ctrl, uid); 287 if (!sdev) 288 return -ENOMEM; 289 290 sdev->dev.parent = parent; 291 sdev->dev.fwnode = node; 292 293 status = ssam_device_add(sdev); 294 if (status) 295 ssam_device_put(sdev); 296 297 return status; 298 } 299 300 static int ssam_hub_add_devices(struct device *parent, struct ssam_controller *ctrl, 301 struct fwnode_handle *node) 302 { 303 struct fwnode_handle *child; 304 int status; 305 306 fwnode_for_each_child_node(node, child) { 307 /* 308 * Try to add the device specified in the firmware node. If 309 * this fails with -EINVAL, the node does not specify any SSAM 310 * device, so ignore it and continue with the next one. 311 */ 312 313 status = ssam_hub_add_device(parent, ctrl, child); 314 if (status && status != -EINVAL) 315 goto err; 316 } 317 318 return 0; 319 err: 320 ssam_hub_remove_devices(parent); 321 return status; 322 } 323 324 325 /* -- SSAM base-hub driver. ------------------------------------------------- */ 326 327 /* 328 * Some devices (especially battery) may need a bit of time to be fully usable 329 * after being (re-)connected. This delay has been determined via 330 * experimentation. 331 */ 332 #define SSAM_BASE_UPDATE_CONNECT_DELAY msecs_to_jiffies(2500) 333 334 enum ssam_base_hub_state { 335 SSAM_BASE_HUB_UNINITIALIZED, 336 SSAM_BASE_HUB_CONNECTED, 337 SSAM_BASE_HUB_DISCONNECTED, 338 }; 339 340 struct ssam_base_hub { 341 struct ssam_device *sdev; 342 343 enum ssam_base_hub_state state; 344 struct delayed_work update_work; 345 346 struct ssam_event_notifier notif; 347 }; 348 349 SSAM_DEFINE_SYNC_REQUEST_R(ssam_bas_query_opmode, u8, { 350 .target_category = SSAM_SSH_TC_BAS, 351 .target_id = 0x01, 352 .command_id = 0x0d, 353 .instance_id = 0x00, 354 }); 355 356 #define SSAM_BAS_OPMODE_TABLET 0x00 357 #define SSAM_EVENT_BAS_CID_CONNECTION 0x0c 358 359 static int ssam_base_hub_query_state(struct ssam_base_hub *hub, enum ssam_base_hub_state *state) 360 { 361 u8 opmode; 362 int status; 363 364 status = ssam_retry(ssam_bas_query_opmode, hub->sdev->ctrl, &opmode); 365 if (status < 0) { 366 dev_err(&hub->sdev->dev, "failed to query base state: %d\n", status); 367 return status; 368 } 369 370 if (opmode != SSAM_BAS_OPMODE_TABLET) 371 *state = SSAM_BASE_HUB_CONNECTED; 372 else 373 *state = SSAM_BASE_HUB_DISCONNECTED; 374 375 return 0; 376 } 377 378 static ssize_t ssam_base_hub_state_show(struct device *dev, struct device_attribute *attr, 379 char *buf) 380 { 381 struct ssam_base_hub *hub = dev_get_drvdata(dev); 382 bool connected = hub->state == SSAM_BASE_HUB_CONNECTED; 383 384 return sysfs_emit(buf, "%d\n", connected); 385 } 386 387 static struct device_attribute ssam_base_hub_attr_state = 388 __ATTR(state, 0444, ssam_base_hub_state_show, NULL); 389 390 static struct attribute *ssam_base_hub_attrs[] = { 391 &ssam_base_hub_attr_state.attr, 392 NULL, 393 }; 394 395 static const struct attribute_group ssam_base_hub_group = { 396 .attrs = ssam_base_hub_attrs, 397 }; 398 399 static void ssam_base_hub_update_workfn(struct work_struct *work) 400 { 401 struct ssam_base_hub *hub = container_of(work, struct ssam_base_hub, update_work.work); 402 struct fwnode_handle *node = dev_fwnode(&hub->sdev->dev); 403 enum ssam_base_hub_state state; 404 int status = 0; 405 406 status = ssam_base_hub_query_state(hub, &state); 407 if (status) 408 return; 409 410 if (hub->state == state) 411 return; 412 hub->state = state; 413 414 if (hub->state == SSAM_BASE_HUB_CONNECTED) 415 status = ssam_hub_add_devices(&hub->sdev->dev, hub->sdev->ctrl, node); 416 else 417 ssam_hub_remove_devices(&hub->sdev->dev); 418 419 if (status) 420 dev_err(&hub->sdev->dev, "failed to update base-hub devices: %d\n", status); 421 } 422 423 static u32 ssam_base_hub_notif(struct ssam_event_notifier *nf, const struct ssam_event *event) 424 { 425 struct ssam_base_hub *hub = container_of(nf, struct ssam_base_hub, notif); 426 unsigned long delay; 427 428 if (event->command_id != SSAM_EVENT_BAS_CID_CONNECTION) 429 return 0; 430 431 if (event->length < 1) { 432 dev_err(&hub->sdev->dev, "unexpected payload size: %u\n", event->length); 433 return 0; 434 } 435 436 /* 437 * Delay update when the base is being connected to give devices/EC 438 * some time to set up. 439 */ 440 delay = event->data[0] ? SSAM_BASE_UPDATE_CONNECT_DELAY : 0; 441 442 schedule_delayed_work(&hub->update_work, delay); 443 444 /* 445 * Do not return SSAM_NOTIF_HANDLED: The event should be picked up and 446 * consumed by the detachment system driver. We're just a (more or less) 447 * silent observer. 448 */ 449 return 0; 450 } 451 452 static int __maybe_unused ssam_base_hub_resume(struct device *dev) 453 { 454 struct ssam_base_hub *hub = dev_get_drvdata(dev); 455 456 schedule_delayed_work(&hub->update_work, 0); 457 return 0; 458 } 459 static SIMPLE_DEV_PM_OPS(ssam_base_hub_pm_ops, NULL, ssam_base_hub_resume); 460 461 static int ssam_base_hub_probe(struct ssam_device *sdev) 462 { 463 struct ssam_base_hub *hub; 464 int status; 465 466 hub = devm_kzalloc(&sdev->dev, sizeof(*hub), GFP_KERNEL); 467 if (!hub) 468 return -ENOMEM; 469 470 hub->sdev = sdev; 471 hub->state = SSAM_BASE_HUB_UNINITIALIZED; 472 473 hub->notif.base.priority = INT_MAX; /* This notifier should run first. */ 474 hub->notif.base.fn = ssam_base_hub_notif; 475 hub->notif.event.reg = SSAM_EVENT_REGISTRY_SAM; 476 hub->notif.event.id.target_category = SSAM_SSH_TC_BAS, 477 hub->notif.event.id.instance = 0, 478 hub->notif.event.mask = SSAM_EVENT_MASK_NONE; 479 hub->notif.event.flags = SSAM_EVENT_SEQUENCED; 480 481 INIT_DELAYED_WORK(&hub->update_work, ssam_base_hub_update_workfn); 482 483 ssam_device_set_drvdata(sdev, hub); 484 485 status = ssam_notifier_register(sdev->ctrl, &hub->notif); 486 if (status) 487 return status; 488 489 status = sysfs_create_group(&sdev->dev.kobj, &ssam_base_hub_group); 490 if (status) 491 goto err; 492 493 schedule_delayed_work(&hub->update_work, 0); 494 return 0; 495 496 err: 497 ssam_notifier_unregister(sdev->ctrl, &hub->notif); 498 cancel_delayed_work_sync(&hub->update_work); 499 ssam_hub_remove_devices(&sdev->dev); 500 return status; 501 } 502 503 static void ssam_base_hub_remove(struct ssam_device *sdev) 504 { 505 struct ssam_base_hub *hub = ssam_device_get_drvdata(sdev); 506 507 sysfs_remove_group(&sdev->dev.kobj, &ssam_base_hub_group); 508 509 ssam_notifier_unregister(sdev->ctrl, &hub->notif); 510 cancel_delayed_work_sync(&hub->update_work); 511 ssam_hub_remove_devices(&sdev->dev); 512 } 513 514 static const struct ssam_device_id ssam_base_hub_match[] = { 515 { SSAM_VDEV(HUB, 0x02, SSAM_ANY_IID, 0x00) }, 516 { }, 517 }; 518 519 static struct ssam_device_driver ssam_base_hub_driver = { 520 .probe = ssam_base_hub_probe, 521 .remove = ssam_base_hub_remove, 522 .match_table = ssam_base_hub_match, 523 .driver = { 524 .name = "surface_aggregator_base_hub", 525 .probe_type = PROBE_PREFER_ASYNCHRONOUS, 526 .pm = &ssam_base_hub_pm_ops, 527 }, 528 }; 529 530 531 /* -- SSAM platform/meta-hub driver. ---------------------------------------- */ 532 533 static const struct acpi_device_id ssam_platform_hub_match[] = { 534 /* Surface Pro 4, 5, and 6 (OMBR < 0x10) */ 535 { "MSHW0081", (unsigned long)ssam_node_group_gen5 }, 536 537 /* Surface Pro 6 (OMBR >= 0x10) */ 538 { "MSHW0111", (unsigned long)ssam_node_group_gen5 }, 539 540 /* Surface Pro 7 */ 541 { "MSHW0116", (unsigned long)ssam_node_group_sp7 }, 542 543 /* Surface Pro 7+ */ 544 { "MSHW0119", (unsigned long)ssam_node_group_sp7 }, 545 546 /* Surface Pro 8 */ 547 { "MSHW0263", (unsigned long)ssam_node_group_sp8 }, 548 549 /* Surface Book 2 */ 550 { "MSHW0107", (unsigned long)ssam_node_group_gen5 }, 551 552 /* Surface Book 3 */ 553 { "MSHW0117", (unsigned long)ssam_node_group_sb3 }, 554 555 /* Surface Laptop 1 */ 556 { "MSHW0086", (unsigned long)ssam_node_group_gen5 }, 557 558 /* Surface Laptop 2 */ 559 { "MSHW0112", (unsigned long)ssam_node_group_gen5 }, 560 561 /* Surface Laptop 3 (13", Intel) */ 562 { "MSHW0114", (unsigned long)ssam_node_group_sl3 }, 563 564 /* Surface Laptop 3 (15", AMD) and 4 (15", AMD) */ 565 { "MSHW0110", (unsigned long)ssam_node_group_sl3 }, 566 567 /* Surface Laptop 4 (13", Intel) */ 568 { "MSHW0250", (unsigned long)ssam_node_group_sl3 }, 569 570 /* Surface Laptop Go 1 */ 571 { "MSHW0118", (unsigned long)ssam_node_group_slg1 }, 572 573 /* Surface Laptop Studio */ 574 { "MSHW0123", (unsigned long)ssam_node_group_sls }, 575 576 { }, 577 }; 578 MODULE_DEVICE_TABLE(acpi, ssam_platform_hub_match); 579 580 static int ssam_platform_hub_probe(struct platform_device *pdev) 581 { 582 const struct software_node **nodes; 583 struct ssam_controller *ctrl; 584 struct fwnode_handle *root; 585 int status; 586 587 nodes = (const struct software_node **)acpi_device_get_match_data(&pdev->dev); 588 if (!nodes) 589 return -ENODEV; 590 591 /* 592 * As we're adding the SSAM client devices as children under this device 593 * and not the SSAM controller, we need to add a device link to the 594 * controller to ensure that we remove all of our devices before the 595 * controller is removed. This also guarantees proper ordering for 596 * suspend/resume of the devices on this hub. 597 */ 598 ctrl = ssam_client_bind(&pdev->dev); 599 if (IS_ERR(ctrl)) 600 return PTR_ERR(ctrl) == -ENODEV ? -EPROBE_DEFER : PTR_ERR(ctrl); 601 602 status = software_node_register_node_group(nodes); 603 if (status) 604 return status; 605 606 root = software_node_fwnode(&ssam_node_root); 607 if (!root) { 608 software_node_unregister_node_group(nodes); 609 return -ENOENT; 610 } 611 612 set_secondary_fwnode(&pdev->dev, root); 613 614 status = ssam_hub_add_devices(&pdev->dev, ctrl, root); 615 if (status) { 616 set_secondary_fwnode(&pdev->dev, NULL); 617 software_node_unregister_node_group(nodes); 618 } 619 620 platform_set_drvdata(pdev, nodes); 621 return status; 622 } 623 624 static int ssam_platform_hub_remove(struct platform_device *pdev) 625 { 626 const struct software_node **nodes = platform_get_drvdata(pdev); 627 628 ssam_hub_remove_devices(&pdev->dev); 629 set_secondary_fwnode(&pdev->dev, NULL); 630 software_node_unregister_node_group(nodes); 631 return 0; 632 } 633 634 static struct platform_driver ssam_platform_hub_driver = { 635 .probe = ssam_platform_hub_probe, 636 .remove = ssam_platform_hub_remove, 637 .driver = { 638 .name = "surface_aggregator_platform_hub", 639 .acpi_match_table = ssam_platform_hub_match, 640 .probe_type = PROBE_PREFER_ASYNCHRONOUS, 641 }, 642 }; 643 644 645 /* -- Module initialization. ------------------------------------------------ */ 646 647 static int __init ssam_device_hub_init(void) 648 { 649 int status; 650 651 status = platform_driver_register(&ssam_platform_hub_driver); 652 if (status) 653 return status; 654 655 status = ssam_device_driver_register(&ssam_base_hub_driver); 656 if (status) 657 platform_driver_unregister(&ssam_platform_hub_driver); 658 659 return status; 660 } 661 module_init(ssam_device_hub_init); 662 663 static void __exit ssam_device_hub_exit(void) 664 { 665 ssam_device_driver_unregister(&ssam_base_hub_driver); 666 platform_driver_unregister(&ssam_platform_hub_driver); 667 } 668 module_exit(ssam_device_hub_exit); 669 670 MODULE_AUTHOR("Maximilian Luz <luzmaximilian@gmail.com>"); 671 MODULE_DESCRIPTION("Device-registry for Surface System Aggregator Module"); 672 MODULE_LICENSE("GPL"); 673