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
7  * Provides support for non-platform/non-ACPI SSAM clients via dedicated
10  * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com>
24 /* -- Surface System Aggregator Module bus. --------------------------------- */
27  * enum ssam_device_domain - SAM device domain.
29  * @SSAM_DOMAIN_SERIALHUB: Physical device connected via Surface Serial Hub.
37  * enum ssam_virtual_tc - Target categories for the virtual SAM domain.
45  * struct ssam_device_uid - Unique identifier for SSAM 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
76  * SSAM_DEVICE() - Initialize a &struct ssam_device_id with the given
82  * @fun: Sub-function of the device.
87  * matching should ignore target ID, instance ID, and/or sub-function,
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
112  * @fun: Sub-function of the device.
118  * instance ID, and/or sub-function, respectively. This macro initializes the
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
135  * @fun: Sub-function of the device.
141  * ID, instance ID, and/or sub-function, respectively. This macro initializes
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.
179  * struct ssam_device_driver - SSAM client device driver.
199  * is_ssam_device() - Check if the given device is a SSAM client device.
208 	return d->type == &ssam_device_type;  in is_ssam_device()
221  * to_ssam_device() - Casts the given device to a SSAM client device.
234  * to_ssam_device_driver() - Casts the given device driver to a SSAM client
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
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.
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.
297  * See ssam_device_put() for the counter-part of this function.
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.
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
368 /* -- Helpers for controller and hub devices. ------------------------------- */
389  * ssam_register_clients() - Register all client devices defined under the
409  * ssam_device_register_clients() - Register all client devices defined under
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
436  * Defines a function executing the synchronous SAM request specified by
438  * specifying parameters are not hard-coded, but instead are provided via the
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
469  * Defines a function executing the synchronous SAM request specified by
471  * return value. Device specifying parameters are not hard-coded, but instead
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
503  * Defines a function executing the synchronous SAM request specified by
505  * type @rtype. Device specifying parameters are not hard-coded, but instead
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
538  * Defines a function executing the synchronous SAM request specified by @spec,
540  * of type @rtype. Device specifying parameters are not hard-coded, but instead
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
576  * SAM event if the notifier is not marked as an observer. If the event is not
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
614  * SAM event if the notifier is not marked as an observer. If the usage counter
617  * In case the device has been marked as hot-removed, the event will not be
620  * Return: Returns zero on success, %-ENOENT if the given notifier block has
623  * event-disable EC-command.
628 	return __ssam_notifier_unregister(sdev->ctrl, n,  in ssam_device_notifier_unregister()