proposal: cmd/compile: make 64-bit fields be 64-bit aligned on 32-bit systems, add //go:packed directive on structs

[danscales]

Summary: We propose to change the default layout of structs on 32-bit systems such that 64-bit fields will be 64-bit aligned. The layout of structs on 64-bit systems will not change. For compatibility reasons (and finer control of struct layout), we also propose the addition of a //go:packed directive that applies to struct types. When the //go:packed directive is specified immediately before a struct type, then that struct will have a fully-packed layout, where fields are placed in order with no padding between them and hence no alignment based on types. The developer must explicitly add padding to enforce any desired alignment.

The main goal of this change is to avoid the bugs that frequently happen on 32-bit systems, where a developer wants to be able to do 64-bit operations on a 64-bit field (such as an atomic operation), but gets an alignment error because the field is not 64-bit aligned. With the current struct layout rules, a developer must often add explicit padding in order to make sure that such a 64-bit field is on a 64-bit boundary. As shown by repeated mentions in issue #599 (18 in 2019 alone), developers still often run into this problem. They may only run into it late in the development cycle as they are testing on 32-bit architectures, or when they execute an uncommon code path that requires the alignment.

As an example, the struct for ticks in runtime/runtime.go is declared as

var ticks struct {
	lock mutex
	pad  uint32 // ensure 8-byte alignment of val on 386
	val  uint64
}

so that the val field is properly aligned on 32-bit architectures. With the change in this proposal, it could be declared as:

var ticks struct {
	lock mutex
	val  uint64
}

and the val field would always be 64-bit aligned, even if other fields are added to struct.

We do not propose changing the alignment of 64-bit types which are arguments or return values, since that would change the Go calling ABI on 32-bit architectures. For consistency, we also don't propose to change the alignment of 64-bit types which are local variables. However, since we are changing the layout of some structs, we could be changing the ABI for functions that take a struct as an argument or return value. However, if assembly code is accessing struct fields, it should be using the symbolic constants (giving the offset of each field in a struct) that are available in go_asm.h (which is automatically generated for any package which contains an assembly file).

However, we do require a new directive for compatibility in the case of cgo and also interactions with the operating system. We propose the addition of a //go:packed directive that applies to struct types. When the //go:packed directive is specified immediately before a struct type, then that struct will have a fully-packed layout, where fields are placed in order with no padding between them and hence no alignment based on types. The developer must explicitly add padding fields to enforce any desired alignment within the structure.

We would then use the //go:packed directive for cgo-generated struct types (with explicit padding added as needed). Also, given the strict layout requirements for structures passed to system calls, we would use //go:packed for structs that are used for system calls (notably Flock_t and Stat_t, used by Linux system calls). We can enforce the use of //go:packed for structures that are passed to system calls (typically via pointers) with the use of a go vet check. I don't think we would particularly encourage the use of //go:packed in any other situations (as with most directives), but it might be useful in a few specific other cases.

This proposal is essentially a solution to issue #599. A related issue #19057 proposes a way to force the overall alignment of structures. That proposal does not propose changing the default alignment of 64-bit fields on 32-bit architectures (the source of the problems mentioned in issue #599), but would provide a mechanism to explicitly align 64-bit fields without using developer-computed padding. With that proposal, aligning a uint64 field (for example) in a struct to a 64-bit boundary on a 32-bit system would require replacing the uint64 type with a struct type that has the required 64-bit alignment (as I understand it).

Compatibility: We are not changing the alignment of arguments, return variables, or local variables. Since we would be changing the default layout of structs, we could affect some programs running on 32-bit systems that depend on the layout of structs. However, the layout of structs is not explicitly defined in the Go language spec, except for than minimum alignment, and we are maintaining the previous minimum alignments. So, I don't believe this change breaks the Go 1 compatibility promise. If assembly code is accessing struct fields, it should be using the symbolic constants (giving the offset of each field in a struct) that are available in go_asm.h. go_asm.h is automatically generated and available for each package that contains an assembler file, or can be explicitly generated for use elsewhere via go tool compile -asmhdr go_asm.h ....

[ianlancetaylor]

If we are going to consider adding a go:packed magic comment that affects code generation, then I think we should also consider a magic comment that permits specifying the desired alignment of a type. That will permit people to align types to a wider boundary than would otherwise be used, which permits using vectorization writting in assembler or C. See #19057.

[josharian]

