gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/tools/checklinkname/README.md (about)

     1  # `checklinkname` Analyzer
     2  
     3  `checklinkname` is an analyzer to provide rudimentary type-checking for
     4  `//go:linkname` directives. Since `//go:linkname` only affects linker behavior,
     5  there is no built-in type safety and it is the programmer's responsibility to
     6  ensure the types on either side are compatible.
     7  
     8  `checklinkname` helps with this by checking that uses match expectations, as
     9  defined in this package.
    10  
    11  `known.go` contains the set of known linkname targets. For most functions, we
    12  expect identical types on both sides of the linkname. In a few cases, the types
    13  may be slightly different (e.g., local redefinition of internal type). It is
    14  still the responsibility of the programmer to ensure the signatures in
    15  `known.go` are compatible and safe.
    16  
    17  ## Findings
    18  
    19  Here are the most common findings from this package, and how to resolve them.
    20  
    21  ### `runtime.foo signature got "BAR" want "BAZ"; stdlib type changed?`
    22  
    23  The definition of `runtime.foo` in the standard library does not match the
    24  expected type in `known.go`. This means that the function signature in the
    25  standard library changed.
    26  
    27  Addressing this will require creating a new linkname directive in a new Go
    28  version build-tagged in any packages using this symbol. Be sure to also check to
    29  ensure use with the new version is safe, as function constraints may have
    30  changed in addition to the signature.
    31  
    32  <!-- TODO(b/165820485): This isn't yet explicitly supported. -->
    33  
    34  `known.go` will also need to be updated to accept the new signature for the new
    35  version of Go.
    36  
    37  ### `Cannot find known symbol "runtime.foo"`
    38  
    39  The standard library has removed runtime.foo entirely. Handling is similar to
    40  above, except existing code must transition away from the symbol entirely (note
    41  that is may simply be renamed).
    42  
    43  ### `linkname to unknown symbol "mypkg.foo"; add this symbol to checklinkname.knownLinknames type-check against the remote type`
    44  
    45  A package has added a new linkname directive for a symbol not listed in
    46  `known.go`. Address this by adding a new entry for the target symbol. The
    47  `local` field should be the expected type in your package, while `remote` should
    48  be expected type in the remote package (e.g., in the standard library). These
    49  are typically identical, in which case `remote` can be omitted.
    50  
    51  ### `usage: //go:linkname localname [linkname]`
    52  
    53  Malformed `//go:linkname` directive. This should be accompanied by a build
    54  failure in the package.