Packet structure diagrams

[PFigs]

Is your feature request related to a problem? Please describe.
No, this is an idea for a new diagram type.

Describe the solution you'd like
Ideally the diagram definition would consist of a box identifier where the text and bit numbering would visible, eg:

PacketDiagram
M[0:32]: Address

Additional context
https://www.thegeekstuff.com/2012/03/ip-protocol-header/

[barakplasma]

I checked the link provided, but I'm not sure which diagram you are referring to replicating.
Can you provide a wireframe or mock up of your idea?

[PFigs]

Hi!

Thanks for taking a look!

I would be useful to build diagrams to depict memory and packet structures. This are basically identified by a box, length in bits and a label with the field name.

Here's an example:

[sesm]

@PFigs very good idea!
Are you aware of any tool that generates this diagrams already? Or any commonly used textual representation of packet structure? That would be a good starting point for implementing this feature.

[PFigs]

Hi!

I am not aware of any proper tool. I see a lot of people using word, visio, powerpoint or plain ascii tables for this purpose. Not ideal!

[barakplasma]

@sesm @PFigs I was able to finda tool which generates an ASCII diagram for custom packet structures at https://github.com/luismartingarcia/protocol

Here's some example usage:
$ protocol "Field4:4,Field4:4,Field8:8,Field16:16,Field32:32,Field64:64?\ bits=16,numbers=y,startchar=*,endchar=*,evenchar=-,oddchar=-,sepchar=|"

     0                   1
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
    *-------------------------------*
    | Field4| Field4|     Field8    |
    *-------------------------------*
    |            Field16            |
    *-------------------------------*
    |                               |
    *            Field32            *
    |                               |
    *-------------------------------*
    |                               |
    *                               *
    |                               |
    *            Field64            *
    |                               |
    *                               *
    |                               |
    *-------------------------------*

Another example:
$ protocol "Source Port:16,Destination Port:16,Sequence Number:32,\ Acknowledgment Number:32,Offset:4,Res.:4,Flags:8,Window:16,Checksum:16,\ Urgent Pointer:16,Options:24,Padding:8"

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |          Source Port          |        Destination Port       |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                        Sequence Number                        |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                     Acknowledgment Number                     |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | Offset|  Res. |     Flags     |             Window            |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |            Checksum           |         Urgent Pointer        |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                    Options                    |    Padding    |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

[PFigs]

Wow quite cool 😎 thanks!

[knsv]

Cool idea. How would you imagine the syntax?

[justyn]

For hints on syntax, see also the extremely basic tool packetdiag

{
  colwidth = 32
  node_height = 72

  0-15: Source Port
  16-31: Destination Port
  32-63: Sequence Number
  64-95: Acknowledgment Number
  96-99: Data Offset
  100-105: Reserved
  106: URG [rotate = 270]
  107: ACK [rotate = 270]
  108: PSH [rotate = 270]
  109: RST [rotate = 270]
  110: SYN [rotate = 270]
  111: FIN [rotate = 270]
  112-127: Window
  128-143: Checksum
  144-159: Urgent Pointer
  160-191: (Options and Padding)
  192-223: data [colheight = 3]
}

[frehberg]

yes, I am missing this diagram type in mermaid as well, for example if I need to document protocol headers in communication protocols, or memory layout of operating systems

[harvester-software]

I'd like to pick this up - any objections?

[jgreywolf]

@harvester-software None at all - If you are still interested lets get this assigned to you!

[GilDev]

I see this is being added in #4839. Just for information, there’s also Bytefield that does this.

[jparrish88]

Hi, I was testing the #4839 , This is great work! I had a couple questions, that are thinly veiled features requests:

• Can I change the column width?
• • My flash pages are a different size than 32.
• Can you just use the size of the block/characteristic?
• -If you use size you wouldn't have to change every line if a single characteristic needed to change position or change size.
• -My assumption is that this would require a config change similar to the showBits config; like useSize.

[duckbrain]

Playing around with the package diagram on mermaid.live, this is really useful, I've used the block diagram in to fill this need in the past.

Another feature that'd be useful to see is reversing the order of the bits. I'm using it to describe the meaning of bits being packed into an int64, but it's easier to reason about it in little-endian. Perhaps listing the bits in reverse order could make it display the other way.

[zanedp]

#5978 is related to this discussion.

[zanedp]

A lot of messages have payloads of variable length, usually indicated by a field in the header or a terminating symbol. It would be great if the syntax and diagram supported that, resorting to showing names instead of number for positions in that case. Maybe, something like this?

0-3: Sync
4-7: Length
+Length: Data
+4: CRC32

| 0  3 | 4    7 | 8     8 + (Length-1) | 8 + Length   12 + Length |
| Sync | Length | Data                 | CRC32                    |

If this is allowed, I don't know how to decide how "wide" to go before dropping down to the next row? Maybe it doesn't? Such a diagram just grows horizontally forever, unless there is an explicit indication of where to "break"? Maybe throw a ... on a line by itself in where there can/should be a break?

[krister-ts]

How about add configuration for endianness? Big-endian is old but still exists.

[carlolars]

I'd like to be able to reverse the bit-order, ie writing from highest number to lowest. This is a imo more intuitive when describing bit-fields since many of us write numbers with the highest value-digit at the left.

0x1234 = 0b0001_0010_0011_0100

[markg85]

Perhaps a bit late and perhaps i should open a new issue for this?

I'm afraid the packet inclusion in mermaid 11, while nice, is a bit too limited. I was looking for ways to describe bits in a byte or just x number of bits. I'm looking for a diagram like one of the following:

This one comes from this project: https://github.com/wavedrom/bitfield

It's nice and visually appealing! But it lacks a bit of verbosity.

A more verbose style (from here):

Or this one, perhaps even better. It's from here and generated by the code there in latex.

Lastly, apparently the Latex bytefield package allows the creation of diagrams like this too (from here):

Any of these diagrams would be very sweet to have and in general would help writing very technical documents in markdown. As mermaid is often included in markdown 😄