Skip to content

Commit

Permalink
langref: improve packed struct memory layout description
Browse files Browse the repository at this point in the history
  • Loading branch information
kj4tmp committed Oct 18, 2024
1 parent fffbb51 commit 030242d
Showing 1 changed file with 9 additions and 9 deletions.
18 changes: 9 additions & 9 deletions doc/langref.html.in
Original file line number Diff line number Diff line change
Expand Up @@ -2180,16 +2180,20 @@ or
Unlike normal structs, {#syntax#}packed{#endsyntax#} structs have guaranteed in-memory layout:
</p>
<ul>
<li>Fields remain in the order declared, least to most significant.</li>
<li>Fields are arranged in the order declared, from the least to the most significant bits of a backing integer.</li>
<li>There is no padding between fields.</li>
<li>Zig supports arbitrary width {#link|Integers#} and although normally, integers with fewer
than 8 bits will still use 1 byte of memory, in packed structs, they use
exactly their bit width.
<li>The backing integer is subject to the same rules as any integer, including {#link|alignment|Alignment#},
having a maximum bit count of 65535, and the host endianness.
On a big endian system, the first declared field will have the highest memory address.
</li>
<li>The backing integer has the same bit count as the fields' total bit width.</li>
<li>Field access and assignment can be understood as shorthand for bitshifts on the backing integer.</li>
<li>Integers will use exactly as many bits as they have. For example, a {#syntax#}u5{#endsyntax#} will use 5 bits of the backing integer.
<li>{#syntax#}bool{#endsyntax#} fields use exactly 1 bit.</li>
<li>An {#link|enum#} field uses exactly the bit width of its integer tag type.</li>
<li>A {#link|packed union#} field uses exactly the bit width of the union field with
the largest bit width.</li>
<li>Packed structs, when they themselves are within a packed struct, will only use as many bits as their backing integer.</li>
<li>Packed structs support equality operators.</li>
</ul>
<p>
Expand All @@ -2200,8 +2204,7 @@ or
{#code|test_packed_structs.zig#}

<p>
The backing integer is inferred from the fields' total bit width.
Optionally, it can be explicitly provided and enforced at compile time:
The backing integer can be inferred or explicitly provided. When inferred it will be unsigned, and when explicitly provided, its bit count will be enforced at compile time:
</p>
{#code|test_missized_packed_struct.zig#}

Expand Down Expand Up @@ -2248,9 +2251,6 @@ or
{#code|test_packed_struct_equality.zig#}

<p>
Using packed structs with {#link|volatile#} is problematic, and may be a compile error in the future.
For details on this subscribe to
<a href="https://github.com/ziglang/zig/issues/1761">this issue</a>.
TODO update these docs with a recommendation on how to use packed structs with MMIO
(the use case for volatile packed structs) once this issue is resolved.
Don't worry, there will be a good solution for this use case in zig.
Expand Down

0 comments on commit 030242d

Please sign in to comment.