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 | */ |
189 | static inline u16 ssh_crc(const u8 *buf, size_t len) |
190 | { |
191 | return crc_itu_t(crc: 0xffff, buffer: 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 | */ |
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 | */ |
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 | */ |
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 | */ |
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 | */ |
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 | */ |
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 | */ |
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 | */ |
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 | */ |
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 | */ |
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 | */ |
653 | static inline struct ssh_request *ssh_request_get(struct ssh_request *r) |
654 | { |
655 | return r ? to_ssh_request(p: ssh_packet_get(p: &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 | */ |
670 | static inline void ssh_request_put(struct ssh_request *r) |
671 | { |
672 | if (r) |
673 | ssh_packet_put(p: &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 | */ |
686 | static inline void ssh_request_set_data(struct ssh_request *r, u8 *ptr, size_t len) |
687 | { |
688 | ssh_packet_set_data(p: &r->packet, ptr, len); |
689 | } |
690 | |
691 | #endif /* _LINUX_SURFACE_AGGREGATOR_SERIAL_HUB_H */ |
692 | |