Add checklocks analyzer.

This validates that struct fields if annotated with "// checklocks:mu" where
"mu" is a mutex field in the same struct then access to the field is only
done with "mu" locked.

All types that are guarded by a mutex must be annotated with

// +checklocks:<mutex field name>

For more details please refer to README.md.

PiperOrigin-RevId: 360729328

5 files changed, 1289 insertions, 0 deletions

diff --git a/tools/checklocks/BUILD b/tools/checklocks/BUILD
new file mode 100644
index 000000000..7d4c63dc7
--- /dev/null
+++ b/tools/checklocks/BUILD
@@ -0,0 +1,16 @@
+load("//tools:defs.bzl", "go_library")
+
+package(licenses = ["notice"])
+
+go_library(
+    name = "checklocks",
+    srcs = ["checklocks.go"],
+    nogo = False,
+    visibility = ["//tools/nogo:__subpackages__"],
+    deps = [
+        "//pkg/log",
+        "@org_golang_x_tools//go/analysis:go_default_library",
+        "@org_golang_x_tools//go/analysis/passes/buildssa:go_default_library",
+        "@org_golang_x_tools//go/ssa:go_default_library",
+    ],
+)
diff --git a/tools/checklocks/README.md b/tools/checklocks/README.md
new file mode 100644
index 000000000..dfb0275ab
--- /dev/null
+++ b/tools/checklocks/README.md
@@ -0,0 +1,142 @@
+# CheckLocks Analyzer
+
+<!--* freshness: { owner: 'gvisor-eng' reviewed: '2020-10-05' } *-->
+
+Checklocks is a nogo analyzer that at compile time uses Go's static analysis
+tools to identify and flag cases where a field that is guarded by a mutex in the
+same struct is accessed outside of a mutex lock.
+
+The analyzer relies on explicit '// +checklocks:<mutex-name>' kind of
+annotations to identify fields that should be checked for access.
+
+Individual struct members may be protected by annotations that indicate how they
+must be accessed. These annotations are of the form:
+
+```go
+type foo struct {
+    mu sync.Mutex
+    // +checklocks:mu
+    bar int
+
+    foo int  // No annotation on foo means it's not guarded by mu.
+
+    secondMu sync.Mutex
+
+    // Multiple annotations indicate that both must be held but the
+    // checker does not assert any lock ordering.
+    // +checklocks:secondMu
+    // +checklocks:mu
+    foobar int
+}
+```
+
+The checklocks annotation may also apply to functions. For example:
+
+```go
+// +checklocks:f.mu
+func (f *foo) doThingLocked() { }
+```
+
+This will check that the "f.mu" is locked for any calls, where possible.
+
+In case of functions which initialize structs that may have annotations one can
+use the following annotation on the function to disable reporting by the lock
+checker. The lock checker will still track any mutexes acquired or released but
+won't report any failures for this function for unguarded field access.
+
+```go
+// +checklocks:ignore
+func newXXX() *X {
+...
+}
+```
+
+***The checker treats both 'sync.Mutex' and 'sync.RWMutex' identically, i.e, as
+a sync.Mutex. The checker does not distinguish between read locks vs. exclusive
+locks and treats all locks as exclusive locks***.
+
+For cases the checker is able to correctly handle today please see test/test.go.
+
+The checklocks check also flags any invalid annotations where the mutex
+annotation refers either to something that is not a 'sync.Mutex' or
+'sync.RWMutex' or where the field does not exist at all. This will prevent the
+annotations from becoming stale over time as fields are renamed, etc.
+
+# Currently not supported
+
+1.  The analyzer does not correctly handle deferred functions. e.g The following
+    code is not correctly checked by the analyzer. The defer call is never
+    evaluated. As a result if the lock was to be say unlocked twice via deferred
+    functions it would not be caught by the analyzer.
+
+    Similarly deferred anonymous functions are not evaluated either.
+
+```go
+type A struct {
+  mu sync.Mutex
+
+  // +checklocks:mu
+  x int
+}
+
+func abc() {
+  var a A
+  a.mu.Lock()
+  defer a.mu.Unlock()
+  defer a.mu.Unlock()
+  a.x = 1
+}
+```
+
+1.  Anonymous functions are not correctly evaluated. The analyzer does not
+    currently support specifying annotations on anonymous functions as a result
+    evaluation of a function that accesses protected fields will fail.
+
+```go
+type A struct {
+  mu sync.Mutex
+
+  // +checklocks:mu
+  x int
+}
+
+func abc() {
+  var a A
+  f := func()  { a.x = 1 }  <=== This line will be flagged by analyzer
+  a.mu.Lock()
+  f()
+  a.mu.Unlock()
+}
+
+```
+
+# Explicitly Not Supported
+
+1.  Checking for embedded mutexes as sync.Locker rather than directly as
+    'sync.Mutex'. In other words, the checker will not track mutex Lock and
+    Unlock() methods where the mutex is behind an interface dispatch.
+
+An example that we won't handle is shown below (this in fact will fail to
+build):
+
+```go
+type A struct {
+  mu sync.Locker
+
+  // +checklocks:mu
+  x int
+}
+
+func abc() {
+   mu sync.Mutex
+   a := A{mu: &mu}
+   a.x = 1 // This won't be flagged by copylocks checker.
+}
+
+```
+
+1.  The checker will not support guards on anything other than the cases
+    described above. For example, global mutexes cannot be referred to by
+    checklocks. Only struct members can be used.
+
+2.  The checker will not support checking for lock ordering violations.
diff --git a/tools/checklocks/checklocks.go b/tools/checklocks/checklocks.go
new file mode 100644
index 000000000..4ec2918f6
--- /dev/null
+++ b/tools/checklocks/checklocks.go
@@ -0,0 +1,761 @@
+// Copyright 2020 The gVisor Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package checklocks performs lock analysis to identify and flag unprotected
+// access to field annotated with a '// +checklocks:<mutex-name>' annotation.
+//
+// For detailed ussage refer to README.md in the same directory.
+package checklocks
+
+import (
+	"bytes"
+	"fmt"
+	"go/ast"
+	"go/token"
+	"go/types"
+	"reflect"
+	"regexp"
+	"strconv"
+	"strings"
+
+	"golang.org/x/tools/go/analysis"
+	"golang.org/x/tools/go/analysis/passes/buildssa"
+	"golang.org/x/tools/go/ssa"
+	"gvisor.dev/gvisor/pkg/log"
+)
+
+const (
+	checkLocksAnnotation = "// +checklocks:"
+	checkLocksIgnore     = "// +checklocksignore"
+	checkLocksFail       = "// +checklocksfail"
+)
+
+// Analyzer is the main entrypoint.
+var Analyzer = &analysis.Analyzer{
+	Name:      "checklocks",
+	Doc:       "checks lock preconditions on functions and fields",
+	Run:       run,
+	Requires:  []*analysis.Analyzer{buildssa.Analyzer},
+	FactTypes: []analysis.Fact{(*lockFieldFacts)(nil), (*lockFunctionFacts)(nil)},
+}
+
+// lockFieldFacts apply on every struct field protected by a lock or that is a
+// lock.
+type lockFieldFacts struct {
+	// GuardedBy tracks the names and field numbers that guard this field.
+	GuardedBy map[string]int
+
+	// IsMutex is true if the field is of type sync.Mutex.
+	IsMutex bool
+
+	// IsRWMutex is true if the field is of type sync.RWMutex.
+	IsRWMutex bool
+
+	// FieldNumber is the number of this field in the struct.
+	FieldNumber int
+}
+
+// AFact implements analysis.Fact.AFact.
+func (*lockFieldFacts) AFact() {}
+
+type functionGuard struct {
+	// ParameterNumber is the index of the object that contains the guarding mutex.
+	// This is required during SSA analysis as field names and parameters names are
+	// not available in SSA. For example, from the example below ParameterNumber would
+	// be 1 and FieldNumber would correspond to the field number of 'mu' within b's type.
+	//
+	// //+checklocks:b.mu
+	// func (a *A) method(b *B, c *C) {
+	//   ...
+	// }
+	ParameterNumber int
+
+	// FieldNumber is the field index of the mutex in the parameter's struct
+	// type. Refer to example above for more details.
+	FieldNumber int
+}
+
+// lockFunctionFacts apply on every method.
+type lockFunctionFacts struct {
+	// GuardedBy tracks the names and number of parameter (including receiver)
+	// lockFuncfields that guard calls to this function.
+	// The key is the name specified in the checklocks annotation. e.g given
+	// the following code.
+	// ```
+	// type A struct {
+	//   mu sync.Mutex
+	//   a int
+	// }
+	//
+	// // +checklocks:a.mu
+	// func xyz(a *A) {..}
+	// ```
+	//
+	// '`+checklocks:a.mu' will result in an entry in this map as shown below.
+	// GuardedBy: {"a.mu" => {ParameterNumber: 0, FieldNumber: 0}
+	GuardedBy map[string]functionGuard
+}
+
+// AFact implements analysis.Fact.AFact.
+func (*lockFunctionFacts) AFact() {}
+
+type positionKey string
+
+// toPositionKey converts from a token.Position to a key we can use to track
+// failures as the position of the failure annotation is not the same as the
+// position of the actual failure (different column/offsets). Hence we ignore
+// these fields and only use the file/line numbers to track failures.
+func toPositionKey(position token.Position) positionKey {
+	return positionKey(fmt.Sprintf("%s:%d", position.Filename, position.Line))
+}
+
+type failData struct {
+	pos   token.Pos
+	count int
+}
+
+func (f failData) String() string {
+	return fmt.Sprintf("pos: %d, count: %d", f.pos, f.count)
+}
+
+type passContext struct {
+	pass *analysis.Pass
+
+	// exemptions tracks functions that should be exempted from lock checking due
+	// to '// +checklocksignore' annotation.
+	exemptions map[types.Object]struct{}
+
+	failures map[positionKey]*failData
+}
+
+var (
+	mutexRE   = regexp.MustCompile("((.*/)|^)sync.(CrossGoroutineMutex|Mutex)")
+	rwMutexRE = regexp.MustCompile("((.*/)|^)sync.(CrossGoroutineRWMutex|RWMutex)")
+)
+
+func (pc *passContext) extractFieldAnnotations(field *ast.Field, fieldType *types.Var) *lockFieldFacts {
+	s := fieldType.Type().String()
+	// We use HasSuffix below because fieldType can be fully qualified with the
+	// package name eg for the gvisor sync package mutex fields have the type:
+	// "<package path>/sync/sync.Mutex"
+	switch {
+	case mutexRE.Match([]byte(s)):
+		return &lockFieldFacts{IsMutex: true}
+	case rwMutexRE.Match([]byte(s)):
+		return &lockFieldFacts{IsRWMutex: true}
+	default:
+	}
+	if field.Doc == nil {
+		return nil
+	}
+	fieldFacts := &lockFieldFacts{GuardedBy: make(map[string]int)}
+	for _, l := range field.Doc.List {
+		if strings.HasPrefix(l.Text, checkLocksAnnotation) {
+			guardName := strings.TrimPrefix(l.Text, checkLocksAnnotation)
+			if _, ok := fieldFacts.GuardedBy[guardName]; ok {
+				pc.pass.Reportf(field.Pos(), "annotation %s specified more than once.", l.Text)
+				continue
+			}
+			fieldFacts.GuardedBy[guardName] = -1
+		}
+	}
+
+	return fieldFacts
+}
+
+func (pc *passContext) findField(v ssa.Value, fieldNumber int) types.Object {
+	structType, ok := v.Type().Underlying().(*types.Struct)
+	if !ok {
+		structType = v.Type().Underlying().(*types.Pointer).Elem().Underlying().(*types.Struct)
+	}
+	return structType.Field(fieldNumber)
+}
+
+// findAndExportStructFacts finds any struct fields that are annotated with the
+// "// +checklocks:" annotation and exports relevant facts about the fields to
+// be used in later analysis.
+func (pc *passContext) findAndExportStructFacts(ss *ast.StructType, structType *types.Struct) {
+	type fieldRef struct {
+		fieldObj *types.Var
+		facts    *lockFieldFacts
+	}
+	mutexes := make(map[string]*fieldRef)
+	rwMutexes := make(map[string]*fieldRef)
+	guardedFields := make(map[string]*fieldRef)
+	for i, field := range ss.Fields.List {
+		fieldObj := structType.Field(i)
+		fieldFacts := pc.extractFieldAnnotations(field, fieldObj)
+		if fieldFacts == nil {
+			continue
+		}
+		fieldFacts.FieldNumber = i
+
+		ref := &fieldRef{fieldObj, fieldFacts}
+		if fieldFacts.IsMutex {
+			mutexes[fieldObj.Name()] = ref
+		}
+		if fieldFacts.IsRWMutex {
+			rwMutexes[fieldObj.Name()] = ref
+		}
+		if len(fieldFacts.GuardedBy) != 0 {
+			guardedFields[fieldObj.Name()] = ref
+		}
+	}
+
+	// Export facts about all mutexes.
+	for _, f := range mutexes {
+		pc.pass.ExportObjectFact(f.fieldObj, f.facts)
+	}
+	// Export facts about all rwMutexes.
+	for _, f := range rwMutexes {
+		pc.pass.ExportObjectFact(f.fieldObj, f.facts)
+	}
+
+	// Validate that guarded fields annotations refer to actual mutexes or
+	// rwMutexes in the struct.
+	for _, gf := range guardedFields {
+		for g := range gf.facts.GuardedBy {
+			if f, ok := mutexes[g]; ok {
+				gf.facts.GuardedBy[g] = f.facts.FieldNumber
+			} else if f, ok := rwMutexes[g]; ok {
+				gf.facts.GuardedBy[g] = f.facts.FieldNumber
+			} else {
+				pc.maybeFail(gf.fieldObj.Pos(), false /* isExempted */, "invalid mutex guard, no such mutex %s in struct %s", g, structType.String())
+				continue
+			}
+			// Export guarded field fact.
+			pc.pass.ExportObjectFact(gf.fieldObj, gf.facts)
+		}
+	}
+}
+
+func (pc *passContext) findAndExportFuncFacts(d *ast.FuncDecl) {
+	log.Debugf("finding and exporting function facts\n")
+	// for each function definition, check for +checklocks:mu annotation, which
+	// means that the function must be called with that lock held.
+	fnObj := pc.pass.TypesInfo.ObjectOf(d.Name)
+	funcFacts := lockFunctionFacts{GuardedBy: make(map[string]functionGuard)}
+	var (
+		ignore    bool
+		ignorePos token.Pos
+	)
+
+outerLoop:
+	for _, l := range d.Doc.List {
+		if strings.HasPrefix(l.Text, checkLocksIgnore) {
+			pc.exemptions[fnObj] = struct{}{}
+			ignore = true
+			ignorePos = l.Pos()
+			continue
+		}
+		if strings.HasPrefix(l.Text, checkLocksAnnotation) {
+			guardName := strings.TrimPrefix(l.Text, checkLocksAnnotation)
+			if _, ok := funcFacts.GuardedBy[guardName]; ok {
+				pc.pass.Reportf(l.Pos(), "annotation %s specified more than once.", l.Text)
+				continue
+			}
+
+			found := false
+			x := strings.Split(guardName, ".")
+			if len(x) != 2 {
+				pc.pass.Reportf(l.Pos(), "checklocks mutex annotation should be of the form 'a.b'")
+				continue
+			}
+			paramName, fieldName := x[0], x[1]
+			log.Debugf("paramName: %s, fieldName: %s", paramName, fieldName)
+			var paramList []*ast.Field
+			if d.Recv != nil {
+				paramList = append(paramList, d.Recv.List...)
+			}
+			if d.Type.Params != nil {
+				paramList = append(paramList, d.Type.Params.List...)
+			}
+			for paramNum, field := range paramList {
+				log.Debugf("field names: %+v", field.Names)
+				if len(field.Names) == 0 {
+					log.Debugf("skipping because parameter is unnamed", paramName)
+					continue
+				}
+				nameExists := false
+				for _, name := range field.Names {
+					if name.Name == paramName {
+						nameExists = true
+					}
+				}
+				if !nameExists {
+					log.Debugf("skipping because parameter name(s) does not match : %s", paramName)
+					continue
+				}
+				ptrType, ok := pc.pass.TypesInfo.TypeOf(field.Type).Underlying().(*types.Pointer)
+				if !ok {
+					// Since mutexes cannot be copied we only care about parameters that
+					// are pointer types when checking for guards.
+					pc.pass.Reportf(l.Pos(), "annotation %s incorrectly specified, parameter name does not refer to a pointer type", l.Text)
+					continue outerLoop
+				}
+
+				structType, ok := ptrType.Elem().Underlying().(*types.Struct)
+				if !ok {
+					pc.pass.Reportf(l.Pos(), "annotation %s incorrectly specified, parameter name does not refer to a pointer to a struct", l.Text)
+					continue outerLoop
+				}
+
+				for i := 0; i < structType.NumFields(); i++ {
+					if structType.Field(i).Name() == fieldName {
+						var fieldFacts lockFieldFacts
+						pc.pass.ImportObjectFact(structType.Field(i), &fieldFacts)
+						if !fieldFacts.IsMutex && !fieldFacts.IsRWMutex {
+							pc.pass.Reportf(l.Pos(), "field %s of param %s is not a mutex or an rwmutex", paramName, structType.Field(i))
+							continue outerLoop
+						}
+						funcFacts.GuardedBy[guardName] = functionGuard{ParameterNumber: paramNum, FieldNumber: i}
+						found = true
+						continue outerLoop
+					}
+				}
+				if !found {
+					pc.pass.Reportf(l.Pos(), "annotation refers to a non-existent field %s in %s", guardName, structType)
+					continue outerLoop
+				}
+			}
+			if !found {
+				pc.pass.Reportf(l.Pos(), "annotation refers to a non-existent parameter %s", paramName)
+			}
+		}
+	}
+
+	if len(funcFacts.GuardedBy) == 0 {
+		return
+	}
+	if ignore {
+		pc.pass.Reportf(ignorePos, "//+checklocksignore cannot be specified with other annotations on the function")
+	}
+	funcObj, ok := pc.pass.TypesInfo.Defs[d.Name].(*types.Func)
+	if !ok {
+		panic(fmt.Sprintf("function type information missing for %+v", d))
+	}
+	log.Debugf("export fact for d: %+v, funcObj: %+v, funcFacts: %+v\n", d, funcObj, funcFacts)
+	pc.pass.ExportObjectFact(funcObj, &funcFacts)
+}
+
+type mutexState struct {
+	// lockedMutexes is used to track which mutexes in a given struct are
+	// currently locked using the field number of the mutex as the key.
+	lockedMutexes map[int]struct{}
+}
+
+// locksHeld tracks all currently held locks.
+type locksHeld struct {
+	locks map[ssa.Value]mutexState
+}
+
+// Same returns true if the locks held by other and l are the same.
+func (l *locksHeld) Same(other *locksHeld) bool {
+	return reflect.DeepEqual(l.locks, other.locks)
+}
+
+// Copy creates a copy of all the lock state held by l.
+func (l *locksHeld) Copy() *locksHeld {
+	out := &locksHeld{locks: make(map[ssa.Value]mutexState)}
+	for ssaVal, mState := range l.locks {
+		newLM := make(map[int]struct{})
+		for k, v := range mState.lockedMutexes {
+			newLM[k] = v
+		}
+		out.locks[ssaVal] = mutexState{lockedMutexes: newLM}
+	}
+	return out
+}
+
+func isAlias(first, second ssa.Value) bool {
+	if first == second {
+		return true
+	}
+	switch x := first.(type) {
+	case *ssa.Field:
+		if y, ok := second.(*ssa.Field); ok {
+			return x.Field == y.Field && isAlias(x.X, y.X)
+		}
+	case *ssa.FieldAddr:
+		if y, ok := second.(*ssa.FieldAddr); ok {
+			return x.Field == y.Field && isAlias(x.X, y.X)
+		}
+	case *ssa.Index:
+		if y, ok := second.(*ssa.Index); ok {
+			return isAlias(x.Index, y.Index) && isAlias(x.X, y.X)
+		}
+	case *ssa.IndexAddr:
+		if y, ok := second.(*ssa.IndexAddr); ok {
+			return isAlias(x.Index, y.Index) && isAlias(x.X, y.X)
+		}
+	case *ssa.UnOp:
+		if y, ok := second.(*ssa.UnOp); ok {
+			return isAlias(x.X, y.X)
+		}
+	}
+	return false
+}
+
+// checkBasicBlocks traverses the control flow graph starting at a set of given
+// block and checks each instruction for allowed operations.
+//
+// funcFact are the exported facts for the enclosing function for these basic
+// blocks.
+func (pc *passContext) checkBasicBlocks(blocks []*ssa.BasicBlock, recoverBlock *ssa.BasicBlock, fn *ssa.Function, funcFact lockFunctionFacts) {
+	if len(blocks) == 0 {
+		return
+	}
+
+	// mutexes is used to track currently locked sync.Mutexes/sync.RWMutexes for a
+	// given *struct identified by ssa.Value.
+	seen := make(map[*ssa.BasicBlock]*locksHeld)
+	var scan func(block *ssa.BasicBlock, parent *locksHeld)
+	scan = func(block *ssa.BasicBlock, parent *locksHeld) {
+		_, isExempted := pc.exemptions[block.Parent().Object()]
+		if oldLocksHeld, ok := seen[block]; ok {
+			if oldLocksHeld.Same(parent) {
+				return
+			}
+			pc.maybeFail(block.Instrs[0].Pos(), isExempted, "failure entering a block %+v with different sets of lock held, oldLocks: %+v, parentLocks: %+v", block, oldLocksHeld, parent)
+			return
+		}
+		seen[block] = parent
+		var lh = parent.Copy()
+		for _, inst := range block.Instrs {
+			pc.checkInstruction(inst, isExempted, lh)
+		}
+		for _, b := range block.Succs {
+			scan(b, lh)
+		}
+	}
+
+	// Initialize lh with any preconditions that require locks to be held for the
+	// method to be invoked.
+	lh := &locksHeld{locks: make(map[ssa.Value]mutexState)}
+	for _, fg := range funcFact.GuardedBy {
+		// The first is the method object itself so we skip that when looking
+		// for receiver/function parameters.
+		log.Debugf("fn: %s, fn.Operands() == %+v", fn, fn.Operands(nil))
+		r := fn.Params[fg.ParameterNumber]
+		guardObj := findField(r, fg.FieldNumber)
+		var fieldFacts lockFieldFacts
+		pc.pass.ImportObjectFact(guardObj, &fieldFacts)
+		if fieldFacts.IsMutex || fieldFacts.IsRWMutex {
+			m, ok := lh.locks[r]
+			if !ok {
+				m = mutexState{lockedMutexes: make(map[int]struct{})}
+				lh.locks[r] = m
+			}
+			m.lockedMutexes[fieldFacts.FieldNumber] = struct{}{}
+		} else {
+			panic(fmt.Sprintf("function: %+v has an invalid guard that is not a mutex: %+v", fn, guardObj))
+		}
+	}
+
+	// Start scanning from the first basic block.
+	scan(blocks[0], lh)
+
+	// Validate that all blocks were touched.
+	for _, b := range blocks {
+		if _, ok := seen[b]; !ok && b != recoverBlock {
+			panic(fmt.Sprintf("block %+v was not visited during checkBasicBlocks", b))
+		}
+	}
+}
+
+func (pc *passContext) checkInstruction(inst ssa.Instruction, isExempted bool, lh *locksHeld) {
+	log.Debugf("checking instruction: %s, isExempted: %t", inst, isExempted)
+	switch x := inst.(type) {
+	case *ssa.Field:
+		pc.checkFieldAccess(inst, x.X, x.Field, isExempted, lh)
+	case *ssa.FieldAddr:
+		pc.checkFieldAccess(inst, x.X, x.Field, isExempted, lh)
+	case *ssa.Call:
+		pc.checkFunctionCall(x, isExempted, lh)
+	}
+}
+
+func findField(v ssa.Value, field int) types.Object {
+	structType, ok := v.Type().Underlying().(*types.Struct)
+	if !ok {
+		ptrType, ok := v.Type().Underlying().(*types.Pointer)
+		if !ok {
+			return nil
+		}
+		structType = ptrType.Elem().Underlying().(*types.Struct)
+	}
+	return structType.Field(field)
+}
+
+func (pc *passContext) maybeFail(pos token.Pos, isExempted bool, fmtStr string, args ...interface{}) {
+	posKey := toPositionKey(pc.pass.Fset.Position(pos))
+	log.Debugf("maybeFail: pos: %d, positionKey: %s", pos, posKey)
+	if fData, ok := pc.failures[posKey]; ok {
+		fData.count--
+		if fData.count == 0 {
+			delete(pc.failures, posKey)
+		}
+		return
+	}
+	if !isExempted {
+		pc.pass.Reportf(pos, fmt.Sprintf(fmtStr, args...))
+	}
+}
+
+func (pc *passContext) checkFieldAccess(inst ssa.Instruction, structObj ssa.Value, field int, isExempted bool, lh *locksHeld) {
+	var fieldFacts lockFieldFacts
+	fieldObj := findField(structObj, field)
+	pc.pass.ImportObjectFact(fieldObj, &fieldFacts)
+	log.Debugf("fieldObj: %s, fieldFacts: %+v", fieldObj, fieldFacts)
+	for _, guardFieldNumber := range fieldFacts.GuardedBy {
+		guardObj := findField(structObj, guardFieldNumber)
+		var guardfieldFacts lockFieldFacts
+		pc.pass.ImportObjectFact(guardObj, &guardfieldFacts)
+		log.Debugf("guardObj: %s, guardFieldFacts: %+v", guardObj, guardfieldFacts)
+		if guardfieldFacts.IsMutex || guardfieldFacts.IsRWMutex {
+			log.Debugf("guard is a mutex")
+			m, ok := lh.locks[structObj]
+			if !ok {
+				pc.maybeFail(inst.Pos(), isExempted, "invalid field access, %s must be locked when accessing %s", guardObj.Name(), fieldObj.Name())
+				continue
+			}
+			if _, ok := m.lockedMutexes[guardfieldFacts.FieldNumber]; !ok {
+				pc.maybeFail(inst.Pos(), isExempted, "invalid field access, %s must be locked when accessing %s", guardObj.Name(), fieldObj.Name())
+			}
+		} else {
+			panic("incorrect guard that is not a mutex or an RWMutex")
+		}
+	}
+}
+
+func (pc *passContext) checkFunctionCall(call *ssa.Call, isExempted bool, lh *locksHeld) {
+	// See: https://godoc.org/golang.org/x/tools/go/ssa#CallCommon
+	//
+	// 1. "call" mode: when Method is nil (!IsInvoke), a CallCommon represents an ordinary
+	//  function call of the value in Value, which may be a *Builtin, a *Function or any
+	//  other value of kind 'func'.
+	//
+	// 	Value may be one of:
+	// (a) a *Function, indicating a statically dispatched call
+	// to a package-level function, an anonymous function, or
+	// a method of a named type.
+	//
+	// (b) a *MakeClosure, indicating an immediately applied
+	// function literal with free variables.
+	//
+	// (c) a *Builtin, indicating a statically dispatched call
+	// to a built-in function.
+	//
+	// (d) any other value, indicating a dynamically dispatched
+	//     function call.
+	fn, ok := call.Common().Value.(*ssa.Function)
+	if !ok {
+		return
+	}
+
+	if fn.Object() == nil {
+		log.Warningf("fn w/ nil Object is: %+v", fn)
+		return
+	}
+
+	// Check if the function should be called with any locks held.
+	var funcFact lockFunctionFacts
+	pc.pass.ImportObjectFact(fn.Object(), &funcFact)
+	if len(funcFact.GuardedBy) > 0 {
+		for _, fg := range funcFact.GuardedBy {
+			// The first is the method object itself so we skip that when looking
+			// for receiver/function parameters.
+			r := (*call.Value().Operands(nil)[fg.ParameterNumber+1])
+			guardObj := findField(r, fg.FieldNumber)
+			if guardObj == nil {
+				log.Infof("guardObj nil but funcFact: %+v", funcFact)
+				continue
+			}
+			var fieldFacts lockFieldFacts
+			pc.pass.ImportObjectFact(guardObj, &fieldFacts)
+			if fieldFacts.IsMutex || fieldFacts.IsRWMutex {
+				heldMutexes, ok := lh.locks[r]
+				if !ok {
+					log.Debugf("fn: %s, funcFact: %+v", fn, funcFact)
+					pc.maybeFail(call.Pos(), isExempted, "invalid function call %s must be held", guardObj.Name())
+					continue
+				}
+				if _, ok := heldMutexes.lockedMutexes[fg.FieldNumber]; !ok {
+					log.Debugf("fn: %s, funcFact: %+v", fn, funcFact)
+					pc.maybeFail(call.Pos(), isExempted, "invalid function call %s must be held", guardObj.Name())
+				}
+			} else {
+				panic(fmt.Sprintf("function: %+v has an invalid guard that is not a mutex: %+v", fn, guardObj))
+			}
+		}
+	}
+
+	// Check if it's a method dispatch for something in the sync package.
+	// See: https://godoc.org/golang.org/x/tools/go/ssa#Function
+	if fn.Package() != nil && fn.Package().Pkg.Name() == "sync" && fn.Signature.Recv() != nil {
+		r, ok := call.Common().Args[0].(*ssa.FieldAddr)
+		if !ok {
+			return
+		}
+		guardObj := findField(r.X, r.Field)
+		var fieldFacts lockFieldFacts
+		pc.pass.ImportObjectFact(guardObj, &fieldFacts)
+		if fieldFacts.IsMutex || fieldFacts.IsRWMutex {
+			switch fn.Name() {
+			case "Lock", "RLock":
+				obj := r.X
+				m := mutexState{lockedMutexes: make(map[int]struct{})}
+				for k, v := range lh.locks {
+					if isAlias(r.X, k) {
+						obj = k
+						m = v
+					}
+				}
+				if _, ok := m.lockedMutexes[r.Field]; ok {
+					// Double locking a mutex that is already locked.
+					pc.maybeFail(call.Pos(), isExempted, "trying to a lock %s when already locked", guardObj.Name())
+					return
+				}
+				m.lockedMutexes[r.Field] = struct{}{}
+				lh.locks[obj] = m
+			case "Unlock", "RUnlock":
+				// Find the associated locker object.
+				var (
+					obj ssa.Value
+					m   mutexState
+				)
+				for k, v := range lh.locks {
+					if isAlias(r.X, k) {
+						obj = k
+						m = v
+						break
+					}
+				}
+				if _, ok := m.lockedMutexes[r.Field]; !ok {
+					pc.maybeFail(call.Pos(), isExempted, "trying to unlock a mutex %s that is already unlocked", guardObj.Name())
+					return
+				}
+				delete(m.lockedMutexes, r.Field)
+				if len(m.lockedMutexes) == 0 {
+					delete(lh.locks, obj)
+				}
+			case "RLocker", "DowngradeLock", "TryLock", "TryRLock":
+				// we explicitly ignore this for now.
+			default:
+				panic(fmt.Sprintf("unexpected mutex/rwmutex method invoked: %s", fn.Name()))
+			}
+		}
+	}
+}
+
+func run(pass *analysis.Pass) (interface{}, error) {
+	pc := &passContext{
+		pass:       pass,
+		exemptions: make(map[types.Object]struct{}),
+		failures:   make(map[positionKey]*failData),
+	}
+
+	// Find all line failure annotations.
+	for _, f := range pass.Files {
+		for _, cg := range f.Comments {
+			for _, c := range cg.List {
+				if strings.Contains(c.Text, checkLocksFail) {
+					cnt := 1
+					if strings.Contains(c.Text, checkLocksFail+":") {
+						parts := strings.SplitAfter(c.Text, checkLocksFail+":")
+						parsedCount, err := strconv.Atoi(parts[1])
+						if err != nil {
+							pc.pass.Reportf(c.Pos(), "invalid checklocks annotation : %s", err)
+							continue
+						}
+						cnt = parsedCount
+					}
+					position := toPositionKey(pass.Fset.Position(c.Pos()))
+					pc.failures[position] = &failData{pos: c.Pos(), count: cnt}
+				}
+			}
+		}
+	}
+
+	// Find all struct declarations and export any relevant facts.
+	for _, f := range pass.Files {
+		for _, decl := range f.Decls {
+			d, ok := decl.(*ast.GenDecl)
+			// A GenDecl node (generic declaration node) represents an import,
+			// constant, type or variable declaration.  We only care about struct
+			// declarations so skip any declaration that doesn't declare a new type.
+			if !ok || d.Tok != token.TYPE {
+				continue
+			}
+
+			for _, gs := range d.Specs {
+				ts := gs.(*ast.TypeSpec)
+				ss, ok := ts.Type.(*ast.StructType)
+				if !ok {
+					continue
+				}
+				structType := pass.TypesInfo.TypeOf(ts.Name).Underlying().(*types.Struct)
+				pc.findAndExportStructFacts(ss, structType)
+			}
+		}
+	}
+
+	// Find all method calls and export any relevant facts.
+	for _, f := range pass.Files {
+		for _, decl := range f.Decls {
+			d, ok := decl.(*ast.FuncDecl)
+			// Ignore any non function declarations and any functions that do not have
+			// any comments.
+			if !ok || d.Doc == nil {
+				continue
+			}
+			pc.findAndExportFuncFacts(d)
+		}
+	}
+
+	// log all known facts and all failures if debug logging is enabled.
+	allFacts := pass.AllObjectFacts()
+	for i := range allFacts {
+		log.Debugf("fact.object: %+v, fact.Fact: %+v", allFacts[i].Object, allFacts[i].Fact)
+	}
+	log.Debugf("all expected failures: %+v", pc.failures)
+
+	// Scan all code looking for invalid accesses.
+	state := pass.ResultOf[buildssa.Analyzer].(*buildssa.SSA)
+	for _, fn := range state.SrcFuncs {
+		var funcFact lockFunctionFacts
+		// Anonymous(closures) functions do not have an object() but do show up in
+		// the SSA.
+		if obj := fn.Object(); obj != nil {
+			pc.pass.ImportObjectFact(fn.Object(), &funcFact)
+		}
+
+		log.Debugf("checking function: %s", fn)
+		var b bytes.Buffer
+		ssa.WriteFunction(&b, fn)
+		log.Debugf("function SSA: %s", b.String())
+		if fn.Recover != nil {
+			pc.checkBasicBlocks([]*ssa.BasicBlock{fn.Recover}, nil, fn, funcFact)
+		}
+		pc.checkBasicBlocks(fn.Blocks, fn.Recover, fn, funcFact)
+	}
+
+	// Scan for remaining failures we expect.
+	for _, failure := range pc.failures {
+		// We are missing expect failures, report as much as possible.
+		pass.Reportf(failure.pos, "expected %d failures", failure.count)
+	}
+
+	return nil, nil
+}
diff --git a/tools/checklocks/test/BUILD b/tools/checklocks/test/BUILD
new file mode 100644
index 000000000..b055e71d9
--- /dev/null
+++ b/tools/checklocks/test/BUILD
@@ -0,0 +1,8 @@
+load("//tools:defs.bzl", "go_library")
+
+package(licenses = ["notice"])
+
+go_library(
+    name = "test",
+    srcs = ["test.go"],
+)
diff --git a/tools/checklocks/test/test.go b/tools/checklocks/test/test.go
new file mode 100644
index 000000000..05693c183
--- /dev/null
+++ b/tools/checklocks/test/test.go
@@ -0,0 +1,362 @@
+// Copyright 2020 The gVisor Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package test is a test package.
+package test
+
+import (
+	"math/rand"
+	"sync"
+)
+
+type oneGuarded struct {
+	mu sync.Mutex
+	// +checklocks:mu
+	guardedField int
+
+	unguardedField int
+}
+
+func testAccessOne() {
+	var tc oneGuarded
+	// Valid access
+	tc.mu.Lock()
+	tc.guardedField = 1
+	tc.unguardedField = 1
+	tc.mu.Unlock()
+
+	// Valid access as unguarded field is not protected by mu.
+	tc.unguardedField = 2
+
+	// Invalid access
+	tc.guardedField = 2 // +checklocksfail
+
+	// Invalid read of a guarded field.
+	x := tc.guardedField // +checklocksfail
+	_ = x
+}
+
+func testFunctionCallsNoParameters() {
+	// Couple of regular function calls with no parameters.
+	funcCallWithValidAccess()
+	funcCallWithInvalidAccess()
+}
+
+func funcCallWithValidAccess() {
+	var tc2 oneGuarded
+	// Valid tc2 access
+	tc2.mu.Lock()
+	tc2.guardedField = 1
+	tc2.mu.Unlock()
+}
+
+func funcCallWithInvalidAccess() {
+	var tc oneGuarded
+	var tc2 oneGuarded
+	// Invalid access, wrong mutex is held.
+	tc.mu.Lock()
+	tc2.guardedField = 2 // +checklocksfail
+	tc.mu.Unlock()
+}
+
+func testParameterPassing() {
+	var tc oneGuarded
+
+	// Valid call where a guardedField is passed to a function as a parameter.
+	tc.mu.Lock()
+	nestedWithGuardByAddr(&tc.guardedField, &tc.unguardedField)
+	tc.mu.Unlock()
+
+	// Invalid call where a guardedField is passed to a function as a parameter
+	// without holding locks.
+	nestedWithGuardByAddr(&tc.guardedField, &tc.unguardedField) // +checklocksfail
+
+	// Valid call where a guardedField is passed to a function as a parameter.
+	tc.mu.Lock()
+	nestedWithGuardByValue(tc.guardedField, tc.unguardedField)
+	tc.mu.Unlock()
+
+	// Invalid call where a guardedField is passed to a function as a parameter
+	// without holding locks.
+	nestedWithGuardByValue(tc.guardedField, tc.unguardedField) // +checklocksfail
+}
+
+func nestedWithGuardByAddr(guardedField, unguardedField *int) {
+	*guardedField = 4
+	*unguardedField = 5
+}
+
+func nestedWithGuardByValue(guardedField, unguardedField int) {
+	// read the fields to keep SA4009 static analyzer happy.
+	_ = guardedField
+	_ = unguardedField
+	guardedField = 4
+	unguardedField = 5
+}
+
+type twoGuarded struct {
+	mu sync.Mutex
+	// +checklocks:mu
+	guardedField1 int
+	// +checklocks:mu
+	guardedField2 int
+}
+
+type twoLocks struct {
+	mu       sync.Mutex
+	secondMu sync.Mutex
+
+	// +checklocks:mu
+	guardedField1 int
+	// +checklocks:secondMu
+	guardedField2 int
+}
+
+type twoLocksDoubleGuard struct {
+	mu       sync.Mutex
+	secondMu sync.Mutex
+
+	// +checklocks:mu
+	// +checklocks:secondMu
+	doubleGuardedField int
+}
+
+func testTwoLocksDoubleGuard() {
+	var tc twoLocksDoubleGuard
+
+	// Double guarded field
+	tc.mu.Lock()
+	tc.secondMu.Lock()
+	tc.doubleGuardedField = 1
+	tc.secondMu.Unlock()
+
+	// This should fail as we released the secondMu.
+	tc.doubleGuardedField = 2 // +checklocksfail
+	tc.mu.Unlock()
+
+	// This should fail as well as now we are not holding any locks.
+	//
+	// This line triggers two failures one for each mutex, hence the 2 after
+	// fail.
+	tc.doubleGuardedField = 3 // +checklocksfail:2
+}
+
+type rwGuarded struct {
+	rwMu sync.RWMutex
+
+	// +checklocks:rwMu
+	rwGuardedField int
+}
+
+func testRWGuarded() {
+	var tc rwGuarded
+
+	// Assignment w/ exclusive lock should pass.
+	tc.rwMu.Lock()
+	tc.rwGuardedField = 1
+	tc.rwMu.Unlock()
+
+	// Assignment w/ RWLock should pass as we don't differentiate between
+	// Lock/RLock.
+	tc.rwMu.RLock()
+	tc.rwGuardedField = 2
+	tc.rwMu.RUnlock()
+
+	// Assignment w/o hold Lock() should fail.
+	tc.rwGuardedField = 3 // +checklocksfail
+
+	// Reading w/o holding lock should fail.
+	x := tc.rwGuardedField + 3 // +checklocksfail
+	_ = x
+}
+
+type nestedFields struct {
+	mu sync.Mutex
+
+	// +checklocks:mu
+	nestedStruct struct {
+		nested1 int
+		nested2 int
+	}
+}
+
+func testNestedStructGuards() {
+	var tc nestedFields
+	// Valid access with mu held.
+	tc.mu.Lock()
+	tc.nestedStruct.nested1 = 1
+	tc.nestedStruct.nested2 = 2
+	tc.mu.Unlock()
+
+	// Invalid access to nested1 wihout holding mu.
+	tc.nestedStruct.nested1 = 1 // +checklocksfail
+}
+
+type testCaseMethods struct {
+	mu sync.Mutex
+
+	// +checklocks:mu
+	guardedField int
+}
+
+func (t *testCaseMethods) Method() {
+	// Valid access
+	t.mu.Lock()
+	t.guardedField = 1
+	t.mu.Unlock()
+
+	// invalid access
+	t.guardedField = 2 // +checklocksfail
+}
+
+// +checklocks:t.mu
+func (t *testCaseMethods) MethodLocked(a, b, c int) {
+	t.guardedField = 3
+}
+
+// +checklocksignore
+func (t *testCaseMethods) IgnoredMethod() {
+	// Invalid access but should not fail as the function is annotated
+	// with "// +checklocksignore"
+	t.guardedField = 2
+}
+
+func testMethodCalls() {
+	var tc2 testCaseMethods
+
+	// Valid use, tc2.Method acquires lock.
+	tc2.Method()
+
+	// Valid access tc2.mu is held before calling tc2.MethodLocked.
+	tc2.mu.Lock()
+	tc2.MethodLocked(1, 2, 3)
+	tc2.mu.Unlock()
+
+	// Invalid access no locks are being held.
+	tc2.MethodLocked(4, 5, 6) // +checklocksfail
+}
+
+type noMutex struct {
+	f int
+	g int
+}
+
+func (n noMutex) method() {
+	n.f = 1
+	n.f = n.g
+}
+
+func testNoMutex() {
+	var n noMutex
+	n.method()
+}
+
+func testMultiple() {
+	var tc1, tc2, tc3 testCaseMethods
+
+	tc1.mu.Lock()
+
+	// Valid access we are holding tc1's lock.
+	tc1.guardedField = 1
+
+	// Invalid access we are not holding tc2 or tc3's lock.
+	tc2.guardedField = 2 // +checklocksfail
+	tc3.guardedField = 3 // +checklocksfail
+	tc1.mu.Unlock()
+}
+
+func testConditionalBranchingLocks() {
+	var tc2 testCaseMethods
+	x := rand.Intn(10)
+	if x%2 == 1 {
+		tc2.mu.Lock()
+	}
+	// This is invalid access as tc2.mu is not held if we never entered
+	// the if block.
+	tc2.guardedField = 1 // +checklocksfail
+
+	var tc3 testCaseMethods
+	if x%2 == 1 {
+		tc3.mu.Lock()
+	} else {
+		tc3.mu.Lock()
+	}
+	// This is valid as tc3.mu is held in if and else blocks.
+	tc3.guardedField = 1
+}
+
+type testMethodWithParams struct {
+	mu sync.Mutex
+
+	// +checklocks:mu
+	guardedField int
+}
+
+type ptrToTestMethodWithParams *testMethodWithParams
+
+// +checklocks:t.mu
+// +checklocks:a.mu
+func (t *testMethodWithParams) methodLockedWithParams(a *testMethodWithParams, b *testMethodWithParams) {
+	t.guardedField = a.guardedField
+	b.guardedField = a.guardedField // +checklocksfail
+}
+
+// +checklocks:t.mu
+// +checklocks:a.mu
+// +checklocks:b.mu
+func (t *testMethodWithParams) methodLockedWithPtrType(a *testMethodWithParams, b ptrToTestMethodWithParams) {
+	t.guardedField = a.guardedField
+	b.guardedField = a.guardedField
+}
+
+// +checklocks:a.mu
+func standaloneFunctionWithGuard(a *testMethodWithParams) {
+	a.guardedField = 1
+	a.mu.Unlock()
+	a.guardedField = 1 // +checklocksfail
+}
+
+type testMethodWithEmbedded struct {
+	mu sync.Mutex
+
+	// +checklocks:mu
+	guardedField int
+	p            *testMethodWithParams
+}
+
+// +checklocks:t.mu
+func (t *testMethodWithEmbedded) DoLocked() {
+	var a, b testMethodWithParams
+	t.guardedField = 1
+	a.mu.Lock()
+	b.mu.Lock()
+	t.p.methodLockedWithParams(&a, &b) // +checklocksfail
+	a.mu.Unlock()
+	b.mu.Unlock()
+}
+
+// UnsupportedLockerExample is a test that verifies that trying to annotate a
+// field that is not a sync.Mutex/RWMutex results in a failure.
+type UnsupportedLockerExample struct {
+	mu sync.Locker
+
+	// +checklocks:mu
+	x int // +checklocksfail
+}
+
+func abc() {
+	var mu sync.Mutex
+	a := UnsupportedLockerExample{mu: &mu}
+	a.x = 1
+}