driver-api/surface_aggregator/ssh.rst

1 .. SPDX-License-Identifier: GPL-2.0+
10 .. |ACK| replace:: ``ACK``  substdef
25 The Surface Serial Hub (SSH) is the central communication interface for the
28 SAM-over-SSH, as opposed to SAM-over-HID for the older generations.
30 On Surface devices with SAM-over-SSH, SAM is connected to the host via UART
33 and power information and events, thermal read-outs and events, and many
34 more. For Surface Laptops, keyboard input is handled via HID directed
38 Note that the standard disclaimer for this subsystem also applies to this
39 document: All of this has been reverse-engineered and may thus be erroneous
42 All CRCs used in the following are two-byte ``crc_itu_t(0xffff, ...)``.
43 All multi-byte values are little-endian, there is no implicit padding between
54 .. flat-table:: SSH Frame
56    :header-rows: 1
58    * - Field
59      - Type
60      - Description
62    * - |TYPE|
63      - |u8|
64      - Type identifier of the frame.
66    * - |LEN|
67      - |u16|
68      - Length of the payload associated with the frame.
70    * - |SEQ|
71      - |u8|
72      - Sequence ID (see explanation below).
83 Additionally, the following fixed two-byte sequences are used:
85 .. flat-table:: SSH Byte Sequences
87    :header-rows: 1
89    * - Name
90      - Value
91      - Description
93    * - |SYN|
94      - ``[0xAA, 0x55]``
95      - Synchronization bytes.
107 .. flat-table:: SSH Frame Types
109    :header-rows: 1
111    * - Name
112      - Value
113      - Short Description
115    * - |NAK|
116      - ``0x04``
117      - Sent on error in previously received message.
119    * - |ACK|
120      - ``0x40``
121      - Sent to acknowledge receival of |DATA| frame.
123    * - |DATA_SEQ|
124      - ``0x80``
125      - Sent to transfer data. Sequenced.
127    * - |DATA_NSQ|
128      - ``0x00``
129      - Same as |DATA_SEQ|, but does not need to be ACKed.
131 Both |NAK|- and |ACK|-type frames are used to control flow of messages and
132 thus do not carry a payload. |DATA_SEQ|- and |DATA_NSQ|-type frames on the
140 Each exchange begins with |SYN|, followed by a |DATA_SEQ|- or
141 |DATA_NSQ|-type frame, followed by its CRC, payload, and payload CRC. In
142 case of a |DATA_NSQ|-type frame, the exchange is then finished. In case of a
143 |DATA_SEQ|-type frame, the receiving party has to acknowledge receival of
144 the frame by responding with a message containing an |ACK|-type frame with
146 the |ACK| frame specifies the |DATA| frame to be acknowledged. In case of an
148 containing an |NAK|-type frame. As the sequence ID of the previous data
149 frame, for which an error is indicated via the |NAK| frame, cannot be relied
151 zero. After receival of an |NAK| frame, the sending party should re-send all
152 outstanding (non-ACKed) messages.
155 are managed independently for each party. Identifying the messages
158 used to associate an ``ACK`` with its ``DATA_SEQ``-type frame, but not
159 ``DATA_SEQ``- or ``DATA_NSQ``-type frames with other ``DATA``- type frames.
165     tx: -- SYN FRAME(D) CRC(F) PAYLOAD CRC(P) -----------------------------
166     rx: ------------------------------------- SYN FRAME(A) CRC(F) CRC(P) --
169 indicates a |DATA_SEQ|-type frame, ``FRAME(A)`` an ``ACK``-type frame,
175     tx: -- SYN FRAME(D) CRC(F) PAYLOAD CRC(P) -----------------------------
176     rx: ------------------------------------- SYN FRAME(N) CRC(F) CRC(P) --
178 upon which the sender should re-send the message. ``FRAME(N)`` indicates an
179 |NAK|-type frame. Note that the sequence ID of the |NAK|-type frame is fixed
180 to zero. For |DATA_NSQ|-type frames, both exchanges are the same:
184     tx: -- SYN FRAME(DATA_NSQ) CRC(F) PAYLOAD CRC(P) ----------------------
185     rx: -------------------------------------------------------------------
197 only known payload type of |DATA| frames, with a payload-type value of
200 The command-type payload (:c:type:`struct ssh_command <ssh_command>`)
201 consists of an eight-byte command structure, followed by optional and
204 ``frame.len - sizeof(struct ssh_command)``. The command struct contains the
207 .. flat-table:: SSH Command
209    :header-rows: 1
211    * - Field
212      - Type
213      - Description
215    * - |TYPE|
216      - |u8|
217      - Type of the payload. For commands always ``0x80``.
219    * - |TC|
220      - |u8|
221      - Target category.
223    * - |TID|
224      - |u8|
225      - Target ID for commands/messages.
227    * - |SID|
228      - |u8|
229      - Source ID for commands/messages.
231    * - |IID|
232      - |u8|
233      - Instance ID.
235    * - |RQID|
236      - |u16|
237      - Request ID.
239    * - |CID|
240      - |u8|
241      - Command ID.
246 Command-type payloads are used by the host to send commands and requests to
254 category for the command (e.g. system in general, vs. battery and AC, vs.
258 between different sub-devices. For example ``TC=3`` ``CID=1`` is a
262 whereas zero may be used for instance independent queries, if applicable. A
268 ID on the frames. Note that the sequence ID of the frames for a
269 request-response pair does not match. Only the request ID has to match.
270 Frame-protocol wise these are two separate exchanges, and may even be
273 |TC| + |CID|. It is the responsibility of the issuing party to wait for a
280 event handler. Request IDs for events are chosen by the host and directed to
282 enable-event-source request). The EC then uses the specified request ID for
295 See (:c:type:`enum ssh_request_id <ssh_request_id>`) for possible values of
300 instance ID values to accept a command. A command that is accepted for
301 ``TID=1``, for example, may not be accepted for ``TID=2`` and vice versa. While
302 this may not always hold in reality, you can think of different target/source
310 with up to ``U16_MAX`` pending requests (neglecting request IDs reserved for
312 (although via a python and thus a user-space program), it seems that the EC
315 commands (ACKed frame but no command response) has been observed. For five
323 possibly also commands) should be re-sent by the host if a certain timeout
324 is exceeded. This is done by the EC for frames with a timeout of one second,
325 up to two re-tries (i.e. three transmissions in total). The limit of
326 re-tries also applies to received NAKs, and, in a worst case scenario, can
329 While this also seems to work fine for pending data frames as long as no
331 depend on the assumption that there is only one non-acknowledged data frame.
334 the EC is sent again, e.g. due to the host not receiving an |ACK|, the EC
343 In conclusion, this suggests a limit of at most one pending un-ACKed frame