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