From 4db13add57e6aa1f4078f89b3fb889e549e42174 Mon Sep 17 00:00:00 2001 From: threadexio Date: Wed, 4 Sep 2024 11:25:18 +0300 Subject: [PATCH] docs: update protocol spec --- spec/.gitignore | 2 + spec/PROTOCOL.md | 8 +-- spec/assets/packet-diagram-dark.svg | 2 +- spec/assets/packet-diagram-light.svg | 2 +- spec/assets/packet-diagram.drawio | 88 ++++++++++++++-------------- 5 files changed, 52 insertions(+), 50 deletions(-) create mode 100644 spec/.gitignore diff --git a/spec/.gitignore b/spec/.gitignore new file mode 100644 index 0000000..83679ed --- /dev/null +++ b/spec/.gitignore @@ -0,0 +1,2 @@ +/.trash +/.obsidian diff --git a/spec/PROTOCOL.md b/spec/PROTOCOL.md index fbb8e8f..4deca0e 100644 --- a/spec/PROTOCOL.md +++ b/spec/PROTOCOL.md @@ -24,9 +24,9 @@ In any case, further communication should not be attempted. This document is the specification of the version `0x42` of the protocol. That is the value this field must have. -### len_words +### flags -This field is a 2 bit unsigned number that encodes the number of 16 bit words the [data_len](###data-len) field spans. Valid values for this field is the entire range of 0 to 3 inclusive. +This field is a 2 bit unsigned number that holds flags for the frame. Currently no flags are used and as such this field must be 0. ### frame_num @@ -34,11 +34,11 @@ This field is a wrapping 6 bit unsigned number that identifies the frame. It all ### checksum -This field is responsible for ensuring that any error in the header is detected. The checksum must be the final modification made to the header before it is sent out and must be calculated while this field is set to 0. The checksum must be calculated from the start of the [version](###version) field to the end of the [data_len](###data-len) field. It does _not_ include the [payload](###payload). The algorithm used for calculating the checksum is the [Internet Checksum](https://en.wikipedia.org/wiki/Internet_checksum) algorithm. +This field is responsible for ensuring that any error in the header is detected. The checksum must be the final modification made to the header before it is sent out and must be calculated while this field is set to 0. The checksum must be calculated from the start of the [version](#version) field to the end of the [data_len](#data_len) field. It does _not_ include the [payload](#payload). The algorithm used for calculating the checksum is the [Internet Checksum](https://en.wikipedia.org/wiki/Internet_checksum) algorithm. ### data_len -This field specifies the length of the [payload](###payload) that follows. It is variable sized field that encodes a little endian 48 bit unsigned number. The value is this field is the length of the payload of the frame. The size of the field is given by the value of the [len_words](###len-words) field multiplied by 2. This is because the [len_words](###len-words) field expresses the length in 16 bit words. Being only 2 bits, the value of [len_words](###len-words) has a range of 0 to 3, meaning the [data_len](###data-len) field can be anywhere within 0 to 3 words (0 to 6 bytes). The maximum value this field can encode is `0xffff_ffff_ffff`, when `len_words` is set to 3. The minimum value of this field is 0, when `len_words` is set to 0. The size of this field must always be even. This means that if a frame that contains a payload with a size that can be represented by an odd number of bytes, there must be a padding byte to ensure the even length. +This field specifies the length of the [payload](#payload) that follows. It is a 32-bit little-endian unsigned number. The value of this field is the length of the payload of the frame. ### payload diff --git a/spec/assets/packet-diagram-dark.svg b/spec/assets/packet-diagram-dark.svg index 31e0f91..6c2ec00 100644 --- a/spec/assets/packet-diagram-dark.svg +++ b/spec/assets/packet-diagram-dark.svg @@ -1,3 +1,3 @@ -
len_words
version
checksum
frame_num
0
7
8
9
10
15
16
31
data_len
payload
 \ No newline at end of file +
flags
version
checksum
frame_num
0
7
8
9
10
15
16
31
data_len
payload
 \ No newline at end of file diff --git a/spec/assets/packet-diagram-light.svg b/spec/assets/packet-diagram-light.svg index 01a1d35..609ead4 100644 --- a/spec/assets/packet-diagram-light.svg +++ b/spec/assets/packet-diagram-light.svg @@ -1,3 +1,3 @@ -
len_words
version
checksum
frame_num
0
7
8
9
10
15
16
31
data_len
payload
 \ No newline at end of file +
flags
version
checksum
frame_num
0
7
8
9
10
15
16
31
data_len
payload
 \ No newline at end of file diff --git a/spec/assets/packet-diagram.drawio b/spec/assets/packet-diagram.drawio index 489273e..534e21d 100644 --- a/spec/assets/packet-diagram.drawio +++ b/spec/assets/packet-diagram.drawio @@ -1,170 +1,170 @@ - + - + - - + + - - + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - + + - + - + - + - - + + - + - + - + - - + +