include/linux/surface_aggregator/controller.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Surface System Aggregator Module (SSAM) controller interface.
   4  *
   5  * Main communication interface for the SSAM EC. Provides a controller
   6  * managing access and communication to and from the SSAM EC, as well as main
   7  * communication structures and definitions.
   8  *
   9  * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com>
  10  */
  11
  12 #ifndef _LINUX_SURFACE_AGGREGATOR_CONTROLLER_H
  13 #define _LINUX_SURFACE_AGGREGATOR_CONTROLLER_H
  14
  15 #include <linux/completion.h>
  16 #include <linux/device.h>
  17 #include <linux/types.h>
  18
  19 #include <linux/surface_aggregator/serial_hub.h>
  20
  21
  22 /* -- Main data types and definitions --------------------------------------- */
  23
  24 /**
  25  * enum ssam_event_flags - Flags for enabling/disabling SAM events
  26  * @SSAM_EVENT_SEQUENCED: The event will be sent via a sequenced data frame.
  27  */
  28 enum ssam_event_flags {
  29         SSAM_EVENT_SEQUENCED = BIT(0),
  30 };
  31
  32 /**
  33  * struct ssam_event - SAM event sent from the EC to the host.
  34  * @target_category: Target category of the event source. See &enum ssam_ssh_tc.
  35  * @target_id:       Target ID of the event source.
  36  * @command_id:      Command ID of the event.
  37  * @instance_id:     Instance ID of the event source.
  38  * @length:          Length of the event payload in bytes.
  39  * @data:            Event payload data.
  40  */
  41 struct ssam_event {
  42         u8 target_category;
  43         u8 target_id;
  44         u8 command_id;
  45         u8 instance_id;
  46         u16 length;
  47         u8 data[] __counted_by(length);
  48 };
  49
  50 /**
  51  * enum ssam_request_flags - Flags for SAM requests.
  52  *
  53  * @SSAM_REQUEST_HAS_RESPONSE:
  54  *      Specifies that the request expects a response. If not set, the request
  55  *      will be directly completed after its underlying packet has been
  56  *      transmitted. If set, the request transport system waits for a response
  57  *      of the request.
  58  *
  59  * @SSAM_REQUEST_UNSEQUENCED:
  60  *      Specifies that the request should be transmitted via an unsequenced
  61  *      packet. If set, the request must not have a response, meaning that this
  62  *      flag and the %SSAM_REQUEST_HAS_RESPONSE flag are mutually exclusive.
  63  */
  64 enum ssam_request_flags {
  65         SSAM_REQUEST_HAS_RESPONSE = BIT(0),
  66         SSAM_REQUEST_UNSEQUENCED  = BIT(1),
  67 };
  68
  69 /**
  70  * struct ssam_request - SAM request description.
  71  * @target_category: Category of the request's target. See &enum ssam_ssh_tc.
  72  * @target_id:       ID of the request's target.
  73  * @command_id:      Command ID of the request.
  74  * @instance_id:     Instance ID of the request's target.
  75  * @flags:           Flags for the request. See &enum ssam_request_flags.
  76  * @length:          Length of the request payload in bytes.
  77  * @payload:         Request payload data.
  78  *
  79  * This struct fully describes a SAM request with payload. It is intended to
  80  * help set up the actual transport struct, e.g. &struct ssam_request_sync,
  81  * and specifically its raw message data via ssam_request_write_data().
  82  */
  83 struct ssam_request {
  84         u8 target_category;
  85         u8 target_id;
  86         u8 command_id;
  87         u8 instance_id;
  88         u16 flags;
  89         u16 length;
  90         const u8 *payload;
  91 };
  92
  93 /**
  94  * struct ssam_response - Response buffer for SAM request.
  95  * @capacity: Capacity of the buffer, in bytes.
  96  * @length:   Length of the actual data stored in the memory pointed to by
  97  *            @pointer, in bytes. Set by the transport system.
  98  * @pointer:  Pointer to the buffer's memory, storing the response payload data.
  99  */
 100 struct ssam_response {
 101         size_t capacity;
 102         size_t length;
 103         u8 *pointer;
 104 };
 105
 106 struct ssam_controller;
 107
 108 struct ssam_controller *ssam_get_controller(void);
 109 struct ssam_controller *ssam_client_bind(struct device *client);
 110 int ssam_client_link(struct ssam_controller *ctrl, struct device *client);
 111
 112 struct device *ssam_controller_device(struct ssam_controller *c);
 113
 114 struct ssam_controller *ssam_controller_get(struct ssam_controller *c);
 115 void ssam_controller_put(struct ssam_controller *c);
 116
 117 void ssam_controller_statelock(struct ssam_controller *c);
 118 void ssam_controller_stateunlock(struct ssam_controller *c);
 119
 120 ssize_t ssam_request_write_data(struct ssam_span *buf,
 121                                 struct ssam_controller *ctrl,
 122                                 const struct ssam_request *spec);
 123
 124
 125 /* -- Synchronous request interface. ---------------------------------------- */
 126
 127 /**
 128  * struct ssam_request_sync - Synchronous SAM request struct.
 129  * @base:   Underlying SSH request.
 130  * @comp:   Completion used to signal full completion of the request. After the
 131  *          request has been submitted, this struct may only be modified or
 132  *          deallocated after the completion has been signaled.
 133  *          request has been submitted,
 134  * @resp:   Buffer to store the response.
 135  * @status: Status of the request, set after the base request has been
 136  *          completed or has failed.
 137  */
 138 struct ssam_request_sync {
 139         struct ssh_request base;
 140         struct completion comp;
 141         struct ssam_response *resp;
 142         int status;
 143 };
 144
 145 int ssam_request_sync_alloc(size_t payload_len, gfp_t flags,
 146                             struct ssam_request_sync **rqst,
 147                             struct ssam_span *buffer);
 148
 149 void ssam_request_sync_free(struct ssam_request_sync *rqst);
 150
 151 int ssam_request_sync_init(struct ssam_request_sync *rqst,
 152                            enum ssam_request_flags flags);
 153
 154 /**
 155  * ssam_request_sync_set_data - Set message data of a synchronous request.
 156  * @rqst: The request.
 157  * @ptr:  Pointer to the request message data.
 158  * @len:  Length of the request message data.
 159  *
 160  * Set the request message data of a synchronous request. The provided buffer
 161  * needs to live until the request has been completed.
 162  */
 163 static inline void ssam_request_sync_set_data(struct ssam_request_sync *rqst,
 164                                               u8 *ptr, size_t len)
 165 {
 166         ssh_request_set_data(&rqst->base, ptr, len);
 167 }
 168
 169 /**
 170  * ssam_request_sync_set_resp - Set response buffer of a synchronous request.
 171  * @rqst: The request.
 172  * @resp: The response buffer.
 173  *
 174  * Sets the response buffer of a synchronous request. This buffer will store
 175  * the response of the request after it has been completed. May be %NULL if no
 176  * response is expected.
 177  */
 178 static inline void ssam_request_sync_set_resp(struct ssam_request_sync *rqst,
 179                                               struct ssam_response *resp)
 180 {
 181         rqst->resp = resp;
 182 }
 183
 184 int ssam_request_sync_submit(struct ssam_controller *ctrl,
 185                              struct ssam_request_sync *rqst);
 186
 187 /**
 188  * ssam_request_sync_wait - Wait for completion of a synchronous request.
 189  * @rqst: The request to wait for.
 190  *
 191  * Wait for completion and release of a synchronous request. After this
 192  * function terminates, the request is guaranteed to have left the transport
 193  * system. After successful submission of a request, this function must be
 194  * called before accessing the response of the request, freeing the request,
 195  * or freeing any of the buffers associated with the request.
 196  *
 197  * This function must not be called if the request has not been submitted yet
 198  * and may lead to a deadlock/infinite wait if a subsequent request submission
 199  * fails in that case, due to the completion never triggering.
 200  *
 201  * Return: Returns the status of the given request, which is set on completion
 202  * of the packet. This value is zero on success and negative on failure.
 203  */
 204 static inline int ssam_request_sync_wait(struct ssam_request_sync *rqst)
 205 {
 206         wait_for_completion(&rqst->comp);
 207         return rqst->status;
 208 }
 209
 210 int ssam_request_do_sync(struct ssam_controller *ctrl,
 211                          const struct ssam_request *spec,
 212                          struct ssam_response *rsp);
 213
 214 int ssam_request_do_sync_with_buffer(struct ssam_controller *ctrl,
 215                                      const struct ssam_request *spec,
 216                                      struct ssam_response *rsp,
 217                                      struct ssam_span *buf);
 218
 219 /**
 220  * ssam_request_do_sync_onstack - Execute a synchronous request on the stack.
 221  * @ctrl: The controller via which the request is submitted.
 222  * @rqst: The request specification.
 223  * @rsp:  The response buffer.
 224  * @payload_len: The (maximum) request payload length.
 225  *
 226  * Allocates a synchronous request with specified payload length on the stack,
 227  * fully initializes it via the provided request specification, submits it,
 228  * and finally waits for its completion before returning its status. This
 229  * helper macro essentially allocates the request message buffer on the stack
 230  * and then calls ssam_request_do_sync_with_buffer().
 231  *
 232  * Note: The @payload_len parameter specifies the maximum payload length, used
 233  * for buffer allocation. The actual payload length may be smaller.
 234  *
 235  * Return: Returns the status of the request or any failure during setup, i.e.
 236  * zero on success and a negative value on failure.
 237  */
 238 #define ssam_request_do_sync_onstack(ctrl, rqst, rsp, payload_len)              \
 239         ({                                                                      \
 240                 u8 __data[SSH_COMMAND_MESSAGE_LENGTH(payload_len)];             \
 241                 struct ssam_span __buf = { &__data[0], ARRAY_SIZE(__data) };    \
 242                                                                                 \
 243                 ssam_request_do_sync_with_buffer(ctrl, rqst, rsp, &__buf);      \
 244         })
 245
 246 /**
 247  * __ssam_retry - Retry request in case of I/O errors or timeouts.
 248  * @request: The request function to execute. Must return an integer.
 249  * @n:       Number of tries.
 250  * @args:    Arguments for the request function.
 251  *
 252  * Executes the given request function, i.e. calls @request. In case the
 253  * request returns %-EREMOTEIO (indicates I/O error) or %-ETIMEDOUT (request
 254  * or underlying packet timed out), @request will be re-executed again, up to
 255  * @n times in total.
 256  *
 257  * Return: Returns the return value of the last execution of @request.
 258  */
 259 #define __ssam_retry(request, n, args...)                               \
 260         ({                                                              \
 261                 int __i, __s = 0;                                       \
 262                                                                         \
 263                 for (__i = (n); __i > 0; __i--) {                       \
 264                         __s = request(args);                            \
 265                         if (__s != -ETIMEDOUT && __s != -EREMOTEIO)     \
 266                                 break;                                  \
 267                 }                                                       \
 268                 __s;                                                    \
 269         })
 270
 271 /**
 272  * ssam_retry - Retry request in case of I/O errors or timeouts up to three
 273  * times in total.
 274  * @request: The request function to execute. Must return an integer.
 275  * @args:    Arguments for the request function.
 276  *
 277  * Executes the given request function, i.e. calls @request. In case the
 278  * request returns %-EREMOTEIO (indicates I/O error) or -%ETIMEDOUT (request
 279  * or underlying packet timed out), @request will be re-executed again, up to
 280  * three times in total.
 281  *
 282  * See __ssam_retry() for a more generic macro for this purpose.
 283  *
 284  * Return: Returns the return value of the last execution of @request.
 285  */
 286 #define ssam_retry(request, args...) \
 287         __ssam_retry(request, 3, args)
 288
 289 /**
 290  * struct ssam_request_spec - Blue-print specification of SAM request.
 291  * @target_category: Category of the request's target. See &enum ssam_ssh_tc.
 292  * @target_id:       ID of the request's target.
 293  * @command_id:      Command ID of the request.
 294  * @instance_id:     Instance ID of the request's target.
 295  * @flags:           Flags for the request. See &enum ssam_request_flags.
 296  *
 297  * Blue-print specification for a SAM request. This struct describes the
 298  * unique static parameters of a request (i.e. type) without specifying any of
 299  * its instance-specific data (e.g. payload). It is intended to be used as base
 300  * for defining simple request functions via the
 301  * ``SSAM_DEFINE_SYNC_REQUEST_x()`` family of macros.
 302  */
 303 struct ssam_request_spec {
 304         u8 target_category;
 305         u8 target_id;
 306         u8 command_id;
 307         u8 instance_id;
 308         u8 flags;
 309 };
 310
 311 /**
 312  * struct ssam_request_spec_md - Blue-print specification for multi-device SAM
 313  * request.
 314  * @target_category: Category of the request's target. See &enum ssam_ssh_tc.
 315  * @command_id:      Command ID of the request.
 316  * @flags:           Flags for the request. See &enum ssam_request_flags.
 317  *
 318  * Blue-print specification for a multi-device SAM request, i.e. a request
 319  * that is applicable to multiple device instances, described by their
 320  * individual target and instance IDs. This struct describes the unique static
 321  * parameters of a request (i.e. type) without specifying any of its
 322  * instance-specific data (e.g. payload) and without specifying any of its
 323  * device specific IDs (i.e. target and instance ID). It is intended to be
 324  * used as base for defining simple multi-device request functions via the
 325  * ``SSAM_DEFINE_SYNC_REQUEST_MD_x()`` and ``SSAM_DEFINE_SYNC_REQUEST_CL_x()``
 326  * families of macros.
 327  */
 328 struct ssam_request_spec_md {
 329         u8 target_category;
 330         u8 command_id;
 331         u8 flags;
 332 };
 333
 334 /**
 335  * SSAM_DEFINE_SYNC_REQUEST_N() - Define synchronous SAM request function
 336  * with neither argument nor return value.
 337  * @name: Name of the generated function.
 338  * @spec: Specification (&struct ssam_request_spec) defining the request.
 339  *
 340  * Defines a function executing the synchronous SAM request specified by
 341  * @spec, with the request having neither argument nor return value. The
 342  * generated function takes care of setting up the request struct and buffer
 343  * allocation, as well as execution of the request itself, returning once the
 344  * request has been fully completed. The required transport buffer will be
 345  * allocated on the stack.
 346  *
 347  * The generated function is defined as ``static int name(struct
 348  * ssam_controller *ctrl)``, returning the status of the request, which is
 349  * zero on success and negative on failure. The ``ctrl`` parameter is the
 350  * controller via which the request is being sent.
 351  *
 352  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 353  * the generated function.
 354  */
 355 #define SSAM_DEFINE_SYNC_REQUEST_N(name, spec...)                               \
 356         static int name(struct ssam_controller *ctrl)                           \
 357         {                                                                       \
 358                 struct ssam_request_spec s = (struct ssam_request_spec)spec;    \
 359                 struct ssam_request rqst;                                       \
 360                                                                                 \
 361                 rqst.target_category = s.target_category;                       \
 362                 rqst.target_id = s.target_id;                                   \
 363                 rqst.command_id = s.command_id;                                 \
 364                 rqst.instance_id = s.instance_id;                               \
 365                 rqst.flags = s.flags;                                           \
 366                 rqst.length = 0;                                                \
 367                 rqst.payload = NULL;                                            \
 368                                                                                 \
 369                 return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, 0);      \
 370         }
 371
 372 /**
 373  * SSAM_DEFINE_SYNC_REQUEST_W() - Define synchronous SAM request function with
 374  * argument.
 375  * @name:  Name of the generated function.
 376  * @atype: Type of the request's argument.
 377  * @spec:  Specification (&struct ssam_request_spec) defining the request.
 378  *
 379  * Defines a function executing the synchronous SAM request specified by
 380  * @spec, with the request taking an argument of type @atype and having no
 381  * return value. The generated function takes care of setting up the request
 382  * struct, buffer allocation, as well as execution of the request itself,
 383  * returning once the request has been fully completed. The required transport
 384  * buffer will be allocated on the stack.
 385  *
 386  * The generated function is defined as ``static int name(struct
 387  * ssam_controller *ctrl, const atype *arg)``, returning the status of the
 388  * request, which is zero on success and negative on failure. The ``ctrl``
 389  * parameter is the controller via which the request is sent. The request
 390  * argument is specified via the ``arg`` pointer.
 391  *
 392  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 393  * the generated function.
 394  */
 395 #define SSAM_DEFINE_SYNC_REQUEST_W(name, atype, spec...)                        \
 396         static int name(struct ssam_controller *ctrl, const atype *arg)         \
 397         {                                                                       \
 398                 struct ssam_request_spec s = (struct ssam_request_spec)spec;    \
 399                 struct ssam_request rqst;                                       \
 400                                                                                 \
 401                 rqst.target_category = s.target_category;                       \
 402                 rqst.target_id = s.target_id;                                   \
 403                 rqst.command_id = s.command_id;                                 \
 404                 rqst.instance_id = s.instance_id;                               \
 405                 rqst.flags = s.flags;                                           \
 406                 rqst.length = sizeof(atype);                                    \
 407                 rqst.payload = (u8 *)arg;                                       \
 408                                                                                 \
 409                 return ssam_request_do_sync_onstack(ctrl, &rqst, NULL,          \
 410                                                     sizeof(atype));             \
 411         }
 412
 413 /**
 414  * SSAM_DEFINE_SYNC_REQUEST_R() - Define synchronous SAM request function with
 415  * return value.
 416  * @name:  Name of the generated function.
 417  * @rtype: Type of the request's return value.
 418  * @spec:  Specification (&struct ssam_request_spec) defining the request.
 419  *
 420  * Defines a function executing the synchronous SAM request specified by
 421  * @spec, with the request taking no argument but having a return value of
 422  * type @rtype. The generated function takes care of setting up the request
 423  * and response structs, buffer allocation, as well as execution of the
 424  * request itself, returning once the request has been fully completed. The
 425  * required transport buffer will be allocated on the stack.
 426  *
 427  * The generated function is defined as ``static int name(struct
 428  * ssam_controller *ctrl, rtype *ret)``, returning the status of the request,
 429  * which is zero on success and negative on failure. The ``ctrl`` parameter is
 430  * the controller via which the request is sent. The request's return value is
 431  * written to the memory pointed to by the ``ret`` parameter.
 432  *
 433  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 434  * the generated function.
 435  */
 436 #define SSAM_DEFINE_SYNC_REQUEST_R(name, rtype, spec...)                        \
 437         static int name(struct ssam_controller *ctrl, rtype *ret)               \
 438         {                                                                       \
 439                 struct ssam_request_spec s = (struct ssam_request_spec)spec;    \
 440                 struct ssam_request rqst;                                       \
 441                 struct ssam_response rsp;                                       \
 442                 int status;                                                     \
 443                                                                                 \
 444                 rqst.target_category = s.target_category;                       \
 445                 rqst.target_id = s.target_id;                                   \
 446                 rqst.command_id = s.command_id;                                 \
 447                 rqst.instance_id = s.instance_id;                               \
 448                 rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE;               \
 449                 rqst.length = 0;                                                \
 450                 rqst.payload = NULL;                                            \
 451                                                                                 \
 452                 rsp.capacity = sizeof(rtype);                                   \
 453                 rsp.length = 0;                                                 \
 454                 rsp.pointer = (u8 *)ret;                                        \
 455                                                                                 \
 456                 status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, 0);    \
 457                 if (status)                                                     \
 458                         return status;                                          \
 459                                                                                 \
 460                 if (rsp.length != sizeof(rtype)) {                              \
 461                         struct device *dev = ssam_controller_device(ctrl);      \
 462                         dev_err(dev,                                            \
 463                                 "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \
 464                                 sizeof(rtype), rsp.length, rqst.target_category,\
 465                                 rqst.command_id);                               \
 466                         return -EIO;                                            \
 467                 }                                                               \
 468                                                                                 \
 469                 return 0;                                                       \
 470         }
 471
 472 /**
 473  * SSAM_DEFINE_SYNC_REQUEST_WR() - Define synchronous SAM request function with
 474  * both argument and return value.
 475  * @name:  Name of the generated function.
 476  * @atype: Type of the request's argument.
 477  * @rtype: Type of the request's return value.
 478  * @spec:  Specification (&struct ssam_request_spec) defining the request.
 479  *
 480  * Defines a function executing the synchronous SAM request specified by @spec,
 481  * with the request taking an argument of type @atype and having a return value
 482  * of type @rtype. The generated function takes care of setting up the request
 483  * and response structs, buffer allocation, as well as execution of the request
 484  * itself, returning once the request has been fully completed. The required
 485  * transport buffer will be allocated on the stack.
 486  *
 487  * The generated function is defined as ``static int name(struct
 488  * ssam_controller *ctrl, const atype *arg, rtype *ret)``, returning the status
 489  * of the request, which is zero on success and negative on failure. The
 490  * ``ctrl`` parameter is the controller via which the request is sent. The
 491  * request argument is specified via the ``arg`` pointer. The request's return
 492  * value is written to the memory pointed to by the ``ret`` parameter.
 493  *
 494  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 495  * the generated function.
 496  */
 497 #define SSAM_DEFINE_SYNC_REQUEST_WR(name, atype, rtype, spec...)                \
 498         static int name(struct ssam_controller *ctrl, const atype *arg, rtype *ret) \
 499         {                                                                       \
 500                 struct ssam_request_spec s = (struct ssam_request_spec)spec;    \
 501                 struct ssam_request rqst;                                       \
 502                 struct ssam_response rsp;                                       \
 503                 int status;                                                     \
 504                                                                                 \
 505                 rqst.target_category = s.target_category;                       \
 506                 rqst.target_id = s.target_id;                                   \
 507                 rqst.command_id = s.command_id;                                 \
 508                 rqst.instance_id = s.instance_id;                               \
 509                 rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE;               \
 510                 rqst.length = sizeof(atype);                                    \
 511                 rqst.payload = (u8 *)arg;                                       \
 512                                                                                 \
 513                 rsp.capacity = sizeof(rtype);                                   \
 514                 rsp.length = 0;                                                 \
 515                 rsp.pointer = (u8 *)ret;                                        \
 516                                                                                 \
 517                 status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \
 518                 if (status)                                                     \
 519                         return status;                                          \
 520                                                                                 \
 521                 if (rsp.length != sizeof(rtype)) {                              \
 522                         struct device *dev = ssam_controller_device(ctrl);      \
 523                         dev_err(dev,                                            \
 524                                 "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \
 525                                 sizeof(rtype), rsp.length, rqst.target_category,\
 526                                 rqst.command_id);                               \
 527                         return -EIO;                                            \
 528                 }                                                               \
 529                                                                                 \
 530                 return 0;                                                       \
 531         }
 532
 533 /**
 534  * SSAM_DEFINE_SYNC_REQUEST_MD_N() - Define synchronous multi-device SAM
 535  * request function with neither argument nor return value.
 536  * @name: Name of the generated function.
 537  * @spec: Specification (&struct ssam_request_spec_md) defining the request.
 538  *
 539  * Defines a function executing the synchronous SAM request specified by
 540  * @spec, with the request having neither argument nor return value. Device
 541  * specifying parameters are not hard-coded, but instead must be provided to
 542  * the function. The generated function takes care of setting up the request
 543  * struct, buffer allocation, as well as execution of the request itself,
 544  * returning once the request has been fully completed. The required transport
 545  * buffer will be allocated on the stack.
 546  *
 547  * The generated function is defined as ``static int name(struct
 548  * ssam_controller *ctrl, u8 tid, u8 iid)``, returning the status of the
 549  * request, which is zero on success and negative on failure. The ``ctrl``
 550  * parameter is the controller via which the request is sent, ``tid`` the
 551  * target ID for the request, and ``iid`` the instance ID.
 552  *
 553  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 554  * the generated function.
 555  */
 556 #define SSAM_DEFINE_SYNC_REQUEST_MD_N(name, spec...)                            \
 557         static int name(struct ssam_controller *ctrl, u8 tid, u8 iid)           \
 558         {                                                                       \
 559                 struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \
 560                 struct ssam_request rqst;                                       \
 561                                                                                 \
 562                 rqst.target_category = s.target_category;                       \
 563                 rqst.target_id = tid;                                           \
 564                 rqst.command_id = s.command_id;                                 \
 565                 rqst.instance_id = iid;                                         \
 566                 rqst.flags = s.flags;                                           \
 567                 rqst.length = 0;                                                \
 568                 rqst.payload = NULL;                                            \
 569                                                                                 \
 570                 return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, 0);      \
 571         }
 572
 573 /**
 574  * SSAM_DEFINE_SYNC_REQUEST_MD_W() - Define synchronous multi-device SAM
 575  * request function with argument.
 576  * @name:  Name of the generated function.
 577  * @atype: Type of the request's argument.
 578  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
 579  *
 580  * Defines a function executing the synchronous SAM request specified by
 581  * @spec, with the request taking an argument of type @atype and having no
 582  * return value. Device specifying parameters are not hard-coded, but instead
 583  * must be provided to the function. The generated function takes care of
 584  * setting up the request struct, buffer allocation, as well as execution of
 585  * the request itself, returning once the request has been fully completed.
 586  * The required transport buffer will be allocated on the stack.
 587  *
 588  * The generated function is defined as ``static int name(struct
 589  * ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg)``, returning the
 590  * status of the request, which is zero on success and negative on failure.
 591  * The ``ctrl`` parameter is the controller via which the request is sent,
 592  * ``tid`` the target ID for the request, and ``iid`` the instance ID. The
 593  * request argument is specified via the ``arg`` pointer.
 594  *
 595  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 596  * the generated function.
 597  */
 598 #define SSAM_DEFINE_SYNC_REQUEST_MD_W(name, atype, spec...)                     \
 599         static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg) \
 600         {                                                                       \
 601                 struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \
 602                 struct ssam_request rqst;                                       \
 603                                                                                 \
 604                 rqst.target_category = s.target_category;                       \
 605                 rqst.target_id = tid;                                           \
 606                 rqst.command_id = s.command_id;                                 \
 607                 rqst.instance_id = iid;                                         \
 608                 rqst.flags = s.flags;                                           \
 609                 rqst.length = sizeof(atype);                                    \
 610                 rqst.payload = (u8 *)arg;                                       \
 611                                                                                 \
 612                 return ssam_request_do_sync_onstack(ctrl, &rqst, NULL,          \
 613                                                  sizeof(atype));                \
 614         }
 615
 616 /**
 617  * SSAM_DEFINE_SYNC_REQUEST_MD_R() - Define synchronous multi-device SAM
 618  * request function with return value.
 619  * @name:  Name of the generated function.
 620  * @rtype: Type of the request's return value.
 621  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
 622  *
 623  * Defines a function executing the synchronous SAM request specified by
 624  * @spec, with the request taking no argument but having a return value of
 625  * type @rtype. Device specifying parameters are not hard-coded, but instead
 626  * must be provided to the function. The generated function takes care of
 627  * setting up the request and response structs, buffer allocation, as well as
 628  * execution of the request itself, returning once the request has been fully
 629  * completed. The required transport buffer will be allocated on the stack.
 630  *
 631  * The generated function is defined as ``static int name(struct
 632  * ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret)``, returning the status
 633  * of the request, which is zero on success and negative on failure. The
 634  * ``ctrl`` parameter is the controller via which the request is sent, ``tid``
 635  * the target ID for the request, and ``iid`` the instance ID. The request's
 636  * return value is written to the memory pointed to by the ``ret`` parameter.
 637  *
 638  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 639  * the generated function.
 640  */
 641 #define SSAM_DEFINE_SYNC_REQUEST_MD_R(name, rtype, spec...)                     \
 642         static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret) \
 643         {                                                                       \
 644                 struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \
 645                 struct ssam_request rqst;                                       \
 646                 struct ssam_response rsp;                                       \
 647                 int status;                                                     \
 648                                                                                 \
 649                 rqst.target_category = s.target_category;                       \
 650                 rqst.target_id = tid;                                           \
 651                 rqst.command_id = s.command_id;                                 \
 652                 rqst.instance_id = iid;                                         \
 653                 rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE;               \
 654                 rqst.length = 0;                                                \
 655                 rqst.payload = NULL;                                            \
 656                                                                                 \
 657                 rsp.capacity = sizeof(rtype);                                   \
 658                 rsp.length = 0;                                                 \
 659                 rsp.pointer = (u8 *)ret;                                        \
 660                                                                                 \
 661                 status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, 0);    \
 662                 if (status)                                                     \
 663                         return status;                                          \
 664                                                                                 \
 665                 if (rsp.length != sizeof(rtype)) {                              \
 666                         struct device *dev = ssam_controller_device(ctrl);      \
 667                         dev_err(dev,                                            \
 668                                 "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \
 669                                 sizeof(rtype), rsp.length, rqst.target_category,\
 670                                 rqst.command_id);                               \
 671                         return -EIO;                                            \
 672                 }                                                               \
 673                                                                                 \
 674                 return 0;                                                       \
 675         }
 676
 677 /**
 678  * SSAM_DEFINE_SYNC_REQUEST_MD_WR() - Define synchronous multi-device SAM
 679  * request function with both argument and return value.
 680  * @name:  Name of the generated function.
 681  * @atype: Type of the request's argument.
 682  * @rtype: Type of the request's return value.
 683  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
 684  *
 685  * Defines a function executing the synchronous SAM request specified by @spec,
 686  * with the request taking an argument of type @atype and having a return value
 687  * of type @rtype. Device specifying parameters are not hard-coded, but instead
 688  * must be provided to the function. The generated function takes care of
 689  * setting up the request and response structs, buffer allocation, as well as
 690  * execution of the request itself, returning once the request has been fully
 691  * completed. The required transport buffer will be allocated on the stack.
 692  *
 693  * The generated function is defined as ``static int name(struct
 694  * ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg, rtype *ret)``,
 695  * returning the status of the request, which is zero on success and negative
 696  * on failure. The ``ctrl`` parameter is the controller via which the request
 697  * is sent, ``tid`` the target ID for the request, and ``iid`` the instance ID.
 698  * The request argument is specified via the ``arg`` pointer. The request's
 699  * return value is written to the memory pointed to by the ``ret`` parameter.
 700  *
 701  * Refer to ssam_request_do_sync_onstack() for more details on the behavior of
 702  * the generated function.
 703  */
 704 #define SSAM_DEFINE_SYNC_REQUEST_MD_WR(name, atype, rtype, spec...)             \
 705         static int name(struct ssam_controller *ctrl, u8 tid, u8 iid,           \
 706                         const atype *arg, rtype *ret)                           \
 707         {                                                                       \
 708                 struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \
 709                 struct ssam_request rqst;                                       \
 710                 struct ssam_response rsp;                                       \
 711                 int status;                                                     \
 712                                                                                 \
 713                 rqst.target_category = s.target_category;                       \
 714                 rqst.target_id = tid;                                           \
 715                 rqst.command_id = s.command_id;                                 \
 716                 rqst.instance_id = iid;                                         \
 717                 rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE;               \
 718                 rqst.length = sizeof(atype);                                    \
 719                 rqst.payload = (u8 *)arg;                                       \
 720                                                                                 \
 721                 rsp.capacity = sizeof(rtype);                                   \
 722                 rsp.length = 0;                                                 \
 723                 rsp.pointer = (u8 *)ret;                                        \
 724                                                                                 \
 725                 status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \
 726                 if (status)                                                     \
 727                         return status;                                          \
 728                                                                                 \
 729                 if (rsp.length != sizeof(rtype)) {                              \
 730                         struct device *dev = ssam_controller_device(ctrl);      \
 731                         dev_err(dev,                                            \
 732                                 "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \
 733                                 sizeof(rtype), rsp.length, rqst.target_category,\
 734                                 rqst.command_id);                               \
 735                         return -EIO;                                            \
 736                 }                                                               \
 737                                                                                 \
 738                 return 0;                                                       \
 739         }
 740
 741
 742 /* -- Event notifier/callbacks. --------------------------------------------- */
 743
 744 #define SSAM_NOTIF_STATE_SHIFT          2
 745 #define SSAM_NOTIF_STATE_MASK           ((1 << SSAM_NOTIF_STATE_SHIFT) - 1)
 746
 747 /**
 748  * enum ssam_notif_flags - Flags used in return values from SSAM notifier
 749  * callback functions.
 750  *
 751  * @SSAM_NOTIF_HANDLED:
 752  *      Indicates that the notification has been handled. This flag should be
 753  *      set by the handler if the handler can act/has acted upon the event
 754  *      provided to it. This flag should not be set if the handler is not a
 755  *      primary handler intended for the provided event.
 756  *
 757  *      If this flag has not been set by any handler after the notifier chain
 758  *      has been traversed, a warning will be emitted, stating that the event
 759  *      has not been handled.
 760  *
 761  * @SSAM_NOTIF_STOP:
 762  *      Indicates that the notifier traversal should stop. If this flag is
 763  *      returned from a notifier callback, notifier chain traversal will
 764  *      immediately stop and any remaining notifiers will not be called. This
 765  *      flag is automatically set when ssam_notifier_from_errno() is called
 766  *      with a negative error value.
 767  */
 768 enum ssam_notif_flags {
 769         SSAM_NOTIF_HANDLED = BIT(0),
 770         SSAM_NOTIF_STOP    = BIT(1),
 771 };
 772
 773 struct ssam_event_notifier;
 774
 775 typedef u32 (*ssam_notifier_fn_t)(struct ssam_event_notifier *nf,
 776                                   const struct ssam_event *event);
 777
 778 /**
 779  * struct ssam_notifier_block - Base notifier block for SSAM event
 780  * notifications.
 781  * @node:     The node for the list of notifiers.
 782  * @fn:       The callback function of this notifier. This function takes the
 783  *            respective notifier block and event as input and should return
 784  *            a notifier value, which can either be obtained from the flags
 785  *            provided in &enum ssam_notif_flags, converted from a standard
 786  *            error value via ssam_notifier_from_errno(), or a combination of
 787  *            both (e.g. ``ssam_notifier_from_errno(e) | SSAM_NOTIF_HANDLED``).
 788  * @priority: Priority value determining the order in which notifier callbacks
 789  *            will be called. A higher value means higher priority, i.e. the
 790  *            associated callback will be executed earlier than other (lower
 791  *            priority) callbacks.
 792  */
 793 struct ssam_notifier_block {
 794         struct list_head node;
 795         ssam_notifier_fn_t fn;
 796         int priority;
 797 };
 798
 799 /**
 800  * ssam_notifier_from_errno() - Convert standard error value to notifier
 801  * return code.
 802  * @err: The error code to convert, must be negative (in case of failure) or
 803  *       zero (in case of success).
 804  *
 805  * Return: Returns the notifier return value obtained by converting the
 806  * specified @err value. In case @err is negative, the %SSAM_NOTIF_STOP flag
 807  * will be set, causing notifier call chain traversal to abort.
 808  */
 809 static inline u32 ssam_notifier_from_errno(int err)
 810 {
 811         if (WARN_ON(err > 0) || err == 0)
 812                 return 0;
 813         else
 814                 return ((-err) << SSAM_NOTIF_STATE_SHIFT) | SSAM_NOTIF_STOP;
 815 }
 816
 817 /**
 818  * ssam_notifier_to_errno() - Convert notifier return code to standard error
 819  * value.
 820  * @ret: The notifier return value to convert.
 821  *
 822  * Return: Returns the negative error value encoded in @ret or zero if @ret
 823  * indicates success.
 824  */
 825 static inline int ssam_notifier_to_errno(u32 ret)
 826 {
 827         return -(ret >> SSAM_NOTIF_STATE_SHIFT);
 828 }
 829
 830
 831 /* -- Event/notification registry. ------------------------------------------ */
 832
 833 /**
 834  * struct ssam_event_registry - Registry specification used for enabling events.
 835  * @target_category: Target category for the event registry requests.
 836  * @target_id:       Target ID for the event registry requests.
 837  * @cid_enable:      Command ID for the event-enable request.
 838  * @cid_disable:     Command ID for the event-disable request.
 839  *
 840  * This struct describes a SAM event registry via the minimal collection of
 841  * SAM IDs specifying the requests to use for enabling and disabling an event.
 842  * The individual event to be enabled/disabled itself is specified via &struct
 843  * ssam_event_id.
 844  */
 845 struct ssam_event_registry {
 846         u8 target_category;
 847         u8 target_id;
 848         u8 cid_enable;
 849         u8 cid_disable;
 850 };
 851
 852 /**
 853  * struct ssam_event_id - Unique event ID used for enabling events.
 854  * @target_category: Target category of the event source.
 855  * @instance:        Instance ID of the event source.
 856  *
 857  * This struct specifies the event to be enabled/disabled via an externally
 858  * provided registry. It does not specify the registry to be used itself, this
 859  * is done via &struct ssam_event_registry.
 860  */
 861 struct ssam_event_id {
 862         u8 target_category;
 863         u8 instance;
 864 };
 865
 866 /**
 867  * enum ssam_event_mask - Flags specifying how events are matched to notifiers.
 868  *
 869  * @SSAM_EVENT_MASK_NONE:
 870  *      Run the callback for any event with matching target category. Do not
 871  *      do any additional filtering.
 872  *
 873  * @SSAM_EVENT_MASK_TARGET:
 874  *      In addition to filtering by target category, only execute the notifier
 875  *      callback for events with a target ID matching to the one of the
 876  *      registry used for enabling/disabling the event.
 877  *
 878  * @SSAM_EVENT_MASK_INSTANCE:
 879  *      In addition to filtering by target category, only execute the notifier
 880  *      callback for events with an instance ID matching to the instance ID
 881  *      used when enabling the event.
 882  *
 883  * @SSAM_EVENT_MASK_STRICT:
 884  *      Do all the filtering above.
 885  */
 886 enum ssam_event_mask {
 887         SSAM_EVENT_MASK_TARGET   = BIT(0),
 888         SSAM_EVENT_MASK_INSTANCE = BIT(1),
 889
 890         SSAM_EVENT_MASK_NONE = 0,
 891         SSAM_EVENT_MASK_STRICT =
 892                   SSAM_EVENT_MASK_TARGET
 893                 | SSAM_EVENT_MASK_INSTANCE,
 894 };
 895
 896 /**
 897  * SSAM_EVENT_REGISTRY() - Define a new event registry.
 898  * @tc:      Target category for the event registry requests.
 899  * @tid:     Target ID for the event registry requests.
 900  * @cid_en:  Command ID for the event-enable request.
 901  * @cid_dis: Command ID for the event-disable request.
 902  *
 903  * Return: Returns the &struct ssam_event_registry specified by the given
 904  * parameters.
 905  */
 906 #define SSAM_EVENT_REGISTRY(tc, tid, cid_en, cid_dis)   \
 907         ((struct ssam_event_registry) {                 \
 908                 .target_category = (tc),                \
 909                 .target_id = (tid),                     \
 910                 .cid_enable = (cid_en),                 \
 911                 .cid_disable = (cid_dis),               \
 912         })
 913
 914 #define SSAM_EVENT_REGISTRY_SAM \
 915         SSAM_EVENT_REGISTRY(SSAM_SSH_TC_SAM, SSAM_SSH_TID_SAM, 0x0b, 0x0c)
 916
 917 #define SSAM_EVENT_REGISTRY_KIP \
 918         SSAM_EVENT_REGISTRY(SSAM_SSH_TC_KIP, SSAM_SSH_TID_KIP, 0x27, 0x28)
 919
 920 #define SSAM_EVENT_REGISTRY_REG(tid)\
 921         SSAM_EVENT_REGISTRY(SSAM_SSH_TC_REG, tid, 0x01, 0x02)
 922
 923 /**
 924  * enum ssam_event_notifier_flags - Flags for event notifiers.
 925  * @SSAM_EVENT_NOTIFIER_OBSERVER:
 926  *      The corresponding notifier acts as observer. Registering a notifier
 927  *      with this flag set will not attempt to enable any event. Equally,
 928  *      unregistering will not attempt to disable any event. Note that a
 929  *      notifier with this flag may not even correspond to a certain event at
 930  *      all, only to a specific event target category. Event matching will not
 931  *      be influenced by this flag.
 932  */
 933 enum ssam_event_notifier_flags {
 934         SSAM_EVENT_NOTIFIER_OBSERVER = BIT(0),
 935 };
 936
 937 /**
 938  * struct ssam_event_notifier - Notifier block for SSAM events.
 939  * @base:        The base notifier block with callback function and priority.
 940  * @event:       The event for which this block will receive notifications.
 941  * @event.reg:   Registry via which the event will be enabled/disabled.
 942  * @event.id:    ID specifying the event.
 943  * @event.mask:  Flags determining how events are matched to the notifier.
 944  * @event.flags: Flags used for enabling the event.
 945  * @flags:       Notifier flags (see &enum ssam_event_notifier_flags).
 946  */
 947 struct ssam_event_notifier {
 948         struct ssam_notifier_block base;
 949
 950         struct {
 951                 struct ssam_event_registry reg;
 952                 struct ssam_event_id id;
 953                 enum ssam_event_mask mask;
 954                 u8 flags;
 955         } event;
 956
 957         unsigned long flags;
 958 };
 959
 960 int ssam_notifier_register(struct ssam_controller *ctrl,
 961                            struct ssam_event_notifier *n);
 962
 963 int __ssam_notifier_unregister(struct ssam_controller *ctrl,
 964                                struct ssam_event_notifier *n, bool disable);
 965
 966 /**
 967  * ssam_notifier_unregister() - Unregister an event notifier.
 968  * @ctrl:    The controller the notifier has been registered on.
 969  * @n:       The event notifier to unregister.
 970  *
 971  * Unregister an event notifier. Decrement the usage counter of the associated
 972  * SAM event if the notifier is not marked as an observer. If the usage counter
 973  * reaches zero, the event will be disabled.
 974  *
 975  * Return: Returns zero on success, %-ENOENT if the given notifier block has
 976  * not been registered on the controller. If the given notifier block was the
 977  * last one associated with its specific event, returns the status of the
 978  * event-disable EC-command.
 979  */
 980 static inline int ssam_notifier_unregister(struct ssam_controller *ctrl,
 981                                            struct ssam_event_notifier *n)
 982 {
 983         return __ssam_notifier_unregister(ctrl, n, true);
 984 }
 985
 986 int ssam_controller_event_enable(struct ssam_controller *ctrl,
 987                                  struct ssam_event_registry reg,
 988                                  struct ssam_event_id id, u8 flags);
 989
 990 int ssam_controller_event_disable(struct ssam_controller *ctrl,
 991                                   struct ssam_event_registry reg,
 992                                   struct ssam_event_id id, u8 flags);
 993
 994 #endif /* _LINUX_SURFACE_AGGREGATOR_CONTROLLER_H */