Commit | Line | Data |
---|---|---|
c167b9c7 ML |
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 | * | |
b2763358 | 9 | * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com> |
c167b9c7 ML |
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 | */ | |
191 | static inline u16 ssh_crc(const u8 *buf, size_t len) | |
192 | { | |
193 | return crc_ccitt_false(0xffff, buf, len); | |
194 | } | |
195 | ||
196 | /* | |
197 | * SSH_NUM_EVENTS - The number of reserved event IDs. | |
198 | * | |
199 | * The number of reserved event IDs, used for registering an SSH event | |
200 | * handler. Valid event IDs are numbers below or equal to this value, with | |
201 | * exception of zero, which is not an event ID. Thus, this is also the | |
202 | * absolute maximum number of event handlers that can be registered. | |
203 | */ | |
204 | #define SSH_NUM_EVENTS 34 | |
205 | ||
206 | /* | |
207 | * SSH_NUM_TARGETS - The number of communication targets used in the protocol. | |
208 | */ | |
209 | #define SSH_NUM_TARGETS 2 | |
210 | ||
211 | /** | |
212 | * ssh_rqid_next_valid() - Return the next valid request ID. | |
213 | * @rqid: The current request ID. | |
214 | * | |
215 | * Return: Returns the next valid request ID, following the current request ID | |
216 | * provided to this function. This function skips any request IDs reserved for | |
217 | * events. | |
218 | */ | |
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 | */ | |
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 | */ | |
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 | */ | |
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 | */ | |
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 | */ | |
264 | static inline bool ssh_tid_is_valid(u8 tid) | |
265 | { | |
266 | return ssh_tid_to_index(tid) < SSH_NUM_TARGETS; | |
267 | } | |
268 | ||
269 | /** | |
270 | * struct ssam_span - Reference to a buffer region. | |
271 | * @ptr: Pointer to the buffer region. | |
272 | * @len: Length of the buffer region. | |
273 | * | |
274 | * A reference to a (non-owned) buffer segment, consisting of pointer and | |
275 | * length. Use of this struct indicates non-owned data, i.e. data of which the | |
276 | * life-time is managed (i.e. it is allocated/freed) via another pointer. | |
277 | */ | |
278 | struct ssam_span { | |
279 | u8 *ptr; | |
280 | size_t len; | |
281 | }; | |
282 | ||
283 | /* | |
284 | * Known SSH/EC target categories. | |
285 | * | |
286 | * List of currently known target category values; "Known" as in we know they | |
287 | * exist and are valid on at least some device/model. Detailed functionality | |
288 | * or the full category name is only known for some of these categories and | |
289 | * is detailed in the respective comment below. | |
290 | * | |
291 | * These values and abbreviations have been extracted from strings inside the | |
292 | * Windows driver. | |
293 | */ | |
294 | enum ssam_ssh_tc { | |
295 | /* Category 0x00 is invalid for EC use. */ | |
296 | SSAM_SSH_TC_SAM = 0x01, /* Generic system functionality, real-time clock. */ | |
297 | SSAM_SSH_TC_BAT = 0x02, /* Battery/power subsystem. */ | |
298 | SSAM_SSH_TC_TMP = 0x03, /* Thermal subsystem. */ | |
299 | SSAM_SSH_TC_PMC = 0x04, | |
300 | SSAM_SSH_TC_FAN = 0x05, | |
301 | SSAM_SSH_TC_PoM = 0x06, | |
302 | SSAM_SSH_TC_DBG = 0x07, | |
303 | SSAM_SSH_TC_KBD = 0x08, /* Legacy keyboard (Laptop 1/2). */ | |
304 | SSAM_SSH_TC_FWU = 0x09, | |
305 | SSAM_SSH_TC_UNI = 0x0a, | |
306 | SSAM_SSH_TC_LPC = 0x0b, | |
307 | SSAM_SSH_TC_TCL = 0x0c, | |
308 | SSAM_SSH_TC_SFL = 0x0d, | |
309 | SSAM_SSH_TC_KIP = 0x0e, | |
310 | SSAM_SSH_TC_EXT = 0x0f, | |
311 | SSAM_SSH_TC_BLD = 0x10, | |
312 | SSAM_SSH_TC_BAS = 0x11, /* Detachment system (Surface Book 2/3). */ | |
313 | SSAM_SSH_TC_SEN = 0x12, | |
314 | SSAM_SSH_TC_SRQ = 0x13, | |
315 | SSAM_SSH_TC_MCU = 0x14, | |
316 | SSAM_SSH_TC_HID = 0x15, /* Generic HID input subsystem. */ | |
317 | SSAM_SSH_TC_TCH = 0x16, | |
318 | SSAM_SSH_TC_BKL = 0x17, | |
319 | SSAM_SSH_TC_TAM = 0x18, | |
320 | SSAM_SSH_TC_ACC = 0x19, | |
321 | SSAM_SSH_TC_UFI = 0x1a, | |
322 | SSAM_SSH_TC_USC = 0x1b, | |
323 | SSAM_SSH_TC_PEN = 0x1c, | |
324 | SSAM_SSH_TC_VID = 0x1d, | |
325 | SSAM_SSH_TC_AUD = 0x1e, | |
326 | SSAM_SSH_TC_SMC = 0x1f, | |
327 | SSAM_SSH_TC_KPD = 0x20, | |
328 | SSAM_SSH_TC_REG = 0x21, /* Extended event registry. */ | |
329 | }; | |
330 | ||
331 | ||
332 | /* -- Packet transport layer (ptl). ----------------------------------------- */ | |
333 | ||
334 | /** | |
335 | * enum ssh_packet_base_priority - Base priorities for &struct ssh_packet. | |
336 | * @SSH_PACKET_PRIORITY_FLUSH: Base priority for flush packets. | |
337 | * @SSH_PACKET_PRIORITY_DATA: Base priority for normal data packets. | |
338 | * @SSH_PACKET_PRIORITY_NAK: Base priority for NAK packets. | |
339 | * @SSH_PACKET_PRIORITY_ACK: Base priority for ACK packets. | |
340 | */ | |
341 | enum ssh_packet_base_priority { | |
342 | SSH_PACKET_PRIORITY_FLUSH = 0, /* same as DATA to sequence flush */ | |
343 | SSH_PACKET_PRIORITY_DATA = 0, | |
344 | SSH_PACKET_PRIORITY_NAK = 1, | |
345 | SSH_PACKET_PRIORITY_ACK = 2, | |
346 | }; | |
347 | ||
348 | /* | |
349 | * Same as SSH_PACKET_PRIORITY() below, only with actual values. | |
350 | */ | |
351 | #define __SSH_PACKET_PRIORITY(base, try) \ | |
352 | (((base) << 4) | ((try) & 0x0f)) | |
353 | ||
354 | /** | |
355 | * SSH_PACKET_PRIORITY() - Compute packet priority from base priority and | |
356 | * number of tries. | |
357 | * @base: The base priority as suffix of &enum ssh_packet_base_priority, e.g. | |
358 | * ``FLUSH``, ``DATA``, ``ACK``, or ``NAK``. | |
359 | * @try: The number of tries (must be less than 16). | |
360 | * | |
361 | * Compute the combined packet priority. The combined priority is dominated by | |
362 | * the base priority, whereas the number of (re-)tries decides the precedence | |
363 | * of packets with the same base priority, giving higher priority to packets | |
364 | * that already have more tries. | |
365 | * | |
366 | * Return: Returns the computed priority as value fitting inside a &u8. A | |
367 | * higher number means a higher priority. | |
368 | */ | |
369 | #define SSH_PACKET_PRIORITY(base, try) \ | |
370 | __SSH_PACKET_PRIORITY(SSH_PACKET_PRIORITY_##base, (try)) | |
371 | ||
372 | /** | |
373 | * ssh_packet_priority_get_try() - Get number of tries from packet priority. | |
374 | * @priority: The packet priority. | |
375 | * | |
376 | * Return: Returns the number of tries encoded in the specified packet | |
377 | * priority. | |
378 | */ | |
379 | static inline u8 ssh_packet_priority_get_try(u8 priority) | |
380 | { | |
381 | return priority & 0x0f; | |
382 | } | |
383 | ||
384 | /** | |
385 | * ssh_packet_priority_get_base - Get base priority from packet priority. | |
386 | * @priority: The packet priority. | |
387 | * | |
388 | * Return: Returns the base priority encoded in the given packet priority. | |
389 | */ | |
390 | static inline u8 ssh_packet_priority_get_base(u8 priority) | |
391 | { | |
392 | return (priority & 0xf0) >> 4; | |
393 | } | |
394 | ||
395 | enum ssh_packet_flags { | |
396 | /* state flags */ | |
397 | SSH_PACKET_SF_LOCKED_BIT, | |
398 | SSH_PACKET_SF_QUEUED_BIT, | |
399 | SSH_PACKET_SF_PENDING_BIT, | |
400 | SSH_PACKET_SF_TRANSMITTING_BIT, | |
401 | SSH_PACKET_SF_TRANSMITTED_BIT, | |
402 | SSH_PACKET_SF_ACKED_BIT, | |
403 | SSH_PACKET_SF_CANCELED_BIT, | |
404 | SSH_PACKET_SF_COMPLETED_BIT, | |
405 | ||
406 | /* type flags */ | |
407 | SSH_PACKET_TY_FLUSH_BIT, | |
408 | SSH_PACKET_TY_SEQUENCED_BIT, | |
409 | SSH_PACKET_TY_BLOCKING_BIT, | |
410 | ||
411 | /* mask for state flags */ | |
412 | SSH_PACKET_FLAGS_SF_MASK = | |
413 | BIT(SSH_PACKET_SF_LOCKED_BIT) | |
414 | | BIT(SSH_PACKET_SF_QUEUED_BIT) | |
415 | | BIT(SSH_PACKET_SF_PENDING_BIT) | |
416 | | BIT(SSH_PACKET_SF_TRANSMITTING_BIT) | |
417 | | BIT(SSH_PACKET_SF_TRANSMITTED_BIT) | |
418 | | BIT(SSH_PACKET_SF_ACKED_BIT) | |
419 | | BIT(SSH_PACKET_SF_CANCELED_BIT) | |
420 | | BIT(SSH_PACKET_SF_COMPLETED_BIT), | |
421 | ||
422 | /* mask for type flags */ | |
423 | SSH_PACKET_FLAGS_TY_MASK = | |
424 | BIT(SSH_PACKET_TY_FLUSH_BIT) | |
425 | | BIT(SSH_PACKET_TY_SEQUENCED_BIT) | |
426 | | BIT(SSH_PACKET_TY_BLOCKING_BIT), | |
427 | }; | |
428 | ||
429 | struct ssh_ptl; | |
430 | struct ssh_packet; | |
431 | ||
432 | /** | |
433 | * struct ssh_packet_ops - Callback operations for a SSH packet. | |
434 | * @release: Function called when the packet reference count reaches zero. | |
435 | * This callback must be relied upon to ensure that the packet has | |
436 | * left the transport system(s). | |
437 | * @complete: Function called when the packet is completed, either with | |
438 | * success or failure. In case of failure, the reason for the | |
439 | * failure is indicated by the value of the provided status code | |
440 | * argument. This value will be zero in case of success. Note that | |
441 | * a call to this callback does not guarantee that the packet is | |
442 | * not in use by the transport system any more. | |
443 | */ | |
444 | struct ssh_packet_ops { | |
445 | void (*release)(struct ssh_packet *p); | |
446 | void (*complete)(struct ssh_packet *p, int status); | |
447 | }; | |
448 | ||
449 | /** | |
450 | * struct ssh_packet - SSH transport packet. | |
451 | * @ptl: Pointer to the packet transport layer. May be %NULL if the packet | |
452 | * (or enclosing request) has not been submitted yet. | |
453 | * @refcnt: Reference count of the packet. | |
454 | * @priority: Priority of the packet. Must be computed via | |
455 | * SSH_PACKET_PRIORITY(). Must only be accessed while holding the | |
456 | * queue lock after first submission. | |
457 | * @data: Raw message data. | |
458 | * @data.len: Length of the raw message data. | |
459 | * @data.ptr: Pointer to the raw message data buffer. | |
460 | * @state: State and type flags describing current packet state (dynamic) | |
461 | * and type (static). See &enum ssh_packet_flags for possible | |
462 | * options. | |
463 | * @timestamp: Timestamp specifying when the latest transmission of a | |
464 | * currently pending packet has been started. May be %KTIME_MAX | |
465 | * before or in-between transmission attempts. Used for the packet | |
466 | * timeout implementation. Must only be accessed while holding the | |
467 | * pending lock after first submission. | |
468 | * @queue_node: The list node for the packet queue. | |
469 | * @pending_node: The list node for the set of pending packets. | |
470 | * @ops: Packet operations. | |
471 | */ | |
472 | struct ssh_packet { | |
473 | struct ssh_ptl *ptl; | |
474 | struct kref refcnt; | |
475 | ||
476 | u8 priority; | |
477 | ||
478 | struct { | |
479 | size_t len; | |
480 | u8 *ptr; | |
481 | } data; | |
482 | ||
483 | unsigned long state; | |
484 | ktime_t timestamp; | |
485 | ||
486 | struct list_head queue_node; | |
487 | struct list_head pending_node; | |
488 | ||
489 | const struct ssh_packet_ops *ops; | |
490 | }; | |
491 | ||
492 | struct ssh_packet *ssh_packet_get(struct ssh_packet *p); | |
493 | void ssh_packet_put(struct ssh_packet *p); | |
494 | ||
495 | /** | |
496 | * ssh_packet_set_data() - Set raw message data of packet. | |
497 | * @p: The packet for which the message data should be set. | |
498 | * @ptr: Pointer to the memory holding the message data. | |
499 | * @len: Length of the message data. | |
500 | * | |
501 | * Sets the raw message data buffer of the packet to the provided memory. The | |
502 | * memory is not copied. Instead, the caller is responsible for management | |
503 | * (i.e. allocation and deallocation) of the memory. The caller must ensure | |
504 | * that the provided memory is valid and contains a valid SSH message, | |
505 | * starting from the time of submission of the packet until the ``release`` | |
506 | * callback has been called. During this time, the memory may not be altered | |
507 | * in any way. | |
508 | */ | |
509 | static inline void ssh_packet_set_data(struct ssh_packet *p, u8 *ptr, size_t len) | |
510 | { | |
511 | p->data.ptr = ptr; | |
512 | p->data.len = len; | |
513 | } | |
514 | ||
515 | ||
516 | /* -- Request transport layer (rtl). ---------------------------------------- */ | |
517 | ||
518 | enum ssh_request_flags { | |
519 | /* state flags */ | |
520 | SSH_REQUEST_SF_LOCKED_BIT, | |
521 | SSH_REQUEST_SF_QUEUED_BIT, | |
522 | SSH_REQUEST_SF_PENDING_BIT, | |
523 | SSH_REQUEST_SF_TRANSMITTING_BIT, | |
524 | SSH_REQUEST_SF_TRANSMITTED_BIT, | |
525 | SSH_REQUEST_SF_RSPRCVD_BIT, | |
526 | SSH_REQUEST_SF_CANCELED_BIT, | |
527 | SSH_REQUEST_SF_COMPLETED_BIT, | |
528 | ||
529 | /* type flags */ | |
530 | SSH_REQUEST_TY_FLUSH_BIT, | |
531 | SSH_REQUEST_TY_HAS_RESPONSE_BIT, | |
532 | ||
533 | /* mask for state flags */ | |
534 | SSH_REQUEST_FLAGS_SF_MASK = | |
535 | BIT(SSH_REQUEST_SF_LOCKED_BIT) | |
536 | | BIT(SSH_REQUEST_SF_QUEUED_BIT) | |
537 | | BIT(SSH_REQUEST_SF_PENDING_BIT) | |
538 | | BIT(SSH_REQUEST_SF_TRANSMITTING_BIT) | |
539 | | BIT(SSH_REQUEST_SF_TRANSMITTED_BIT) | |
540 | | BIT(SSH_REQUEST_SF_RSPRCVD_BIT) | |
541 | | BIT(SSH_REQUEST_SF_CANCELED_BIT) | |
542 | | BIT(SSH_REQUEST_SF_COMPLETED_BIT), | |
543 | ||
544 | /* mask for type flags */ | |
545 | SSH_REQUEST_FLAGS_TY_MASK = | |
546 | BIT(SSH_REQUEST_TY_FLUSH_BIT) | |
547 | | BIT(SSH_REQUEST_TY_HAS_RESPONSE_BIT), | |
548 | }; | |
549 | ||
550 | struct ssh_rtl; | |
551 | struct ssh_request; | |
552 | ||
553 | /** | |
554 | * struct ssh_request_ops - Callback operations for a SSH request. | |
555 | * @release: Function called when the request's reference count reaches zero. | |
556 | * This callback must be relied upon to ensure that the request has | |
557 | * left the transport systems (both, packet an request systems). | |
558 | * @complete: Function called when the request is completed, either with | |
559 | * success or failure. The command data for the request response | |
560 | * is provided via the &struct ssh_command parameter (``cmd``), | |
561 | * the command payload of the request response via the &struct | |
562 | * ssh_span parameter (``data``). | |
563 | * | |
564 | * If the request does not have any response or has not been | |
565 | * completed with success, both ``cmd`` and ``data`` parameters will | |
566 | * be NULL. If the request response does not have any command | |
567 | * payload, the ``data`` span will be an empty (zero-length) span. | |
568 | * | |
569 | * In case of failure, the reason for the failure is indicated by | |
570 | * the value of the provided status code argument (``status``). This | |
571 | * value will be zero in case of success and a regular errno | |
572 | * otherwise. | |
573 | * | |
574 | * Note that a call to this callback does not guarantee that the | |
575 | * request is not in use by the transport systems any more. | |
576 | */ | |
577 | struct ssh_request_ops { | |
578 | void (*release)(struct ssh_request *rqst); | |
579 | void (*complete)(struct ssh_request *rqst, | |
580 | const struct ssh_command *cmd, | |
581 | const struct ssam_span *data, int status); | |
582 | }; | |
583 | ||
584 | /** | |
585 | * struct ssh_request - SSH transport request. | |
586 | * @packet: The underlying SSH transport packet. | |
587 | * @node: List node for the request queue and pending set. | |
588 | * @state: State and type flags describing current request state (dynamic) | |
589 | * and type (static). See &enum ssh_request_flags for possible | |
590 | * options. | |
591 | * @timestamp: Timestamp specifying when we start waiting on the response of | |
592 | * the request. This is set once the underlying packet has been | |
593 | * completed and may be %KTIME_MAX before that, or when the request | |
594 | * does not expect a response. Used for the request timeout | |
595 | * implementation. | |
596 | * @ops: Request Operations. | |
597 | */ | |
598 | struct ssh_request { | |
599 | struct ssh_packet packet; | |
600 | struct list_head node; | |
601 | ||
602 | unsigned long state; | |
603 | ktime_t timestamp; | |
604 | ||
605 | const struct ssh_request_ops *ops; | |
606 | }; | |
607 | ||
608 | /** | |
609 | * to_ssh_request() - Cast a SSH packet to its enclosing SSH request. | |
610 | * @p: The packet to cast. | |
611 | * | |
612 | * Casts the given &struct ssh_packet to its enclosing &struct ssh_request. | |
613 | * The caller is responsible for making sure that the packet is actually | |
614 | * wrapped in a &struct ssh_request. | |
615 | * | |
616 | * Return: Returns the &struct ssh_request wrapping the provided packet. | |
617 | */ | |
618 | static inline struct ssh_request *to_ssh_request(struct ssh_packet *p) | |
619 | { | |
620 | return container_of(p, struct ssh_request, packet); | |
621 | } | |
622 | ||
623 | /** | |
624 | * ssh_request_get() - Increment reference count of request. | |
625 | * @r: The request to increment the reference count of. | |
626 | * | |
627 | * Increments the reference count of the given request by incrementing the | |
628 | * reference count of the underlying &struct ssh_packet, enclosed in it. | |
629 | * | |
630 | * See also ssh_request_put(), ssh_packet_get(). | |
631 | * | |
632 | * Return: Returns the request provided as input. | |
633 | */ | |
634 | static inline struct ssh_request *ssh_request_get(struct ssh_request *r) | |
635 | { | |
636 | return r ? to_ssh_request(ssh_packet_get(&r->packet)) : NULL; | |
637 | } | |
638 | ||
639 | /** | |
640 | * ssh_request_put() - Decrement reference count of request. | |
641 | * @r: The request to decrement the reference count of. | |
642 | * | |
643 | * Decrements the reference count of the given request by decrementing the | |
644 | * reference count of the underlying &struct ssh_packet, enclosed in it. If | |
645 | * the reference count reaches zero, the ``release`` callback specified in the | |
646 | * request's &struct ssh_request_ops, i.e. ``r->ops->release``, will be | |
647 | * called. | |
648 | * | |
649 | * See also ssh_request_get(), ssh_packet_put(). | |
650 | */ | |
651 | static inline void ssh_request_put(struct ssh_request *r) | |
652 | { | |
653 | if (r) | |
654 | ssh_packet_put(&r->packet); | |
655 | } | |
656 | ||
657 | /** | |
658 | * ssh_request_set_data() - Set raw message data of request. | |
659 | * @r: The request for which the message data should be set. | |
660 | * @ptr: Pointer to the memory holding the message data. | |
661 | * @len: Length of the message data. | |
662 | * | |
663 | * Sets the raw message data buffer of the underlying packet to the specified | |
664 | * buffer. Does not copy the actual message data, just sets the buffer pointer | |
665 | * and length. Refer to ssh_packet_set_data() for more details. | |
666 | */ | |
667 | static inline void ssh_request_set_data(struct ssh_request *r, u8 *ptr, size_t len) | |
668 | { | |
669 | ssh_packet_set_data(&r->packet, ptr, len); | |
670 | } | |
671 | ||
672 | #endif /* _LINUX_SURFACE_AGGREGATOR_SERIAL_HUB_H */ |