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