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 */
ssh_crc(const u8 * buf,size_t len)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 */
ssh_rqid_next_valid(u16 rqid)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 */
ssh_rqid_to_event(u16 rqid)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 */
ssh_rqid_is_event(u16 rqid)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 */
ssh_tc_to_rqid(u8 tc)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 */
ssh_tid_to_index(u8 tid)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 */
ssh_tid_is_valid(u8 tid)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 */
ssh_packet_priority_get_try(u8 priority)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 */
ssh_packet_priority_get_base(u8 priority)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 */
ssh_packet_set_data(struct ssh_packet * p,u8 * ptr,size_t len)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 */
to_ssh_request(struct ssh_packet * p)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 */
ssh_request_get(struct ssh_request * r)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 */
ssh_request_put(struct ssh_request * r)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 */
ssh_request_set_data(struct ssh_request * r,u8 * ptr,size_t len)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