1 /* SPDX-License-Identifier: GPL-2.0+ */ 2 /* 3 * Surface Serial Hub (SSH) protocol and communication interface. 4 * 5 * Lower-level communication layers and SSH protocol definitions for the 6 * Surface System Aggregator Module (SSAM). Provides the interface for basic 7 * packet- and request-based communication with the SSAM EC via SSH. 8 * 9 * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com> 10 */ 11 12 #ifndef _LINUX_SURFACE_AGGREGATOR_SERIAL_HUB_H 13 #define _LINUX_SURFACE_AGGREGATOR_SERIAL_HUB_H 14 15 #include <linux/crc-ccitt.h> 16 #include <linux/kref.h> 17 #include <linux/ktime.h> 18 #include <linux/list.h> 19 #include <linux/types.h> 20 21 22 /* -- Data structures for SAM-over-SSH communication. ----------------------- */ 23 24 /** 25 * enum ssh_frame_type - Frame types for SSH frames. 26 * 27 * @SSH_FRAME_TYPE_DATA_SEQ: 28 * Indicates a data frame, followed by a payload with the length specified 29 * in the ``struct ssh_frame.len`` field. This frame is sequenced, meaning 30 * that an ACK is required. 31 * 32 * @SSH_FRAME_TYPE_DATA_NSQ: 33 * Same as %SSH_FRAME_TYPE_DATA_SEQ, but unsequenced, meaning that the 34 * message does not have to be ACKed. 35 * 36 * @SSH_FRAME_TYPE_ACK: 37 * Indicates an ACK message. 38 * 39 * @SSH_FRAME_TYPE_NAK: 40 * Indicates an error response for previously sent frame. In general, this 41 * means that the frame and/or payload is malformed, e.g. a CRC is wrong. 42 * For command-type payloads, this can also mean that the command is 43 * invalid. 44 */ 45 enum ssh_frame_type { 46 SSH_FRAME_TYPE_DATA_SEQ = 0x80, 47 SSH_FRAME_TYPE_DATA_NSQ = 0x00, 48 SSH_FRAME_TYPE_ACK = 0x40, 49 SSH_FRAME_TYPE_NAK = 0x04, 50 }; 51 52 /** 53 * struct ssh_frame - SSH communication frame. 54 * @type: The type of the frame. See &enum ssh_frame_type. 55 * @len: The length of the frame payload directly following the CRC for this 56 * frame. Does not include the final CRC for that payload. 57 * @seq: The sequence number for this message/exchange. 58 */ 59 struct ssh_frame { 60 u8 type; 61 __le16 len; 62 u8 seq; 63 } __packed; 64 65 static_assert(sizeof(struct ssh_frame) == 4); 66 67 /* 68 * SSH_FRAME_MAX_PAYLOAD_SIZE - Maximum SSH frame payload length in bytes. 69 * 70 * This is the physical maximum length of the protocol. Implementations may 71 * set a more constrained limit. 72 */ 73 #define SSH_FRAME_MAX_PAYLOAD_SIZE U16_MAX 74 75 /** 76 * enum ssh_payload_type - Type indicator for the SSH payload. 77 * @SSH_PLD_TYPE_CMD: The payload is a command structure with optional command 78 * payload. 79 */ 80 enum ssh_payload_type { 81 SSH_PLD_TYPE_CMD = 0x80, 82 }; 83 84 /** 85 * struct ssh_command - Payload of a command-type frame. 86 * @type: The type of the payload. See &enum ssh_payload_type. Should be 87 * SSH_PLD_TYPE_CMD for this struct. 88 * @tc: Command target category. 89 * @tid_out: Output target ID. Should be zero if this an incoming (EC to host) 90 * message. 91 * @tid_in: Input target ID. Should be zero if this is an outgoing (host to 92 * EC) message. 93 * @iid: Instance ID. 94 * @rqid: Request ID. Used to match requests with responses and differentiate 95 * between responses and events. 96 * @cid: Command ID. 97 */ 98 struct ssh_command { 99 u8 type; 100 u8 tc; 101 u8 tid_out; 102 u8 tid_in; 103 u8 iid; 104 __le16 rqid; 105 u8 cid; 106 } __packed; 107 108 static_assert(sizeof(struct ssh_command) == 8); 109 110 /* 111 * SSH_COMMAND_MAX_PAYLOAD_SIZE - Maximum SSH command payload length in bytes. 112 * 113 * This is the physical maximum length of the protocol. Implementations may 114 * set a more constrained limit. 115 */ 116 #define SSH_COMMAND_MAX_PAYLOAD_SIZE \ 117 (SSH_FRAME_MAX_PAYLOAD_SIZE - sizeof(struct ssh_command)) 118 119 /* 120 * SSH_MSG_LEN_BASE - Base-length of a SSH message. 121 * 122 * This is the minimum number of bytes required to form a message. The actual 123 * message length is SSH_MSG_LEN_BASE plus the length of the frame payload. 124 */ 125 #define SSH_MSG_LEN_BASE (sizeof(struct ssh_frame) + 3ull * sizeof(u16)) 126 127 /* 128 * SSH_MSG_LEN_CTRL - Length of a SSH control message. 129 * 130 * This is the length of a SSH control message, which is equal to a SSH 131 * message without any payload. 132 */ 133 #define SSH_MSG_LEN_CTRL SSH_MSG_LEN_BASE 134 135 /** 136 * SSH_MESSAGE_LENGTH() - Compute length of SSH message. 137 * @payload_size: Length of the payload inside the SSH frame. 138 * 139 * Return: Returns the length of a SSH message with payload of specified size. 140 */ 141 #define SSH_MESSAGE_LENGTH(payload_size) (SSH_MSG_LEN_BASE + (payload_size)) 142 143 /** 144 * SSH_COMMAND_MESSAGE_LENGTH() - Compute length of SSH command message. 145 * @payload_size: Length of the command payload. 146 * 147 * Return: Returns the length of a SSH command message with command payload of 148 * specified size. 149 */ 150 #define SSH_COMMAND_MESSAGE_LENGTH(payload_size) \ 151 SSH_MESSAGE_LENGTH(sizeof(struct ssh_command) + (payload_size)) 152 153 /** 154 * SSH_MSGOFFSET_FRAME() - Compute offset in SSH message to specified field in 155 * frame. 156 * @field: The field for which the offset should be computed. 157 * 158 * Return: Returns the offset of the specified &struct ssh_frame field in the 159 * raw SSH message data as. Takes SYN bytes (u16) preceding the frame into 160 * account. 161 */ 162 #define SSH_MSGOFFSET_FRAME(field) \ 163 (sizeof(u16) + offsetof(struct ssh_frame, field)) 164 165 /** 166 * SSH_MSGOFFSET_COMMAND() - Compute offset in SSH message to specified field 167 * in command. 168 * @field: The field for which the offset should be computed. 169 * 170 * Return: Returns the offset of the specified &struct ssh_command field in 171 * the raw SSH message data. Takes SYN bytes (u16) preceding the frame and the 172 * frame CRC (u16) between frame and command into account. 173 */ 174 #define SSH_MSGOFFSET_COMMAND(field) \ 175 (2ull * sizeof(u16) + sizeof(struct ssh_frame) \ 176 + offsetof(struct ssh_command, field)) 177 178 /* 179 * SSH_MSG_SYN - SSH message synchronization (SYN) bytes as u16. 180 */ 181 #define SSH_MSG_SYN ((u16)0x55aa) 182 183 /** 184 * ssh_crc() - Compute CRC for SSH messages. 185 * @buf: The pointer pointing to the data for which the CRC should be computed. 186 * @len: The length of the data for which the CRC should be computed. 187 * 188 * Return: Returns the CRC computed on the provided data, as used for SSH 189 * messages. 190 */ 191 static inline u16 ssh_crc(const u8 *buf, size_t len) 192 { 193 return crc_ccitt_false(0xffff, buf, len); 194 } 195 196 /* 197 * SSH_NUM_EVENTS - The number of reserved event IDs. 198 * 199 * The number of reserved event IDs, used for registering an SSH event 200 * handler. Valid event IDs are numbers below or equal to this value, with 201 * exception of zero, which is not an event ID. Thus, this is also the 202 * absolute maximum number of event handlers that can be registered. 203 */ 204 #define SSH_NUM_EVENTS 38 205 206 /* 207 * SSH_NUM_TARGETS - The number of communication targets used in the protocol. 208 */ 209 #define SSH_NUM_TARGETS 2 210 211 /** 212 * ssh_rqid_next_valid() - Return the next valid request ID. 213 * @rqid: The current request ID. 214 * 215 * Return: Returns the next valid request ID, following the current request ID 216 * provided to this function. This function skips any request IDs reserved for 217 * events. 218 */ 219 static inline u16 ssh_rqid_next_valid(u16 rqid) 220 { 221 return rqid > 0 ? rqid + 1u : rqid + SSH_NUM_EVENTS + 1u; 222 } 223 224 /** 225 * ssh_rqid_to_event() - Convert request ID to its corresponding event ID. 226 * @rqid: The request ID to convert. 227 */ 228 static inline u16 ssh_rqid_to_event(u16 rqid) 229 { 230 return rqid - 1u; 231 } 232 233 /** 234 * ssh_rqid_is_event() - Check if given request ID is a valid event ID. 235 * @rqid: The request ID to check. 236 */ 237 static inline bool ssh_rqid_is_event(u16 rqid) 238 { 239 return ssh_rqid_to_event(rqid) < SSH_NUM_EVENTS; 240 } 241 242 /** 243 * ssh_tc_to_rqid() - Convert target category to its corresponding request ID. 244 * @tc: The target category to convert. 245 */ 246 static inline u16 ssh_tc_to_rqid(u8 tc) 247 { 248 return tc; 249 } 250 251 /** 252 * ssh_tid_to_index() - Convert target ID to its corresponding target index. 253 * @tid: The target ID to convert. 254 */ 255 static inline u8 ssh_tid_to_index(u8 tid) 256 { 257 return tid - 1u; 258 } 259 260 /** 261 * ssh_tid_is_valid() - Check if target ID is valid/supported. 262 * @tid: The target ID to check. 263 */ 264 static inline bool ssh_tid_is_valid(u8 tid) 265 { 266 return ssh_tid_to_index(tid) < SSH_NUM_TARGETS; 267 } 268 269 /** 270 * struct ssam_span - Reference to a buffer region. 271 * @ptr: Pointer to the buffer region. 272 * @len: Length of the buffer region. 273 * 274 * A reference to a (non-owned) buffer segment, consisting of pointer and 275 * length. Use of this struct indicates non-owned data, i.e. data of which the 276 * life-time is managed (i.e. it is allocated/freed) via another pointer. 277 */ 278 struct ssam_span { 279 u8 *ptr; 280 size_t len; 281 }; 282 283 /* 284 * Known SSH/EC target categories. 285 * 286 * List of currently known target category values; "Known" as in we know they 287 * exist and are valid on at least some device/model. Detailed functionality 288 * or the full category name is only known for some of these categories and 289 * is detailed in the respective comment below. 290 * 291 * These values and abbreviations have been extracted from strings inside the 292 * Windows driver. 293 */ 294 enum ssam_ssh_tc { 295 /* Category 0x00 is invalid for EC use. */ 296 SSAM_SSH_TC_SAM = 0x01, /* Generic system functionality, real-time clock. */ 297 SSAM_SSH_TC_BAT = 0x02, /* Battery/power subsystem. */ 298 SSAM_SSH_TC_TMP = 0x03, /* Thermal subsystem. */ 299 SSAM_SSH_TC_PMC = 0x04, 300 SSAM_SSH_TC_FAN = 0x05, 301 SSAM_SSH_TC_PoM = 0x06, 302 SSAM_SSH_TC_DBG = 0x07, 303 SSAM_SSH_TC_KBD = 0x08, /* Legacy keyboard (Laptop 1/2). */ 304 SSAM_SSH_TC_FWU = 0x09, 305 SSAM_SSH_TC_UNI = 0x0a, 306 SSAM_SSH_TC_LPC = 0x0b, 307 SSAM_SSH_TC_TCL = 0x0c, 308 SSAM_SSH_TC_SFL = 0x0d, 309 SSAM_SSH_TC_KIP = 0x0e, /* Manages detachable peripherals (Pro X/8 keyboard cover) */ 310 SSAM_SSH_TC_EXT = 0x0f, 311 SSAM_SSH_TC_BLD = 0x10, 312 SSAM_SSH_TC_BAS = 0x11, /* Detachment system (Surface Book 2/3). */ 313 SSAM_SSH_TC_SEN = 0x12, 314 SSAM_SSH_TC_SRQ = 0x13, 315 SSAM_SSH_TC_MCU = 0x14, 316 SSAM_SSH_TC_HID = 0x15, /* Generic HID input subsystem. */ 317 SSAM_SSH_TC_TCH = 0x16, 318 SSAM_SSH_TC_BKL = 0x17, 319 SSAM_SSH_TC_TAM = 0x18, 320 SSAM_SSH_TC_ACC0 = 0x19, 321 SSAM_SSH_TC_UFI = 0x1a, 322 SSAM_SSH_TC_USC = 0x1b, 323 SSAM_SSH_TC_PEN = 0x1c, 324 SSAM_SSH_TC_VID = 0x1d, 325 SSAM_SSH_TC_AUD = 0x1e, 326 SSAM_SSH_TC_SMC = 0x1f, 327 SSAM_SSH_TC_KPD = 0x20, 328 SSAM_SSH_TC_REG = 0x21, /* Extended event registry. */ 329 SSAM_SSH_TC_SPT = 0x22, 330 SSAM_SSH_TC_SYS = 0x23, 331 SSAM_SSH_TC_ACC1 = 0x24, 332 SSAM_SSH_TC_SHB = 0x25, 333 SSAM_SSH_TC_POS = 0x26, /* For obtaining Laptop Studio screen position. */ 334 }; 335 336 337 /* -- Packet transport layer (ptl). ----------------------------------------- */ 338 339 /** 340 * enum ssh_packet_base_priority - Base priorities for &struct ssh_packet. 341 * @SSH_PACKET_PRIORITY_FLUSH: Base priority for flush packets. 342 * @SSH_PACKET_PRIORITY_DATA: Base priority for normal data packets. 343 * @SSH_PACKET_PRIORITY_NAK: Base priority for NAK packets. 344 * @SSH_PACKET_PRIORITY_ACK: Base priority for ACK packets. 345 */ 346 enum ssh_packet_base_priority { 347 SSH_PACKET_PRIORITY_FLUSH = 0, /* same as DATA to sequence flush */ 348 SSH_PACKET_PRIORITY_DATA = 0, 349 SSH_PACKET_PRIORITY_NAK = 1, 350 SSH_PACKET_PRIORITY_ACK = 2, 351 }; 352 353 /* 354 * Same as SSH_PACKET_PRIORITY() below, only with actual values. 355 */ 356 #define __SSH_PACKET_PRIORITY(base, try) \ 357 (((base) << 4) | ((try) & 0x0f)) 358 359 /** 360 * SSH_PACKET_PRIORITY() - Compute packet priority from base priority and 361 * number of tries. 362 * @base: The base priority as suffix of &enum ssh_packet_base_priority, e.g. 363 * ``FLUSH``, ``DATA``, ``ACK``, or ``NAK``. 364 * @try: The number of tries (must be less than 16). 365 * 366 * Compute the combined packet priority. The combined priority is dominated by 367 * the base priority, whereas the number of (re-)tries decides the precedence 368 * of packets with the same base priority, giving higher priority to packets 369 * that already have more tries. 370 * 371 * Return: Returns the computed priority as value fitting inside a &u8. A 372 * higher number means a higher priority. 373 */ 374 #define SSH_PACKET_PRIORITY(base, try) \ 375 __SSH_PACKET_PRIORITY(SSH_PACKET_PRIORITY_##base, (try)) 376 377 /** 378 * ssh_packet_priority_get_try() - Get number of tries from packet priority. 379 * @priority: The packet priority. 380 * 381 * Return: Returns the number of tries encoded in the specified packet 382 * priority. 383 */ 384 static inline u8 ssh_packet_priority_get_try(u8 priority) 385 { 386 return priority & 0x0f; 387 } 388 389 /** 390 * ssh_packet_priority_get_base - Get base priority from packet priority. 391 * @priority: The packet priority. 392 * 393 * Return: Returns the base priority encoded in the given packet priority. 394 */ 395 static inline u8 ssh_packet_priority_get_base(u8 priority) 396 { 397 return (priority & 0xf0) >> 4; 398 } 399 400 enum ssh_packet_flags { 401 /* state flags */ 402 SSH_PACKET_SF_LOCKED_BIT, 403 SSH_PACKET_SF_QUEUED_BIT, 404 SSH_PACKET_SF_PENDING_BIT, 405 SSH_PACKET_SF_TRANSMITTING_BIT, 406 SSH_PACKET_SF_TRANSMITTED_BIT, 407 SSH_PACKET_SF_ACKED_BIT, 408 SSH_PACKET_SF_CANCELED_BIT, 409 SSH_PACKET_SF_COMPLETED_BIT, 410 411 /* type flags */ 412 SSH_PACKET_TY_FLUSH_BIT, 413 SSH_PACKET_TY_SEQUENCED_BIT, 414 SSH_PACKET_TY_BLOCKING_BIT, 415 416 /* mask for state flags */ 417 SSH_PACKET_FLAGS_SF_MASK = 418 BIT(SSH_PACKET_SF_LOCKED_BIT) 419 | BIT(SSH_PACKET_SF_QUEUED_BIT) 420 | BIT(SSH_PACKET_SF_PENDING_BIT) 421 | BIT(SSH_PACKET_SF_TRANSMITTING_BIT) 422 | BIT(SSH_PACKET_SF_TRANSMITTED_BIT) 423 | BIT(SSH_PACKET_SF_ACKED_BIT) 424 | BIT(SSH_PACKET_SF_CANCELED_BIT) 425 | BIT(SSH_PACKET_SF_COMPLETED_BIT), 426 427 /* mask for type flags */ 428 SSH_PACKET_FLAGS_TY_MASK = 429 BIT(SSH_PACKET_TY_FLUSH_BIT) 430 | BIT(SSH_PACKET_TY_SEQUENCED_BIT) 431 | BIT(SSH_PACKET_TY_BLOCKING_BIT), 432 }; 433 434 struct ssh_ptl; 435 struct ssh_packet; 436 437 /** 438 * struct ssh_packet_ops - Callback operations for a SSH packet. 439 * @release: Function called when the packet reference count reaches zero. 440 * This callback must be relied upon to ensure that the packet has 441 * left the transport system(s). 442 * @complete: Function called when the packet is completed, either with 443 * success or failure. In case of failure, the reason for the 444 * failure is indicated by the value of the provided status code 445 * argument. This value will be zero in case of success. Note that 446 * a call to this callback does not guarantee that the packet is 447 * not in use by the transport system any more. 448 */ 449 struct ssh_packet_ops { 450 void (*release)(struct ssh_packet *p); 451 void (*complete)(struct ssh_packet *p, int status); 452 }; 453 454 /** 455 * struct ssh_packet - SSH transport packet. 456 * @ptl: Pointer to the packet transport layer. May be %NULL if the packet 457 * (or enclosing request) has not been submitted yet. 458 * @refcnt: Reference count of the packet. 459 * @priority: Priority of the packet. Must be computed via 460 * SSH_PACKET_PRIORITY(). Must only be accessed while holding the 461 * queue lock after first submission. 462 * @data: Raw message data. 463 * @data.len: Length of the raw message data. 464 * @data.ptr: Pointer to the raw message data buffer. 465 * @state: State and type flags describing current packet state (dynamic) 466 * and type (static). See &enum ssh_packet_flags for possible 467 * options. 468 * @timestamp: Timestamp specifying when the latest transmission of a 469 * currently pending packet has been started. May be %KTIME_MAX 470 * before or in-between transmission attempts. Used for the packet 471 * timeout implementation. Must only be accessed while holding the 472 * pending lock after first submission. 473 * @queue_node: The list node for the packet queue. 474 * @pending_node: The list node for the set of pending packets. 475 * @ops: Packet operations. 476 */ 477 struct ssh_packet { 478 struct ssh_ptl *ptl; 479 struct kref refcnt; 480 481 u8 priority; 482 483 struct { 484 size_t len; 485 u8 *ptr; 486 } data; 487 488 unsigned long state; 489 ktime_t timestamp; 490 491 struct list_head queue_node; 492 struct list_head pending_node; 493 494 const struct ssh_packet_ops *ops; 495 }; 496 497 struct ssh_packet *ssh_packet_get(struct ssh_packet *p); 498 void ssh_packet_put(struct ssh_packet *p); 499 500 /** 501 * ssh_packet_set_data() - Set raw message data of packet. 502 * @p: The packet for which the message data should be set. 503 * @ptr: Pointer to the memory holding the message data. 504 * @len: Length of the message data. 505 * 506 * Sets the raw message data buffer of the packet to the provided memory. The 507 * memory is not copied. Instead, the caller is responsible for management 508 * (i.e. allocation and deallocation) of the memory. The caller must ensure 509 * that the provided memory is valid and contains a valid SSH message, 510 * starting from the time of submission of the packet until the ``release`` 511 * callback has been called. During this time, the memory may not be altered 512 * in any way. 513 */ 514 static inline void ssh_packet_set_data(struct ssh_packet *p, u8 *ptr, size_t len) 515 { 516 p->data.ptr = ptr; 517 p->data.len = len; 518 } 519 520 521 /* -- Request transport layer (rtl). ---------------------------------------- */ 522 523 enum ssh_request_flags { 524 /* state flags */ 525 SSH_REQUEST_SF_LOCKED_BIT, 526 SSH_REQUEST_SF_QUEUED_BIT, 527 SSH_REQUEST_SF_PENDING_BIT, 528 SSH_REQUEST_SF_TRANSMITTING_BIT, 529 SSH_REQUEST_SF_TRANSMITTED_BIT, 530 SSH_REQUEST_SF_RSPRCVD_BIT, 531 SSH_REQUEST_SF_CANCELED_BIT, 532 SSH_REQUEST_SF_COMPLETED_BIT, 533 534 /* type flags */ 535 SSH_REQUEST_TY_FLUSH_BIT, 536 SSH_REQUEST_TY_HAS_RESPONSE_BIT, 537 538 /* mask for state flags */ 539 SSH_REQUEST_FLAGS_SF_MASK = 540 BIT(SSH_REQUEST_SF_LOCKED_BIT) 541 | BIT(SSH_REQUEST_SF_QUEUED_BIT) 542 | BIT(SSH_REQUEST_SF_PENDING_BIT) 543 | BIT(SSH_REQUEST_SF_TRANSMITTING_BIT) 544 | BIT(SSH_REQUEST_SF_TRANSMITTED_BIT) 545 | BIT(SSH_REQUEST_SF_RSPRCVD_BIT) 546 | BIT(SSH_REQUEST_SF_CANCELED_BIT) 547 | BIT(SSH_REQUEST_SF_COMPLETED_BIT), 548 549 /* mask for type flags */ 550 SSH_REQUEST_FLAGS_TY_MASK = 551 BIT(SSH_REQUEST_TY_FLUSH_BIT) 552 | BIT(SSH_REQUEST_TY_HAS_RESPONSE_BIT), 553 }; 554 555 struct ssh_rtl; 556 struct ssh_request; 557 558 /** 559 * struct ssh_request_ops - Callback operations for a SSH request. 560 * @release: Function called when the request's reference count reaches zero. 561 * This callback must be relied upon to ensure that the request has 562 * left the transport systems (both, packet an request systems). 563 * @complete: Function called when the request is completed, either with 564 * success or failure. The command data for the request response 565 * is provided via the &struct ssh_command parameter (``cmd``), 566 * the command payload of the request response via the &struct 567 * ssh_span parameter (``data``). 568 * 569 * If the request does not have any response or has not been 570 * completed with success, both ``cmd`` and ``data`` parameters will 571 * be NULL. If the request response does not have any command 572 * payload, the ``data`` span will be an empty (zero-length) span. 573 * 574 * In case of failure, the reason for the failure is indicated by 575 * the value of the provided status code argument (``status``). This 576 * value will be zero in case of success and a regular errno 577 * otherwise. 578 * 579 * Note that a call to this callback does not guarantee that the 580 * request is not in use by the transport systems any more. 581 */ 582 struct ssh_request_ops { 583 void (*release)(struct ssh_request *rqst); 584 void (*complete)(struct ssh_request *rqst, 585 const struct ssh_command *cmd, 586 const struct ssam_span *data, int status); 587 }; 588 589 /** 590 * struct ssh_request - SSH transport request. 591 * @packet: The underlying SSH transport packet. 592 * @node: List node for the request queue and pending set. 593 * @state: State and type flags describing current request state (dynamic) 594 * and type (static). See &enum ssh_request_flags for possible 595 * options. 596 * @timestamp: Timestamp specifying when we start waiting on the response of 597 * the request. This is set once the underlying packet has been 598 * completed and may be %KTIME_MAX before that, or when the request 599 * does not expect a response. Used for the request timeout 600 * implementation. 601 * @ops: Request Operations. 602 */ 603 struct ssh_request { 604 struct ssh_packet packet; 605 struct list_head node; 606 607 unsigned long state; 608 ktime_t timestamp; 609 610 const struct ssh_request_ops *ops; 611 }; 612 613 /** 614 * to_ssh_request() - Cast a SSH packet to its enclosing SSH request. 615 * @p: The packet to cast. 616 * 617 * Casts the given &struct ssh_packet to its enclosing &struct ssh_request. 618 * The caller is responsible for making sure that the packet is actually 619 * wrapped in a &struct ssh_request. 620 * 621 * Return: Returns the &struct ssh_request wrapping the provided packet. 622 */ 623 static inline struct ssh_request *to_ssh_request(struct ssh_packet *p) 624 { 625 return container_of(p, struct ssh_request, packet); 626 } 627 628 /** 629 * ssh_request_get() - Increment reference count of request. 630 * @r: The request to increment the reference count of. 631 * 632 * Increments the reference count of the given request by incrementing the 633 * reference count of the underlying &struct ssh_packet, enclosed in it. 634 * 635 * See also ssh_request_put(), ssh_packet_get(). 636 * 637 * Return: Returns the request provided as input. 638 */ 639 static inline struct ssh_request *ssh_request_get(struct ssh_request *r) 640 { 641 return r ? to_ssh_request(ssh_packet_get(&r->packet)) : NULL; 642 } 643 644 /** 645 * ssh_request_put() - Decrement reference count of request. 646 * @r: The request to decrement the reference count of. 647 * 648 * Decrements the reference count of the given request by decrementing the 649 * reference count of the underlying &struct ssh_packet, enclosed in it. If 650 * the reference count reaches zero, the ``release`` callback specified in the 651 * request's &struct ssh_request_ops, i.e. ``r->ops->release``, will be 652 * called. 653 * 654 * See also ssh_request_get(), ssh_packet_put(). 655 */ 656 static inline void ssh_request_put(struct ssh_request *r) 657 { 658 if (r) 659 ssh_packet_put(&r->packet); 660 } 661 662 /** 663 * ssh_request_set_data() - Set raw message data of request. 664 * @r: The request for which the message data should be set. 665 * @ptr: Pointer to the memory holding the message data. 666 * @len: Length of the message data. 667 * 668 * Sets the raw message data buffer of the underlying packet to the specified 669 * buffer. Does not copy the actual message data, just sets the buffer pointer 670 * and length. Refer to ssh_packet_set_data() for more details. 671 */ 672 static inline void ssh_request_set_data(struct ssh_request *r, u8 *ptr, size_t len) 673 { 674 ssh_packet_set_data(&r->packet, ptr, len); 675 } 676 677 #endif /* _LINUX_SURFACE_AGGREGATOR_SERIAL_HUB_H */ 678