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-2020 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[];
  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_sync(struct ssam_controller *ctrl,
 211                       const struct ssam_request *spec,
 212                       struct ssam_response *rsp);
 213
 214 int ssam_request_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_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_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_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_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_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_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_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_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_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_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_MD_N() - Define synchronous multi-device SAM
 474  * request function with neither argument nor return value.
 475  * @name: Name of the generated function.
 476  * @spec: Specification (&struct ssam_request_spec_md) defining the request.
 477  *
 478  * Defines a function executing the synchronous SAM request specified by
 479  * @spec, with the request having neither argument nor return value. Device
 480  * specifying parameters are not hard-coded, but instead must be provided to
 481  * the function. The generated function takes care of setting up the request
 482  * struct, buffer allocation, as well as execution of the request itself,
 483  * returning once the request has been fully completed. The required transport
 484  * buffer will be allocated on the stack.
 485  *
 486  * The generated function is defined as ``static int name(struct
 487  * ssam_controller *ctrl, u8 tid, u8 iid)``, returning the status of the
 488  * request, which is zero on success and negative on failure. The ``ctrl``
 489  * parameter is the controller via which the request is sent, ``tid`` the
 490  * target ID for the request, and ``iid`` the instance ID.
 491  *
 492  * Refer to ssam_request_sync_onstack() for more details on the behavior of
 493  * the generated function.
 494  */
 495 #define SSAM_DEFINE_SYNC_REQUEST_MD_N(name, spec...)                            \
 496         static int name(struct ssam_controller *ctrl, u8 tid, u8 iid)           \
 497         {                                                                       \
 498                 struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \
 499                 struct ssam_request rqst;                                       \
 500                                                                                 \
 501                 rqst.target_category = s.target_category;                       \
 502                 rqst.target_id = tid;                                           \
 503                 rqst.command_id = s.command_id;                                 \
 504                 rqst.instance_id = iid;                                         \
 505                 rqst.flags = s.flags;                                           \
 506                 rqst.length = 0;                                                \
 507                 rqst.payload = NULL;                                            \
 508                                                                                 \
 509                 return ssam_request_sync_onstack(ctrl, &rqst, NULL, 0);         \
 510         }
 511
 512 /**
 513  * SSAM_DEFINE_SYNC_REQUEST_MD_W() - Define synchronous multi-device SAM
 514  * request function with argument.
 515  * @name:  Name of the generated function.
 516  * @atype: Type of the request's argument.
 517  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
 518  *
 519  * Defines a function executing the synchronous SAM request specified by
 520  * @spec, with the request taking an argument of type @atype and having no
 521  * return value. Device specifying parameters are not hard-coded, but instead
 522  * must be provided to the function. The generated function takes care of
 523  * setting up the request struct, buffer allocation, as well as execution of
 524  * the request itself, returning once the request has been fully completed.
 525  * The required transport buffer will be allocated on the stack.
 526  *
 527  * The generated function is defined as ``static int name(struct
 528  * ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg)``, returning the
 529  * status of the request, which is zero on success and negative on failure.
 530  * The ``ctrl`` parameter is the controller via which the request is sent,
 531  * ``tid`` the target ID for the request, and ``iid`` the instance ID. The
 532  * request argument is specified via the ``arg`` pointer.
 533  *
 534  * Refer to ssam_request_sync_onstack() for more details on the behavior of
 535  * the generated function.
 536  */
 537 #define SSAM_DEFINE_SYNC_REQUEST_MD_W(name, atype, spec...)                     \
 538         static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg) \
 539         {                                                                       \
 540                 struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \
 541                 struct ssam_request rqst;                                       \
 542                                                                                 \
 543                 rqst.target_category = s.target_category;                       \
 544                 rqst.target_id = tid;                                           \
 545                 rqst.command_id = s.command_id;                                 \
 546                 rqst.instance_id = iid;                                         \
 547                 rqst.flags = s.flags;                                           \
 548                 rqst.length = sizeof(atype);                                    \
 549                 rqst.payload = (u8 *)arg;                                       \
 550                                                                                 \
 551                 return ssam_request_sync_onstack(ctrl, &rqst, NULL,             \
 552                                                  sizeof(atype));                \
 553         }
 554
 555 /**
 556  * SSAM_DEFINE_SYNC_REQUEST_MD_R() - Define synchronous multi-device SAM
 557  * request function with return value.
 558  * @name:  Name of the generated function.
 559  * @rtype: Type of the request's return value.
 560  * @spec:  Specification (&struct ssam_request_spec_md) defining the request.
 561  *
 562  * Defines a function executing the synchronous SAM request specified by
 563  * @spec, with the request taking no argument but having a return value of
 564  * type @rtype. Device specifying parameters are not hard-coded, but instead
 565  * must be provided to the function. The generated function takes care of
 566  * setting up the request and response structs, buffer allocation, as well as
 567  * execution of the request itself, returning once the request has been fully
 568  * completed. The required transport buffer will be allocated on the stack.
 569  *
 570  * The generated function is defined as ``static int name(struct
 571  * ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret)``, returning the status
 572  * of the request, which is zero on success and negative on failure. The
 573  * ``ctrl`` parameter is the controller via which the request is sent, ``tid``
 574  * the target ID for the request, and ``iid`` the instance ID. The request's
 575  * return value is written to the memory pointed to by the ``ret`` parameter.
 576  *
 577  * Refer to ssam_request_sync_onstack() for more details on the behavior of
 578  * the generated function.
 579  */
 580 #define SSAM_DEFINE_SYNC_REQUEST_MD_R(name, rtype, spec...)                     \
 581         static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret) \
 582         {                                                                       \
 583                 struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \
 584                 struct ssam_request rqst;                                       \
 585                 struct ssam_response rsp;                                       \
 586                 int status;                                                     \
 587                                                                                 \
 588                 rqst.target_category = s.target_category;                       \
 589                 rqst.target_id = tid;                                           \
 590                 rqst.command_id = s.command_id;                                 \
 591                 rqst.instance_id = iid;                                         \
 592                 rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE;               \
 593                 rqst.length = 0;                                                \
 594                 rqst.payload = NULL;                                            \
 595                                                                                 \
 596                 rsp.capacity = sizeof(rtype);                                   \
 597                 rsp.length = 0;                                                 \
 598                 rsp.pointer = (u8 *)ret;                                        \
 599                                                                                 \
 600                 status = ssam_request_sync_onstack(ctrl, &rqst, &rsp, 0);       \
 601                 if (status)                                                     \
 602                         return status;                                          \
 603                                                                                 \
 604                 if (rsp.length != sizeof(rtype)) {                              \
 605                         struct device *dev = ssam_controller_device(ctrl);      \
 606                         dev_err(dev,                                            \
 607                                 "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \
 608                                 sizeof(rtype), rsp.length, rqst.target_category,\
 609                                 rqst.command_id);                               \
 610                         return -EIO;                                            \
 611                 }                                                               \
 612                                                                                 \
 613                 return 0;                                                       \
 614         }
 615
 616
 617 /* -- Event notifier/callbacks. --------------------------------------------- */
 618
 619 #define SSAM_NOTIF_STATE_SHIFT          2
 620 #define SSAM_NOTIF_STATE_MASK           ((1 << SSAM_NOTIF_STATE_SHIFT) - 1)
 621
 622 /**
 623  * enum ssam_notif_flags - Flags used in return values from SSAM notifier
 624  * callback functions.
 625  *
 626  * @SSAM_NOTIF_HANDLED:
 627  *      Indicates that the notification has been handled. This flag should be
 628  *      set by the handler if the handler can act/has acted upon the event
 629  *      provided to it. This flag should not be set if the handler is not a
 630  *      primary handler intended for the provided event.
 631  *
 632  *      If this flag has not been set by any handler after the notifier chain
 633  *      has been traversed, a warning will be emitted, stating that the event
 634  *      has not been handled.
 635  *
 636  * @SSAM_NOTIF_STOP:
 637  *      Indicates that the notifier traversal should stop. If this flag is
 638  *      returned from a notifier callback, notifier chain traversal will
 639  *      immediately stop and any remaining notifiers will not be called. This
 640  *      flag is automatically set when ssam_notifier_from_errno() is called
 641  *      with a negative error value.
 642  */
 643 enum ssam_notif_flags {
 644         SSAM_NOTIF_HANDLED = BIT(0),
 645         SSAM_NOTIF_STOP    = BIT(1),
 646 };
 647
 648 struct ssam_event_notifier;
 649
 650 typedef u32 (*ssam_notifier_fn_t)(struct ssam_event_notifier *nf,
 651                                   const struct ssam_event *event);
 652
 653 /**
 654  * struct ssam_notifier_block - Base notifier block for SSAM event
 655  * notifications.
 656  * @node:     The node for the list of notifiers.
 657  * @fn:       The callback function of this notifier. This function takes the
 658  *            respective notifier block and event as input and should return
 659  *            a notifier value, which can either be obtained from the flags
 660  *            provided in &enum ssam_notif_flags, converted from a standard
 661  *            error value via ssam_notifier_from_errno(), or a combination of
 662  *            both (e.g. ``ssam_notifier_from_errno(e) | SSAM_NOTIF_HANDLED``).
 663  * @priority: Priority value determining the order in which notifier callbacks
 664  *            will be called. A higher value means higher priority, i.e. the
 665  *            associated callback will be executed earlier than other (lower
 666  *            priority) callbacks.
 667  */
 668 struct ssam_notifier_block {
 669         struct list_head node;
 670         ssam_notifier_fn_t fn;
 671         int priority;
 672 };
 673
 674 /**
 675  * ssam_notifier_from_errno() - Convert standard error value to notifier
 676  * return code.
 677  * @err: The error code to convert, must be negative (in case of failure) or
 678  *       zero (in case of success).
 679  *
 680  * Return: Returns the notifier return value obtained by converting the
 681  * specified @err value. In case @err is negative, the %SSAM_NOTIF_STOP flag
 682  * will be set, causing notifier call chain traversal to abort.
 683  */
 684 static inline u32 ssam_notifier_from_errno(int err)
 685 {
 686         if (WARN_ON(err > 0) || err == 0)
 687                 return 0;
 688         else
 689                 return ((-err) << SSAM_NOTIF_STATE_SHIFT) | SSAM_NOTIF_STOP;
 690 }
 691
 692 /**
 693  * ssam_notifier_to_errno() - Convert notifier return code to standard error
 694  * value.
 695  * @ret: The notifier return value to convert.
 696  *
 697  * Return: Returns the negative error value encoded in @ret or zero if @ret
 698  * indicates success.
 699  */
 700 static inline int ssam_notifier_to_errno(u32 ret)
 701 {
 702         return -(ret >> SSAM_NOTIF_STATE_SHIFT);
 703 }
 704
 705
 706 /* -- Event/notification registry. ------------------------------------------ */
 707
 708 /**
 709  * struct ssam_event_registry - Registry specification used for enabling events.
 710  * @target_category: Target category for the event registry requests.
 711  * @target_id:       Target ID for the event registry requests.
 712  * @cid_enable:      Command ID for the event-enable request.
 713  * @cid_disable:     Command ID for the event-disable request.
 714  *
 715  * This struct describes a SAM event registry via the minimal collection of
 716  * SAM IDs specifying the requests to use for enabling and disabling an event.
 717  * The individual event to be enabled/disabled itself is specified via &struct
 718  * ssam_event_id.
 719  */
 720 struct ssam_event_registry {
 721         u8 target_category;
 722         u8 target_id;
 723         u8 cid_enable;
 724         u8 cid_disable;
 725 };
 726
 727 /**
 728  * struct ssam_event_id - Unique event ID used for enabling events.
 729  * @target_category: Target category of the event source.
 730  * @instance:        Instance ID of the event source.
 731  *
 732  * This struct specifies the event to be enabled/disabled via an externally
 733  * provided registry. It does not specify the registry to be used itself, this
 734  * is done via &struct ssam_event_registry.
 735  */
 736 struct ssam_event_id {
 737         u8 target_category;
 738         u8 instance;
 739 };
 740
 741 /**
 742  * enum ssam_event_mask - Flags specifying how events are matched to notifiers.
 743  *
 744  * @SSAM_EVENT_MASK_NONE:
 745  *      Run the callback for any event with matching target category. Do not
 746  *      do any additional filtering.
 747  *
 748  * @SSAM_EVENT_MASK_TARGET:
 749  *      In addition to filtering by target category, only execute the notifier
 750  *      callback for events with a target ID matching to the one of the
 751  *      registry used for enabling/disabling the event.
 752  *
 753  * @SSAM_EVENT_MASK_INSTANCE:
 754  *      In addition to filtering by target category, only execute the notifier
 755  *      callback for events with an instance ID matching to the instance ID
 756  *      used when enabling the event.
 757  *
 758  * @SSAM_EVENT_MASK_STRICT:
 759  *      Do all the filtering above.
 760  */
 761 enum ssam_event_mask {
 762         SSAM_EVENT_MASK_TARGET   = BIT(0),
 763         SSAM_EVENT_MASK_INSTANCE = BIT(1),
 764
 765         SSAM_EVENT_MASK_NONE = 0,
 766         SSAM_EVENT_MASK_STRICT =
 767                   SSAM_EVENT_MASK_TARGET
 768                 | SSAM_EVENT_MASK_INSTANCE,
 769 };
 770
 771 /**
 772  * SSAM_EVENT_REGISTRY() - Define a new event registry.
 773  * @tc:      Target category for the event registry requests.
 774  * @tid:     Target ID for the event registry requests.
 775  * @cid_en:  Command ID for the event-enable request.
 776  * @cid_dis: Command ID for the event-disable request.
 777  *
 778  * Return: Returns the &struct ssam_event_registry specified by the given
 779  * parameters.
 780  */
 781 #define SSAM_EVENT_REGISTRY(tc, tid, cid_en, cid_dis)   \
 782         ((struct ssam_event_registry) {                 \
 783                 .target_category = (tc),                \
 784                 .target_id = (tid),                     \
 785                 .cid_enable = (cid_en),                 \
 786                 .cid_disable = (cid_dis),               \
 787         })
 788
 789 #define SSAM_EVENT_REGISTRY_SAM \
 790         SSAM_EVENT_REGISTRY(SSAM_SSH_TC_SAM, 0x01, 0x0b, 0x0c)
 791
 792 #define SSAM_EVENT_REGISTRY_KIP \
 793         SSAM_EVENT_REGISTRY(SSAM_SSH_TC_KIP, 0x02, 0x27, 0x28)
 794
 795 #define SSAM_EVENT_REGISTRY_REG \
 796         SSAM_EVENT_REGISTRY(SSAM_SSH_TC_REG, 0x02, 0x01, 0x02)
 797
 798 /**
 799  * struct ssam_event_notifier - Notifier block for SSAM events.
 800  * @base:        The base notifier block with callback function and priority.
 801  * @event:       The event for which this block will receive notifications.
 802  * @event.reg:   Registry via which the event will be enabled/disabled.
 803  * @event.id:    ID specifying the event.
 804  * @event.mask:  Flags determining how events are matched to the notifier.
 805  * @event.flags: Flags used for enabling the event.
 806  */
 807 struct ssam_event_notifier {
 808         struct ssam_notifier_block base;
 809
 810         struct {
 811                 struct ssam_event_registry reg;
 812                 struct ssam_event_id id;
 813                 enum ssam_event_mask mask;
 814                 u8 flags;
 815         } event;
 816 };
 817
 818 int ssam_notifier_register(struct ssam_controller *ctrl,
 819                            struct ssam_event_notifier *n);
 820
 821 int ssam_notifier_unregister(struct ssam_controller *ctrl,
 822                              struct ssam_event_notifier *n);
 823
 824 #endif /* _LINUX_SURFACE_AGGREGATOR_CONTROLLER_H */