include/linux/surface_aggregator/serial_hub.h

   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-2020 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          34
 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,
 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_ACC = 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 };
 330
 331
 332 /* -- Packet transport layer (ptl). ----------------------------------------- */
 333
 334 /**
 335  * enum ssh_packet_base_priority - Base priorities for &struct ssh_packet.
 336  * @SSH_PACKET_PRIORITY_FLUSH: Base priority for flush packets.
 337  * @SSH_PACKET_PRIORITY_DATA:  Base priority for normal data packets.
 338  * @SSH_PACKET_PRIORITY_NAK:   Base priority for NAK packets.
 339  * @SSH_PACKET_PRIORITY_ACK:   Base priority for ACK packets.
 340  */
 341 enum ssh_packet_base_priority {
 342         SSH_PACKET_PRIORITY_FLUSH = 0,  /* same as DATA to sequence flush */
 343         SSH_PACKET_PRIORITY_DATA  = 0,
 344         SSH_PACKET_PRIORITY_NAK   = 1,
 345         SSH_PACKET_PRIORITY_ACK   = 2,
 346 };
 347
 348 /*
 349  * Same as SSH_PACKET_PRIORITY() below, only with actual values.
 350  */
 351 #define __SSH_PACKET_PRIORITY(base, try) \
 352         (((base) << 4) | ((try) & 0x0f))
 353
 354 /**
 355  * SSH_PACKET_PRIORITY() - Compute packet priority from base priority and
 356  * number of tries.
 357  * @base: The base priority as suffix of &enum ssh_packet_base_priority, e.g.
 358  *        ``FLUSH``, ``DATA``, ``ACK``, or ``NAK``.
 359  * @try:  The number of tries (must be less than 16).
 360  *
 361  * Compute the combined packet priority. The combined priority is dominated by
 362  * the base priority, whereas the number of (re-)tries decides the precedence
 363  * of packets with the same base priority, giving higher priority to packets
 364  * that already have more tries.
 365  *
 366  * Return: Returns the computed priority as value fitting inside a &u8. A
 367  * higher number means a higher priority.
 368  */
 369 #define SSH_PACKET_PRIORITY(base, try) \
 370         __SSH_PACKET_PRIORITY(SSH_PACKET_PRIORITY_##base, (try))
 371
 372 /**
 373  * ssh_packet_priority_get_try() - Get number of tries from packet priority.
 374  * @priority: The packet priority.
 375  *
 376  * Return: Returns the number of tries encoded in the specified packet
 377  * priority.
 378  */
 379 static inline u8 ssh_packet_priority_get_try(u8 priority)
 380 {
 381         return priority & 0x0f;
 382 }
 383
 384 /**
 385  * ssh_packet_priority_get_base - Get base priority from packet priority.
 386  * @priority: The packet priority.
 387  *
 388  * Return: Returns the base priority encoded in the given packet priority.
 389  */
 390 static inline u8 ssh_packet_priority_get_base(u8 priority)
 391 {
 392         return (priority & 0xf0) >> 4;
 393 }
 394
 395 enum ssh_packet_flags {
 396         /* state flags */
 397         SSH_PACKET_SF_LOCKED_BIT,
 398         SSH_PACKET_SF_QUEUED_BIT,
 399         SSH_PACKET_SF_PENDING_BIT,
 400         SSH_PACKET_SF_TRANSMITTING_BIT,
 401         SSH_PACKET_SF_TRANSMITTED_BIT,
 402         SSH_PACKET_SF_ACKED_BIT,
 403         SSH_PACKET_SF_CANCELED_BIT,
 404         SSH_PACKET_SF_COMPLETED_BIT,
 405
 406         /* type flags */
 407         SSH_PACKET_TY_FLUSH_BIT,
 408         SSH_PACKET_TY_SEQUENCED_BIT,
 409         SSH_PACKET_TY_BLOCKING_BIT,
 410
 411         /* mask for state flags */
 412         SSH_PACKET_FLAGS_SF_MASK =
 413                   BIT(SSH_PACKET_SF_LOCKED_BIT)
 414                 | BIT(SSH_PACKET_SF_QUEUED_BIT)
 415                 | BIT(SSH_PACKET_SF_PENDING_BIT)
 416                 | BIT(SSH_PACKET_SF_TRANSMITTING_BIT)
 417                 | BIT(SSH_PACKET_SF_TRANSMITTED_BIT)
 418                 | BIT(SSH_PACKET_SF_ACKED_BIT)
 419                 | BIT(SSH_PACKET_SF_CANCELED_BIT)
 420                 | BIT(SSH_PACKET_SF_COMPLETED_BIT),
 421
 422         /* mask for type flags */
 423         SSH_PACKET_FLAGS_TY_MASK =
 424                   BIT(SSH_PACKET_TY_FLUSH_BIT)
 425                 | BIT(SSH_PACKET_TY_SEQUENCED_BIT)
 426                 | BIT(SSH_PACKET_TY_BLOCKING_BIT),
 427 };
 428
 429 struct ssh_ptl;
 430 struct ssh_packet;
 431
 432 /**
 433  * struct ssh_packet_ops - Callback operations for a SSH packet.
 434  * @release:  Function called when the packet reference count reaches zero.
 435  *            This callback must be relied upon to ensure that the packet has
 436  *            left the transport system(s).
 437  * @complete: Function called when the packet is completed, either with
 438  *            success or failure. In case of failure, the reason for the
 439  *            failure is indicated by the value of the provided status code
 440  *            argument. This value will be zero in case of success. Note that
 441  *            a call to this callback does not guarantee that the packet is
 442  *            not in use by the transport system any more.
 443  */
 444 struct ssh_packet_ops {
 445         void (*release)(struct ssh_packet *p);
 446         void (*complete)(struct ssh_packet *p, int status);
 447 };
 448
 449 /**
 450  * struct ssh_packet - SSH transport packet.
 451  * @ptl:      Pointer to the packet transport layer. May be %NULL if the packet
 452  *            (or enclosing request) has not been submitted yet.
 453  * @refcnt:   Reference count of the packet.
 454  * @priority: Priority of the packet. Must be computed via
 455  *            SSH_PACKET_PRIORITY(). Must only be accessed while holding the
 456  *            queue lock after first submission.
 457  * @data:     Raw message data.
 458  * @data.len: Length of the raw message data.
 459  * @data.ptr: Pointer to the raw message data buffer.
 460  * @state:    State and type flags describing current packet state (dynamic)
 461  *            and type (static). See &enum ssh_packet_flags for possible
 462  *            options.
 463  * @timestamp: Timestamp specifying when the latest transmission of a
 464  *            currently pending packet has been started. May be %KTIME_MAX
 465  *            before or in-between transmission attempts. Used for the packet
 466  *            timeout implementation. Must only be accessed while holding the
 467  *            pending lock after first submission.
 468  * @queue_node: The list node for the packet queue.
 469  * @pending_node: The list node for the set of pending packets.
 470  * @ops:      Packet operations.
 471  */
 472 struct ssh_packet {
 473         struct ssh_ptl *ptl;
 474         struct kref refcnt;
 475
 476         u8 priority;
 477
 478         struct {
 479                 size_t len;
 480                 u8 *ptr;
 481         } data;
 482
 483         unsigned long state;
 484         ktime_t timestamp;
 485
 486         struct list_head queue_node;
 487         struct list_head pending_node;
 488
 489         const struct ssh_packet_ops *ops;
 490 };
 491
 492 struct ssh_packet *ssh_packet_get(struct ssh_packet *p);
 493 void ssh_packet_put(struct ssh_packet *p);
 494
 495 /**
 496  * ssh_packet_set_data() - Set raw message data of packet.
 497  * @p:   The packet for which the message data should be set.
 498  * @ptr: Pointer to the memory holding the message data.
 499  * @len: Length of the message data.
 500  *
 501  * Sets the raw message data buffer of the packet to the provided memory. The
 502  * memory is not copied. Instead, the caller is responsible for management
 503  * (i.e. allocation and deallocation) of the memory. The caller must ensure
 504  * that the provided memory is valid and contains a valid SSH message,
 505  * starting from the time of submission of the packet until the ``release``
 506  * callback has been called. During this time, the memory may not be altered
 507  * in any way.
 508  */
 509 static inline void ssh_packet_set_data(struct ssh_packet *p, u8 *ptr, size_t len)
 510 {
 511         p->data.ptr = ptr;
 512         p->data.len = len;
 513 }
 514
 515
 516 /* -- Request transport layer (rtl). ---------------------------------------- */
 517
 518 enum ssh_request_flags {
 519         /* state flags */
 520         SSH_REQUEST_SF_LOCKED_BIT,
 521         SSH_REQUEST_SF_QUEUED_BIT,
 522         SSH_REQUEST_SF_PENDING_BIT,
 523         SSH_REQUEST_SF_TRANSMITTING_BIT,
 524         SSH_REQUEST_SF_TRANSMITTED_BIT,
 525         SSH_REQUEST_SF_RSPRCVD_BIT,
 526         SSH_REQUEST_SF_CANCELED_BIT,
 527         SSH_REQUEST_SF_COMPLETED_BIT,
 528
 529         /* type flags */
 530         SSH_REQUEST_TY_FLUSH_BIT,
 531         SSH_REQUEST_TY_HAS_RESPONSE_BIT,
 532
 533         /* mask for state flags */
 534         SSH_REQUEST_FLAGS_SF_MASK =
 535                   BIT(SSH_REQUEST_SF_LOCKED_BIT)
 536                 | BIT(SSH_REQUEST_SF_QUEUED_BIT)
 537                 | BIT(SSH_REQUEST_SF_PENDING_BIT)
 538                 | BIT(SSH_REQUEST_SF_TRANSMITTING_BIT)
 539                 | BIT(SSH_REQUEST_SF_TRANSMITTED_BIT)
 540                 | BIT(SSH_REQUEST_SF_RSPRCVD_BIT)
 541                 | BIT(SSH_REQUEST_SF_CANCELED_BIT)
 542                 | BIT(SSH_REQUEST_SF_COMPLETED_BIT),
 543
 544         /* mask for type flags */
 545         SSH_REQUEST_FLAGS_TY_MASK =
 546                   BIT(SSH_REQUEST_TY_FLUSH_BIT)
 547                 | BIT(SSH_REQUEST_TY_HAS_RESPONSE_BIT),
 548 };
 549
 550 struct ssh_rtl;
 551 struct ssh_request;
 552
 553 /**
 554  * struct ssh_request_ops - Callback operations for a SSH request.
 555  * @release:  Function called when the request's reference count reaches zero.
 556  *            This callback must be relied upon to ensure that the request has
 557  *            left the transport systems (both, packet an request systems).
 558  * @complete: Function called when the request is completed, either with
 559  *            success or failure. The command data for the request response
 560  *            is provided via the &struct ssh_command parameter (``cmd``),
 561  *            the command payload of the request response via the &struct
 562  *            ssh_span parameter (``data``).
 563  *
 564  *            If the request does not have any response or has not been
 565  *            completed with success, both ``cmd`` and ``data`` parameters will
 566  *            be NULL. If the request response does not have any command
 567  *            payload, the ``data`` span will be an empty (zero-length) span.
 568  *
 569  *            In case of failure, the reason for the failure is indicated by
 570  *            the value of the provided status code argument (``status``). This
 571  *            value will be zero in case of success and a regular errno
 572  *            otherwise.
 573  *
 574  *            Note that a call to this callback does not guarantee that the
 575  *            request is not in use by the transport systems any more.
 576  */
 577 struct ssh_request_ops {
 578         void (*release)(struct ssh_request *rqst);
 579         void (*complete)(struct ssh_request *rqst,
 580                          const struct ssh_command *cmd,
 581                          const struct ssam_span *data, int status);
 582 };
 583
 584 /**
 585  * struct ssh_request - SSH transport request.
 586  * @packet: The underlying SSH transport packet.
 587  * @node:   List node for the request queue and pending set.
 588  * @state:  State and type flags describing current request state (dynamic)
 589  *          and type (static). See &enum ssh_request_flags for possible
 590  *          options.
 591  * @timestamp: Timestamp specifying when we start waiting on the response of
 592  *          the request. This is set once the underlying packet has been
 593  *          completed and may be %KTIME_MAX before that, or when the request
 594  *          does not expect a response. Used for the request timeout
 595  *          implementation.
 596  * @ops:    Request Operations.
 597  */
 598 struct ssh_request {
 599         struct ssh_packet packet;
 600         struct list_head node;
 601
 602         unsigned long state;
 603         ktime_t timestamp;
 604
 605         const struct ssh_request_ops *ops;
 606 };
 607
 608 /**
 609  * to_ssh_request() - Cast a SSH packet to its enclosing SSH request.
 610  * @p: The packet to cast.
 611  *
 612  * Casts the given &struct ssh_packet to its enclosing &struct ssh_request.
 613  * The caller is responsible for making sure that the packet is actually
 614  * wrapped in a &struct ssh_request.
 615  *
 616  * Return: Returns the &struct ssh_request wrapping the provided packet.
 617  */
 618 static inline struct ssh_request *to_ssh_request(struct ssh_packet *p)
 619 {
 620         return container_of(p, struct ssh_request, packet);
 621 }
 622
 623 /**
 624  * ssh_request_get() - Increment reference count of request.
 625  * @r: The request to increment the reference count of.
 626  *
 627  * Increments the reference count of the given request by incrementing the
 628  * reference count of the underlying &struct ssh_packet, enclosed in it.
 629  *
 630  * See also ssh_request_put(), ssh_packet_get().
 631  *
 632  * Return: Returns the request provided as input.
 633  */
 634 static inline struct ssh_request *ssh_request_get(struct ssh_request *r)
 635 {
 636         return r ? to_ssh_request(ssh_packet_get(&r->packet)) : NULL;
 637 }
 638
 639 /**
 640  * ssh_request_put() - Decrement reference count of request.
 641  * @r: The request to decrement the reference count of.
 642  *
 643  * Decrements the reference count of the given request by decrementing the
 644  * reference count of the underlying &struct ssh_packet, enclosed in it. If
 645  * the reference count reaches zero, the ``release`` callback specified in the
 646  * request's &struct ssh_request_ops, i.e. ``r->ops->release``, will be
 647  * called.
 648  *
 649  * See also ssh_request_get(), ssh_packet_put().
 650  */
 651 static inline void ssh_request_put(struct ssh_request *r)
 652 {
 653         if (r)
 654                 ssh_packet_put(&r->packet);
 655 }
 656
 657 /**
 658  * ssh_request_set_data() - Set raw message data of request.
 659  * @r:   The request for which the message data should be set.
 660  * @ptr: Pointer to the memory holding the message data.
 661  * @len: Length of the message data.
 662  *
 663  * Sets the raw message data buffer of the underlying packet to the specified
 664  * buffer. Does not copy the actual message data, just sets the buffer pointer
 665  * and length. Refer to ssh_packet_set_data() for more details.
 666  */
 667 static inline void ssh_request_set_data(struct ssh_request *r, u8 *ptr, size_t len)
 668 {
 669         ssh_packet_set_data(&r->packet, ptr, len);
 670 }
 671
 672 #endif /* _LINUX_SURFACE_AGGREGATOR_SERIAL_HUB_H */