1 // SPDX-License-Identifier: GPL-2.0+
3 * Surface System Aggregator Module (SSAM) client device registry.
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
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>
21 #include <linux/surface_aggregator/controller.h>
22 #include <linux/surface_aggregator/device.h>
25 /* -- Device registry. ------------------------------------------------------ */
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
35 * Where, 'dd', 'cc', 'tt', 'ii', and 'ff' are the two-digit hexadecimal
36 * values mentioned above, respectively.
40 static const struct software_node ssam_node_root = {
41 .name = "ssam_platform_hub",
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,
51 static const struct software_node ssam_node_bat_ac = {
52 .name = "ssam:01:02:01:01:01",
53 .parent = &ssam_node_root,
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,
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,
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,
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,
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,
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,
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,
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,
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,
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,
117 static const struct software_node ssam_node_hid_main_keyboard = {
118 .name = "ssam:01:15:02:01:00",
119 .parent = &ssam_node_root,
123 static const struct software_node ssam_node_hid_main_touchpad = {
124 .name = "ssam:01:15:02:03:00",
125 .parent = &ssam_node_root,
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,
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,
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,
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,
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,
159 * Devices for 5th- and 6th-generations models:
161 * - Surface Laptop 1 and 2,
162 * - Surface Pro 5 and 6.
164 static const struct software_node *ssam_node_group_gen5[] = {
166 &ssam_node_tmp_pprof,
170 /* Devices for Surface Book 3. */
171 static const struct software_node *ssam_node_group_sb3[] = {
176 &ssam_node_bat_sb3base,
177 &ssam_node_tmp_pprof,
179 &ssam_node_hid_base_keyboard,
180 &ssam_node_hid_base_touchpad,
181 &ssam_node_hid_base_iid5,
182 &ssam_node_hid_base_iid6,
186 /* Devices for Surface Laptop 3 and 4. */
187 static const struct software_node *ssam_node_group_sl3[] = {
191 &ssam_node_tmp_pprof,
192 &ssam_node_hid_main_keyboard,
193 &ssam_node_hid_main_touchpad,
194 &ssam_node_hid_main_iid5,
198 /* Devices for Surface Laptop Studio. */
199 static const struct software_node *ssam_node_group_sls[] = {
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,
213 /* Devices for Surface Laptop Go. */
214 static const struct software_node *ssam_node_group_slg1[] = {
218 &ssam_node_tmp_pprof,
222 /* Devices for Surface Pro 7 and Surface Pro 7+. */
223 static const struct software_node *ssam_node_group_sp7[] = {
227 &ssam_node_tmp_pprof,
231 static const struct software_node *ssam_node_group_sp8[] = {
235 &ssam_node_tmp_pprof,
236 /* TODO: Add support for keyboard cover. */
241 /* -- Device registry helper functions. ------------------------------------- */
243 static int ssam_uid_from_string(const char *str, struct ssam_device_uid *uid)
245 u8 d, tc, tid, iid, fn;
248 n = sscanf(str, "ssam:%hhx:%hhx:%hhx:%hhx:%hhx", &d, &tc, &tid, &iid, &fn);
261 static int ssam_hub_remove_devices_fn(struct device *dev, void *data)
263 if (!is_ssam_device(dev))
266 ssam_device_remove(to_ssam_device(dev));
270 static void ssam_hub_remove_devices(struct device *parent)
272 device_for_each_child_reverse(parent, NULL, ssam_hub_remove_devices_fn);
275 static int ssam_hub_add_device(struct device *parent, struct ssam_controller *ctrl,
276 struct fwnode_handle *node)
278 struct ssam_device_uid uid;
279 struct ssam_device *sdev;
282 status = ssam_uid_from_string(fwnode_get_name(node), &uid);
286 sdev = ssam_device_alloc(ctrl, uid);
290 sdev->dev.parent = parent;
291 sdev->dev.fwnode = node;
293 status = ssam_device_add(sdev);
295 ssam_device_put(sdev);
300 static int ssam_hub_add_devices(struct device *parent, struct ssam_controller *ctrl,
301 struct fwnode_handle *node)
303 struct fwnode_handle *child;
306 fwnode_for_each_child_node(node, child) {
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.
313 status = ssam_hub_add_device(parent, ctrl, child);
314 if (status && status != -EINVAL)
320 ssam_hub_remove_devices(parent);
325 /* -- SSAM base-hub driver. ------------------------------------------------- */
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
332 #define SSAM_BASE_UPDATE_CONNECT_DELAY msecs_to_jiffies(2500)
334 enum ssam_base_hub_state {
335 SSAM_BASE_HUB_UNINITIALIZED,
336 SSAM_BASE_HUB_CONNECTED,
337 SSAM_BASE_HUB_DISCONNECTED,
340 struct ssam_base_hub {
341 struct ssam_device *sdev;
343 enum ssam_base_hub_state state;
344 struct delayed_work update_work;
346 struct ssam_event_notifier notif;
349 SSAM_DEFINE_SYNC_REQUEST_R(ssam_bas_query_opmode, u8, {
350 .target_category = SSAM_SSH_TC_BAS,
356 #define SSAM_BAS_OPMODE_TABLET 0x00
357 #define SSAM_EVENT_BAS_CID_CONNECTION 0x0c
359 static int ssam_base_hub_query_state(struct ssam_base_hub *hub, enum ssam_base_hub_state *state)
364 status = ssam_retry(ssam_bas_query_opmode, hub->sdev->ctrl, &opmode);
366 dev_err(&hub->sdev->dev, "failed to query base state: %d\n", status);
370 if (opmode != SSAM_BAS_OPMODE_TABLET)
371 *state = SSAM_BASE_HUB_CONNECTED;
373 *state = SSAM_BASE_HUB_DISCONNECTED;
378 static ssize_t ssam_base_hub_state_show(struct device *dev, struct device_attribute *attr,
381 struct ssam_base_hub *hub = dev_get_drvdata(dev);
382 bool connected = hub->state == SSAM_BASE_HUB_CONNECTED;
384 return sysfs_emit(buf, "%d\n", connected);
387 static struct device_attribute ssam_base_hub_attr_state =
388 __ATTR(state, 0444, ssam_base_hub_state_show, NULL);
390 static struct attribute *ssam_base_hub_attrs[] = {
391 &ssam_base_hub_attr_state.attr,
395 static const struct attribute_group ssam_base_hub_group = {
396 .attrs = ssam_base_hub_attrs,
399 static void ssam_base_hub_update_workfn(struct work_struct *work)
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;
406 status = ssam_base_hub_query_state(hub, &state);
410 if (hub->state == state)
414 if (hub->state == SSAM_BASE_HUB_CONNECTED)
415 status = ssam_hub_add_devices(&hub->sdev->dev, hub->sdev->ctrl, node);
417 ssam_hub_remove_devices(&hub->sdev->dev);
420 dev_err(&hub->sdev->dev, "failed to update base-hub devices: %d\n", status);
423 static u32 ssam_base_hub_notif(struct ssam_event_notifier *nf, const struct ssam_event *event)
425 struct ssam_base_hub *hub = container_of(nf, struct ssam_base_hub, notif);
428 if (event->command_id != SSAM_EVENT_BAS_CID_CONNECTION)
431 if (event->length < 1) {
432 dev_err(&hub->sdev->dev, "unexpected payload size: %u\n", event->length);
437 * Delay update when the base is being connected to give devices/EC
438 * some time to set up.
440 delay = event->data[0] ? SSAM_BASE_UPDATE_CONNECT_DELAY : 0;
442 schedule_delayed_work(&hub->update_work, delay);
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)
452 static int __maybe_unused ssam_base_hub_resume(struct device *dev)
454 struct ssam_base_hub *hub = dev_get_drvdata(dev);
456 schedule_delayed_work(&hub->update_work, 0);
459 static SIMPLE_DEV_PM_OPS(ssam_base_hub_pm_ops, NULL, ssam_base_hub_resume);
461 static int ssam_base_hub_probe(struct ssam_device *sdev)
463 struct ssam_base_hub *hub;
466 hub = devm_kzalloc(&sdev->dev, sizeof(*hub), GFP_KERNEL);
471 hub->state = SSAM_BASE_HUB_UNINITIALIZED;
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;
481 INIT_DELAYED_WORK(&hub->update_work, ssam_base_hub_update_workfn);
483 ssam_device_set_drvdata(sdev, hub);
485 status = ssam_notifier_register(sdev->ctrl, &hub->notif);
489 status = sysfs_create_group(&sdev->dev.kobj, &ssam_base_hub_group);
493 schedule_delayed_work(&hub->update_work, 0);
497 ssam_notifier_unregister(sdev->ctrl, &hub->notif);
498 cancel_delayed_work_sync(&hub->update_work);
499 ssam_hub_remove_devices(&sdev->dev);
503 static void ssam_base_hub_remove(struct ssam_device *sdev)
505 struct ssam_base_hub *hub = ssam_device_get_drvdata(sdev);
507 sysfs_remove_group(&sdev->dev.kobj, &ssam_base_hub_group);
509 ssam_notifier_unregister(sdev->ctrl, &hub->notif);
510 cancel_delayed_work_sync(&hub->update_work);
511 ssam_hub_remove_devices(&sdev->dev);
514 static const struct ssam_device_id ssam_base_hub_match[] = {
515 { SSAM_VDEV(HUB, 0x02, SSAM_ANY_IID, 0x00) },
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,
524 .name = "surface_aggregator_base_hub",
525 .probe_type = PROBE_PREFER_ASYNCHRONOUS,
526 .pm = &ssam_base_hub_pm_ops,
531 /* -- SSAM platform/meta-hub driver. ---------------------------------------- */
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 },
537 /* Surface Pro 6 (OMBR >= 0x10) */
538 { "MSHW0111", (unsigned long)ssam_node_group_gen5 },
541 { "MSHW0116", (unsigned long)ssam_node_group_sp7 },
544 { "MSHW0119", (unsigned long)ssam_node_group_sp7 },
547 { "MSHW0263", (unsigned long)ssam_node_group_sp8 },
550 { "MSHW0107", (unsigned long)ssam_node_group_gen5 },
553 { "MSHW0117", (unsigned long)ssam_node_group_sb3 },
555 /* Surface Laptop 1 */
556 { "MSHW0086", (unsigned long)ssam_node_group_gen5 },
558 /* Surface Laptop 2 */
559 { "MSHW0112", (unsigned long)ssam_node_group_gen5 },
561 /* Surface Laptop 3 (13", Intel) */
562 { "MSHW0114", (unsigned long)ssam_node_group_sl3 },
564 /* Surface Laptop 3 (15", AMD) and 4 (15", AMD) */
565 { "MSHW0110", (unsigned long)ssam_node_group_sl3 },
567 /* Surface Laptop 4 (13", Intel) */
568 { "MSHW0250", (unsigned long)ssam_node_group_sl3 },
570 /* Surface Laptop Go 1 */
571 { "MSHW0118", (unsigned long)ssam_node_group_slg1 },
573 /* Surface Laptop Studio */
574 { "MSHW0123", (unsigned long)ssam_node_group_sls },
578 MODULE_DEVICE_TABLE(acpi, ssam_platform_hub_match);
580 static int ssam_platform_hub_probe(struct platform_device *pdev)
582 const struct software_node **nodes;
583 struct ssam_controller *ctrl;
584 struct fwnode_handle *root;
587 nodes = (const struct software_node **)acpi_device_get_match_data(&pdev->dev);
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.
598 ctrl = ssam_client_bind(&pdev->dev);
600 return PTR_ERR(ctrl) == -ENODEV ? -EPROBE_DEFER : PTR_ERR(ctrl);
602 status = software_node_register_node_group(nodes);
606 root = software_node_fwnode(&ssam_node_root);
608 software_node_unregister_node_group(nodes);
612 set_secondary_fwnode(&pdev->dev, root);
614 status = ssam_hub_add_devices(&pdev->dev, ctrl, root);
616 set_secondary_fwnode(&pdev->dev, NULL);
617 software_node_unregister_node_group(nodes);
620 platform_set_drvdata(pdev, nodes);
624 static int ssam_platform_hub_remove(struct platform_device *pdev)
626 const struct software_node **nodes = platform_get_drvdata(pdev);
628 ssam_hub_remove_devices(&pdev->dev);
629 set_secondary_fwnode(&pdev->dev, NULL);
630 software_node_unregister_node_group(nodes);
634 static struct platform_driver ssam_platform_hub_driver = {
635 .probe = ssam_platform_hub_probe,
636 .remove = ssam_platform_hub_remove,
638 .name = "surface_aggregator_platform_hub",
639 .acpi_match_table = ssam_platform_hub_match,
640 .probe_type = PROBE_PREFER_ASYNCHRONOUS,
645 /* -- Module initialization. ------------------------------------------------ */
647 static int __init ssam_device_hub_init(void)
651 status = platform_driver_register(&ssam_platform_hub_driver);
655 status = ssam_device_driver_register(&ssam_base_hub_driver);
657 platform_driver_unregister(&ssam_platform_hub_driver);
661 module_init(ssam_device_hub_init);
663 static void __exit ssam_device_hub_exit(void)
665 ssam_device_driver_unregister(&ssam_base_hub_driver);
666 platform_driver_unregister(&ssam_platform_hub_driver);
668 module_exit(ssam_device_hub_exit);
671 MODULE_DESCRIPTION("Device-registry for Surface System Aggregator Module");
672 MODULE_LICENSE("GPL");