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 static inline
 247 struct ssam_device_driver *to_ssam_device_driver(struct device_driver *d)
 248 {
 249         return container_of(d, struct ssam_device_driver, driver);
 250 }
 251
 252 const struct ssam_device_id *ssam_device_id_match(const struct ssam_device_id *table,
 253                                                   const struct ssam_device_uid uid);
 254
 255 const struct ssam_device_id *ssam_device_get_match(const struct ssam_device *dev);
 256
 257 const void *ssam_device_get_match_data(const struct ssam_device *dev);
 258
 259 struct ssam_device *ssam_device_alloc(struct ssam_controller *ctrl,
 260                                       struct ssam_device_uid uid);
 261
 262 int ssam_device_add(struct ssam_device *sdev);
 263 void ssam_device_remove(struct ssam_device *sdev);
 264
 265 /**
 266  * ssam_device_mark_hot_removed() - Mark the given device as hot-removed.
 267  * @sdev: The device to mark as hot-removed.
 268  *
 269  * Mark the device as having been hot-removed. This signals drivers using the
 270  * device that communication with the device should be avoided and may lead to
 271  * timeouts.
 272  */
 273 static inline void ssam_device_mark_hot_removed(struct ssam_device *sdev)
 274 {
 275         dev_dbg(&sdev->dev, "marking device as hot-removed\n");
 276         set_bit(SSAM_DEVICE_HOT_REMOVED_BIT, &sdev->flags);
 277 }
 278
 279 /**
 280  * ssam_device_is_hot_removed() - Check if the given device has been
 281  * hot-removed.
 282  * @sdev: The device to check.
 283  *
 284  * Checks if the given device has been marked as hot-removed. See
 285  * ssam_device_mark_hot_removed() for more details.
 286  *
 287  * Return: Returns ``true`` if the device has been marked as hot-removed.
 288  */
 289 static inline bool ssam_device_is_hot_removed(struct ssam_device *sdev)
 290 {
 291         return test_bit(SSAM_DEVICE_HOT_REMOVED_BIT, &sdev->flags);
 292 }
 293
 294 /**
 295  * ssam_device_get() - Increment reference count of SSAM client device.
 296  * @sdev: The device to increment the reference count of.
 297  *
 298  * Increments the reference count of the given SSAM client device by
 299  * incrementing the reference count of the enclosed &struct device via
 300  * get_device().
 301  *
 302  * See ssam_device_put() for the counter-part of this function.
 303  *
 304  * Return: Returns the device provided as input.
 305  */
 306 static inline struct ssam_device *ssam_device_get(struct ssam_device *sdev)
 307 {
 308         return sdev ? to_ssam_device(get_device(&sdev->dev)) : NULL;
 309 }
 310
 311 /**
 312  * ssam_device_put() - Decrement reference count of SSAM client device.
 313  * @sdev: The device to decrement the reference count of.
 314  *
 315  * Decrements the reference count of the given SSAM client device by
 316  * decrementing the reference count of the enclosed &struct device via
 317  * put_device().
 318  *
 319  * See ssam_device_get() for the counter-part of this function.
 320  */
 321 static inline void ssam_device_put(struct ssam_device *sdev)
 322 {
 323         if (sdev)
 324                 put_device(&sdev->dev);
 325 }
 326
 327 /**
 328  * ssam_device_get_drvdata() - Get driver-data of SSAM client device.
 329  * @sdev: The device to get the driver-data from.
 330  *
 331  * Return: Returns the driver-data of the given device, previously set via
 332  * ssam_device_set_drvdata().
 333  */
 334 static inline void *ssam_device_get_drvdata(struct ssam_device *sdev)
 335 {
 336         return dev_get_drvdata(&sdev->dev);
 337 }
 338
 339 /**
 340  * ssam_device_set_drvdata() - Set driver-data of SSAM client device.
 341  * @sdev: The device to set the driver-data of.
 342  * @data: The data to set the device's driver-data pointer to.
 343  */
 344 static inline void ssam_device_set_drvdata(struct ssam_device *sdev, void *data)
 345 {
 346         dev_set_drvdata(&sdev->dev, data);
 347 }
 348
 349 int __ssam_device_driver_register(struct ssam_device_driver *d, struct module *o);
 350 void ssam_device_driver_unregister(struct ssam_device_driver *d);
 351
 352 /**
 353  * ssam_device_driver_register() - Register a SSAM client device driver.
 354  * @drv: The driver to register.
 355  */
 356 #define ssam_device_driver_register(drv) \
 357         __ssam_device_driver_register(drv, THIS_MODULE)
 358
 359 /**
 360  * module_ssam_device_driver() - Helper macro for SSAM device driver
 361  * registration.
 362  * @drv: The driver managed by this module.
 363  *
 364  * Helper macro to register a SSAM device driver via module_init() and
 365  * module_exit(). This macro may only be used once per module and replaces the
 366  * aforementioned definitions.
 367  */
 368 #define module_ssam_device_driver(drv)                  \
 369         module_driver(drv, ssam_device_driver_register, \
 370                       ssam_device_driver_unregister)
 371
 372
 373 /* -- Helpers for controller and hub devices. ------------------------------- */
 374
 375 #ifdef CONFIG_SURFACE_AGGREGATOR_BUS
 376
 377 int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl,
 378                             struct fwnode_handle *node);
 379 void ssam_remove_clients(struct device *dev);
 380
 381 #else /* CONFIG_SURFACE_AGGREGATOR_BUS */
 382
 383 static inline int __ssam_register_clients(struct device *parent, struct ssam_controller *ctrl,
 384                                           struct fwnode_handle *node)
 385 {
 386         return 0;
 387 }
 388
 389 static inline void ssam_remove_clients(struct device *dev) {}
 390
 391 #endif /* CONFIG_SURFACE_AGGREGATOR_BUS */
 392
 393 /**
 394  * ssam_register_clients() - Register all client devices defined under the
 395  * given parent device.
 396  * @dev: The parent device under which clients should be registered.
 397  * @ctrl: The controller with which client should be registered.
 398  *
 399  * Register all clients that have via firmware nodes been defined as children
 400  * of the given (parent) device. The respective child firmware nodes will be
 401  * associated with the correspondingly created child devices.
 402  *
 403  * The given controller will be used to instantiate the new devices. See
 404  * ssam_device_add() for details.
 405  *
 406  * Return: Returns zero on success, nonzero on failure.
 407  */
 408 static inline int ssam_register_clients(struct device *dev, struct ssam_controller *ctrl)
 409 {
 410         return __ssam_register_clients(dev, ctrl, dev_fwnode(dev));
 411 }
 412
 413 /**
 414  * ssam_device_register_clients() - Register all client devices defined under
 415  * the given SSAM parent device.
 416  * @sdev: The parent device under which clients should be registered.
 417  *
 418  * Register all clients that have via firmware nodes been defined as children
 419  * of the given (parent) device. The respective child firmware nodes will be
 420  * associated with the correspondingly created child devices.
 421  *
 422  * The controller used by the parent device will be used to instantiate the new
 423  * devices. See ssam_device_add() for details.
 424  *
 425  * Return: Returns zero on success, nonzero on failure.
 426  */
 427 static inline int ssam_device_register_clients(struct ssam_device *sdev)
 428 {
 429         return ssam_register_clients(&sdev->dev, sdev->ctrl);
 430 }
 431
 432
 433 /* -- Helpers for client-device requests. ----------------------------------- */
 434
 435 /**
 436  * SSAM_DEFINE_SYNC_REQUEST_CL_N() - Define synchronous client-device SAM
 437  * request function with neither argument nor return value.
 438  * @name: Name of the generated function.
 439  * @spec: Specification (&struct ssam_request_spec_md) defining the request.
 440  *
 441  * Defines a function executing the synchronous SAM request specified by
 442  * @spec, with the request having neither argument nor return value. Device
 443  * specifying parameters are not hard-coded, but instead are provided via the
 444  * client device, specifically its UID, supplied when calling this function.
 445  * The generated function takes care of setting up the request struct, buffer
 446  * allocation, as well as execution of the request itself, returning once the
 447  * request has been fully completed. The required transport buffer will be
 448  * allocated on the stack.
 449  *
 450  * The generated function is defined as ``static int name(struct ssam_device
 451  * *sdev)``, returning the status of the request, which is zero on success and
 452  * negative on failure. The ``sdev`` parameter specifies both the target
 453  * device of the request and by association the controller via which the
 454  * request is sent.
 455  *
 456  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 457  * the generated function.
 458  */
 459 #define SSAM_DEFINE_SYNC_REQUEST_CL_N(name, spec...)                    \
 460         SSAM_DEFINE_SYNC_REQUEST_MD_N(__raw_##name, spec)               \
 461         static int name(struct ssam_device *sdev)                       \
 462         {                                                               \
 463                 return __raw_##name(sdev->ctrl, sdev->uid.target,       \
 464                                     sdev->uid.instance);                \
 465         }
 466
 467 /**
 468  * SSAM_DEFINE_SYNC_REQUEST_CL_W() - Define synchronous client-device SAM
 469  * request function with argument.
 470  * @name:  Name of the generated function.
 471  * @atype: Type of the request's argument.
 472  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
 473  *
 474  * Defines a function executing the synchronous SAM request specified by
 475  * @spec, with the request taking an argument of type @atype and having no
 476  * return value. Device specifying parameters are not hard-coded, but instead
 477  * are provided via the client device, specifically its UID, supplied when
 478  * calling this function. The generated function takes care of setting up the
 479  * request struct, buffer allocation, as well as execution of the request
 480  * itself, returning once the request has been fully completed. The required
 481  * transport buffer will be allocated on the stack.
 482  *
 483  * The generated function is defined as ``static int name(struct ssam_device
 484  * *sdev, const atype *arg)``, returning the status of the request, which is
 485  * zero on success and negative on failure. The ``sdev`` parameter specifies
 486  * both the target device of the request and by association the controller via
 487  * which the request is sent. The request's argument is specified via the
 488  * ``arg`` pointer.
 489  *
 490  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 491  * the generated function.
 492  */
 493 #define SSAM_DEFINE_SYNC_REQUEST_CL_W(name, atype, spec...)             \
 494         SSAM_DEFINE_SYNC_REQUEST_MD_W(__raw_##name, atype, spec)        \
 495         static int name(struct ssam_device *sdev, const atype *arg)     \
 496         {                                                               \
 497                 return __raw_##name(sdev->ctrl, sdev->uid.target,       \
 498                                     sdev->uid.instance, arg);           \
 499         }
 500
 501 /**
 502  * SSAM_DEFINE_SYNC_REQUEST_CL_R() - Define synchronous client-device SAM
 503  * request function with return value.
 504  * @name:  Name of the generated function.
 505  * @rtype: Type of the request's return value.
 506  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
 507  *
 508  * Defines a function executing the synchronous SAM request specified by
 509  * @spec, with the request taking no argument but having a return value of
 510  * type @rtype. Device specifying parameters are not hard-coded, but instead
 511  * are provided via the client device, specifically its UID, supplied when
 512  * calling this function. The generated function takes care of setting up the
 513  * request struct, buffer allocation, as well as execution of the request
 514  * itself, returning once the request has been fully completed. The required
 515  * transport buffer will be allocated on the stack.
 516  *
 517  * The generated function is defined as ``static int name(struct ssam_device
 518  * *sdev, rtype *ret)``, returning the status of the request, which is zero on
 519  * success and negative on failure. The ``sdev`` parameter specifies both the
 520  * target device of the request and by association the controller via which
 521  * the request is sent. The request's return value is written to the memory
 522  * pointed to by the ``ret`` parameter.
 523  *
 524  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 525  * the generated function.
 526  */
 527 #define SSAM_DEFINE_SYNC_REQUEST_CL_R(name, rtype, spec...)             \
 528         SSAM_DEFINE_SYNC_REQUEST_MD_R(__raw_##name, rtype, spec)        \
 529         static int name(struct ssam_device *sdev, rtype *ret)           \
 530         {                                                               \
 531                 return __raw_##name(sdev->ctrl, sdev->uid.target,       \
 532                                     sdev->uid.instance, ret);           \
 533         }
 534
 535 /**
 536  * SSAM_DEFINE_SYNC_REQUEST_CL_WR() - Define synchronous client-device SAM
 537  * request function with argument and return value.
 538  * @name:  Name of the generated function.
 539  * @atype: Type of the request's argument.
 540  * @rtype: Type of the request's return value.
 541  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
 542  *
 543  * Defines a function executing the synchronous SAM request specified by @spec,
 544  * with the request taking an argument of type @atype and having a return value
 545  * of type @rtype. Device specifying parameters are not hard-coded, but instead
 546  * are provided via the client device, specifically its UID, supplied when
 547  * calling this function. The generated function takes care of setting up the
 548  * request struct, buffer allocation, as well as execution of the request
 549  * itself, returning once the request has been fully completed. The required
 550  * transport buffer will be allocated on the stack.
 551  *
 552  * The generated function is defined as ``static int name(struct ssam_device
 553  * *sdev, const atype *arg, rtype *ret)``, returning the status of the request,
 554  * which is zero on success and negative on failure. The ``sdev`` parameter
 555  * specifies both the target device of the request and by association the
 556  * controller via which the request is sent. The request's argument is
 557  * specified via the ``arg`` pointer. The request's return value is written to
 558  * the memory pointed to by the ``ret`` parameter.
 559  *
 560  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 561  * the generated function.
 562  */
 563 #define SSAM_DEFINE_SYNC_REQUEST_CL_WR(name, atype, rtype, spec...)             \
 564         SSAM_DEFINE_SYNC_REQUEST_MD_WR(__raw_##name, atype, rtype, spec)        \
 565         static int name(struct ssam_device *sdev, const atype *arg, rtype *ret) \
 566         {                                                                       \
 567                 return __raw_##name(sdev->ctrl, sdev->uid.target,               \
 568                                     sdev->uid.instance, arg, ret);              \
 569         }
 570
 571
 572 /* -- Helpers for client-device notifiers. ---------------------------------- */
 573
 574 /**
 575  * ssam_device_notifier_register() - Register an event notifier for the
 576  * specified client device.
 577  * @sdev: The device the notifier should be registered on.
 578  * @n:    The event notifier to register.
 579  *
 580  * Register an event notifier. Increment the usage counter of the associated
 581  * SAM event if the notifier is not marked as an observer. If the event is not
 582  * marked as an observer and is currently not enabled, it will be enabled
 583  * during this call. If the notifier is marked as an observer, no attempt will
 584  * be made at enabling any event and no reference count will be modified.
 585  *
 586  * Notifiers marked as observers do not need to be associated with one specific
 587  * event, i.e. as long as no event matching is performed, only the event target
 588  * category needs to be set.
 589  *
 590  * Return: Returns zero on success, %-ENOSPC if there have already been
 591  * %INT_MAX notifiers for the event ID/type associated with the notifier block
 592  * registered, %-ENOMEM if the corresponding event entry could not be
 593  * allocated, %-ENODEV if the device is marked as hot-removed. If this is the
 594  * first time that a notifier block is registered for the specific associated
 595  * event, returns the status of the event-enable EC-command.
 596  */
 597 static inline int ssam_device_notifier_register(struct ssam_device *sdev,
 598                                                 struct ssam_event_notifier *n)
 599 {
 600         /*
 601          * Note that this check does not provide any guarantees whatsoever as
 602          * hot-removal could happen at any point and we can't protect against
 603          * it. Nevertheless, if we can detect hot-removal, bail early to avoid
 604          * communication timeouts.
 605          */
 606         if (ssam_device_is_hot_removed(sdev))
 607                 return -ENODEV;
 608
 609         return ssam_notifier_register(sdev->ctrl, n);
 610 }
 611
 612 /**
 613  * ssam_device_notifier_unregister() - Unregister an event notifier for the
 614  * specified client device.
 615  * @sdev: The device the notifier has been registered on.
 616  * @n:    The event notifier to unregister.
 617  *
 618  * Unregister an event notifier. Decrement the usage counter of the associated
 619  * SAM event if the notifier is not marked as an observer. If the usage counter
 620  * reaches zero, the event will be disabled.
 621  *
 622  * In case the device has been marked as hot-removed, the event will not be
 623  * disabled on the EC, as in those cases any attempt at doing so may time out.
 624  *
 625  * Return: Returns zero on success, %-ENOENT if the given notifier block has
 626  * not been registered on the controller. If the given notifier block was the
 627  * last one associated with its specific event, returns the status of the
 628  * event-disable EC-command.
 629  */
 630 static inline int ssam_device_notifier_unregister(struct ssam_device *sdev,
 631                                                   struct ssam_event_notifier *n)
 632 {
 633         return __ssam_notifier_unregister(sdev->ctrl, n,
 634                                           !ssam_device_is_hot_removed(sdev));
 635 }
 636
 637 #endif /* _LINUX_SURFACE_AGGREGATOR_DEVICE_H */