release 13.0.0 versions & docs (#1695)

- update dyninst version

- update CHANGELOG.md

- produce manuals with updated release dates and versions

- fix .tex files to eliminate latex errors:
  - invalid char in symtabAPI/doc/API/Types/Type.tex
  - invalid char in parseAPI/doc/API/Function.tex
  - invalid char in patchAPI/doc/section/4_api_public.tex
  - invlide line break in parseAPI/doc/API/CodeObject.tex

- restore parseAPI example code needed by docs removed in 6c2e31c

Co-authored-by: James Kupsch <kupsch@vmbp15.local>

CMakeLists.txt

@@ -10,8 +10,8 @@ if(POLICY CMP0144)
   cmake_policy(SET CMP0144 NEW)
 endif()
 
-set(DYNINST_MAJOR_VERSION 12)
-set(DYNINST_MINOR_VERSION 3)
+set(DYNINST_MAJOR_VERSION 13)
+set(DYNINST_MINOR_VERSION 0)
 set(DYNINST_PATCH_VERSION 0)
 
 set(DYNINST_SOVERSION "${DYNINST_MAJOR_VERSION}.${DYNINST_MINOR_VERSION}")

common/doc/manual_frontpage.tex

@@ -42,9 +42,9 @@
 %    };
 
     \node [anchor=west,font=\sffamily] (rel1) at ($(origin)+(0.75in,-5.0in)$)
-        {\fontsize{24}{32}\selectfont 12.3 Release};
+        {\fontsize{24}{32}\selectfont 13.0 Release};
     \node [anchor=west,font=\sffamily] (rel2) at ($(rel1.west)+(0in,-32pt)$)
