# CS6332: PINTOOL Tutorial
## inscount.so example
1. Download [inscount][inscounts.tar.gz] examples
```shell
$ mkdir inscounts
$ cd inscounts
inscounts $ wget https://cs6332.syssec.org/l/week07/res/inscounts.tar.gz
# or
$ mkdir inscounts
$ cd inscounts
inscount $ cp /home/labs/inscounts.tar.gz .
...
```
2. Decompess
```
inscounts $ tar xvf ./inscounts.tar.gz
inscount0.cpp
inscount1.cpp
inscount2.cpp
Makefile
nullpin.cpp
obj-intel64/
opcodemix.cpp
```
3. PINTOOL Build
```
inscounts $ mkdir obj-intel64 # optional
inscounts $ make -e obj-intel64/inscount0.so
...
```
4. Run
```
inscounts $ pin -t obj-intel64/inscount0.so -- ls
```
### inscount0.cpp (source)
```cpp=
/*
* Copyright (C) 2004-2021 Intel Corporation.
* SPDX-License-Identifier: MIT
*/
#include <iostream>
#include <fstream>
#include "pin.H"
using std::cerr;
using std::endl;
using std::ios;
using std::ofstream;
using std::string;
ofstream OutFile;
// The running count of instructions is kept here
// make it static to help the compiler optimize docount
static UINT64 icount = 0;
// This function is called before every instruction is executed
VOID docount() { icount++; }
// Pin calls this function every time a new instruction is encountered
VOID Instruction(INS ins, VOID* v)
{
// Insert a call to docount before every instruction, no arguments are passed
INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR)docount, IARG_END);
}
KNOB< string > KnobOutputFile(KNOB_MODE_WRITEONCE, "pintool", "o", "inscount.out", "specify output file name");
// This function is called when the application exits
VOID Fini(INT32 code, VOID* v)
{
// Write to a file since cout and cerr maybe closed by the application
OutFile.setf(ios::showbase);
OutFile << "Count " << icount << endl;
OutFile.close();
}
/* ===================================================================== */
/* Print Help Message */
/* ===================================================================== */
INT32 Usage()
{
cerr << "This tool counts the number of dynamic instructions executed" << endl;
cerr << endl << KNOB_BASE::StringKnobSummary() << endl;
return -1;
}
/* ===================================================================== */
/* Main */
/* ===================================================================== */
/* argc, argv are the entire command line: pin -t <toolname> -- ... */
/* ===================================================================== */
int main(int argc, char* argv[])
{
// Initialize pin
if (PIN_Init(argc, argv)) return Usage();
OutFile.open(KnobOutputFile.Value().c_str());
// Register Instruction to be called to instrument instructions
INS_AddInstrumentFunction(Instruction, 0);
// Register Fini to be called when the application exits
PIN_AddFiniFunction(Fini, 0);
// Start the program, never returns
PIN_StartProgram();
return 0;
}
```
---
## Common Terms in the Pin API
### 1. Instrumentation Routine
An **instrumentation routine** defines **where instrumentation is inserted**.
Example:
```cpp
Instruction(INS ins, VOID* v)
```
For example, `IPOINT_BEFORE` specifies that the instrumentation should execute before the instruction.
### 2. Analysis Routine
An **analysis routine** defines **what to do when the instrumented instruction executes**.
For example, a function such as:
```cpp
docount()
```
may increment an instruction counter.
Analysis routines may receive arguments from Pin. Examples include:
- `IARG_INST_PTR` — passes the instruction pointer (program counter) value.
- `IARG_MEMORY_READ_EA` — passes the effective memory address of a memory read.
### 3. `PIN_Init`
`PIN_Init` initializes the Pintool.
It also detects incorrect command-line input supplied by the user.
Details of its implementation are in `pin.H`.
### 4. `INS_AddInstrumentFunction()`
`INS_AddInstrumentFunction()` registers the Pin callback used for instrumentation or injecting code at every instruction.
### 5. `PIN_AddFiniFunction`
`PIN_AddFiniFunction` registers a function that is called before the application exits.
> Note: This is **not** an instrumentation function.
### 6. Further Documentation
More details are available in the Intel Pin documentation.
## Resources
* [PIN User Guide]
* [PIN API]
###### tags: `pintools`,`inscount`,`pintool`
[inscounts.tar.gz]:https://cs6332.syssec.org/l/week07/res/inscounts.tar.gz
[PIN User Guide]:https://software.intel.com/sites/landingpage/pintool/docs/98484/Pin/html/index.html
[PIN API]:https://software.intel.com/sites/landingpage/pintool/docs/98650/Pin/doc/html/group__API__OVERVIEW.html
[PIN Tutorial]:https://docs.hex-rays.com/user-guide/debugger/debugger-tutorials/debugger_pin