1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3  * Surface System Aggregator Module (SSAM) bus and client-device subsystem.
4  *
5  * Main interface for the surface-aggregator bus, surface-aggregator client
6  * devices, and respective drivers building on top of the SSAM controller.
7  * Provides support for non-platform/non-ACPI SSAM clients via dedicated
8  * subsystem.
9  *
10  * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com>
11  */
12 
13 #ifndef _LINUX_SURFACE_AGGREGATOR_DEVICE_H
14 #define _LINUX_SURFACE_AGGREGATOR_DEVICE_H
15 
16 #include <linux/device.h>
17 #include <linux/mod_devicetable.h>
18 #include <linux/property.h>
19 #include <linux/types.h>
20 
21 #include <linux/surface_aggregator/controller.h>
22 
23 
24 /* -- Surface System Aggregator Module bus. --------------------------------- */
25 
26 /**
27  * enum ssam_device_domain - SAM device domain.
28  * @SSAM_DOMAIN_VIRTUAL:   Virtual device.
29  * @SSAM_DOMAIN_SERIALHUB: Physical device connected via Surface Serial Hub.
30  */
31 enum ssam_device_domain {
32 	SSAM_DOMAIN_VIRTUAL   = 0x00,
33 	SSAM_DOMAIN_SERIALHUB = 0x01,
34 };
35 
36 /**
37  * enum ssam_virtual_tc - Target categories for the virtual SAM domain.
38  * @SSAM_VIRTUAL_TC_HUB: Device hub category.
39  */
40 enum ssam_virtual_tc {
41 	SSAM_VIRTUAL_TC_HUB = 0x00,
42 };
43 
44 /**
45  * struct ssam_device_uid - Unique identifier for SSAM device.
46  * @domain:   Domain of the device.
47  * @category: Target category of the device.
48  * @target:   Target ID of the device.
49  * @instance: Instance ID of the device.
50  * @function: Sub-function of the device. This field can be used to split a
51  *            single SAM device into multiple virtual subdevices to separate
52  *            different functionality of that device and allow one driver per
53  *            such functionality.
54  */
55 struct ssam_device_uid {
56 	u8 domain;
57 	u8 category;
58 	u8 target;
59 	u8 instance;
60 	u8 function;
61 };
62 
63 /*
64  * Special values for device matching.
65  *
66  * These values are intended to be used with SSAM_DEVICE(), SSAM_VDEV(), and
67  * SSAM_SDEV() exclusively. Specifically, they are used to initialize the
68  * match_flags member of the device ID structure. Do not use them directly
69  * with struct ssam_device_id or struct ssam_device_uid.
70  */
71 #define SSAM_SSH_TID_ANY	0xffff
72 #define SSAM_SSH_IID_ANY	0xffff
73 #define SSAM_SSH_FUN_ANY	0xffff
74 
75 /**
76  * SSAM_DEVICE() - Initialize a &struct ssam_device_id with the given
77  * parameters.
78  * @d:   Domain of the device.
79  * @cat: Target category of the device.
80  * @tid: Target ID of the device.
81  * @iid: Instance ID of the device.
82  * @fun: Sub-function of the device.
83  *
84  * Initializes a &struct ssam_device_id with the given parameters. See &struct
85  * ssam_device_uid for details regarding the parameters. The special values
86  * %SSAM_SSH_TID_ANY, %SSAM_SSH_IID_ANY, and %SSAM_SSH_FUN_ANY can be used to specify that
87  * matching should ignore target ID, instance ID, and/or sub-function,
88  * respectively. This macro initializes the ``match_flags`` field based on the
89  * given parameters.
90  *
91  * Note: The parameters @d and @cat must be valid &u8 values, the parameters
92  * @tid, @iid, and @fun must be either valid &u8 values or %SSAM_SSH_TID_ANY,
93  * %SSAM_SSH_IID_ANY, or %SSAM_SSH_FUN_ANY, respectively. Other non-&u8 values are not
94  * allowed.
95  */
96 #define SSAM_DEVICE(d, cat, tid, iid, fun)					\
97 	.match_flags = (((tid) != SSAM_SSH_TID_ANY) ? SSAM_MATCH_TARGET : 0)	\
98 		     | (((iid) != SSAM_SSH_IID_ANY) ? SSAM_MATCH_INSTANCE : 0)	\
99 		     | (((fun) != SSAM_SSH_FUN_ANY) ? SSAM_MATCH_FUNCTION : 0),	\
100 	.domain   = d,								\
101 	.category = cat,							\
102 	.target   = __builtin_choose_expr((tid) != SSAM_SSH_TID_ANY, (tid), 0),	\
103 	.instance = __builtin_choose_expr((iid) != SSAM_SSH_IID_ANY, (iid), 0),	\
104 	.function = __builtin_choose_expr((fun) != SSAM_SSH_FUN_ANY, (fun), 0)
105 
106 /**
107  * SSAM_VDEV() - Initialize a &struct ssam_device_id as virtual device with
108  * the given parameters.
109  * @cat: Target category of the device.
110  * @tid: Target ID of the device.
111  * @iid: Instance ID of the device.
112  * @fun: Sub-function of the device.
113  *
114  * Initializes a &struct ssam_device_id with the given parameters in the
115  * virtual domain. See &struct ssam_device_uid for details regarding the
116  * parameters. The special values %SSAM_SSH_TID_ANY, %SSAM_SSH_IID_ANY, and
117  * %SSAM_SSH_FUN_ANY can be used to specify that matching should ignore target ID,
118  * instance ID, and/or sub-function, respectively. This macro initializes the
119  * ``match_flags`` field based on the given parameters.
120  *
121  * Note: The parameter @cat must be a valid &u8 value, the parameters @tid,
122  * @iid, and @fun must be either valid &u8 values or %SSAM_SSH_TID_ANY,
123  * %SSAM_SSH_IID_ANY, or %SSAM_SSH_FUN_ANY, respectively. Other non-&u8 values are not
124  * allowed.
125  */
126 #define SSAM_VDEV(cat, tid, iid, fun) \
127 	SSAM_DEVICE(SSAM_DOMAIN_VIRTUAL, SSAM_VIRTUAL_TC_##cat, SSAM_SSH_TID_##tid, iid, fun)
128 
129 /**
130  * SSAM_SDEV() - Initialize a &struct ssam_device_id as physical SSH device
131  * with the given parameters.
132  * @cat: Target category of the device.
133  * @tid: Target ID of the device.
134  * @iid: Instance ID of the device.
135  * @fun: Sub-function of the device.
136  *
137  * Initializes a &struct ssam_device_id with the given parameters in the SSH
138  * domain. See &struct ssam_device_uid for details regarding the parameters.
139  * The special values %SSAM_SSH_TID_ANY, %SSAM_SSH_IID_ANY, and
140  * %SSAM_SSH_FUN_ANY can be used to specify that matching should ignore target
141  * ID, instance ID, and/or sub-function, respectively. This macro initializes
142  * the ``match_flags`` field based on the given parameters.
143  *
144  * Note: The parameter @cat must be a valid &u8 value, the parameters @tid,
145  * @iid, and @fun must be either valid &u8 values or %SSAM_SSH_TID_ANY,
146  * %SSAM_SSH_IID_ANY, or %SSAM_SSH_FUN_ANY, respectively. Other non-&u8 values
147  * are not allowed.
148  */
149 #define SSAM_SDEV(cat, tid, iid, fun) \
150 	SSAM_DEVICE(SSAM_DOMAIN_SERIALHUB, SSAM_SSH_TC_##cat, SSAM_SSH_TID_##tid, iid, fun)
151 
152 /*
153  * enum ssam_device_flags - Flags for SSAM client devices.
154  * @SSAM_DEVICE_HOT_REMOVED_BIT:
155  *	The device has been hot-removed. Further communication with it may time
156  *	out and should be avoided.
157  */
158 enum ssam_device_flags {
159 	SSAM_DEVICE_HOT_REMOVED_BIT = 0,
160 };
161 
162 /**
163  * struct ssam_device - SSAM client device.
164  * @dev:   Driver model representation of the device.
165  * @ctrl:  SSAM controller managing this device.
166  * @uid:   UID identifying the device.
167  * @flags: Device state flags, see &enum ssam_device_flags.
168  */
169 struct ssam_device {
170 	struct device dev;
171 	struct ssam_controller *ctrl;
172 
173 	struct ssam_device_uid uid;
174 
175 	unsigned long flags;
176 };
177 
178 /**
179  * struct ssam_device_driver - SSAM client device driver.
180  * @driver:      Base driver model structure.
181  * @match_table: Match table specifying which devices the driver should bind to.
182  * @probe:       Called when the driver is being bound to a device.
183  * @remove:      Called when the driver is being unbound from the device.
184  */
185 struct ssam_device_driver {
186 	struct device_driver driver;
187 
188 	const struct ssam_device_id *match_table;
189 
190 	int  (*probe)(struct ssam_device *sdev);
191 	void (*remove)(struct ssam_device *sdev);
192 };
193 
194 #ifdef CONFIG_SURFACE_AGGREGATOR_BUS
195 
196 extern struct bus_type ssam_bus_type;
197 extern const struct device_type ssam_device_type;
198 
199 /**
200  * is_ssam_device() - Check if the given device is a SSAM client device.
201  * @d: The device to test the type of.
202  *
203  * Return: Returns %true if the specified device is of type &struct
204  * ssam_device, i.e. the device type points to %ssam_device_type, and %false
205  * otherwise.
206  */
is_ssam_device(struct device * d)207 static inline bool is_ssam_device(struct device *d)
208 {
209 	return d->type == &ssam_device_type;
210 }
211 
212 #else /* CONFIG_SURFACE_AGGREGATOR_BUS */
213 
is_ssam_device(struct device * d)214 static inline bool is_ssam_device(struct device *d)
215 {
216 	return false;
217 }
218 
219 #endif /* CONFIG_SURFACE_AGGREGATOR_BUS */
220 
221 /**
222  * to_ssam_device() - Casts the given device to a SSAM client device.
223  * @d: The device to cast.
224  *
225  * Casts the given &struct device to a &struct ssam_device. The caller has to
226  * ensure that the given device is actually enclosed in a &struct ssam_device,
227  * e.g. by calling is_ssam_device().
228  *
229  * Return: Returns a pointer to the &struct ssam_device wrapping the given
230  * device @d.
231  */
232 #define to_ssam_device(d)	container_of_const(d, struct ssam_device, dev)
233 
234 /**
235  * to_ssam_device_driver() - Casts the given device driver to a SSAM client
236  * device driver.
237  * @d: The driver to cast.
238  *
239  * Casts the given &struct device_driver to a &struct ssam_device_driver. The
240  * caller has to ensure that the given driver is actually enclosed in a
241  * &struct ssam_device_driver.
242  *
243  * Return: Returns the pointer to the &struct ssam_device_driver wrapping the
244  * given device driver @d.
245  */
246 #define to_ssam_device_driver(d)	container_of_const(d, struct ssam_device_driver, driver)
247 
248 const struct ssam_device_id *ssam_device_id_match(const struct ssam_device_id *table,
249 						  const struct ssam_device_uid uid);
250 
251 const struct ssam_device_id *ssam_device_get_match(const struct ssam_device *dev);
252 
253 const void *ssam_device_get_match_data(const struct ssam_device *dev);
254 
255 struct ssam_device *ssam_device_alloc(struct ssam_controller *ctrl,
256 				      struct ssam_device_uid uid);
257 
258 int ssam_device_add(struct ssam_device *sdev);
259 void ssam_device_remove(struct ssam_device *sdev);
260 
261 /**
262  * ssam_device_mark_hot_removed() - Mark the given device as hot-removed.
263  * @sdev: The device to mark as hot-removed.
264  *
265  * Mark the device as having been hot-removed. This signals drivers using the
266  * device that communication with the device should be avoided and may lead to
267  * timeouts.
268  */
ssam_device_mark_hot_removed(struct ssam_device * sdev)269 static inline void ssam_device_mark_hot_removed(struct ssam_device *sdev)
270 {
271 	dev_dbg(&sdev->dev, "marking device as hot-removed\n");
272 	set_bit(SSAM_DEVICE_HOT_REMOVED_BIT, &sdev->flags);
273 }
274 
275 /**
276  * ssam_device_is_hot_removed() - Check if the given device has been
277  * hot-removed.
278  * @sdev: The device to check.
279  *
280  * Checks if the given device has been marked as hot-removed. See
281  * ssam_device_mark_hot_removed() for more details.
282  *
283  * Return: Returns ``true`` if the device has been marked as hot-removed.
284  */
ssam_device_is_hot_removed(struct ssam_device * sdev)285 static inline bool ssam_device_is_hot_removed(struct ssam_device *sdev)
286 {
287 	return test_bit(SSAM_DEVICE_HOT_REMOVED_BIT, &sdev->flags);
288 }
289 
290 /**
291  * ssam_device_get() - Increment reference count of SSAM client device.
292  * @sdev: The device to increment the reference count of.
293  *
294  * Increments the reference count of the given SSAM client device by
295  * incrementing the reference count of the enclosed &struct device via
296  * get_device().
297  *
298  * See ssam_device_put() for the counter-part of this function.
299  *
300  * Return: Returns the device provided as input.
301  */
ssam_device_get(struct ssam_device * sdev)302 static inline struct ssam_device *ssam_device_get(struct ssam_device *sdev)
303 {
304 	return sdev ? to_ssam_device(get_device(&sdev->dev)) : NULL;
305 }
306 
307 /**
308  * ssam_device_put() - Decrement reference count of SSAM client device.
309  * @sdev: The device to decrement the reference count of.
310  *
311  * Decrements the reference count of the given SSAM client device by
312  * decrementing the reference count of the enclosed &struct device via
313  * put_device().
314  *
315  * See ssam_device_get() for the counter-part of this function.
316  */
ssam_device_put(struct ssam_device * sdev)317 static inline void ssam_device_put(struct ssam_device *sdev)
318 {
319 	if (sdev)
320 		put_device(&sdev->dev);
321 }
322 
323 /**
324  * ssam_device_get_drvdata() - Get driver-data of SSAM client device.
325  * @sdev: The device to get the driver-data from.
326  *
327  * Return: Returns the driver-data of the given device, previously set via
328  * ssam_device_set_drvdata().
329  */
ssam_device_get_drvdata(struct ssam_device * sdev)330 static inline void *ssam_device_get_drvdata(struct ssam_device *sdev)
331 {
332 	return dev_get_drvdata(&sdev->dev);
333 }
334 
335 /**
336  * ssam_device_set_drvdata() - Set driver-data of SSAM client device.
337  * @sdev: The device to set the driver-data of.
338  * @data: The data to set the device's driver-data pointer to.
339  */
ssam_device_set_drvdata(struct ssam_device * sdev,void * data)340 static inline void ssam_device_set_drvdata(struct ssam_device *sdev, void *data)
341 {
342 	dev_set_drvdata(&sdev->dev, data);
343 }
344 
345 int __ssam_device_driver_register(struct ssam_device_driver *d, struct module *o);
346 void ssam_device_driver_unregister(struct ssam_device_driver *d);
347 
348 /**
349  * ssam_device_driver_register() - Register a SSAM client device driver.
350  * @drv: The driver to register.
351  */
352 #define ssam_device_driver_register(drv) \
353 	__ssam_device_driver_register(drv, THIS_MODULE)
354 
355 /**
356  * module_ssam_device_driver() - Helper macro for SSAM device driver
357  * registration.
358  * @drv: The driver managed by this module.
359  *
360  * Helper macro to register a SSAM device driver via module_init() and
361  * module_exit(). This macro may only be used once per module and replaces the
362  * aforementioned definitions.
363  */
364 #define module_ssam_device_driver(drv)			\
365 	module_driver(drv, ssam_device_driver_register,	\
366 		      ssam_device_driver_unregister)
367 
368 
369 /* -- Helpers for controller and hub devices. ------------------------------- */
370 
371 #ifdef CONFIG_SURFACE_AGGREGATOR_BUS
372 
373 int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl,
374 			    struct fwnode_handle *node);
375 void ssam_remove_clients(struct device *dev);
376 
377 #else /* CONFIG_SURFACE_AGGREGATOR_BUS */
378 
__ssam_register_clients(struct device * parent,struct ssam_controller * ctrl,struct fwnode_handle * node)379 static inline int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl,
380 					  struct fwnode_handle *node)
381 {
382 	return 0;
383 }
384 
ssam_remove_clients(struct device * dev)385 static inline void ssam_remove_clients(struct device *dev) {}
386 
387 #endif /* CONFIG_SURFACE_AGGREGATOR_BUS */
388 
389 /**
390  * ssam_register_clients() - Register all client devices defined under the
391  * given parent device.
392  * @dev: The parent device under which clients should be registered.
393  * @ctrl: The controller with which client should be registered.
394  *
395  * Register all clients that have via firmware nodes been defined as children
396  * of the given (parent) device. The respective child firmware nodes will be
397  * associated with the correspondingly created child devices.
398  *
399  * The given controller will be used to instantiate the new devices. See
400  * ssam_device_add() for details.
401  *
402  * Return: Returns zero on success, nonzero on failure.
403  */
ssam_register_clients(struct device * dev,struct ssam_controller * ctrl)404 static inline int ssam_register_clients(struct device *dev, struct ssam_controller *ctrl)
405 {
406 	return __ssam_register_clients(dev, ctrl, dev_fwnode(dev));
407 }
408 
409 /**
410  * ssam_device_register_clients() - Register all client devices defined under
411  * the given SSAM parent device.
412  * @sdev: The parent device under which clients should be registered.
413  *
414  * Register all clients that have via firmware nodes been defined as children
415  * of the given (parent) device. The respective child firmware nodes will be
416  * associated with the correspondingly created child devices.
417  *
418  * The controller used by the parent device will be used to instantiate the new
419  * devices. See ssam_device_add() for details.
420  *
421  * Return: Returns zero on success, nonzero on failure.
422  */
ssam_device_register_clients(struct ssam_device * sdev)423 static inline int ssam_device_register_clients(struct ssam_device *sdev)
424 {
425 	return ssam_register_clients(&sdev->dev, sdev->ctrl);
426 }
427 
428 
429 /* -- Helpers for client-device requests. ----------------------------------- */
430 
431 /**
432  * SSAM_DEFINE_SYNC_REQUEST_CL_N() - Define synchronous client-device SAM
433  * request function with neither argument nor return value.
434  * @name: Name of the generated function.
435  * @spec: Specification (&struct ssam_request_spec_md) defining the request.
436  *
437  * Defines a function executing the synchronous SAM request specified by
438  * @spec, with the request having neither argument nor return value. Device
439  * specifying parameters are not hard-coded, but instead are provided via the
440  * client device, specifically its UID, supplied when calling this function.
441  * The generated function takes care of setting up the request struct, buffer
442  * allocation, as well as execution of the request itself, returning once the
443  * request has been fully completed. The required transport buffer will be
444  * allocated on the stack.
445  *
446  * The generated function is defined as ``static int name(struct ssam_device
447  * *sdev)``, returning the status of the request, which is zero on success and
448  * negative on failure. The ``sdev`` parameter specifies both the target
449  * device of the request and by association the controller via which the
450  * request is sent.
451  *
452  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
453  * the generated function.
454  */
455 #define SSAM_DEFINE_SYNC_REQUEST_CL_N(name, spec...)			\
456 	SSAM_DEFINE_SYNC_REQUEST_MD_N(__raw_##name, spec)		\
457 	static int name(struct ssam_device *sdev)			\
458 	{								\
459 		return __raw_##name(sdev->ctrl, sdev->uid.target,	\
460 				    sdev->uid.instance);		\
461 	}
462 
463 /**
464  * SSAM_DEFINE_SYNC_REQUEST_CL_W() - Define synchronous client-device SAM
465  * request function with argument.
466  * @name:  Name of the generated function.
467  * @atype: Type of the request's argument.
468  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
469  *
470  * Defines a function executing the synchronous SAM request specified by
471  * @spec, with the request taking an argument of type @atype and having no
472  * return value. Device specifying parameters are not hard-coded, but instead
473  * are provided via the client device, specifically its UID, supplied when
474  * calling this function. The generated function takes care of setting up the
475  * request struct, buffer allocation, as well as execution of the request
476  * itself, returning once the request has been fully completed. The required
477  * transport buffer will be allocated on the stack.
478  *
479  * The generated function is defined as ``static int name(struct ssam_device
480  * *sdev, const atype *arg)``, returning the status of the request, which is
481  * zero on success and negative on failure. The ``sdev`` parameter specifies
482  * both the target device of the request and by association the controller via
483  * which the request is sent. The request's argument is specified via the
484  * ``arg`` pointer.
485  *
486  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
487  * the generated function.
488  */
489 #define SSAM_DEFINE_SYNC_REQUEST_CL_W(name, atype, spec...)		\
490 	SSAM_DEFINE_SYNC_REQUEST_MD_W(__raw_##name, atype, spec)	\
491 	static int name(struct ssam_device *sdev, const atype *arg)	\
492 	{								\
493 		return __raw_##name(sdev->ctrl, sdev->uid.target,	\
494 				    sdev->uid.instance, arg);		\
495 	}
496 
497 /**
498  * SSAM_DEFINE_SYNC_REQUEST_CL_R() - Define synchronous client-device SAM
499  * request function with return value.
500  * @name:  Name of the generated function.
501  * @rtype: Type of the request's return value.
502  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
503  *
504  * Defines a function executing the synchronous SAM request specified by
505  * @spec, with the request taking no argument but having a return value of
506  * type @rtype. Device specifying parameters are not hard-coded, but instead
507  * are provided via the client device, specifically its UID, supplied when
508  * calling this function. The generated function takes care of setting up the
509  * request struct, buffer allocation, as well as execution of the request
510  * itself, returning once the request has been fully completed. The required
511  * transport buffer will be allocated on the stack.
512  *
513  * The generated function is defined as ``static int name(struct ssam_device
514  * *sdev, rtype *ret)``, returning the status of the request, which is zero on
515  * success and negative on failure. The ``sdev`` parameter specifies both the
516  * target device of the request and by association the controller via which
517  * the request is sent. The request's return value is written to the memory
518  * pointed to by the ``ret`` parameter.
519  *
520  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
521  * the generated function.
522  */
523 #define SSAM_DEFINE_SYNC_REQUEST_CL_R(name, rtype, spec...)		\
524 	SSAM_DEFINE_SYNC_REQUEST_MD_R(__raw_##name, rtype, spec)	\
525 	static int name(struct ssam_device *sdev, rtype *ret)		\
526 	{								\
527 		return __raw_##name(sdev->ctrl, sdev->uid.target,	\
528 				    sdev->uid.instance, ret);		\
529 	}
530 
531 /**
532  * SSAM_DEFINE_SYNC_REQUEST_CL_WR() - Define synchronous client-device SAM
533  * request function with argument and return value.
534  * @name:  Name of the generated function.
535  * @atype: Type of the request's argument.
536  * @rtype: Type of the request's return value.
537  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
538  *
539  * Defines a function executing the synchronous SAM request specified by @spec,
540  * with the request taking an argument of type @atype and having a return value
541  * of type @rtype. Device specifying parameters are not hard-coded, but instead
542  * are provided via the client device, specifically its UID, supplied when
543  * calling this function. The generated function takes care of setting up the
544  * request struct, buffer allocation, as well as execution of the request
545  * itself, returning once the request has been fully completed. The required
546  * transport buffer will be allocated on the stack.
547  *
548  * The generated function is defined as ``static int name(struct ssam_device
549  * *sdev, const atype *arg, rtype *ret)``, returning the status of the request,
550  * which is zero on success and negative on failure. The ``sdev`` parameter
551  * specifies both the target device of the request and by association the
552  * controller via which the request is sent. The request's argument is
553  * specified via the ``arg`` pointer. The request's return value is written to
554  * the memory pointed to by the ``ret`` parameter.
555  *
556  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
557  * the generated function.
558  */
559 #define SSAM_DEFINE_SYNC_REQUEST_CL_WR(name, atype, rtype, spec...)		\
560 	SSAM_DEFINE_SYNC_REQUEST_MD_WR(__raw_##name, atype, rtype, spec)	\
561 	static int name(struct ssam_device *sdev, const atype *arg, rtype *ret)	\
562 	{									\
563 		return __raw_##name(sdev->ctrl, sdev->uid.target,		\
564 				    sdev->uid.instance, arg, ret);		\
565 	}
566 
567 
568 /* -- Helpers for client-device notifiers. ---------------------------------- */
569 
570 /**
571  * ssam_device_notifier_register() - Register an event notifier for the
572  * specified client device.
573  * @sdev: The device the notifier should be registered on.
574  * @n:    The event notifier to register.
575  *
576  * Register an event notifier. Increment the usage counter of the associated
577  * SAM event if the notifier is not marked as an observer. If the event is not
578  * marked as an observer and is currently not enabled, it will be enabled
579  * during this call. If the notifier is marked as an observer, no attempt will
580  * be made at enabling any event and no reference count will be modified.
581  *
582  * Notifiers marked as observers do not need to be associated with one specific
583  * event, i.e. as long as no event matching is performed, only the event target
584  * category needs to be set.
585  *
586  * Return: Returns zero on success, %-ENOSPC if there have already been
587  * %INT_MAX notifiers for the event ID/type associated with the notifier block
588  * registered, %-ENOMEM if the corresponding event entry could not be
589  * allocated, %-ENODEV if the device is marked as hot-removed. If this is the
590  * first time that a notifier block is registered for the specific associated
591  * event, returns the status of the event-enable EC-command.
592  */
ssam_device_notifier_register(struct ssam_device * sdev,struct ssam_event_notifier * n)593 static inline int ssam_device_notifier_register(struct ssam_device *sdev,
594 						struct ssam_event_notifier *n)
595 {
596 	/*
597 	 * Note that this check does not provide any guarantees whatsoever as
598 	 * hot-removal could happen at any point and we can't protect against
599 	 * it. Nevertheless, if we can detect hot-removal, bail early to avoid
600 	 * communication timeouts.
601 	 */
602 	if (ssam_device_is_hot_removed(sdev))
603 		return -ENODEV;
604 
605 	return ssam_notifier_register(sdev->ctrl, n);
606 }
607 
608 /**
609  * ssam_device_notifier_unregister() - Unregister an event notifier for the
610  * specified client device.
611  * @sdev: The device the notifier has been registered on.
612  * @n:    The event notifier to unregister.
613  *
614  * Unregister an event notifier. Decrement the usage counter of the associated
615  * SAM event if the notifier is not marked as an observer. If the usage counter
616  * reaches zero, the event will be disabled.
617  *
618  * In case the device has been marked as hot-removed, the event will not be
619  * disabled on the EC, as in those cases any attempt at doing so may time out.
620  *
621  * Return: Returns zero on success, %-ENOENT if the given notifier block has
622  * not been registered on the controller. If the given notifier block was the
623  * last one associated with its specific event, returns the status of the
624  * event-disable EC-command.
625  */
ssam_device_notifier_unregister(struct ssam_device * sdev,struct ssam_event_notifier * n)626 static inline int ssam_device_notifier_unregister(struct ssam_device *sdev,
627 						  struct ssam_event_notifier *n)
628 {
629 	return __ssam_notifier_unregister(sdev->ctrl, n,
630 					  !ssam_device_is_hot_removed(sdev));
631 }
632 
633 #endif /* _LINUX_SURFACE_AGGREGATOR_DEVICE_H */
634