Lines Matching +full:on +full:- +full:device
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_ANY_IID, or %SSAM_ANY_FUN, 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_ANY_IID, or %SSAM_ANY_FUN, 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 * sub-function, respectively. This macro initializes the ``match_flags``
142 * field based on the given parameters.
146 * %SSAM_ANY_IID, or %SSAM_ANY_FUN, respectively. Other non-&u8 values are not
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.
200 * is_ssam_device() - Check if the given device is a SSAM client device.
201 * @d: The device to test the type of.
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
207 static inline bool is_ssam_device(struct device *d) in is_ssam_device()
209 return d->type == &ssam_device_type; in is_ssam_device()
214 static inline bool is_ssam_device(struct device *d) in is_ssam_device()
222 * to_ssam_device() - Casts the given device to a SSAM client device.
223 * @d: The device to cast.
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,
230 * device @d.
232 static inline struct ssam_device *to_ssam_device(struct device *d) in to_ssam_device()
238 * to_ssam_device_driver() - Casts the given device driver to a SSAM client
239 * device driver.
247 * given device driver @d.
269 * ssam_device_mark_hot_removed() - Mark the given device as hot-removed.
270 * @sdev: The device to mark as hot-removed.
272 * Mark the device as having been hot-removed. This signals drivers using the
273 * device that communication with the device should be avoided and may lead to
278 dev_dbg(&sdev->dev, "marking device as hot-removed\n"); in ssam_device_mark_hot_removed()
279 set_bit(SSAM_DEVICE_HOT_REMOVED_BIT, &sdev->flags); in ssam_device_mark_hot_removed()
283 * ssam_device_is_hot_removed() - Check if the given device has been
284 * hot-removed.
285 * @sdev: The device to check.
287 * Checks if the given device has been marked as hot-removed. See
290 * Return: Returns ``true`` if the device has been marked as hot-removed.
294 return test_bit(SSAM_DEVICE_HOT_REMOVED_BIT, &sdev->flags); in ssam_device_is_hot_removed()
298 * ssam_device_get() - Increment reference count of SSAM client device.
299 * @sdev: The device to increment the reference count of.
301 * Increments the reference count of the given SSAM client device by
302 * incrementing the reference count of the enclosed &struct device via
305 * See ssam_device_put() for the counter-part of this function.
307 * Return: Returns the device provided as input.
311 return sdev ? to_ssam_device(get_device(&sdev->dev)) : NULL; in ssam_device_get()
315 * ssam_device_put() - Decrement reference count of SSAM client device.
316 * @sdev: The device to decrement the reference count of.
318 * Decrements the reference count of the given SSAM client device by
319 * decrementing the reference count of the enclosed &struct device via
322 * See ssam_device_get() for the counter-part of this function.
327 put_device(&sdev->dev); in ssam_device_put()
331 * ssam_device_get_drvdata() - Get driver-data of SSAM client device.
332 * @sdev: The device to get the driver-data from.
334 * Return: Returns the driver-data of the given device, previously set via
339 return dev_get_drvdata(&sdev->dev); in ssam_device_get_drvdata()
343 * ssam_device_set_drvdata() - Set driver-data of SSAM client device.
344 * @sdev: The device to set the driver-data of.
345 * @data: The data to set the device's driver-data pointer to.
349 dev_set_drvdata(&sdev->dev, data); in ssam_device_set_drvdata()
356 * ssam_device_driver_register() - Register a SSAM client device driver.
363 * module_ssam_device_driver() - Helper macro for SSAM device driver
367 * Helper macro to register a SSAM device driver via module_init() and
376 /* -- Helpers for controller and hub devices. ------------------------------- */
380 int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl,
382 void ssam_remove_clients(struct device *dev);
386 static inline int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl, in __ssam_register_clients()
392 static inline void ssam_remove_clients(struct device *dev) {} in ssam_remove_clients()
397 * ssam_register_clients() - Register all client devices defined under the
398 * given parent device.
399 * @dev: The parent device under which clients should be registered.
403 * of the given (parent) device. The respective child firmware nodes will be
409 * Return: Returns zero on success, nonzero on failure.
411 static inline int ssam_register_clients(struct device *dev, struct ssam_controller *ctrl) in ssam_register_clients()
417 * ssam_device_register_clients() - Register all client devices defined under
418 * the given SSAM parent device.
419 * @sdev: The parent device under which clients should be registered.
422 * of the given (parent) device. The respective child firmware nodes will be
425 * The controller used by the parent device will be used to instantiate the new
428 * Return: Returns zero on success, nonzero on failure.
432 return ssam_register_clients(&sdev->dev, sdev->ctrl); in ssam_device_register_clients()
436 /* -- Helpers for client-device requests. ----------------------------------- */
439 * SSAM_DEFINE_SYNC_REQUEST_CL_N() - Define synchronous client-device SAM
445 * @spec, with the request having neither argument nor return value. Device
446 * specifying parameters are not hard-coded, but instead are provided via the
447 * client device, specifically its UID, supplied when calling this function.
451 * allocated on the stack.
454 * *sdev)``, returning the status of the request, which is zero on success and
455 * negative on failure. The ``sdev`` parameter specifies both the target
456 * device of the request and by association the controller via which the
459 * Refer to ssam_request_sync_onstack() for more details on the behavior of
466 return __raw_##name(sdev->ctrl, sdev->uid.target, \
467 sdev->uid.instance); \
471 * SSAM_DEFINE_SYNC_REQUEST_CL_W() - Define synchronous client-device SAM
479 * return value. Device specifying parameters are not hard-coded, but instead
480 * are provided via the client device, specifically its UID, supplied when
484 * transport buffer will be allocated on the stack.
488 * zero on success and negative on failure. The ``sdev`` parameter specifies
489 * both the target device of the request and by association the controller via
493 * Refer to ssam_request_sync_onstack() for more details on the behavior of
500 return __raw_##name(sdev->ctrl, sdev->uid.target, \
501 sdev->uid.instance, arg); \
505 * SSAM_DEFINE_SYNC_REQUEST_CL_R() - Define synchronous client-device SAM
513 * type @rtype. Device specifying parameters are not hard-coded, but instead
514 * are provided via the client device, specifically its UID, supplied when
518 * transport buffer will be allocated on the stack.
521 * *sdev, rtype *ret)``, returning the status of the request, which is zero on
522 * success and negative on failure. The ``sdev`` parameter specifies both the
523 * target device of the request and by association the controller via which
527 * Refer to ssam_request_sync_onstack() for more details on the behavior of
534 return __raw_##name(sdev->ctrl, sdev->uid.target, \
535 sdev->uid.instance, ret); \
539 * SSAM_DEFINE_SYNC_REQUEST_CL_WR() - Define synchronous client-device SAM
548 * of type @rtype. Device specifying parameters are not hard-coded, but instead
549 * are provided via the client device, specifically its UID, supplied when
553 * transport buffer will be allocated on the stack.
557 * which is zero on success and negative on failure. The ``sdev`` parameter
558 * specifies both the target device of the request and by association the
563 * Refer to ssam_request_sync_onstack() for more details on the behavior of
570 return __raw_##name(sdev->ctrl, sdev->uid.target, \
571 sdev->uid.instance, arg, ret); \
575 /* -- Helpers for client-device notifiers. ---------------------------------- */
578 * ssam_device_notifier_register() - Register an event notifier for the
579 * specified client device.
580 * @sdev: The device the notifier should be registered on.
593 * Return: Returns zero on success, %-ENOSPC if there have already been
595 * registered, %-ENOMEM if the corresponding event entry could not be
596 * allocated, %-ENODEV if the device is marked as hot-removed. If this is the
598 * event, returns the status of the event-enable EC-command.
605 * hot-removal could happen at any point and we can't protect against in ssam_device_notifier_register()
606 * it. Nevertheless, if we can detect hot-removal, bail early to avoid in ssam_device_notifier_register()
610 return -ENODEV; in ssam_device_notifier_register()
612 return ssam_notifier_register(sdev->ctrl, n); in ssam_device_notifier_register()
616 * ssam_device_notifier_unregister() - Unregister an event notifier for the
617 * specified client device.
618 * @sdev: The device the notifier has been registered on.
625 * In case the device has been marked as hot-removed, the event will not be
626 * disabled on the EC, as in those cases any attempt at doing so may time out.
628 * Return: Returns zero on success, %-ENOENT if the given notifier block has
629 * not been registered on the controller. If the given notifier block was the
631 * event-disable EC-command.
636 return __ssam_notifier_unregister(sdev->ctrl, n, in ssam_device_notifier_unregister()