driver-api/surface_aggregator/ssh.rst

1 .. SPDX-License-Identifier: GPL-2.0+
22 Surface Serial Hub Protocol
25 The Surface Serial Hub (SSH) is the central communication interface for the
26 embedded Surface Aggregator Module controller (SAM or EC), found on newer
27 Surface generations. We will refer to this protocol and interface as
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
32 significant functionality is provided via SAM, including access to battery
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
35 through SAM, on the Surface Laptop 3 and Surface Book 3 this also includes
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
148 containing an |NAK|-type frame. As the sequence ID of the previous data
151 zero. After receival of an |NAK| frame, the sending party should re-send all
152 outstanding (non-ACKed) 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
258 between different sub-devices. For example ``TC=3`` ``CID=1`` is 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
282 enable-event-source request). The EC then uses the specified request ID for
312 (although via a python and thus a user-space program), it seems that the EC
323 possibly also commands) should be re-sent by the host if a certain timeout
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
331 depend on the assumption that there is only one non-acknowledged data frame.
343 In conclusion, this suggests a limit of at most one pending un-ACKed frame