cctlib | Automatically exported from code.google.com/p/cctlib

cctlib is a C++ library. cctlib has no bugs, it has no vulnerabilities, it has a Permissive License and it has low support. You can download it from GitHub.

int PinCCTLibInit(IsInterestingInsFptr isInterestingIns, FILE* logFile, CCTLibInstrumentInsCallback userCallback, VOID* userCallbackArg, BOOL doDataCentric = false); Description: CCTLib clients must call this before using CCTLib. Note: For postmortem analysis call PinCCTLibInitForPostmortemAnalysis() instead. Arguments: isInterestingIns: a client tool callback that should return boolean true/false if a given INS needs to collect context. Following predefined values are available for client tools: INTERESTING_INS_ALL => client tool needs the calling context on each instruction. tests/cct_client.cpp is a good example to demonstrate this use case. INTERESTING_INS_MEMORY_ACCESS => client tool needs the calling context on each load/store instruction. tests/cct_client_mem_only.cpp is a good example to demonstrate this use case. INTERESTING_INS_NONE => client tool does not require calling context only to the level of function names and callsites, leaf level instructions are ignored. logFile: file pointer where CCTLib will put its output data. userCallback: a client callback that CCTLib calls on each INS for which isInterestingIns is true passing it userCallbackArg value. userCallbackArg: is a void pointer that CCTLib takes and passes back to the client tool callback provided by userCallback argument. doDataCentric: should be set to true if the client wants CCTLib to do data-centric attribution. ContextHandle_t GetContextHandle(THREADID threadId, uint32_t opaqueHandle); Description: Client tools call this API when they need the calling context handle (ContextHandle_t). Arguments: threadId: Pin's thread id of the asking thread. opaqueHandle: handle passed by CCTLib to the client tool in its userCallback. DataHandle_t GetDataObjectHandle(VOID* address, THREADID threadId); Description: Client tools call this API when they need handle to the data object (DataHandle_t). Arguments: address: effective address for which the data object is needed. threadId: Pin's thread id of the asking thread. Note: Make sure that you have finite stack size. Don't set "ulimit -s unlimited". VOID PrintFullCallingContext(ContextHandle_t ctxtHandle); Description: Prints the full calling context whose handle is ctxtHandle. Client tools must call PIN_LockClient() before calling this API and release lock via PIN_UnlockClient(). I have intentionally made client tool to hold lock (PIN_LockClient) instead of CCTLib holding the lock so that it becomes efficient and the granularity of locking is left to the user. If the client tool is already holding the lock, it does not make sense for CCTLib to acquire it again (It is not clear from Pin manual if this lock is reentrant), hence this design is justified. Typical use: PIN_LockClient();. VOID GetFullCallingContext(ContextHandle_t ctxtHandle, vector & contextVec); Description: Returns the full calling context whose handle is ctxtHandle. Client tools must call PIN_LockClient() before calling this API and release lock via PIN_UnlockClient(). I have intentionally made client tool to hold lock (PIN_LockClient) instead of CCTLib holding the lock so that it becomes efficient and the granularity of locking is left to the user. If the client tool is already holding the lock, it does not make sense for CCTLib to acquire it again (It is not clear from Pin manual if this lock is reentrant), hence this design is justified. Typical use: PIN_LockClient();. Arguments: ctxtHandle: is the context handle for which the full call path is requested. contextVec: is a vector that will be populated with the full call path. int PinCCTLibInitForPostmortemAnalysis(FILE* logFile, string serializedFilesDirectory); Description: Reads serialized CCT metadata and rebuilds CCTs for postmortem analysis. Arguments: logFile: file pointer where CCTLib will put its output data. serializedFilesDirectory: Path to directory where previously files were serialized. void SerializeMetadata(string directoryForSerializationFiles = ""); Description: Serializes all CCTLib data into files for postmortem analysis. Arguments: directoryForSerializationFiles: directory where serialized files are written. void DottifyAllCCTs() Description: Dumps all CCTs into DOT files for visualization. bool IsSameSourceLine(ContextHandle_t ctxt1, ContextHandle_t ctxt2) Description: Given two contexts handles, returns true if they both map to the same source line (could be different instructions). Client tools must call PIN_LockClient() before calling this API and release lock after via PIN_UnlockClient(). Follow instructions similar to GetFullCallingContext() to decide the granularity of locking.