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		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  */
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,
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  */
ssh_packet_priority_get_try(u8 priority)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  */
ssh_packet_priority_get_base(u8 priority)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  */
ssh_packet_set_data(struct ssh_packet * p,u8 * ptr,size_t len)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  */
to_ssh_request(struct ssh_packet * p)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  */
ssh_request_get(struct ssh_request * r)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  */
ssh_request_put(struct ssh_request * r)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  */
ssh_request_set_data(struct ssh_request * r,u8 * ptr,size_t len)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 */
673