include/linux/surface_aggregator/device.h

   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 <[email protected]>
  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  */
 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
 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  */
 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  */
 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  */
 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  */
 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  */
 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  */
 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
 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
 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  */
 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  */
 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  */
 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  */
 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 */