Lines Matching +full:e +full:- +full:book
1 .. SPDX-License-Identifier: GPL-2.0+
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
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).
77 its own CRC (over all payload bytes). If the payload is not present (i.e.
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.
98 CRC) and, if specified in the frame (i.e. ``LEN > 0``), payload 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
147 error, e.g. an invalid CRC, the receiving party responds with a message
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: -------------------------------------------------------------------
188 sending party. These exchanges are symmetric, i.e. switching ``rx`` and
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
203 from the frame payload length given in the corresponding frame, i.e. it is
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.
244 detection mechanism (e.g. CRCs), this is solely done on the frame level.
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
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
271 separated, e.g. by an event being sent after the request but before the
282 enable-event-source request). The EC then uses the specified request ID for
293 and target IDs swapped when compared to the original request (i.e. the request
312 (although via a python and thus a user-space program), it seems that the EC
321 pending requests, no dropped commands (i.e. command being dropped but frame
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.
334 the EC is sent again, e.g. due to the host not receiving an |ACK|, the EC
339 been received, i.e. twice in this example. Sending ``SEQ=0``, ``SEQ=1`` and
343 In conclusion, this suggests a limit of at most one pending un-ACKed frame