comments

Author: adrianherrera

include/pcc.h

@@ -1,3 +1,18 @@
+//===-- pcc.h - Probabilistic Calling Context runtime ---------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file can be used to query the current calling context.
+///
+//===----------------------------------------------------------------------===//
+
 #include <stdint.h>
 
+/// Query the current calling context.
 uintptr_t __pcc_get();

pcc/PCC.cpp

@@ -1,3 +1,18 @@
+//===-- PCC.cpp - Probabilistic Calling Context ---------------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains an implementation of Michael Bond's "probabilistic
+/// calling context" (PCC) for maintaining runtime calling context information.
+///
+//===----------------------------------------------------------------------===//
+
 #include <stdint.h>
 #include <stdlib.h>
 
@@ -15,8 +30,10 @@ using namespace llvm;
 namespace {
 
 static const char *const PCCCalculateName = "__pcc_calculate";
-static const char *const PCCVName = "__pcc_V";
+static const char *const PCCVarName = "__pcc_V";
 
+/// ProbabilisticCallingContext: instrument the code in a module to maintain a
+/// probabilistic unique value representing the current calling context.
 class ProbabilisticCallingContext : public ModulePass {
 public:
   static char ID;
@@ -27,7 +44,8 @@ class ProbabilisticCallingContext : public ModulePass {
 
 } // namespace
 
-static Function *getPCCFunction(Constant *FuncOrBitcast) {
+// Adapted from llvm::checkSanitizerInterfaceFunction
+static Function *checkPCCInterfaceFunction(Constant *FuncOrBitcast) {
   if (isa<Function>(FuncOrBitcast)) {
     return cast<Function>(FuncOrBitcast);
   }
@@ -46,29 +64,38 @@ bool ProbabilisticCallingContext::runOnModule(Module &M) {
   LLVMContext &C = M.getContext();
   const DataLayout &DL = M.getDataLayout();
 
+  // Either 32 or 64 bit depending on the target
   IntegerType *IntTy = DL.getIntPtrType(C);
 
-  Function *PCCFunc = getPCCFunction(
+  // PCCCalculate is the function `__pcc_calculate` that (funny enough)
+  // calculates the probabilistic calling context
+  Function *PCCCalculate = checkPCCInterfaceFunction(
       M.getOrInsertFunction(PCCCalculateName, IntTy, IntTy, IntTy));
+  // PCCVar is the variable `__pcc_V` that stores the probabilistic calling
+  // context
   GlobalVariable *PCCVar = new GlobalVariable(
-      M, IntTy, false, GlobalValue::ExternalLinkage, nullptr, PCCVName, nullptr,
-      GlobalVariable::GeneralDynamicTLSModel, 0, false);
+      M, IntTy, false, GlobalValue::ExternalLinkage, nullptr, PCCVarName,
+      nullptr, GlobalVariable::GeneralDynamicTLSModel, 0, false);
 
   for (auto &F : M.functions()) {
+    // We can only instrument functions that we have an implementation of
     if (F.isDeclaration()) {
       continue;
     }
 
+    // Load the current PCC value into a local variable (temp)
     BasicBlock::iterator IP = F.getEntryBlock().getFirstInsertionPt();
     IRBuilder<> EntryIRB(&*IP);
     LoadInst *Temp = EntryIRB.CreateLoad(PCCVar);
 
     for (auto I = inst_begin(F); I != inst_end(F); ++I) {
+      // At each call site, compute the next calling context with `f` and
+      // update the global variable `V`
       if (auto *Call = dyn_cast<CallInst>(&*I)) {
         ConstantInt *CS = ConstantInt::get(IntTy, random());
 
         IRBuilder<> CallSiteIRB(Call);
-        CallInst *CallF = CallSiteIRB.CreateCall(PCCFunc, {Temp, CS});
+        CallInst *CallF = CallSiteIRB.CreateCall(PCCCalculate, {Temp, CS});
         CallSiteIRB.CreateStore(CallF, PCCVar);
       }
     }

pcc/pcc-rt.c

@@ -1,7 +1,31 @@
+//===-- pcc-rt.cpp - Probabilistic Calling Context runtime ----------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains the run time component used to calculate and maintain
+/// the probabilsitic calling context (PCC).
+///
+//===----------------------------------------------------------------------===//
+
 #include "pcc.h"
 
+/// Unique value representing the current calling context.
 __thread uintptr_t __pcc_V = 0;
 
+/// Non-commutative but efficiently composable function to compute PCC values.
+///
+/// This corresponds to the function \p f in Mike Bond's paper.
+///
+/// \param V current calling context value
+/// \param cs call site identifier
+///
+/// \returns the updated calling context value
 uintptr_t __pcc_calculate(uintptr_t V, uintptr_t cs) { return 3 * V + cs; }
 
 uintptr_t __pcc_get() { return __pcc_V; }