df5d377521
They are no-ops, so the standard rule works fine. PiperOrigin-RevId: 268776264 |
||
---|---|---|
.. | ||
analysis | ||
gomarshal | ||
marshal | ||
test | ||
BUILD | ||
README.md | ||
defs.bzl | ||
main.go |
README.md
This package implements the go_marshal utility.
Overview
go_marshal
is a code generation utility similar to go_stateify
for
automatically generating code to marshal go data structures to memory.
go_marshal
attempts to improve on binary.Write
and the sentry's
binary.Marshal
by moving the go runtime reflection necessary to marshal a
struct to compile-time.
go_marshal
automatically generates implementations for abi.Marshallable
and
safemem.{Reader,Writer}
. Call-sites for serialization (typically syscall
implementations) can directly invoke safemem.Reader.ReadToBlocks
and
safemem.Writer.WriteFromBlocks
. Data structures that require custom
serialization will have manual implementations for these interfaces.
Data structures can be flagged for code generation by adding a struct-level
comment // +marshal
.
Usage
See defs.bzl
: two new rules are provided, go_marshal
and go_library
.
The recommended way to generate a go library with marshalling is to use the
go_library
with mostly identical configuration as the native go_library rule.
load("<PKGPATH>/gvisor/tools/go_marshal:defs.bzl", "go_library")
go_library(
name = "foo",
srcs = ["foo.go"],
)
Under the hood, the go_marshal
rule is used to generate a file that will
appear in a Go target; the output file should appear explicitly in a srcs list.
For example (note that the above is the preferred method):
load("<PKGPATH>/gvisor/tools/go_marshal:defs.bzl", "go_marshal")
go_marshal(
name = "foo_abi",
srcs = ["foo.go"],
out = "foo_abi.go",
package = "foo",
)
go_library(
name = "foo",
srcs = [
"foo.go",
"foo_abi.go",
],
deps = [
"<PKGPATH>/gvisor/pkg/abi",
"<PKGPATH>/gvisor/pkg/sentry/safemem/safemem",
"<PKGPATH>/gvisor/pkg/sentry/usermem/usermem",
],
)
As part of the interface generation, go_marshal
also generates some tests for
sanity checking the struct definitions for potential alignment issues, and a
simple round-trip test through Marshal/Unmarshal to verify the implementation.
These tests use reflection to verify properties of the ABI struct, and should be
considered part of the generated interfaces (but are too expensive to execute at
runtime). Ensure these tests run at some point.
$ cat BUILD
load("<PKGPATH>/gvisor/tools/go_marshal:defs.bzl", "go_library")
go_library(
name = "foo",
srcs = ["foo.go"],
)
$ blaze build :foo
$ blaze query ...
<path-to-dir>:foo_abi_autogen
<path-to-dir>:foo_abi_autogen_test
$ blaze test :foo_abi_autogen_test
<test-output>
Restrictions
Not all valid go type definitions can be used with go_marshal
. go_marshal
is
intended for ABI structs, which have these additional restrictions:
-
At the moment,
go_marshal
only supports struct declarations. -
Structs are marshalled as packed types. This means no implicit padding is inserted between fields shorter than the platform register size. For alignment, manually insert padding fields.
-
Structs used with
go_marshal
must have a compile-time static size. This means no dynamically sizes fields like slices or strings. Use statically sized array (byte arrays for strings) instead. -
No pointers, channel, map or function pointer fields, and no fields that are arrays of these types. These don't make sense in an ABI data structure.
-
We could support opaque pointers as
uintptr
, but this is currently not implemented. Implementing this would require handling the architecture dependent native pointer size. -
Fields must either be a primitive integer type (
byte
,[u]int{8,16,32,64}
), or of a type that implements abi.Marshallable. -
int
anduint
fields are not allowed. Use an explicitly-sized numeric type. -
float*
fields are currently not supported, but could be if necessary.
Appendix
Working with Non-Packed Structs
ABI structs must generally be packed types, meaning they should have no implicit
padding between short fields. However, if a field is tagged
marshal:"unaligned"
, go_marshal
will fall back to a safer but slower
mechanism to deal with potentially unaligned fields.
Note that the non-packed property is inheritted by any other struct that embeds
this struct, since the go_marshal
tool currently can't reason about alignments
for embedded structs that are not aligned.
Because of this, it's generally best to avoid using marshal:"unaligned"
and
insert explicit padding fields instead.
Debugging go_marshal
To enable debugging output from the go marshal tool, pass the -debug
flag to
the tool. When using the build rules from above, add a debug = True
field to
the build rule like this:
load("<PKGPATH>/gvisor/tools/go_marshal:defs.bzl", "go_library")
go_library(
name = "foo",
srcs = ["foo.go"],
debug = True,
)
Modifying the go_marshal
Tool
The following are some guidelines for modifying the go_marshal
tool:
-
The
go_marshal
tool currently does a single pass over all types requesting code generation, in arbitrary order. This means the generated code can't directly obtain information about embedded marshallable types at compile-time. One way to work around this restriction is to add a new Marshallable interface method providing this piece of information, and calling it from the generated code. Use this sparingly, as we want to rely on compile-time information as much as possible for performance. -
No runtime reflection in the code generated for the marshallable interface. The entire point of the tool is to avoid runtime reflection. The generated tests may use reflection.