sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget5/translations/zh_CN/driver-api/surface_aggregator/sshmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget5/translations/zh_TW/driver-api/surface_aggregator/sshmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget5/translations/it_IT/driver-api/surface_aggregator/sshmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget5/translations/ja_JP/driver-api/surface_aggregator/sshmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget5/translations/ko_KR/driver-api/surface_aggregator/sshmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget5/translations/pt_BR/driver-api/surface_aggregator/sshmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget5/translations/sp_SP/driver-api/surface_aggregator/sshmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h!SPDX-License-Identifier: GPL-2.0+h]h!SPDX-License-Identifier: GPL-2.0+}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhO/var/lib/git/docbuild/linux/Documentation/driver-api/surface_aggregator/ssh.rsthKubhsubstitution_definition)}(h#.. |u8| replace:: :c:type:`u8 `h]h)}(h:c:type:`u8 `h]hliteral)}(hhh]hu8}(hhhhhNhNubah}(h]h ](xrefcc-typeeh"]h$]h&]uh1hhhubah}(h]h ]h"]h$]h&]refdoc!driver-api/surface_aggregator/ssh refdomainhߌreftypetype refexplicitrefwarn reftargetu8uh1hhhhKhhubah}(h]h ]h"]u8ah$]h&]uh1hhhhKhhhhubh)}(h&.. |u16| replace:: :c:type:`u16 `h]h)}(h:c:type:`u16 `h]h)}(hjh]hu16}(hjhhhNhNubah}(h]h ](hhߌc-typeeh"]h$]h&]uh1hhhubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypetype refexplicitrefwarnhu16uh1hhhhKhhubah}(h]h ]h"]u16ah$]h&]uh1hhhhKhhhhubh)}(h.. |TYPE| replace:: ``TYPE``h]h)}(h``TYPE``h]hTYPE}hj(sbah}(h]h ]h"]h$]h&]uh1hhj$ubah}(h]h ]h"]TYPEah$]h&]uh1hhhhKhhhhubh)}(h.. |LEN| replace:: ``LEN``h]h)}(h``LEN``h]hLEN}hjAsbah}(h]h ]h"]h$]h&]uh1hhj=ubah}(h]h ]h"]LENah$]h&]uh1hhhhKhhhhubh)}(h.. |SEQ| replace:: ``SEQ``h]h)}(h``SEQ``h]hSEQ}hjZsbah}(h]h ]h"]h$]h&]uh1hhjVubah}(h]h ]h"]SEQah$]h&]uh1hhhhKhhhhubh)}(h.. |SYN| replace:: ``SYN``h]h)}(h``SYN``h]hSYN}hjssbah}(h]h ]h"]h$]h&]uh1hhjoubah}(h]h ]h"]SYNah$]h&]uh1hhhhKhhhhubh)}(h.. |NAK| replace:: ``NAK``h]h)}(h``NAK``h]hNAK}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]NAKah$]h&]uh1hhhhK hhhhubh)}(h.. |ACK| replace:: ``ACK``h]h)}(h``ACK``h]hACK}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]ACKah$]h&]uh1hhhhK hhhhubh)}(h.. |DATA| replace:: ``DATA``h]h)}(h``DATA``h]hDATA}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]DATAah$]h&]uh1hhhhK hhhhubh)}(h$.. |DATA_SEQ| replace:: ``DATA_SEQ``h]h)}(h ``DATA_SEQ``h]hDATA_SEQ}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]DATA_SEQah$]h&]uh1hhhhK hhhhubh)}(h$.. |DATA_NSQ| replace:: ``DATA_NSQ``h]h)}(h ``DATA_NSQ``h]hDATA_NSQ}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]DATA_NSQah$]h&]uh1hhhhK hhhhubh)}(h.. |TC| replace:: ``TC``h]h)}(h``TC``h]hTC}hj sbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]TCah$]h&]uh1hhhhKhhhhubh)}(h.. |TID| replace:: ``TID``h]h)}(h``TID``h]hTID}hj"sbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]TIDah$]h&]uh1hhhhKhhhhubh)}(h.. |SID| replace:: ``SID``h]h)}(h``SID``h]hSID}hj;sbah}(h]h ]h"]h$]h&]uh1hhj7ubah}(h]h ]h"]SIDah$]h&]uh1hhhhKhhhhubh)}(h.. |IID| replace:: ``IID``h]h)}(h``IID``h]hIID}hjTsbah}(h]h ]h"]h$]h&]uh1hhjPubah}(h]h ]h"]IIDah$]h&]uh1hhhhKhhhhubh)}(h.. |RQID| replace:: ``RQID``h]h)}(h``RQID``h]hRQID}hjmsbah}(h]h ]h"]h$]h&]uh1hhjiubah}(h]h ]h"]RQIDah$]h&]uh1hhhhKhhhhubh)}(h.. |CID| replace:: ``CID`` h]h)}(h``CID``h]hCID}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]CIDah$]h&]uh1hhhhKhhhhubhsection)}(hhh](htitle)}(hSurface Serial Hub Protocolh]hSurface Serial Hub Protocol}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhhhKubh paragraph)}(hXThe Surface Serial Hub (SSH) is the central communication interface for the embedded Surface Aggregator Module controller (SAM or EC), found on newer Surface generations. We will refer to this protocol and interface as SAM-over-SSH, as opposed to SAM-over-HID for the older generations.h]hXThe Surface Serial Hub (SSH) is the central communication interface for the embedded Surface Aggregator Module controller (SAM or EC), found on newer Surface generations. We will refer to this protocol and interface as SAM-over-SSH, as opposed to SAM-over-HID for the older generations.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hXOn Surface devices with SAM-over-SSH, SAM is connected to the host via UART and defined in ACPI as device with ID ``MSHW0084``. On these devices, significant functionality is provided via SAM, including access to battery and power information and events, thermal read-outs and events, and many more. For Surface Laptops, keyboard input is handled via HID directed through SAM, on the Surface Laptop 3 and Surface Book 3 this also includes touchpad input.h](hrOn Surface devices with SAM-over-SSH, SAM is connected to the host via UART and defined in ACPI as device with ID }(hjhhhNhNubh)}(h ``MSHW0084``h]hMSHW0084}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhXH. On these devices, significant functionality is provided via SAM, including access to battery and power information and events, thermal read-outs and events, and many more. For Surface Laptops, keyboard input is handled via HID directed through SAM, on the Surface Laptop 3 and Surface Book 3 this also includes touchpad input.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hNote that the standard disclaimer for this subsystem also applies to this document: All of this has been reverse-engineered and may thus be erroneous and/or incomplete.h]hNote that the standard disclaimer for this subsystem also applies to this document: All of this has been reverse-engineered and may thus be erroneous and/or incomplete.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK&hjhhubj)}(hAll CRCs used in the following are two-byte ``crc_itu_t(0xffff, ...)``. All multi-byte values are little-endian, there is no implicit padding between values.h](h,All CRCs used in the following are two-byte }(hjhhhNhNubh)}(h``crc_itu_t(0xffff, ...)``h]hcrc_itu_t(0xffff, ...)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhW. All multi-byte values are little-endian, there is no implicit padding between values.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhK*hjhhubj)}(hhh](j)}(h SSH Packet Protocol: Definitionsh]h SSH Packet Protocol: Definitions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhhhK0ubj)}(hThe fundamental communication unit of the SSH protocol is a frame (:c:type:`struct ssh_frame `). A frame consists of the following fields, packed together and in order:h](hCThe fundamental communication unit of the SSH protocol is a frame (}(hjhhhNhNubh)}(h&:c:type:`struct ssh_frame `h]h)}(hj)h]hstruct ssh_frame}(hj+hhhNhNubah}(h]h ](hhߌc-typeeh"]h$]h&]uh1hhj'ubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypetype refexplicitrefwarnh ssh_frameuh1hhhhK2hjubhJ). A frame consists of the following fields, packed together and in order:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhK2hjhhubhtable)}(hhh](j)}(h SSH Frameh]h SSH Frame}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK6hjRubhtgroup)}(hhh](hcolspec)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhjeubji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhjeubji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhjeubhthead)}(hhh]hrow)}(hhh](hentry)}(hhh]j)}(hFieldh]hField}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK:hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hTypeh]hType}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK;hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h Descriptionh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h|u8|h]h)}(hhh]h)}(hhh]hu8}(hjhhhNhNubah}(h]h ](hhheh"]h$]h&]uh1hhNhNhjubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypeh refexplicitrefwarn reftargethuh1hhhhKhjhhubah}(h]h ]h"]h$]h&]uh1jhhhK?hj ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hType identifier of the frame.h]hType identifier of the frame.}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK@hj<ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(h|LEN|h]h)}(hjCh]hLEN}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj_hhubah}(h]h ]h"]h$]h&]uh1jhhhKBhj\ubah}(h]h ]h"]h$]h&]uh1jhjYubj)}(hhh]j)}(h|u16|h]h)}(hjh]h)}(hjh]hu16}(hjhhhNhNubah}(h]h ](hhj eh"]h$]h&]uh1hhNhNhjubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypej refexplicitrefwarn reftargetjuh1hhhhKhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKChj|ubah}(h]h ]h"]h$]h&]uh1jhjYubj)}(hhh]j)}(h0Length of the payload associated with the frame.h]h0Length of the payload associated with the frame.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKDhjubah}(h]h ]h"]h$]h&]uh1jhjYubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(h|SEQ|h]h)}(hj\h]hSEQ}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKFhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h|u8|h]h)}(hhh]h)}(hhh]hu8}(hjhhhNhNubah}(h]h ](hhheh"]h$]h&]uh1hhNhNhjubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypeh refexplicitrefwarn reftargethuh1hhhhKhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKGhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h$Sequence ID (see explanation below).h]h$Sequence ID (see explanation below).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKHhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjeubeh}(h]h ]h"]h$]h&]colsKuh1jchjRubeh}(h]id1ah ]h"]h$]h&]uh1jPhjhhhNhNubj)}(hXEach frame structure is followed by a CRC over this structure. The CRC over the frame structure (|TYPE|, |LEN|, and |SEQ| fields) is placed directly after the frame structure and before the payload. The payload is followed by its own CRC (over all payload bytes). If the payload is not present (i.e. the frame has ``LEN=0``), the CRC of the payload is still present and will evaluate to ``0xffff``. The |LEN| field does not include any of the CRCs, it equals the number of bytes between the CRC of the frame and the CRC of the payload.h](haEach frame structure is followed by a CRC over this structure. The CRC over the frame structure (}(hjKhhhNhNubh)}(hj*h]hTYPE}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjKhhubh, }(hjKhhhNhNubh)}(hjCh]hLEN}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjKhhubh, and }(hjKhhhNhNubh)}(hj\h]hSEQ}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjKhhubh fields) is placed directly after the frame structure and before the payload. The payload is followed by its own CRC (over all payload bytes). If the payload is not present (i.e. the frame has }(hjKhhhNhNubh)}(h ``LEN=0``h]hLEN=0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjKubh@), the CRC of the payload is still present and will evaluate to }(hjKhhhNhNubh)}(h ``0xffff``h]h0xffff}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjKubh. The }(hjKhhhNhNubh)}(hjCh]hLEN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjKhhubh field does not include any of the CRCs, it equals the number of bytes between the CRC of the frame and the CRC of the payload.}(hjKhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKJhjhhubj)}(h>Additionally, the following fixed two-byte sequences are used:h]h>Additionally, the following fixed two-byte sequences are used:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKShjhhubjQ)}(hhh](j)}(hSSH Byte Sequencesh]hSSH Byte Sequences}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKUhjubjd)}(hhh](ji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhjubji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhjubji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhjubj)}(hhh]j)}(hhh](j)}(hhh]j)}(hNameh]hName}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKYhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hValueh]hValue}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKZhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h Descriptionh]h Description}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK[hj5ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hhh](j)}(hhh]j)}(h|SYN|h]h)}(hjuh]hSYN}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjahhubah}(h]h ]h"]h$]h&]uh1jhhhK]hj^ubah}(h]h ]h"]h$]h&]uh1jhj[ubj)}(hhh]j)}(h``[0xAA, 0x55]``h]h)}(hjh]h [0xAA, 0x55]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1jhhhK^hj~ubah}(h]h ]h"]h$]h&]uh1jhj[ubj)}(hhh]j)}(hSynchronization bytes.h]hSynchronization bytes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK_hjubah}(h]h ]h"]h$]h&]uh1jhj[ubeh}(h]h ]h"]h$]h&]uh1jhjXubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jchjubeh}(h]id2ah ]h"]h$]h&]uh1jPhjhhhNhNubj)}(hXA message consists of |SYN|, followed by the frame (|TYPE|, |LEN|, |SEQ| and CRC) and, if specified in the frame (i.e. ``LEN > 0``), payload bytes, followed finally, regardless if the payload is present, the payload CRC. The messages corresponding to an exchange are, in part, identified by having the same sequence ID (|SEQ|), stored inside the frame (more on this in the next section). The sequence ID is a wrapping counter.h](hA message consists of }(hjhhhNhNubh)}(hjuh]hSYN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubh, followed by the frame (}(hjhhhNhNubh)}(hj*h]hTYPE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubh, }(hjhhhNhNubh)}(hjCh]hLEN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubh, }hjsbh)}(hj\h]hSEQ}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubh/ and CRC) and, if specified in the frame (i.e. }(hjhhhNhNubh)}(h ``LEN > 0``h]hLEN > 0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh), payload bytes, followed finally, regardless if the payload is present, the payload CRC. The messages corresponding to an exchange are, in part, identified by having the same sequence ID (}(hjhhhNhNubh)}(hj\h]hSEQ}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubhe), stored inside the frame (more on this in the next section). The sequence ID is a wrapping counter.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKahjhhubj)}(hVA frame can have the following types (:c:type:`enum ssh_frame_type `):h](h&A frame can have the following types (}(hjDhhhNhNubh)}(h.:c:type:`enum ssh_frame_type `h]h)}(hjNh]henum ssh_frame_type}(hjPhhhNhNubah}(h]h ](hhߌc-typeeh"]h$]h&]uh1hhjLubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypetype refexplicitrefwarnhssh_frame_typeuh1hhhhKhhjDubh):}(hjDhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhhjhhubjQ)}(hhh](j)}(hSSH Frame Typesh]hSSH Frame Types}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKkhjuubjd)}(hhh](ji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhjubji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhjubji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhjubj)}(hhh]j)}(hhh](j)}(hhh]j)}(hNameh]hName}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKohjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hValueh]hValue}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKphjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hShort Descriptionh]hShort Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKqhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh](j)}(hhh]j)}(h|NAK|h]h)}(hjh]hNAK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKshjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h``0x04``h]h)}(hj)h]h0x04}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj'ubah}(h]h ]h"]h$]h&]uh1jhhhKthj$ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h-Sent on error in previously received message.h]h-Sent on error in previously received message.}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKuhjDubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(h|ACK|h]h)}(hjh]hACK}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjghhubah}(h]h ]h"]h$]h&]uh1jhhhKwhjdubah}(h]h ]h"]h$]h&]uh1jhjaubj)}(hhh]j)}(h``0x40``h]h)}(hjh]h0x40}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1jhhhKxhjubah}(h]h ]h"]h$]h&]uh1jhjaubj)}(hhh]j)}(h-Sent to acknowledge receival of |DATA| frame.h](h Sent to acknowledge receival of }(hjhhhNhNubh)}(hjh]hDATA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubh frame.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKyhjubah}(h]h ]h"]h$]h&]uh1jhjaubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(h |DATA_SEQ|h]h)}(hjh]hDATA_SEQ}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubah}(h]h ]h"]h$]h&]uh1jhhhK{hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h``0x80``h]h)}(hjh]h0x80}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1jhhhK|hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h!Sent to transfer data. Sequenced.h]h!Sent to transfer data. Sequenced.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK}hj ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(h |DATA_NSQ|h]h)}(hjh]hDATA_NSQ}(hj< hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj8 hhubah}(h]h ]h"]h$]h&]uh1jhhhKhj5 ubah}(h]h ]h"]h$]h&]uh1jhj2 ubj)}(hhh]j)}(h``0x00``h]h)}(hjZ h]h0x00}(hj\ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjX ubah}(h]h ]h"]h$]h&]uh1jhhhKhjU ubah}(h]h ]h"]h$]h&]uh1jhj2 ubj)}(hhh]j)}(h2Same as |DATA_SEQ|, but does not need to be ACKed.h](hSame as }(hjx hhhNhNubh)}(hjh]hDATA_SEQ}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjx hhubh , but does not need to be ACKed.}(hjx hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhju ubah}(h]h ]h"]h$]h&]uh1jhj2 ubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jchjuubeh}(h]id3ah ]h"]h$]h&]uh1jPhjhhhNhNubj)}(hX&Both |NAK|- and |ACK|-type frames are used to control flow of messages and thus do not carry a payload. |DATA_SEQ|- and |DATA_NSQ|-type frames on the other hand must carry a payload. The flow sequence and interaction of different frame types will be described in more depth in the next section.h](hBoth }(hj hhhNhNubh)}(hjh]hNAK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj hhubh- and }(hj hhhNhNubh)}(hjh]hACK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj hhubhS-type frames are used to control flow of messages and thus do not carry a payload. }(hj hhhNhNubh)}(hjh]hDATA_SEQ}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj hhubh- and }hj sbh)}(hjh]hDATA_NSQ}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj hhubh-type frames on the other hand must carry a payload. The flow sequence and interaction of different frame types will be described in more depth in the next section.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubeh}(h]ssh-packet-protocol-definitionsah ]h"] ssh packet protocol: definitionsah$]h&]uh1jhjhhhhhK0ubj)}(hhh](j)}(h"SSH Packet Protocol: Flow Sequenceh]h"SSH Packet Protocol: Flow Sequence}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj hhhhhKubj)}(hXEach exchange begins with |SYN|, followed by a |DATA_SEQ|- or |DATA_NSQ|-type frame, followed by its CRC, payload, and payload CRC. In case of a |DATA_NSQ|-type frame, the exchange is then finished. In case of a |DATA_SEQ|-type frame, the receiving party has to acknowledge receival of the frame by responding with a message containing an |ACK|-type frame with the same sequence ID of the |DATA| frame. In other words, the sequence ID of the |ACK| frame specifies the |DATA| frame to be acknowledged. In case of an error, e.g. an invalid CRC, the receiving party responds with a message containing an |NAK|-type frame. As the sequence ID of the previous data frame, for which an error is indicated via the |NAK| frame, cannot be relied upon, the sequence ID of the |NAK| frame should not be used and is set to zero. After receival of an |NAK| frame, the sending party should re-send all outstanding (non-ACKed) messages.h](hEach exchange begins with }(hj" hhhNhNubh)}(hjuh]hSYN}(hj* hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubh, followed by a }(hj" hhhNhNubh)}(hjh]hDATA_SEQ}(hj; hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubh- or }(hj" hhhNhNubh)}(hjh]hDATA_NSQ}(hjL hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubhI-type frame, followed by its CRC, payload, and payload CRC. In case of a }(hj" hhhNhNubh)}(hjh]hDATA_NSQ}(hj] hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubh9-type frame, the exchange is then finished. In case of a }(hj" hhhNhNubh)}(hjh]hDATA_SEQ}(hjn hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubhu-type frame, the receiving party has to acknowledge receival of the frame by responding with a message containing an }(hj" hhhNhNubh)}(hjh]hACK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubh--type frame with the same sequence ID of the }(hj" hhhNhNubh)}(hjh]hDATA}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubh/ frame. In other words, the sequence ID of the }(hj" hhhNhNubh)}(hjh]hACK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubh frame specifies the }(hj" hhhNhNubh)}(hjh]hDATA}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubh frame to be acknowledged. In case of an error, e.g. an invalid CRC, the receiving party responds with a message containing an }(hj" hhhNhNubh)}(hjh]hNAK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubhd-type frame. As the sequence ID of the previous data frame, for which an error is indicated via the }(hj" hhhNhNubh)}(hjh]hNAK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubh6 frame, cannot be relied upon, the sequence ID of the }(hj" hhhNhNubh)}(hjh]hNAK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubhC frame should not be used and is set to zero. After receival of an }(hj" hhhNhNubh)}(hjh]hNAK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj" hhubhN frame, the sending party should re-send all outstanding (non-ACKed) messages.}(hj" hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(hXSequence IDs are not synchronized between the two parties, meaning that they are managed independently for each party. Identifying the messages corresponding to a single exchange thus relies on the sequence ID as well as the type of the message, and the context. Specifically, the sequence ID is used to associate an ``ACK`` with its ``DATA_SEQ``-type frame, but not ``DATA_SEQ``- or ``DATA_NSQ``-type frames with other ``DATA``- type frames.h](hX=Sequence IDs are not synchronized between the two parties, meaning that they are managed independently for each party. Identifying the messages corresponding to a single exchange thus relies on the sequence ID as well as the type of the message, and the context. Specifically, the sequence ID is used to associate an }(hj hhhNhNubh)}(h``ACK``h]hACK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh with its }(hj hhhNhNubh)}(h ``DATA_SEQ``h]hDATA_SEQ}(hj' hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh-type frame, but not }(hj hhhNhNubh)}(h ``DATA_SEQ``h]hDATA_SEQ}(hj9 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh- or }(hj hhhNhNubh)}(h ``DATA_NSQ``h]hDATA_NSQ}(hjK hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh-type frames with other }(hj hhhNhNubh)}(h``DATA``h]hDATA}(hj] hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh- type frames.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(h)An example exchange might look like this:h]h)An example exchange might look like this:}(hju hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj hhubh literal_block)}(htx: -- SYN FRAME(D) CRC(F) PAYLOAD CRC(P) ----------------------------- rx: ------------------------------------- SYN FRAME(A) CRC(F) CRC(P) --h]htx: -- SYN FRAME(D) CRC(F) PAYLOAD CRC(P) ----------------------------- rx: ------------------------------------- SYN FRAME(A) CRC(F) CRC(P) --}hj sbah}(h]h ]h"]h$]h&]hhuh1j hhhKhj hhubj)}(hX"where both frames have the same sequence ID (``SEQ``). Here, ``FRAME(D)`` indicates a |DATA_SEQ|-type frame, ``FRAME(A)`` an ``ACK``-type frame, ``CRC(F)`` the CRC over the previous frame, ``CRC(P)`` the CRC over the previous payload. In case of an error, the exchange would look like this:h](h-where both frames have the same sequence ID (}(hj hhhNhNubh)}(h``SEQ``h]hSEQ}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh ). Here, }(hj hhhNhNubh)}(h ``FRAME(D)``h]hFRAME(D)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh indicates a }(hj hhhNhNubh)}(hjh]hDATA_SEQ}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj hhubh -type frame, }(hj hhhNhNubh)}(h ``FRAME(A)``h]hFRAME(A)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh an }(hj hhhNhNubh)}(h``ACK``h]hACK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh -type frame, }(hj hhhNhNubh)}(h ``CRC(F)``h]hCRC(F)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh" the CRC over the previous frame, }(hj hhhNhNubh)}(h ``CRC(P)``h]hCRC(P)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh[ the CRC over the previous payload. In case of an error, the exchange would look like this:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj )}(htx: -- SYN FRAME(D) CRC(F) PAYLOAD CRC(P) ----------------------------- rx: ------------------------------------- SYN FRAME(N) CRC(F) CRC(P) --h]htx: -- SYN FRAME(D) CRC(F) PAYLOAD CRC(P) ----------------------------- rx: ------------------------------------- SYN FRAME(N) CRC(F) CRC(P) --}hj sbah}(h]h ]h"]h$]h&]hhuh1j hhhKhj hhubj)}(hupon which the sender should re-send the message. ``FRAME(N)`` indicates an |NAK|-type frame. Note that the sequence ID of the |NAK|-type frame is fixed to zero. For |DATA_NSQ|-type frames, both exchanges are the same:h](h2upon which the sender should re-send the message. }(hj, hhhNhNubh)}(h ``FRAME(N)``h]hFRAME(N)}(hj4 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj, ubh indicates an }(hj, hhhNhNubh)}(hjh]hNAK}(hjF hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj, hhubh.-type frame. Note that the sequence ID of the }(hj, hhhNhNubh)}(hjh]hNAK}(hjW hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj, hhubh"-type frame is fixed to zero. For }(hj, hhhNhNubh)}(hjh]hDATA_NSQ}(hjh hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj, hhubh*-type frames, both exchanges are the same:}(hj, hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj )}(htx: -- SYN FRAME(DATA_NSQ) CRC(F) PAYLOAD CRC(P) ---------------------- rx: -------------------------------------------------------------------h]htx: -- SYN FRAME(DATA_NSQ) CRC(F) PAYLOAD CRC(P) ---------------------- rx: -------------------------------------------------------------------}hj sbah}(h]h ]h"]h$]h&]hhuh1j hhhKhj hhubj)}(hHere, an error can be detected, but not corrected or indicated to the sending party. These exchanges are symmetric, i.e. switching ``rx`` and ``tx`` results again in a valid exchange. Currently, no longer exchanges are known.h](hHere, an error can be detected, but not corrected or indicated to the sending party. These exchanges are symmetric, i.e. switching }(hj hhhNhNubh)}(h``rx``h]hrx}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh and }(hj hhhNhNubh)}(h``tx``h]htx}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubhM results again in a valid exchange. Currently, no longer exchanges are known.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubeh}(h]!ssh-packet-protocol-flow-sequenceah ]h"]"ssh packet protocol: flow sequenceah$]h&]uh1jhjhhhhhKubj)}(hhh](j)}(h)Commands: Requests, Responses, and Eventsh]h)Commands: Requests, Responses, and Events}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj hhhhhKubj)}(hCommands are sent as payload inside a data frame. Currently, this is the only known payload type of |DATA| frames, with a payload-type value of ``0x80`` (:c:type:`SSH_PLD_TYPE_CMD `).h](hdCommands are sent as payload inside a data frame. Currently, this is the only known payload type of }(hj hhhNhNubh)}(hjh]hDATA}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj hhubh& frames, with a payload-type value of }(hj hhhNhNubh)}(h``0x80``h]h0x80}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh (}(hj hhhNhNubh)}(h-:c:type:`SSH_PLD_TYPE_CMD `h]h)}(hj h]hSSH_PLD_TYPE_CMD}(hj hhhNhNubah}(h]h ](hhߌc-typeeh"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypetype refexplicitrefwarnhssh_payload_typeuh1hhhhKhj ubh).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(hXThe command-type payload (:c:type:`struct ssh_command `) consists of an eight-byte command structure, followed by optional and variable length command data. The length of this optional data is derived from the frame payload length given in the corresponding frame, i.e. it is ``frame.len - sizeof(struct ssh_command)``. The command struct contains the following fields, packed together and in order:h](hThe command-type payload (}(hj, hhhNhNubh)}(h*:c:type:`struct ssh_command `h]h)}(hj6 h]hstruct ssh_command}(hj8 hhhNhNubah}(h]h ](hhߌc-typeeh"]h$]h&]uh1hhj4 ubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypetype refexplicitrefwarnh ssh_commanduh1hhhhKhj, ubh) consists of an eight-byte command structure, followed by optional and variable length command data. The length of this optional data is derived from the frame payload length given in the corresponding frame, i.e. it is }(hj, hhhNhNubh)}(h*``frame.len - sizeof(struct ssh_command)``h]h&frame.len - sizeof(struct ssh_command)}(hjW hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj, ubhQ. The command struct contains the following fields, packed together and in order:}(hj, hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubjQ)}(hhh](j)}(h SSH Commandh]h SSH Command}(hjr hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjo ubjd)}(hhh](ji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhj ubji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhj ubji)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhhj ubj)}(hhh]j)}(hhh](j)}(hhh]j)}(hFieldh]hField}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]j)}(hTypeh]hType}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]j)}(h Descriptionh]h Description}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh](j)}(hhh]j)}(h|TYPE|h]h)}(hj*h]hTYPE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]j)}(h|u8|h]h)}(hhh]h)}(hhh]hu8}(hj(hhhNhNubah}(h]h ](hhheh"]h$]h&]uh1hhNhNhj%ubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypeh refexplicitrefwarn reftargethuh1hhhhKhj!hhubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]j)}(h2Type of the payload. For commands always ``0x80``.h](h)Type of the payload. For commands always }(hjPhhhNhNubh)}(h``0x80``h]h0x80}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjPubh.}(hjPhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjMubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]j)}(h|TC|h]h)}(hj h]hTC}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj|ubj)}(hhh]j)}(h|u8|h]h)}(hhh]h)}(hhh]hu8}(hjhhhNhNubah}(h]h ](hhheh"]h$]h&]uh1hhNhNhjubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypeh refexplicitrefwarn reftargethuh1hhhhKhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj|ubj)}(hhh]j)}(hTarget category.h]hTarget category.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj|ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]j)}(h|TID|h]h)}(hj$h]hTID}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h|u8|h]h)}(hhh]h)}(hhh]hu8}(hjhhhNhNubah}(h]h ](hhheh"]h$]h&]uh1hhNhNhjubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypeh refexplicitrefwarn reftargethuh1hhhhKhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h Target ID for commands/messages.h]h Target ID for commands/messages.}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj=ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]j)}(h|SID|h]h)}(hj=h]hSID}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj`hhubah}(h]h ]h"]h$]h&]uh1jhhhKhj]ubah}(h]h ]h"]h$]h&]uh1jhjZubj)}(hhh]j)}(h|u8|h]h)}(hhh]h)}(hhh]hu8}(hjhhhNhNubah}(h]h ](hhheh"]h$]h&]uh1hhNhNhjubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypeh refexplicitrefwarn reftargethuh1hhhhKhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKhj}ubah}(h]h ]h"]h$]h&]uh1jhjZubj)}(hhh]j)}(h Source ID for commands/messages.h]h Source ID for commands/messages.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjZubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]j)}(h|IID|h]h)}(hjVh]hIID}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h|u8|h]h)}(hhh]h)}(hhh]hu8}(hjhhhNhNubah}(h]h ](hhheh"]h$]h&]uh1hhNhNhjubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypeh refexplicitrefwarn reftargethuh1hhhhKhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h Instance ID.h]h Instance ID.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]j)}(h|RQID|h]h)}(hjoh]hRQID}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhj>hhubah}(h]h ]h"]h$]h&]uh1jhhhKhj;ubah}(h]h ]h"]h$]h&]uh1jhj8ubj)}(hhh]j)}(h|u16|h]h)}(hjh]h)}(hjh]hu16}(hjehhhNhNubah}(h]h ](hhj eh"]h$]h&]uh1hhNhNhjbubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypej refexplicitrefwarn reftargetjuh1hhhhKhj^hhubah}(h]h ]h"]h$]h&]uh1jhhhKhj[ubah}(h]h ]h"]h$]h&]uh1jhj8ubj)}(hhh]j)}(h Request ID.h]h Request ID.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj8ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]j)}(h|CID|h]h)}(hjh]hCID}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h|u8|h]h)}(hhh]h)}(hhh]hu8}(hjhhhNhNubah}(h]h ](hhheh"]h$]h&]uh1hhNhNhjubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypeh refexplicitrefwarn reftargethuh1hhhhKhjhhubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(h Command ID.h]h Command ID.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]colsKuh1jchjo ubeh}(h]id4ah ]h"]h$]h&]uh1jPhj hhhNhNubj)}(hThe command struct and data, in general, does not contain any failure detection mechanism (e.g. CRCs), this is solely done on the frame level.h]hThe command struct and data, in general, does not contain any failure detection mechanism (e.g. CRCs), this is solely done on the frame level.}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(hX:Command-type payloads are used by the host to send commands and requests to the EC as well as by the EC to send responses and events back to the host. We differentiate between requests (sent by the host), responses (sent by the EC in response to a request), and events (sent by the EC without a preceding request).h]hX:Command-type payloads are used by the host to send commands and requests to the EC as well as by the EC to send responses and events back to the host. We differentiate between requests (sent by the host), responses (sent by the EC in response to a request), and events (sent by the EC without a preceding request).}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(hXCommands and events are uniquely identified by their target category (``TC``) and command ID (``CID``). The target category specifies a general category for the command (e.g. system in general, vs. battery and AC, vs. temperature, and so on), while the command ID specifies the command inside that category. Only the combination of |TC| + |CID| is unique. Additionally, commands have an instance ID (``IID``), which is used to differentiate between different sub-devices. For example ``TC=3`` ``CID=1`` is a request to get the temperature on a thermal sensor, where |IID| specifies the respective sensor. If the instance ID is not used, it should be set to zero. If instance IDs are used, they, in general, start with a value of one, whereas zero may be used for instance independent queries, if applicable. A response to a request should have the same target category, command ID, and instance ID as the corresponding request.h](hFCommands and events are uniquely identified by their target category (}(hjFhhhNhNubh)}(h``TC``h]hTC}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjFubh) and command ID (}(hjFhhhNhNubh)}(h``CID``h]hCID}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjFubh). The target category specifies a general category for the command (e.g. system in general, vs. battery and AC, vs. temperature, and so on), while the command ID specifies the command inside that category. Only the combination of }(hjFhhhNhNubh)}(hj h]hTC}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjFhhubh + }(hjFhhhNhNubh)}(hjh]hCID}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjFhhubh8 is unique. Additionally, commands have an instance ID (}(hjFhhhNhNubh)}(h``IID``h]hIID}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjFubhM), which is used to differentiate between different sub-devices. For example }(hjFhhhNhNubh)}(h``TC=3``h]hTC=3}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjFubh }(hjFhhhNhNubh)}(h ``CID=1``h]hCID=1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjFubh@ is a request to get the temperature on a thermal sensor, where }(hjFhhhNhNubh)}(hjVh]hIID}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjFhhubhXd specifies the respective sensor. If the instance ID is not used, it should be set to zero. If instance IDs are used, they, in general, start with a value of one, whereas zero may be used for instance independent queries, if applicable. A response to a request should have the same target category, command ID, and instance ID as the corresponding request.}(hjFhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(hXResponses are matched to their corresponding request via the request ID (``RQID``) field. This is a 16 bit wrapping counter similar to the sequence ID on the frames. Note that the sequence ID of the frames for a request-response pair does not match. Only the request ID has to match. Frame-protocol wise these are two separate exchanges, and may even be separated, e.g. by an event being sent after the request but before the response. Not all commands produce a response, and this is not detectable by |TC| + |CID|. It is the responsibility of the issuing party to wait for a response (or signal this to the communication framework, as is done in SAN/ACPI via the ``SNC`` flag).h](hIResponses are matched to their corresponding request via the request ID (}(hjhhhNhNubh)}(h``RQID``h]hRQID}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhX) field. This is a 16 bit wrapping counter similar to the sequence ID on the frames. Note that the sequence ID of the frames for a request-response pair does not match. Only the request ID has to match. Frame-protocol wise these are two separate exchanges, and may even be separated, e.g. by an event being sent after the request but before the response. Not all commands produce a response, and this is not detectable by }(hjhhhNhNubh)}(hj h]hTC}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubh + }(hjhhhNhNubh)}(hjh]hCID}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjhhubh. It is the responsibility of the issuing party to wait for a response (or signal this to the communication framework, as is done in SAN/ACPI via the }(hjhhhNhNubh)}(h``SNC``h]hSNC}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh flag).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM hj hhubj)}(hXEvents are identified by unique and reserved request IDs. These IDs should not be used by the host when sending a new request. They are used on the host to, first, detect events and, second, match them with a registered event handler. Request IDs for events are chosen by the host and directed to the EC when setting up and enabling an event source (via the enable-event-source request). The EC then uses the specified request ID for events sent from the respective source. Note that an event should still be identified by its target category, command ID, and, if applicable, instance ID, as a single event source can send multiple different event types. In general, however, a single target category should map to a single reserved event request ID.h]hXEvents are identified by unique and reserved request IDs. These IDs should not be used by the host when sending a new request. They are used on the host to, first, detect events and, second, match them with a registered event handler. Request IDs for events are chosen by the host and directed to the EC when setting up and enabling an event source (via the enable-event-source request). The EC then uses the specified request ID for events sent from the respective source. Note that an event should still be identified by its target category, command ID, and, if applicable, instance ID, as a single event source can send multiple different event types. In general, however, a single target category should map to a single reserved event request ID.}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhj hhubj)}(hXFurthermore, requests, responses, and events have an associated target ID (``TID``) and source ID (``SID``). These two fields indicate where a message originates from (``SID``) and what the intended target of the message is (``TID``). Note that a response to a specific request therefore has the source and target IDs swapped when compared to the original request (i.e. the request target is the response source and the request source is the response target). See (:c:type:`enum ssh_request_id `) for possible values of both.h](hKFurthermore, requests, responses, and events have an associated target ID (}(hjChhhNhNubh)}(h``TID``h]hTID}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjCubh) and source ID (}(hjChhhNhNubh)}(h``SID``h]hSID}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjCubh>). These two fields indicate where a message originates from (}(hjChhhNhNubh)}(h``SID``h]hSID}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhjCubh2) and what the intended target of the message is (}(hjChhhNhNubh)}(h``TID``h]hTID}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjCubh). Note that a response to a specific request therefore has the source and target IDs swapped when compared to the original request (i.e. the request target is the response source and the request source is the response target). See (}(hjChhhNhNubh)}(h.:c:type:`enum ssh_request_id `h]h)}(hjh]henum ssh_request_id}(hjhhhNhNubah}(h]h ](hhߌc-typeeh"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]refdoch refdomainhߌreftypetype refexplicitrefwarnhssh_request_iduh1hhhhM!hjCubh) for possible values of both.}(hjChhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM!hj hhubj)}(hXNote that, even though requests and events should be uniquely identifiable by target category and command ID alone, the EC may require specific target ID and instance ID values to accept a command. A command that is accepted for ``TID=1``, for example, may not be accepted for ``TID=2`` and vice versa. While this may not always hold in reality, you can think of different target/source IDs indicating different physical ECs with potentially different feature sets.h](hNote that, even though requests and events should be uniquely identifiable by target category and command ID alone, the EC may require specific target ID and instance ID values to accept a command. A command that is accepted for }(hjhhhNhNubh)}(h ``TID=1``h]hTID=1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh', for example, may not be accepted for }(hjhhhNhNubh)}(h ``TID=2``h]hTID=2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh and vice versa. While this may not always hold in reality, you can think of different target/source IDs indicating different physical ECs with potentially different feature sets.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM*hj hhubeh}(h]&commands-requests-responses-and-eventsah ]h"])commands: requests, responses, and eventsah$]h&]uh1jhjhhhhhKubj)}(hhh](j)}(hLimitations and Observationsh]hLimitations and Observations}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhhhM3ubj)}(hXsThe protocol can, in theory, handle up to ``U8_MAX`` frames in parallel, with up to ``U16_MAX`` pending requests (neglecting request IDs reserved for events). In practice, however, this is more limited. From our testing (although via a python and thus a user-space program), it seems that the EC can handle up to four requests (mostly) reliably in parallel at a certain time. With five or more requests in parallel, consistent discarding of commands (ACKed frame but no command response) has been observed. For five simultaneous commands, this reproducibly resulted in one command being dropped and four commands being handled.h](h*The protocol can, in theory, handle up to }(hjhhhNhNubh)}(h ``U8_MAX``h]hU8_MAX}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh frames in parallel, with up to }(hjhhhNhNubh)}(h ``U16_MAX``h]hU16_MAX}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhX pending requests (neglecting request IDs reserved for events). In practice, however, this is more limited. From our testing (although via a python and thus a user-space program), it seems that the EC can handle up to four requests (mostly) reliably in parallel at a certain time. With five or more requests in parallel, consistent discarding of commands (ACKed frame but no command response) has been observed. For five simultaneous commands, this reproducibly resulted in one command being dropped and four commands being handled.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM5hjhhubj)}(hXwHowever, it has also been noted that, even with three requests in parallel, occasional frame drops happen. Apart from this, with a limit of three pending requests, no dropped commands (i.e. command being dropped but frame carrying command being ACKed) have been observed. In any case, frames (and possibly also commands) should be re-sent by the host if a certain timeout is exceeded. This is done by the EC for frames with a timeout of one second, up to two re-tries (i.e. three transmissions in total). The limit of re-tries also applies to received NAKs, and, in a worst case scenario, can lead to entire messages being dropped.h]hXwHowever, it has also been noted that, even with three requests in parallel, occasional frame drops happen. Apart from this, with a limit of three pending requests, no dropped commands (i.e. command being dropped but frame carrying command being ACKed) have been observed. In any case, frames (and possibly also commands) should be re-sent by the host if a certain timeout is exceeded. This is done by the EC for frames with a timeout of one second, up to two re-tries (i.e. three transmissions in total). The limit of re-tries also applies to received NAKs, and, in a worst case scenario, can lead to entire messages being dropped.}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM?hjhhubj)}(hXWhile this also seems to work fine for pending data frames as long as no transmission failures occur, implementation and handling of these seems to depend on the assumption that there is only one non-acknowledged data frame. In particular, the detection of repeated frames relies on the last sequence number. This means that, if a frame that has been successfully received by the EC is sent again, e.g. due to the host not receiving an |ACK|, the EC will only detect this if it has the sequence ID of the last frame received by the EC. As an example: Sending two frames with ``SEQ=0`` and ``SEQ=1`` followed by a repetition of ``SEQ=0`` will not detect the second ``SEQ=0`` frame as such, and thus execute the command in this frame each time it has been received, i.e. twice in this example. Sending ``SEQ=0``, ``SEQ=1`` and then repeating ``SEQ=1`` will detect the second ``SEQ=1`` as repetition of the first one and ignore it, thus executing the contained command only once.h](hXWhile this also seems to work fine for pending data frames as long as no transmission failures occur, implementation and handling of these seems to depend on the assumption that there is only one non-acknowledged data frame. In particular, the detection of repeated frames relies on the last sequence number. This means that, if a frame that has been successfully received by the EC is sent again, e.g. due to the host not receiving an }(hjGhhhNhNubh)}(hjh]hACK}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhNhNhjGhhubh, the EC will only detect this if it has the sequence ID of the last frame received by the EC. As an example: Sending two frames with }(hjGhhhNhNubh)}(h ``SEQ=0``h]hSEQ=0}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGubh and }(hjGhhhNhNubh)}(h ``SEQ=1``h]hSEQ=1}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGubh followed by a repetition of }(hjGhhhNhNubh)}(h ``SEQ=0``h]hSEQ=0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGubh will not detect the second }(hjGhhhNhNubh)}(h ``SEQ=0``h]hSEQ=0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGubh frame as such, and thus execute the command in this frame each time it has been received, i.e. twice in this example. Sending }(hjGhhhNhNubh)}(h ``SEQ=0``h]hSEQ=0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGubh, }(hjGhhhNhNubh)}(h ``SEQ=1``h]hSEQ=1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGubh and then repeating }(hjGhhhNhNubh)}(h ``SEQ=1``h]hSEQ=1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGubh will detect the second }(hjGhhhNhNubh)}(h ``SEQ=1``h]hSEQ=1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGubh^ as repetition of the first one and ignore it, thus executing the contained command only once.}(hjGhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMIhjhhubj)}(hX In conclusion, this suggests a limit of at most one pending un-ACKed frame (per party, effectively leading to synchronous communication regarding frames) and at most three pending commands. The limit to synchronous frame transfers seems to be consistent with behavior observed on Windows.h]hX In conclusion, this suggests a limit of at most one pending un-ACKed frame (per party, effectively leading to synchronous communication regarding frames) and at most three pending commands. The limit to synchronous frame transfers seems to be consistent with behavior observed on Windows.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMWhjhhubeh}(h]limitations-and-observationsah ]h"]limitations and observationsah$]h&]uh1jhjhhhhhM3ubeh}(h]surface-serial-hub-protocolah ]h"]surface serial hub protocolah$]h&]uh1jhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(jN generator+ N datestampN source_linkN source_urlN toc_backlinksjfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj6error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}(hhj!hj:j$jSj=jljVjjojjjjjjjjjjjjj4jjMj7jfjPjjijjusubstitution_names}(u8hu16j!typej:lenjSseqjlsynjnakjackjdatajdata_seqjdata_nsqjtcjtidj4sidjMiidjfrqidjcidjurefnames}refids}nameids}(jjj j j j jjj ju nametypes}(jj j jj uh}(jjj jj j jj jjjFjRjjj juj%jo u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jDKsRparse_messages]transform_messages] transformerN include_log] decorationNhhub.