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-itu-t.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_itu_t(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