Documentation for 'align' Does Not Include Bitfield Alignment

[nsmryan]

Zig Version

0.11.0-dev.3+0bbb00035

Steps to Reproduce and Observed Behavior

The documentation for the 'align' keyword (section 13.2 of the Zig Language Reference) only covers the syntax for setting byte alignment.
However, section 15.3 'packed struct' shows that another syntax is valid, with an error message giving a hint on its meaning.
This example program also uses this syntax for align:

const std = @import("std");

const S = packed struct {
    a: u2,
    b: u2,
    c: u2,
};

pub fn main() void {
    var s: S = S{ .a = 1, .b = 2, .c = 3 };
    const ptr: *align(1:2:1) u2 = &s.b;

    std.debug.print("ptr = {}\n", .{ptr});
    std.debug.print("@typeInfo(ptr) = {}\n", .{@typeInfo(@TypeOf(ptr))});
}

I don't see any indication that this syntax is valid, or how to use it, in the current documentation.

This came up with my project zig_tcl when dealing with bit aligned fields across a C API boundary, and I don't know how to proceed without a better understanding of alignment in Zig.

Expected Behavior

I expect documentation for the 'align' keyword to include this, seemingly valid, use of the keyword.

[gadzbi123]

I was exploring the topic, but I got stuck a bit 😆

How does align work

I know how the align(A:B:C) function works:

• A - pointer alignment - the alignment of the pointer in bytes (can be 2^n but less then 2<<29)
• B - pointer bit offset - the bit at which data from that pointer starts at (0 based)
• C - pointer host size - the size of the acctual data (in bytes), that is pointed to.

What is the problem

I have written 2 scenarios of usage for *align() function.

const std = @import("std");
const expectEqual = std.testing.expectEqual;

const NormalStruct = packed struct {
    a: u8,
    b: u16,
    c: u16,
};
test "packed 5 byte struct" {
    var s: NormalStruct = NormalStruct{ .a = 1, .b = 2, .c = 3 };
    const ptr: *align(1) u16 = &s.b; // Part 1. You should be able to use align(8:8:5), but it is not allowed
    // Part 2. We have error here. left = 1 and right = 8
    try expectEqual(@typeInfo(@TypeOf(ptr)).pointer.alignment, @alignOf(@TypeOf(ptr)));
}

const UnalignedStruct = packed struct {
    a: u9, // different from NormalStruct
    b: u16,
    c: u16,
};
test "packed 5 byte and 1 bit struct (6 bytes total)" {
    var s: UnalignedStruct = UnalignedStruct{ .a = 1, .b = 2, .c = 3 };
    const ptr: *align(8:9:6) u16 = &s.b; // Part 3.
    try expectEqual(@typeInfo(@TypeOf(ptr)).pointer.alignment, @alignOf(@TypeOf(ptr)));
}

Part 1

I think that you should be able to use align function align(8:8:5) for this. Why is it not possible?
I thought I can use @aligncast but it doesn't seem to work

const ptr: *align(8:8:5) u16 = @alignCast(&s.b); // error: pointer host size '0' cannot coerce into pointer host size '5'
const ptr2: *align(0:8:5) u16 = @alignCast(&s.b); // error: alignment must be >= 1

Part 2

I think this is the error in compiler. The documentation for @alignOf() is misleading:
When the child type of a pointer has this alignment, the alignment can be omitted from the type.

Part 3

You can see that we have pointer aligned like:
8 - alignment is 8 because it can be 2^n and the size of struct is 6 bytes (or 5 bytes and 1 bit).
9 - The ninth bit is the place there b is located.
6 - The actual size of data.

Conclusion

Maybe some of it can be used in documentation. Is there anyone who can confirm what I discovered?
I am new here so let me know if I made mistake somewhere.

[mlugg]

@gadzbi123 I can't look at your specific examples right now, but just wanted to say that bit-pointers right now, as well as being kind of a mess, are also quite broken at times. Note #24061, which would replace status quo bit pointers with a more understandable and more correct feature.