We expect that any assembler functions that depend on the layout of a struct argument or return value should be using unsafe.Offsetof to determine field offsets within a struct.

Does the assembler accept unsafe.Offsetof for FP offsets? I don’t recall ever seeing that in assembly code.

The good news is that vet checks these offsets, so breakage should be caught as a matter of course. (It’ll mean teaching go/types about the annotations, but that would need to happen anyway.)

Or do I misunderstand?

[josharian]

During the discussion of changing the Go ABI, several people expressed the opinion that if we're going to break a bunch of assembly code, we'd rather do that only once. I share that opinion.

Making this change and then an ABI change would mean breaking Go assembly twice.

I'd hate to gate this proposal on figuring out the ABI changes. What if instead, as a prerequisite for this change, we teach the Go assembler some way to express things like "first argument" or "offset of field F within struct S". Then we could update the assembly once to use these higher level constructs, and if we change the ABI later, if we've done our job well, no further assembly changes would be necessary. It'd also lower the cost of ABI experimentation.

[danscales]

We expect that any assembler functions that depend on the layout of a struct argument or return value should be using unsafe.Offsetof to determine field offsets within a struct.

Does the assembler accept unsafe.Offsetof for FP offsets? I don’t recall ever seeing that in assembly code.

I was thinking that you could have a Go init routine that stores the relevant values of unsafe.OffsetOf in some global variables that are accessed by the assembler routine. Also, Ian pointed out to me that in many situations you can use 'go tool compile -asmhdr go_asm.h ...' on the Go file that defines the type to get the relevant offsets written out to a go_asm.h file. I can clarify this in the proposal.

The good news is that vet checks these offsets, so breakage should be caught as a matter of course. (It’ll mean teaching go/types about the annotations, but that would need to happen anyway.)

Or do I misunderstand?

I don't really understand what you mean by 'vet checks these offsets' in this case. What vet rule is this? Or are you talking about the suggested new vet checks that I mention in the proposal?

Making this change and then an ABI change would mean breaking Go assembly twice.

