Commit 3746b3d93ce895131ab1b2dea5391e5efa9fccf7 | zig

author	Andrew Kelley <andrew@ziglang.org> 2025-04-16 04:56:22-04:00
committer	GitHub <noreply@github.com> 2025-04-16 04:56:22-04:00
log	3746b3d93ce895131ab1b2dea5391e5efa9fccf7
tree	0e7df5a25d1706e050ef806ef97be69f0a4c553f
parent	ae38fc6a50dfcece964d7d19d9e35ac5dc583daa
parent	bd38c417fc9ba367b3cfcd49d29b52412ef04251
signature	Signed by PGP key B5690EEEBB952194

Merge pull request #21741 from kj4tmp/langref-packed-structs

langref: improve packed struct memory layout description

2 files changed, 44 insertions(+), 19 deletions(-)

doc
- langref.html.in
- langref
  - packed_struct_mmio.zig

doc/langref.html.in+25-19

 @@ -1649,6 +1649,7 @@ unwrapped == 1234{#endsyntax#}</pre>
               <li>{#link|Floats#}</li>
               <li>{#link|bool|Primitive Types#}</li>
               <li>{#link|type|Primitive Types#}</li>
+              <li>{#link|packed struct#}</li>
             </ul>
           </td>
           <td>
 @@ -2224,20 +2225,24 @@ or
       {#header_open|packed struct#}
       <p>
-      Unlike normal structs, {#syntax#}packed{#endsyntax#} structs have guaranteed in-memory layout:
+      {#syntax#}packed{#endsyntax#} structs, like {#syntax#}enum{#endsyntax#}, are based on the concept
+      of interpreting integers differently. All packed structs have a <strong>backing integer</strong>,
+      which is implicitly determined by the total bit count of fields, or explicitly specified.
+      Packed structs have well-defined memory layout - exactly the same ABI as their backing integer.
+      </p>
+      <p>
+      Each field of a packed struct is interpreted as a logical sequence of bits, arranged from
+      least to most significant. Allowed field types:
       </p>
       <ul>
-        <li>Fields remain in the order declared, least to most significant.</li>
+        <li>An {#link|integer|Integers#} field uses exactly as many bits as its
-        <li>There is no padding between fields.</li>
+        bit width. For example, a {#syntax#}u5{#endsyntax#} will use 5 bits of
-        <li>Zig supports arbitrary width {#link|Integers#} and although normally, integers with fewer
+        the backing integer.</li>
-        than 8 bits will still use 1 byte of memory, in packed structs, they use
+        <li>A {#link|bool|Primitive Types#} field uses exactly 1 bit.</li>
-        exactly their bit width.
-        </li>
-        <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 support equality operators.</li>
+        <li>A {#syntax#}packed struct{#endsyntax#} field uses the bits of its backing integer.</li>
       </ul>
       <p>
       This means that a {#syntax#}packed struct{#endsyntax#} can participate
 @@ -2245,10 +2250,11 @@ or
       This even works at {#link|comptime#}:
       </p>
       {#code|test_packed_structs.zig#}
       <p>
-      The backing integer is inferred from the fields' total bit width.
+      The backing integer can be inferred or explicitly provided. When
-      Optionally, it can be explicitly provided and enforced at compile time:
+      inferred, it will be unsigned. When explicitly provided, its bit width
+      will be enforced at compile time to exactly match the total bit width of
+      the fields:
       </p>
       {#code|test_missized_packed_struct.zig#}
 @@ -2290,18 +2296,18 @@ or
       <p>
       Equating packed structs results in a comparison of the backing integer,
-      and only works for the `==` and `!=` operators.
+      and only works for the {#syntax#}=={#endsyntax#} and {#syntax#}!={#endsyntax#} {#link|Operators#}.
       </p>
       {#code|test_packed_struct_equality.zig#}
       <p>
-      Using packed structs with {#link|volatile#} is problematic, and may be a compile error in the future.
+      Field access and assignment can be understood as shorthand for bitshifts
-      For details on this subscribe to
+      on the backing integer. These operations are not {#link|atomic|Atomics#},
-      <a href="https://github.com/ziglang/zig/issues/1761">this issue</a>.
+      so beware using field access syntax when combined with memory-mapped
-      TODO update these docs with a recommendation on how to use packed structs with MMIO
+      input-output (MMIO). Instead of field access on {#link|volatile#} {#link|Pointers#},
-      (the use case for volatile packed structs) once this issue is resolved.
+      construct a fully-formed new value first, then write that value to the volatile pointer.
-      Don't worry, there will be a good solution for this use case in zig.
       </p>
+      {#code|packed_struct_mmio.zig#}
       {#header_close#}
       {#header_open|Struct Naming#}

doc/langref/packed_struct_mmio.zig created+19

...	@@ -0,0 +1,19 @@
1	pub const GpioRegister = packed struct(u8) {
2	GPIO0: bool,
3	GPIO1: bool,
4	GPIO2: bool,
5	GPIO3: bool,
6	reserved: u4 = 0,
7	};
8
9	const gpio: *volatile GpioRegister = @ptrFromInt(0x0123);
10
11	pub fn writeToGpio(new_states: GpioRegister) void {
12	// Example of what not to do:
13	// BAD! gpio.GPIO0 = true; BAD!
14
15	// Instead, do this:
16	gpio.* = new_states;
17	}
18
19	// syntax