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-2022 Maximilian Luz <luzmaximilian@gmail.com>
10  */
11 
12 #include <linux/acpi.h>
13 #include <linux/kernel.h>
14 #include <linux/module.h>
15 #include <linux/platform_device.h>
16 #include <linux/property.h>
17 #include <linux/types.h>
18 
19 #include <linux/surface_aggregator/device.h>
20 
21 
22 /* -- Device registry. ------------------------------------------------------ */
23 
24 /*
25  * SSAM device names follow the SSAM module alias, meaning they are prefixed
26  * with 'ssam:', followed by domain, category, target ID, instance ID, and
27  * function, each encoded as two-digit hexadecimal, separated by ':'. In other
28  * words, it follows the scheme
29  *
30  *      ssam:dd:cc:tt:ii:ff
31  *
32  * Where, 'dd', 'cc', 'tt', 'ii', and 'ff' are the two-digit hexadecimal
33  * values mentioned above, respectively.
34  */
35 
36 /* Root node. */
37 static const struct software_node ssam_node_root = {
38 	.name = "ssam_platform_hub",
39 };
40 
41 /* KIP device hub (connects keyboard cover devices on Surface Pro 8). */
42 static const struct software_node ssam_node_hub_kip = {
43 	.name = "ssam:00:00:01:0e:00",
44 	.parent = &ssam_node_root,
45 };
46 
47 /* Base device hub (devices attached to Surface Book 3 base). */
48 static const struct software_node ssam_node_hub_base = {
49 	.name = "ssam:00:00:01:11:00",
50 	.parent = &ssam_node_root,
51 };
52 
53 /* AC adapter. */
54 static const struct software_node ssam_node_bat_ac = {
55 	.name = "ssam:01:02:01:01:01",
56 	.parent = &ssam_node_root,
57 };
58 
59 /* Primary battery. */
60 static const struct software_node ssam_node_bat_main = {
61 	.name = "ssam:01:02:01:01:00",
62 	.parent = &ssam_node_root,
63 };
64 
65 /* Secondary battery (Surface Book 3). */
66 static const struct software_node ssam_node_bat_sb3base = {
67 	.name = "ssam:01:02:02:01:00",
68 	.parent = &ssam_node_hub_base,
69 };
70 
71 /* Platform profile / performance-mode device. */
72 static const struct software_node ssam_node_tmp_pprof = {
73 	.name = "ssam:01:03:01:00:01",
74 	.parent = &ssam_node_root,
75 };
76 
77 /* Tablet-mode switch via KIP subsystem. */
78 static const struct software_node ssam_node_kip_tablet_switch = {
79 	.name = "ssam:01:0e:01:00:01",
80 	.parent = &ssam_node_root,
81 };
82 
83 /* DTX / detachment-system device (Surface Book 3). */
84 static const struct software_node ssam_node_bas_dtx = {
85 	.name = "ssam:01:11:01:00:00",
86 	.parent = &ssam_node_root,
87 };
88 
89 /* HID keyboard (SAM, TID=1). */
90 static const struct software_node ssam_node_hid_sam_keyboard = {
91 	.name = "ssam:01:15:01:01:00",
92 	.parent = &ssam_node_root,
93 };
94 
95 /* HID pen stash (SAM, TID=1; pen taken / stashed away evens). */
96 static const struct software_node ssam_node_hid_sam_penstash = {
97 	.name = "ssam:01:15:01:02:00",
98 	.parent = &ssam_node_root,
99 };
100 
101 /* HID touchpad (SAM, TID=1). */
102 static const struct software_node ssam_node_hid_sam_touchpad = {
103 	.name = "ssam:01:15:01:03:00",
104 	.parent = &ssam_node_root,
105 };
106 
107 /* HID device instance 6 (SAM, TID=1, HID sensor collection). */
108 static const struct software_node ssam_node_hid_sam_sensors = {
109 	.name = "ssam:01:15:01:06:00",
110 	.parent = &ssam_node_root,
111 };
112 
113 /* HID device instance 7 (SAM, TID=1, UCM UCSI HID client). */
114 static const struct software_node ssam_node_hid_sam_ucm_ucsi = {
115 	.name = "ssam:01:15:01:07:00",
116 	.parent = &ssam_node_root,
117 };
118 
119 /* HID system controls (SAM, TID=1). */
120 static const struct software_node ssam_node_hid_sam_sysctrl = {
121 	.name = "ssam:01:15:01:08:00",
122 	.parent = &ssam_node_root,
123 };
124 
125 /* HID keyboard. */
126 static const struct software_node ssam_node_hid_main_keyboard = {
127 	.name = "ssam:01:15:02:01:00",
128 	.parent = &ssam_node_root,
129 };
130 
131 /* HID touchpad. */
132 static const struct software_node ssam_node_hid_main_touchpad = {
133 	.name = "ssam:01:15:02:03:00",
134 	.parent = &ssam_node_root,
135 };
136 
137 /* HID device instance 5 (unknown HID device). */
138 static const struct software_node ssam_node_hid_main_iid5 = {
139 	.name = "ssam:01:15:02:05:00",
140 	.parent = &ssam_node_root,
141 };
142 
143 /* HID keyboard (base hub). */
144 static const struct software_node ssam_node_hid_base_keyboard = {
145 	.name = "ssam:01:15:02:01:00",
146 	.parent = &ssam_node_hub_base,
147 };
148 
149 /* HID touchpad (base hub). */
150 static const struct software_node ssam_node_hid_base_touchpad = {
151 	.name = "ssam:01:15:02:03:00",
152 	.parent = &ssam_node_hub_base,
153 };
154 
155 /* HID device instance 5 (unknown HID device, base hub). */
156 static const struct software_node ssam_node_hid_base_iid5 = {
157 	.name = "ssam:01:15:02:05:00",
158 	.parent = &ssam_node_hub_base,
159 };
160 
161 /* HID device instance 6 (unknown HID device, base hub). */
162 static const struct software_node ssam_node_hid_base_iid6 = {
163 	.name = "ssam:01:15:02:06:00",
164 	.parent = &ssam_node_hub_base,
165 };
166 
167 /* HID keyboard (KIP hub). */
168 static const struct software_node ssam_node_hid_kip_keyboard = {
169 	.name = "ssam:01:15:02:01:00",
170 	.parent = &ssam_node_hub_kip,
171 };
172 
173 /* HID pen stash (KIP hub; pen taken / stashed away evens). */
174 static const struct software_node ssam_node_hid_kip_penstash = {
175 	.name = "ssam:01:15:02:02:00",
176 	.parent = &ssam_node_hub_kip,
177 };
178 
179 /* HID touchpad (KIP hub). */
180 static const struct software_node ssam_node_hid_kip_touchpad = {
181 	.name = "ssam:01:15:02:03:00",
182 	.parent = &ssam_node_hub_kip,
183 };
184 
185 /* HID device instance 5 (KIP hub, type-cover firmware update). */
186 static const struct software_node ssam_node_hid_kip_fwupd = {
187 	.name = "ssam:01:15:02:05:00",
188 	.parent = &ssam_node_hub_kip,
189 };
190 
191 /* Tablet-mode switch via POS subsystem. */
192 static const struct software_node ssam_node_pos_tablet_switch = {
193 	.name = "ssam:01:26:01:00:01",
194 	.parent = &ssam_node_root,
195 };
196 
197 /*
198  * Devices for 5th- and 6th-generations models:
199  * - Surface Book 2,
200  * - Surface Laptop 1 and 2,
201  * - Surface Pro 5 and 6.
202  */
203 static const struct software_node *ssam_node_group_gen5[] = {
204 	&ssam_node_root,
205 	&ssam_node_tmp_pprof,
206 	NULL,
207 };
208 
209 /* Devices for Surface Book 3. */
210 static const struct software_node *ssam_node_group_sb3[] = {
211 	&ssam_node_root,
212 	&ssam_node_hub_base,
213 	&ssam_node_bat_ac,
214 	&ssam_node_bat_main,
215 	&ssam_node_bat_sb3base,
216 	&ssam_node_tmp_pprof,
217 	&ssam_node_bas_dtx,
218 	&ssam_node_hid_base_keyboard,
219 	&ssam_node_hid_base_touchpad,
220 	&ssam_node_hid_base_iid5,
221 	&ssam_node_hid_base_iid6,
222 	NULL,
223 };
224 
225 /* Devices for Surface Laptop 3 and 4. */
226 static const struct software_node *ssam_node_group_sl3[] = {
227 	&ssam_node_root,
228 	&ssam_node_bat_ac,
229 	&ssam_node_bat_main,
230 	&ssam_node_tmp_pprof,
231 	&ssam_node_hid_main_keyboard,
232 	&ssam_node_hid_main_touchpad,
233 	&ssam_node_hid_main_iid5,
234 	NULL,
235 };
236 
237 /* Devices for Surface Laptop 5. */
238 static const struct software_node *ssam_node_group_sl5[] = {
239 	&ssam_node_root,
240 	&ssam_node_bat_ac,
241 	&ssam_node_bat_main,
242 	&ssam_node_tmp_pprof,
243 	&ssam_node_hid_main_keyboard,
244 	&ssam_node_hid_main_touchpad,
245 	&ssam_node_hid_main_iid5,
246 	&ssam_node_hid_sam_ucm_ucsi,
247 	NULL,
248 };
249 
250 /* Devices for Surface Laptop Studio. */
251 static const struct software_node *ssam_node_group_sls[] = {
252 	&ssam_node_root,
253 	&ssam_node_bat_ac,
254 	&ssam_node_bat_main,
255 	&ssam_node_tmp_pprof,
256 	&ssam_node_pos_tablet_switch,
257 	&ssam_node_hid_sam_keyboard,
258 	&ssam_node_hid_sam_penstash,
259 	&ssam_node_hid_sam_touchpad,
260 	&ssam_node_hid_sam_sensors,
261 	&ssam_node_hid_sam_ucm_ucsi,
262 	&ssam_node_hid_sam_sysctrl,
263 	NULL,
264 };
265 
266 /* Devices for Surface Laptop Go. */
267 static const struct software_node *ssam_node_group_slg1[] = {
268 	&ssam_node_root,
269 	&ssam_node_bat_ac,
270 	&ssam_node_bat_main,
271 	&ssam_node_tmp_pprof,
272 	NULL,
273 };
274 
275 /* Devices for Surface Pro 7 and Surface Pro 7+. */
276 static const struct software_node *ssam_node_group_sp7[] = {
277 	&ssam_node_root,
278 	&ssam_node_bat_ac,
279 	&ssam_node_bat_main,
280 	&ssam_node_tmp_pprof,
281 	NULL,
282 };
283 
284 /* Devices for Surface Pro 8 */
285 static const struct software_node *ssam_node_group_sp8[] = {
286 	&ssam_node_root,
287 	&ssam_node_hub_kip,
288 	&ssam_node_bat_ac,
289 	&ssam_node_bat_main,
290 	&ssam_node_tmp_pprof,
291 	&ssam_node_kip_tablet_switch,
292 	&ssam_node_hid_kip_keyboard,
293 	&ssam_node_hid_kip_penstash,
294 	&ssam_node_hid_kip_touchpad,
295 	&ssam_node_hid_kip_fwupd,
296 	&ssam_node_hid_sam_sensors,
297 	&ssam_node_hid_sam_ucm_ucsi,
298 	NULL,
299 };
300 
301 /* Devices for Surface Pro 9 */
302 static const struct software_node *ssam_node_group_sp9[] = {
303 	&ssam_node_root,
304 	&ssam_node_hub_kip,
305 	&ssam_node_bat_ac,
306 	&ssam_node_bat_main,
307 	&ssam_node_tmp_pprof,
308 	/* TODO: Tablet mode switch (via POS subsystem) */
309 	&ssam_node_hid_kip_keyboard,
310 	&ssam_node_hid_kip_penstash,
311 	&ssam_node_hid_kip_touchpad,
312 	&ssam_node_hid_kip_fwupd,
313 	&ssam_node_hid_sam_sensors,
314 	&ssam_node_hid_sam_ucm_ucsi,
315 	NULL,
316 };
317 
318 
319 /* -- SSAM platform/meta-hub driver. ---------------------------------------- */
320 
321 static const struct acpi_device_id ssam_platform_hub_match[] = {
322 	/* Surface Pro 4, 5, and 6 (OMBR < 0x10) */
323 	{ "MSHW0081", (unsigned long)ssam_node_group_gen5 },
324 
325 	/* Surface Pro 6 (OMBR >= 0x10) */
326 	{ "MSHW0111", (unsigned long)ssam_node_group_gen5 },
327 
328 	/* Surface Pro 7 */
329 	{ "MSHW0116", (unsigned long)ssam_node_group_sp7 },
330 
331 	/* Surface Pro 7+ */
332 	{ "MSHW0119", (unsigned long)ssam_node_group_sp7 },
333 
334 	/* Surface Pro 8 */
335 	{ "MSHW0263", (unsigned long)ssam_node_group_sp8 },
336 
337 	/* Surface Pro 9 */
338 	{ "MSHW0343", (unsigned long)ssam_node_group_sp9 },
339 
340 	/* Surface Book 2 */
341 	{ "MSHW0107", (unsigned long)ssam_node_group_gen5 },
342 
343 	/* Surface Book 3 */
344 	{ "MSHW0117", (unsigned long)ssam_node_group_sb3 },
345 
346 	/* Surface Laptop 1 */
347 	{ "MSHW0086", (unsigned long)ssam_node_group_gen5 },
348 
349 	/* Surface Laptop 2 */
350 	{ "MSHW0112", (unsigned long)ssam_node_group_gen5 },
351 
352 	/* Surface Laptop 3 (13", Intel) */
353 	{ "MSHW0114", (unsigned long)ssam_node_group_sl3 },
354 
355 	/* Surface Laptop 3 (15", AMD) and 4 (15", AMD) */
356 	{ "MSHW0110", (unsigned long)ssam_node_group_sl3 },
357 
358 	/* Surface Laptop 4 (13", Intel) */
359 	{ "MSHW0250", (unsigned long)ssam_node_group_sl3 },
360 
361 	/* Surface Laptop 5 */
362 	{ "MSHW0350", (unsigned long)ssam_node_group_sl5 },
363 
364 	/* Surface Laptop Go 1 */
365 	{ "MSHW0118", (unsigned long)ssam_node_group_slg1 },
366 
367 	/* Surface Laptop Go 2 */
368 	{ "MSHW0290", (unsigned long)ssam_node_group_slg1 },
369 
370 	/* Surface Laptop Studio */
371 	{ "MSHW0123", (unsigned long)ssam_node_group_sls },
372 
373 	{ },
374 };
375 MODULE_DEVICE_TABLE(acpi, ssam_platform_hub_match);
376 
377 static int ssam_platform_hub_probe(struct platform_device *pdev)
378 {
379 	const struct software_node **nodes;
380 	struct ssam_controller *ctrl;
381 	struct fwnode_handle *root;
382 	int status;
383 
384 	nodes = (const struct software_node **)acpi_device_get_match_data(&pdev->dev);
385 	if (!nodes)
386 		return -ENODEV;
387 
388 	/*
389 	 * As we're adding the SSAM client devices as children under this device
390 	 * and not the SSAM controller, we need to add a device link to the
391 	 * controller to ensure that we remove all of our devices before the
392 	 * controller is removed. This also guarantees proper ordering for
393 	 * suspend/resume of the devices on this hub.
394 	 */
395 	ctrl = ssam_client_bind(&pdev->dev);
396 	if (IS_ERR(ctrl))
397 		return PTR_ERR(ctrl) == -ENODEV ? -EPROBE_DEFER : PTR_ERR(ctrl);
398 
399 	status = software_node_register_node_group(nodes);
400 	if (status)
401 		return status;
402 
403 	root = software_node_fwnode(&ssam_node_root);
404 	if (!root) {
405 		software_node_unregister_node_group(nodes);
406 		return -ENOENT;
407 	}
408 
409 	set_secondary_fwnode(&pdev->dev, root);
410 
411 	status = __ssam_register_clients(&pdev->dev, ctrl, root);
412 	if (status) {
413 		set_secondary_fwnode(&pdev->dev, NULL);
414 		software_node_unregister_node_group(nodes);
415 	}
416 
417 	platform_set_drvdata(pdev, nodes);
418 	return status;
419 }
420 
421 static int ssam_platform_hub_remove(struct platform_device *pdev)
422 {
423 	const struct software_node **nodes = platform_get_drvdata(pdev);
424 
425 	ssam_remove_clients(&pdev->dev);
426 	set_secondary_fwnode(&pdev->dev, NULL);
427 	software_node_unregister_node_group(nodes);
428 	return 0;
429 }
430 
431 static struct platform_driver ssam_platform_hub_driver = {
432 	.probe = ssam_platform_hub_probe,
433 	.remove = ssam_platform_hub_remove,
434 	.driver = {
435 		.name = "surface_aggregator_platform_hub",
436 		.acpi_match_table = ssam_platform_hub_match,
437 		.probe_type = PROBE_PREFER_ASYNCHRONOUS,
438 	},
439 };
440 module_platform_driver(ssam_platform_hub_driver);
441 
442 MODULE_AUTHOR("Maximilian Luz <luzmaximilian@gmail.com>");
443 MODULE_DESCRIPTION("Device-registry for Surface System Aggregator Module");
444 MODULE_LICENSE("GPL");
445