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