-        {\fontsize{24}{32}\selectfont February 2023};
+        {\fontsize{24}{32}\selectfont February 2024};
 
     % Contact information
 %    \matrix (UWaddress) [%

parseAPI/doc/API/CodeObject.tex

@@ -93,7 +93,7 @@ \subsection{Class CodeObject}
 \apidesc{Speculatively parse the indicated region of the binary using the specified technique to find likely function entry points, enabled on the x86 and x86-64 platforms.}
 
 \fbox{\begin{minipage}[t]{1\columnwidth}%
-\begin{center}{\textbf{A note on using the lookup functions}}\end{center}\\
+\begin{center}{\textbf{A note on using the lookup functions}}\end{center}
 When parsing binary objects such as .o files and static libraries which may have multiple
 \texttt{CodeRegion} objects that overlap in the address space, the \texttt{CodeRegion} argument
 \textit{must} be passed. For executable binaries and shared libraries that are fully linked, there

parseAPI/doc/API/Function.tex

@@ -106,7 +106,7 @@ \subsection{Class Function}
 \begin{apient}
 Block* getImmediateDominator(Block *A);
 \end{apient}
-\apidesc{Return the immediate dominator of block \code{A}，\code{NULL} if the block \code{A} does not have an immediate dominator.}
+\apidesc{Return the immediate dominator of block \code{A}, \code{NULL} if the block \code{A} does not have an immediate dominator.}
 
 \begin{apient}
 void getImmediateDominates(Block *A, set<Block*> &imm);
@@ -127,7 +127,7 @@ \subsection{Class Function}
 \begin{apient}
 Block* getImmediatePostDominator(Block *A);
 \end{apient}
-\apidesc{Return the immediate post-dominator of block \code{A}，\code{NULL} if the block \code{A} does not have an immediate post-dominator.}
+\apidesc{Return the immediate post-dominator of block \code{A}, \code{NULL} if the block \code{A} does not have an immediate post-dominator.}
 
 \begin{apient}
 void getImmediatePostDominates(Block *A, set<Block*> &imm);

parseAPI/doc/code_sample.cc

@@ -0,0 +1,84 @@
+/*
+   Copyright (C) 2015 Alin Mindroc
+   (mindroc dot alin at gmail dot com)
+
+   This is a sample program that shows how to use InstructionAPI in order to
+   6  print the assembly code and functions in a provided binary.
+
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   11  License as published by the Free Software Foundation; either
+   version 2.1 of the License, or (at your option) any later version.
+   */
+#include <iostream>
+#include "CodeObject.h"
+#include "InstructionDecoder.h"
+using namespace std;
+using namespace Dyninst;
+using namespace ParseAPI;
+
+using namespace InstructionAPI;
+int main(int argc, char **argv){
+    if(argc != 2){
+	printf("Usage: %s <binary path>\n", argv[0]);
+	return -1;
+    }
+    char *binaryPath = argv[1];
+
+    SymtabCodeSource *sts;
+    CodeObject *co;
+    Instruction::Ptr instr;
+    SymtabAPI::Symtab *symTab;
+    std::string binaryPathStr(binaryPath);
+    bool isParsable = SymtabAPI::Symtab::openFile(symTab, binaryPathStr);
+    if(isParsable == false){
+	const char *error = "error: file can not be parsed";
+	cout << error;
+	return - 1;
+    }
+    sts = new SymtabCodeSource(binaryPath);
+    co = new CodeObject(sts);
+    //parse the binary given as a command line arg
+    co->parse();
+
+    //get list of all functions in the binary
+    const CodeObject::funclist &all = co->funcs();
+    if(all.size() == 0){
+	const char *error = "error: no functions in file";
+	cout << error;
+	return - 1;
+    }
+    auto fit = all.begin();
+    Function *f = *fit;
+    //create an Instruction decoder which will convert the binary opcodes to strings
+    InstructionDecoder decoder(f->isrc()->getPtrToInstruction(f->addr()),
+	    InstructionDecoder::maxInstructionLength,
+	    f->region()->getArch());
+    for(;fit != all.end(); ++fit){
+	Function *f = *fit;
+	//get address of entry point for current function
+
+	Address crtAddr = f->addr();
+	int instr_count = 0;
+	instr = decoder.decode((unsigned char *)f->isrc()->getPtrToInstruction(crtAddr));
+	auto fbl = f->blocks().end();
+	fbl--;
+	Block *b = *fbl;
+	Address lastAddr = b->last();
+	//if current function has zero instructions, don't output it
+	if(crtAddr == lastAddr)
+	    continue;
+	cout << "\n\n\"" << f->name() << "\" :";
+	while(crtAddr < lastAddr){
+	    //decode current instruction
+	    instr = decoder.decode((unsigned char *)f->isrc()->getPtrToInstruction(crtAddr));
+	    cout << "\n" << hex << crtAddr;
+	    cout << ": \"" << instr->format() << "\"";
+	    //go to the address of the next instruction
+	    crtAddr += instr->size();
+	    instr_count++;
+	}
+    }
+    return 0;
+}

parseAPI/doc/example.cc

@@ -0,0 +1,96 @@
+// Example ParseAPI program; produces a graph (in DOT format) of the
+// control flow graph of the provided binary. 
+//
+// Improvements by E. Robbins (er209 at kent dot ac dot uk)
+//
+
+#include <stdio.h>
+#include <map>
+#include <vector>
+#include <unordered_map>
+#include <sstream>
+#include "CodeObject.h"
+#include "CFG.h"
+
+using namespace std;
+using namespace Dyninst;
+using namespace ParseAPI;
+
+int main(int argc, char * argv[])
+{
+   map<Address, bool> seen;
+   vector<Function *> funcs;
+   SymtabCodeSource *sts;
+   CodeObject *co;
+
+   // Create a new binary code object from the filename argument
+   sts = new SymtabCodeSource( argv[1] );
+   co = new CodeObject( sts );
+
+   // Parse the binary
+   co->parse();
+   cout << "digraph G {" << endl;
+
+   // Print the control flow graph
+   const CodeObject::funclist& all = co->funcs();
+   auto fit = all.begin();
+   for(int i = 0; fit != all.end(); ++fit, i++) { // i is index for clusters
+      Function *f = *fit;
+
+      // Make a cluster for nodes of this function
+      cout << "\t subgraph cluster_" << i 
+           << " { \n\t\t label=\""
+           << f->name()
+           << "\"; \n\t\t color=blue;" << endl;
+
+      cout << "\t\t\"" << hex << f->addr() << dec
+           << "\" [shape=box";
+      if (f->retstatus() == NORETURN)
+         cout << ",color=red";
+      cout << "]" << endl;
+
+      // Label functions by name
+      cout << "\t\t\"" << hex << f->addr() << dec
+           << "\" [label = \""
+           << f->name() << "\\n" << hex << f->addr() << dec
+           << "\"];" << endl;
+
+      stringstream edgeoutput;
+
+      auto bit = f->blocks().begin();
+      for( ; bit != f->blocks().end(); ++bit) {
+         Block *b = *bit;
+         // Don't revisit blocks in shared code
+         if(seen.find(b->start()) != seen.end())
+            continue;
+
+         seen[b->start()] = true;
+
+         cout << "\t\t\"" << hex << b->start() << dec << 
+            "\";" << endl;
+
+         auto it = b->targets().begin();
+         for( ; it != b->targets().end(); ++it) {
+            if(!*it) continue;
+            std::string s = "";
+            if((*it)->type() == CALL)
+               s = " [color=blue]";
+            else if((*it)->type() == RET)
+               s = " [color=green]";
+
+            // Store the edges somewhere to be printed outside of the cluster
+            edgeoutput << "\t\"" 
+                       << hex << (*it)->src()->start()
+                       << "\" -> \""
+                       << (*it)->trg()->start()
+                       << "\"" << s << endl;
+         }
+      }
+      // End cluster
+      cout << "\t}" << endl;
+
+      // Print edges
+      cout << edgeoutput.str() << endl;
+   }
+   cout << "}" << endl;
+}

patchAPI/doc/section/4_api_public.tex

@@ -295,7 +295,7 @@ \subsubsection{PatchFunction}
 \begin{apient}
 PatchBlock* getImmediateDominator(PatchBlock *A);
 \end{apient}
-\apidesc{Return the immediate dominator of block \code{A}，\code{NULL} if the block \code{A} does not have an immediate dominator.}
+\apidesc{Return the immediate dominator of block \code{A}, \code{NULL} if the block \code{A} does not have an immediate dominator.}
 
 \begin{apient}
 void getImmediateDominates(PatchBlock *A, set<PatchBlock*> &imm);
@@ -316,7 +316,7 @@ \subsubsection{PatchFunction}
 \begin{apient}
 PatchBlock* getImmediatePostDominator(PatchBlock *A);
 \end{apient}
-\apidesc{Return the immediate post-dominator of block \code{A}，\code{NULL} if the block \code{A} does not have an immediate post-dominator.}
+\apidesc{Return the immediate post-dominator of block \code{A}, \code{NULL} if the block \code{A} does not have an immediate post-dominator.}
 
 \begin{apient}
 void getImmediatePostDominates(PatchBlock *A, set<PatchBlock*> &imm);

symtabAPI/doc/API/Types/Type.tex

@@ -165,7 +165,7 @@ \subsection{Class typeEnum}
                         Symtab *obj)
 \end{apient}
 \apidesc{
-These factory methods create a new enumerated type. There are two variations to this function. \code{consts} supplies the names and Id’s of the constants of the enum. The first variant is used when user-defined identifiers are required; the second variant is used when system-defined identifiers will be used. 
+These factory methods create a new enumerated type. There are two variations to this function. \code{consts} supplies the names and Id's of the constants of the enum. The first variant is used when user-defined identifiers are required; the second variant is used when system-defined identifiers will be used. 
 The newly created type is added to the \code{Symtab} object \code{obj}. If \code{obj} is \code{NULL} the type is not added to any object file, but it will be available for further queries.
 }