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[]; 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_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_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_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_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_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_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_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_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_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_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_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, 0x01, 0x0b, 0x0c) 916 917 #define SSAM_EVENT_REGISTRY_KIP \ 918 SSAM_EVENT_REGISTRY(SSAM_SSH_TC_KIP, 0x02, 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 */ 995