Re: [quicwg/base-drafts] Don't use bitmap frames to describe varint structures (#3115)

[Nick Harper <[e-mail]>]

My preference is something closer to the TLS presentation language for specifying packet formats (at least in the transport draft).

For example, the initial packet header format is currently described as 

```
+-+-+-+-+-+-+-+-+
|1|1| 0 |R R|P P|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         Version (32)                          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| DCID Len (8)  |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               Destination Connection ID (0..160)            ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| SCID Len (8)  |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                 Source Connection ID (0..160)               ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         Token Length (i)                    ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            Token (*)                        ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           Length (i)                        ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                    Packet Number (8/16/24/32)               ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                          Payload (*)                        ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```

Only one of fields drawn to be 32 bits wide is actually 32 bits (the version) - for the rest of them that drawing style (even though there's a `...` instead of a `|` at the end of the line) isn't particularly helpful.

Here's an example of what that would look like done in something like the TLS presentation language:

```
struct {
  uint8 flags;
  uint32 version;
  uint8 dcid_len;
  blob[dcid_len] dcid;
  uint8 scid_len;
  blob[scid_len] scid;
  varint token_len;
  blob[token_len] token;
  varint length;
  blob[pn_len] packet_number;
  blob[length-pn_len] payload;
} InitialPacket;
```

The only place where this struct loses clarity compared to the diagram is the `flags` field (and regardless of whether a struct or a diagram is used, prose is still needed to describe what the bits are). For the rest of this struct layout, it's a list of fields, which is essentially what the diagram is, but the types and/or lengths of the fields are described in better detail.

If there's interest in making such a change to the drafts, I volunteer to help make those changes.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/issues/3115#issuecomment-547082729