As I understand it, the goal with introducing a new ABI would be to use it in Go code mainly, and not break existing assembly code (which would stay with the original Go ABI, referenced as ABI0 in
Austin's changes).

I do agree that this proposal could break some existing assembly code. I'm guessing that it might be quite minimal (but that may definitely be wrong), and certainly possibly breaking some assembler code is relevant to deciding about the benefits/drawbacks of this proposal.

[josharian]

I can clarify this in the proposal.

I think that that would be helpful.

I don't really understand what you mean by 'vet checks these offsets' in this case.

I was thinking of https://github.com/golang/tools/blob/master/go/analysis/passes/asmdecl/asmdecl.go

[beoran]

I hope that whatever change there is to the ABI or to struct layouts, that it does not make interfacing with the OS or with C code any harder than it is now. At best the ABI and struct layout stays as it is and any special directives only affect that when used, not by default.

The only reasons I consider worth while of to change the Go ABI would be to make C calls faster by getting rid of the segmented stack, for the rest I'm not sure what the benefits would be.

[bradfitz]

The other day I proposed adding a zero-width type (like unsafe.Packed) that could be embedded instead of a magic comment. (We do something similar with sync/cond.go:type noCopy struct{}.)

[rsc]

Note that it is critical that this proposal include a vet check to ensure that all places where we hand data structures to C/syscall/asm/DLL get marked as "packed". That gives us the benefit, after going through the work of marking all those places (helped by vet), of letting the compiler rearrange fields in unmarked structs, such as to fill in alignment-induced gaps with upcoming fields. (We've talked about doing this for a long time, but we held back because we didn't want to break compatibility with C/etc. If we're not compatible anyway, then we should make sure to get a benefit. Today, we rearrange fields to fill in gaps today by hand, which is not great.)

The exact annotation for how to mark "this struct is packed" is less important than the semantic change. We should probably decide "do we want to do this at all" first.

The alignment note that Ian suggested is another semantic change. That suggestion is to mark a specific type as having a specific alignment (anywhere a value of that type is represented in memory). That may or may not be separable from this issue, but if we think we want to do it at some point, it would be good to choose a marking scheme for packed/not that matches an eventual marking scheme for per-type overall alignment.

[beoran]

I think that perhaps, it's already too late to make this change, as there are hundreds if not thousands of Go projects out there that use C/syscall/asm/DLL with the assumption that the struct layout in Go is as it is today, without automatic rearrangements. While what we have now isn't all too great, it does work in practice, and I know that if I am careful, then I can manually lay out the Go struct in such a way that the kernel/C code/DLL can use it.

As an aside, while it is true that in this kind of low level situations, instead of a struct I could use a []byte in conjunction with "encoding/binary", this is not a very satisfactory solution due to the overhead of the function calls and the lack of convenience.

While letting the compiler automatically rearrange fields in a struct will save on some memory space, I don't see that as a benefit that is worth breaking millions of lines of working code over. Making such a change now truly will lead to an incompatible Go v2, which risks the same problem as python 3 had.

Rather than making such changes, I would specify and document how one can manually lay out a struct efficiently, and then make a tool that can rearrange structs to be more compact according to this documentation. Furthermore, I would be in favor of changes which make laying out a struct manually more easy or more precise.

Furthermore, a "go vet" check alone is not enough to fix this, we would also need a "go fix" for this so this can be fixed automatically. However, I suspect that either will be difficult to implement because exported structs can be used freely everywhere, so it is hard to see if a struct is involved in a situation where the compiler should not rearrange it.

I do agree that this issue is not separate from other alignment and packing issues. If changes are to be made, they should all be made together, to make the transition somewhat easier.

[aclements]

During the discussion of changing the Go ABI, several people expressed the opinion that if we're going to break a bunch of assembly code, we'd rather do that only once. I share that opinion.

Dan's change doesn't affect argument layouts, so no FP offsets would change in assembly code. The prototype implementation actually separates the concerns of struct layout from argument frame layout in order to keep this working. Since we have the ABI0/ABIInternal split, we could in principle use struct-style layout for Go calls while still keeping the existing alignment rules for assembly calls (though I don't know if that would be worthwhile).

The one place that it does potentially affect assembly code is if the assembly hard-codes offsets into Go structures. Our hope is that any assembly that is using struct offsets is just including go_asm.h and using the symbolic values already created by the compiler. (You don't even have to use "go tool compile -asmhdr go_asm.h" like Dan mentioned above; the go tool does this automatically.)

[aclements]

A few points that have been made in in-person discussions about this proposal:

• Some architectures will trap on unaligned access. We can either say that's up to the user to avoid, or have the compiler emit the necessary code to avoid the unaligned access. GCC, for example, will load unaligned fields one byte at a time if it has to.

• @dr2chase pointed out one reason you may need both a "packed" annotation and an "alignment" annotation on the same struct. If "packed" has the effect of making all fields alignment 1, then the whole struct has alignment 1 and you have no control over what happens if that struct is embedded in another type. In particular, you may be laying out a type carefully so that some fields are aligned, but that alignment may be broken when the type is put in a larger type. However, this can be handled if you can specify both that the struct is packed and explicitly specify its overall alignment.

• @mknyszek pointed out that the garbage collector requires that pointers be word-aligned. It would be unfortunate to say "you can't have pointers in a packed struct", so I think pointers need to be word-aligned even in packed structs (which also affects overall struct alignment). We can either make this happen silently, or we can say it's an error if a pointer in a packed struct doesn't already fall on a word boundary.

[aclements]

I think that perhaps, it's already too late to make this change, as there are hundreds if not thousands of Go projects out there that use C/syscall/asm/DLL with the assumption that the struct layout in Go is as it is today, without automatic rearrangements.

I personally think this is a significant overestimate, but of course, I don't have any data to back up that claim either. If we implement a vet check, we could at least automatically scan a large corpus and get a better sense.

While letting the compiler automatically rearrange fields in a struct will save on some memory space, I don't see that as a benefit that is worth breaking millions of lines of working code over. ... Rather than making such changes, I would specify and document how one can manually lay out a struct efficiently ...

Note that we're not currently proposing field rearrangement. This proposal isn't about saving memory at all; it's about addressing a persistent source of run-time crashes in configurations that are often poorly tested.

Furthermore, a "go vet" check alone is not enough to fix this, we would also need a "go fix" for this so this can be fixed automatically.

Yes, we've actually been talking about this. It probably wouldn't be a "go fix" just because "go fix" is built to make as few assumptions about the code as possible, but it could be a new flag to "go vet", since "go vet" can do the sorts of type and flow analysis that you want for this. We've been thinking about doing this for some other vet checks as well that have clear automatic fixes.