Notes on future transport frame headers

[pavel-kirienko]

At some point in the future we may want to consider updating the transport frame header definitions for UDP and serial. When that happens, we should consider this:

1. It is desirable to add the total transfer payload size in the header. Yes, every frame of a transfer will carry the size of that transfer's payload, because in non-CAN transports frames may arrive out of order and even interleave with neighboring transfers. Having the size allows us to allocate not just extent-sized payload buffers but min(extent,size), which saves memory if the extent is large.

2. Depending on how the named topic design goes, it is likely to be a good idea to add at least a 32-bit field for the topic discriminator. Per the current proposal, the topic discriminator is just a hash of the topic name that is added to every transfer and frame to manage topic allocation collisions. Currently, in the UDP and serial transports we only have space for 16~25 bits of the topic discriminator, depending on how you count.

Cyphal/UDP specific

The subject-ID and the destination node-ID are available in the IP multicast group address.

uint5  version               #= 2
uint3  priority
bool   end_of_transfer
bool   flag_ack_required
void6  # Reserved for future flags.
uint16 source_node_id
uint32 frame_index
uint64 topic_hash_or_rpc # if rpc: service_id|(is_response<<15)|(dst_node_id<<16)
uint64 transfer_id
uint32 transfer_payload_size # Capped at 2^32-1 if larger than 4 GiB.
uint32 header_crc32c         # Same as the transfer payload CRC.
@assert _offset_ == {32*8}

struct header_t {
    uint8_t  version_priority;
    uint8_t  flags;
    uint16_t source_node_id;
    uint32_t frame_index;
    uint64_t topic_hash_or_rpc;
    uint64_t transfer_id;
    uint32_t transfer_payload_size;
    uint32_t header_crc32c;
};

Cyphal/serial specific

All Cyphal/serial transfers are single-frame transfers.

uint5  version               #= 2
uint3  priority
bool   flag_ack_required
void7  # Reserved for future flags.
uint16 source_node_id
uint16 destination_node_id   # 65535 for topic transfers, otherwise this is RPC
uint16 data_specifier        # if dst=65535, this is subject-ID, otherwise service-ID
uint64 topic_hash            # zero if RPC
uint64 transfer_id
uint32 transfer_payload_size # Capped at 2^32-1 if larger than 4 GiB.
uint32 header_crc32c         # Same as the transfer payload CRC.
@assert _offset_ == {32*8}

struct header_t {
    uint8_t  version_priority;
    uint8_t  flags;
    uint16_t source_node_id;
    uint16_t destination_node_id;
    uint16_t data_specifier;
    uint64_t topic_hash;
    uint64_t transfer_id;
    uint32_t transfer_payload_size;
    uint32_t header_crc32c;
};