linux/surface_aggregator/device.h

1 /* SPDX-License-Identifier: GPL-2.0+ */
3  * Surface System Aggregator Module (SSAM) bus and client-device subsystem.
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
10  * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com>
16 #include <linux/device.h>
24 /* -- Surface System Aggregator Module bus. --------------------------------- */
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.
37  * enum ssam_virtual_tc - Target categories for the virtual SAM domain.
38  * @SSAM_VIRTUAL_TC_HUB: Device hub category.
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
64  * Special values for device matching.
68  * match_flags member of the device ID structure. Do not use them directly
76  * SSAM_DEVICE() - Initialize a &struct ssam_device_id with the given
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.
87  * matching should ignore target ID, instance ID, and/or sub-function,
88  * respectively. This macro initializes the ``match_flags`` field based on the
93  * %SSAM_SSH_IID_ANY, or %SSAM_SSH_FUN_ANY, respectively. Other non-&u8 values are not
107  * SSAM_VDEV() - Initialize a &struct ssam_device_id as virtual device with
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.
118  * instance ID, and/or sub-function, respectively. This macro initializes the
119  * ``match_flags`` field based on the given parameters.
123  * %SSAM_SSH_IID_ANY, or %SSAM_SSH_FUN_ANY, respectively. Other non-&u8 values are not
130  * SSAM_SDEV() - Initialize a &struct ssam_device_id as physical SSH device
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.
141  * ID, instance ID, and/or sub-function, respectively. This macro initializes
142  * the ``match_flags`` field based on the given parameters.
146  * %SSAM_SSH_IID_ANY, or %SSAM_SSH_FUN_ANY, respectively. Other non-&u8 values
153  * enum ssam_device_flags - Flags for SSAM client devices.
155  *	The device has been hot-removed. Further communication with it may time
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.
170 	struct device dev;
179  * struct ssam_device_driver - SSAM client device driver.
182  * @probe:       Called when the driver is being bound to a device.
183  * @remove:      Called when the driver is being unbound from the device.
199  * is_ssam_device() - Check if the given device is a SSAM client device.
200  * @d: The device to test the type of.
202  * Return: Returns %true if the specified device is of type &struct
203  * ssam_device, i.e. the device type points to %ssam_device_type, and %false
206 static inline bool is_ssam_device(struct device *d)  in is_ssam_device()
208 	return d->type == &ssam_device_type;  in is_ssam_device()
213 static inline bool is_ssam_device(struct device *d)  in is_ssam_device()
221  * to_ssam_device() - Casts the given device to a SSAM client device.
222  * @d: The device to cast.
224  * Casts the given &struct device to a &struct ssam_device. The caller has to
225  * ensure that the given device is actually enclosed in a &struct ssam_device,
229  * device @d.
234  * to_ssam_device_driver() - Casts the given device driver to a SSAM client
235  * device driver.
243  * given device driver @d.
261  * ssam_device_mark_hot_removed() - Mark the given device as hot-removed.
262  * @sdev: The device to mark as hot-removed.
264  * Mark the device as having been hot-removed. This signals drivers using the
265  * device that communication with the device should be avoided and may lead to
270 	dev_dbg(&sdev->dev, "marking device as hot-removed\n");  in ssam_device_mark_hot_removed()
271 	set_bit(SSAM_DEVICE_HOT_REMOVED_BIT, &sdev->flags);  in ssam_device_mark_hot_removed()
275  * ssam_device_is_hot_removed() - Check if the given device has been
276  * hot-removed.
277  * @sdev: The device to check.
279  * Checks if the given device has been marked as hot-removed. See
282  * Return: Returns ``true`` if the device has been marked as hot-removed.
286 	return test_bit(SSAM_DEVICE_HOT_REMOVED_BIT, &sdev->flags);  in ssam_device_is_hot_removed()
290  * ssam_device_get() - Increment reference count of SSAM client device.
291  * @sdev: The device to increment the reference count of.
293  * Increments the reference count of the given SSAM client device by
294  * incrementing the reference count of the enclosed &struct device via
297  * See ssam_device_put() for the counter-part of this function.
299  * Return: Returns the device provided as input.
303 	return sdev ? to_ssam_device(get_device(&sdev->dev)) : NULL;  in ssam_device_get()
307  * ssam_device_put() - Decrement reference count of SSAM client device.
308  * @sdev: The device to decrement the reference count of.
310  * Decrements the reference count of the given SSAM client device by
311  * decrementing the reference count of the enclosed &struct device via
314  * See ssam_device_get() for the counter-part of this function.
319 		put_device(&sdev->dev);  in ssam_device_put()
323  * ssam_device_get_drvdata() - Get driver-data of SSAM client device.
324  * @sdev: The device to get the driver-data from.
326  * Return: Returns the driver-data of the given device, previously set via
331 	return dev_get_drvdata(&sdev->dev);  in ssam_device_get_drvdata()
335  * ssam_device_set_drvdata() - Set driver-data of SSAM client device.
336  * @sdev: The device to set the driver-data of.
337  * @data: The data to set the device's driver-data pointer to.
341 	dev_set_drvdata(&sdev->dev, data);  in ssam_device_set_drvdata()
348  * ssam_device_driver_register() - Register a SSAM client device driver.
355  * module_ssam_device_driver() - Helper macro for SSAM device driver
359  * Helper macro to register a SSAM device driver via module_init() and
368 /* -- Helpers for controller and hub devices. ------------------------------- */
372 int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl,
374 void ssam_remove_clients(struct device *dev);
378 static inline int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl,  in __ssam_register_clients()
384 static inline void ssam_remove_clients(struct device *dev) {}  in ssam_remove_clients()
389  * ssam_register_clients() - Register all client devices defined under the
390  * given parent device.
391  * @dev: The parent device under which clients should be registered.
395  * of the given (parent) device. The respective child firmware nodes will be
401  * Return: Returns zero on success, nonzero on failure.
403 static inline int ssam_register_clients(struct device *dev, struct ssam_controller *ctrl)  in ssam_register_clients()
409  * ssam_device_register_clients() - Register all client devices defined under
410  * the given SSAM parent device.
411  * @sdev: The parent device under which clients should be registered.
414  * of the given (parent) device. The respective child firmware nodes will be
417  * The controller used by the parent device will be used to instantiate the new
420  * Return: Returns zero on success, nonzero on failure.
424 	return ssam_register_clients(&sdev->dev, sdev->ctrl);  in ssam_device_register_clients()
428 /* -- Helpers for client-device requests. ----------------------------------- */
431  * SSAM_DEFINE_SYNC_REQUEST_CL_N() - Define synchronous client-device SAM
437  * @spec, with the request having neither argument nor return value. Device
438  * specifying parameters are not hard-coded, but instead are provided via the
439  * client device, specifically its UID, supplied when calling this function.
443  * allocated on the stack.
446  * *sdev)``, returning the status of the request, which is zero on success and
447  * negative on failure. The ``sdev`` parameter specifies both the target
448  * device of the request and by association the controller via which the
451  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
458 		return __raw_##name(sdev->ctrl, sdev->uid.target,	\
459 				    sdev->uid.instance);		\
463  * SSAM_DEFINE_SYNC_REQUEST_CL_W() - Define synchronous client-device SAM
471  * return value. Device specifying parameters are not hard-coded, but instead
472  * are provided via the client device, specifically its UID, supplied when
476  * transport buffer will be allocated on the stack.
480  * zero on success and negative on failure. The ``sdev`` parameter specifies
481  * both the target device of the request and by association the controller via
485  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
492 		return __raw_##name(sdev->ctrl, sdev->uid.target,	\
493 				    sdev->uid.instance, arg);		\
497  * SSAM_DEFINE_SYNC_REQUEST_CL_R() - Define synchronous client-device SAM
505  * type @rtype. Device specifying parameters are not hard-coded, but instead
506  * are provided via the client device, specifically its UID, supplied when
510  * transport buffer will be allocated on the stack.
513  * *sdev, rtype *ret)``, returning the status of the request, which is zero on
514  * success and negative on failure. The ``sdev`` parameter specifies both the
515  * target device of the request and by association the controller via which
519  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
526 		return __raw_##name(sdev->ctrl, sdev->uid.target,	\
527 				    sdev->uid.instance, ret);		\
531  * SSAM_DEFINE_SYNC_REQUEST_CL_WR() - Define synchronous client-device SAM
540  * of type @rtype. Device specifying parameters are not hard-coded, but instead
541  * are provided via the client device, specifically its UID, supplied when
545  * transport buffer will be allocated on the stack.
549  * which is zero on success and negative on failure. The ``sdev`` parameter
550  * specifies both the target device of the request and by association the
555  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
562 		return __raw_##name(sdev->ctrl, sdev->uid.target,		\
563 				    sdev->uid.instance, arg, ret);		\
567 /* -- Helpers for client-device notifiers. ---------------------------------- */
570  * ssam_device_notifier_register() - Register an event notifier for the
571  * specified client device.
572  * @sdev: The device the notifier should be registered on.
585  * Return: Returns zero on success, %-ENOSPC if there have already been
587  * registered, %-ENOMEM if the corresponding event entry could not be
588  * allocated, %-ENODEV if the device is marked as hot-removed. If this is the
590  * event, returns the status of the event-enable EC-command.
597 	 * hot-removal could happen at any point and we can't protect against  in ssam_device_notifier_register()
598 	 * it. Nevertheless, if we can detect hot-removal, bail early to avoid  in ssam_device_notifier_register()
602 		return -ENODEV;  in ssam_device_notifier_register()
604 	return ssam_notifier_register(sdev->ctrl, n);  in ssam_device_notifier_register()
608  * ssam_device_notifier_unregister() - Unregister an event notifier for the
609  * specified client device.
610  * @sdev: The device the notifier has been registered on.
617  * In case the device has been marked as hot-removed, the event will not be
618  * disabled on the EC, as in those cases any attempt at doing so may time out.
620  * Return: Returns zero on success, %-ENOENT if the given notifier block has
621  * not been registered on the controller. If the given notifier block was the
623  * event-disable EC-command.
628 	return __ssam_notifier_unregister(sdev->ctrl, n,  in ssam_device_notifier_unregister()