From 0d99fe0c221e0b3de555ffae9a94ef88cadbdc89 Mon Sep 17 00:00:00 2001 From: plebhash Date: Tue, 17 Dec 2024 17:01:16 +0700 Subject: [PATCH] fix descriptions of msg_type and extension_type on framing_sv2 docs.. for more details see https://github.com/stratum-mining/sv2-spec/issues/117 --- protocols/v2/framing-sv2/README.md | 16 +++++++++++++--- protocols/v2/framing-sv2/src/lib.rs | 6 +++--- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/protocols/v2/framing-sv2/README.md b/protocols/v2/framing-sv2/README.md index e4f3d92737..f49d14bbfa 100644 --- a/protocols/v2/framing-sv2/README.md +++ b/protocols/v2/framing-sv2/README.md @@ -14,13 +14,23 @@ type, message type, and message length (six bytes in total), followed by a varia message. The message framing is outlined below ([according to Sv2 specs ](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#32-framing)): -| Protocol Type | Byte Length | Description | +| Field Name | Byte Length | Description | |----------------|-------------|-------------| -| `extension_type` | `U16` | Unique identifier of the extension describing this protocol message.

Most significant bit (i.e.bit `15`, `0`-indexed, aka `channel_msg`) indicates a message which is specific to a channel, whereas if the most significant bit is unset, the message is to be interpreted by the immediate receiving device.

Note that the `channel_msg` bit is ignored in the extension lookup, i.e.an `extension_type` of `0x8ABC` is for the same "extension" as `0x0ABC`.

If the `channel_msg` bit is set, the first four bytes of the payload field is a `U32` representing the `channel_id` this message is destined for (these bytes are repeated in the message framing descriptions below).

Note that for the Job Declaration and Template Distribution Protocols the `channel_msg` bit is always unset. | -| `msg_type` | `U8` | Unique identifier of the extension describing this protocol message. | +| `extension_type` | `U16` | Unique identifier of the extension associated with this protocol message. | +| `msg_type` | `U8` | Unique identifier of this protocol message. | | `msg_length` | `U24` | Length of the protocol message, not including this header. | | `payload` | `BYTES` | Message-specific payload of length `msg_length`. If the MSB in `extension_type` (the `channel_msg` bit) is set the first four bytes are defined as a `U32` `"channel_id"`, though this definition is repeated in the message definitions below and these 4 bytes are included in `msg_length`. | +Some bits of the `extension_type` field can also be repurposed for signaling on how the frame should be handled across channels. + +The least significant bit of `extension_type` (i.e.bit 15, 0-indexed, aka `channel_msg`) indicates a message which is specific to a channel, whereas if the most significant bit is unset, the message is to be interpreted by the immediate receiving device. + +Note that the `channel_msg` bit is ignored in the extension lookup, i.e.an `extension_type` of `0x8ABC` is for the same "extension" as `0x0ABC`. + +If the `channel_msg` bit is set, the first four bytes of the payload field is a `U32` representing the `channel_id` this message is destined for (these bytes are repeated in the message framing descriptions below). + +Note that for the Job Declaration and Template Distribution Protocols the `channel_msg` bit is always unset. + ## Main Components - **Header**: Defines the 6-byte Sv2 message header with information about the message payload, diff --git a/protocols/v2/framing-sv2/src/lib.rs b/protocols/v2/framing-sv2/src/lib.rs index 4ea121f080..fd33802cf5 100644 --- a/protocols/v2/framing-sv2/src/lib.rs +++ b/protocols/v2/framing-sv2/src/lib.rs @@ -12,10 +12,10 @@ //! The message framing is outlined below ([according to Sv2 specs //! ](https://stratumprotocol.org/specification/03-Protocol-Overview/#32-framing)): //! -//! | Protocol Type | Byte Length | Description | +//! | Field Name | Byte Length | Description | //! |----------------|-------------|-------------| -//! | `extension_type` | `U16` | Unique identifier of the extension describing this protocol message.

Most significant bit (i.e.bit `15`, `0`-indexed, aka `channel_msg`) indicates a message which is specific to a channel, whereas if the most significant bit is unset, the message is to be interpreted by the immediate receiving device.

Note that the `channel_msg` bit is ignored in the extension lookup, i.e.an `extension_type` of `0x8ABC` is for the same "extension" as `0x0ABC`.

If the `channel_msg` bit is set, the first four bytes of the payload field is a `U32` representing the `channel_id` this message is destined for (these bytes are repeated in the message framing descriptions below).

Note that for the Job Declaration and Template Distribution Protocols the `channel_msg` bit is always unset. | -//! | `msg_type` | `U8` | Unique identifier of the extension describing this protocol message. | +//! | `extension_type` | `U16` | Unique identifier of the extension associated with this protocol message. | +//! | `msg_type` | `U8` | Unique identifier of this protocol message. | //! | `msg_length` | `U24` | Length of the protocol message, not including this header. | //! | `payload` | `BYTES` | Message-specific payload of length `msg_length`. If the MSB in `extension_type` (the `channel_msg` bit) is set the first four bytes are defined as a `U32` `"channel_id"`, though this definition is repeated in the message definitions below and these 4 bytes are included in `msg_length`. | //!