User:Dandorid/sandbox/PHD/doc

{{APHD}} is a template for generating Augmented Packet Header Diagrams. An effort is underway to standardize diagrams in RFCs and to make them machine readable. This macro, however, is solely intended for generating diagrams for human consumption. As such, and building on Wikipedia's history, they will differ somewhat.

The generated diagram (a wiki table) has been designed and improved by many earlier editors on many wiki pages. This template merely standardizes this work and simplifies its use.

The diagram includes a header that numbers bits from 0 to 31, with 0 being the most significant bit. These bits are numbered in network byte order, since they are, with very few exceptions, transmitted over the line in this order.

Usage

The easiest way to see how it works is by giving an example. We start with the header, and we add a title, embellished with a reference.

{{APHD|start|title=TCP's header format{{Ref RFC|9293}}}}

Next we define two 16-bit fields, starting at octet 0:

{{APHD|0|bits1=16|bits2=16|field1=Source Port|field2=Destination Port}}

We follow with two 32-bit fields, starting at octet 4 and 8. Suppose some emphasis is required on the name of a field, you can give it a different colour:

{{APHD|4|bits1=32|field1=Sequence Number|color1=saddlebrown}}

{{APHD|8|bits1=32|field1=Acknowledgement Number (meaningful when ACK bit set)}}

Now, things get interesting. Let's define 11 fields of various sizes and display some of them vertically. Note that we do not have to specify the widths of fields of only one bit.

{{APHD|12|bits1=4|bits2=4|bits11=16|field1=Data Offset|field2=Reserved|vfield3=CWR|vfield4=ECE| vfield5=URG|vfield6=ACK|vfield7=PSH|vfield8=RST|vfield9=SYN|vfield10=FIN|field11=Window}}

Then we repeat a line with two 16-bit fields. You can include wikilinks in the fields' text, as well as references:

{{APHD|16|bits1=16|bits2=16|field1=[[Internet checksum|Checksum]]|field2=Urgent Pointer (meaningful when URG bit set){{Ref RFC|9293|rsection=3.8.5}}}}

We end the fields with a large, 320-bit field, which would span ten lines but is summarized on just 3 lines. We give it a very light salmon colour ('misty rose') to indicate it is optional:

{{APHD|20|bits1=320|background1=mistyrose|field1=[Options] If present, Data Offset will be greater than 5.{{break}}Padded with zeroes to a multiple of 32 bits, since Data Offset counts words of 4 octets.}}

Background colours can be specified using a standard HTML colour name, or a hexadecimal colour code with 3 or 6 digits. Finally, we end the wikitable with:

{{APHD|end}}

It does not generate output, but ends the table in a proper manner. It should always be included at the end of the table.

As an example, we give a description of some of the fields:

{{APHD|def|Source Port|16 bits|Identifies the sending port.}}

{{APHD|def|Reserved|4 bits|For future use and should be set to zero.

:From 2003–2017, the last bit (bit 103 of the header) was defined as the NS (Nonce Sum) flag by the experimental RFC 3540, ECN-nonce. ECN-nonce never gained widespread use and the RFC was moved to Historic status.{{Ref RFC|3540}}}}

(Notice the line break after 'zero.' and the start of the next line with a colon to indent it properly.)

{{APHD|def|Options|Variable 0–320 bits, in units of 32 bits|The length of this field is determined by the ''data offset'' field. Options have up to three fields: Option-Kind (1 byte), Option-Length (1 byte), Option-Data (variable). The Option-Kind field indicates the type of option and is the only field that is not optional. Depending on Option-Kind value, the next two fields may be set. Option-Length indicates the total length of the option, and Option-Data contains data associated with the option, if applicable. For example, an Option-Kind byte of 1 indicates that this is a no operation option used only for padding, and does not have...}}

Or you could just use extra text outside the start of the field definitions.

This is the result:

TCP's header format

Offset	Octet	0								1								2								3
Octet	Bit	0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20	21	22	23	24	25	26	27	28	29	30	31
0	0	Source Port																Destination Port
4	32	Sequence Number
8	64	Acknowledgement Number (meaningful when ACK bit set)
12	96	Data Offset				Reserved				CWR	ECE	URG	ACK	PSH	RST	SYN	FIN	Window
16	128	Checksum																Urgent Pointer (meaningful when URG bit set)
20	160	[Options] If present, Data Offset will be greater than 5. Padded with zeroes to a multiple of 32 bits, since Data Offset counts words of 4 octets.
⋮	⋮
56	448
60	480	Data
64	512
⋮	⋮

Source Port (16 bits)

Identifies the sending port.

Or you could just use extra text outside the start of the field definitions.

Reserved (4 bits)

For future use and should be set to zero.

From 2003–2017, the last bit (bit 103 of the header) was defined as the NS (Nonce Sum) flag by the experimental RFC 3540, ECN-nonce. ECN-nonce never gained widespread use and the RFC was moved to Historic status.

Options (Variable 0–320 bits, in units of 32 bits)

The length of this field is determined by the data offset field. Options have up to three fields: Option-Kind (1 byte), Option-Length (1 byte), Option-Data (variable). The Option-Kind field indicates the type of option and is the only field that is not optional. Depending on Option-Kind value, the next two fields may be set. Option-Length indicates the total length of the option, and Option-Data contains data associated with the option, if applicable. For example, an Option-Kind byte of 1 indicates that this is a no operation option used only for padding, and does not have...

Template data

Template {{APHD}} is used to create augmented packet header diagrams, in close co-ordination with the writers of the standardization effort.

Template parameters

Parameter		Description	Type	Status
table header	1 (start)	Generates the header. Example start	String	suggested
offset	1 (numerical)	If this parameter is numerical then it is interpreted as the octet offset of this 4 octet-sized table row, which is displayed in the left header. The bit offset is calculated automatically. Example 4	Number	suggested
table end	1 (end)	Generates the end of the table. Example end	String	suggested
field length	bits1-bits12	Size of field field1 - field12 in bits. Default 1 Example 16	String	optional
field name	field1-field12	Field name of field1 - field12. Example Options	String	optional
vertical field name	vfield1-vfield12	Field name of field1 - field12. Displayed vertically. A 'fieldX' takes precedence over a 'vfieldX'. Example SYN	String	optional