Expose MCInst in C Disassembler API

[maurer]

Summary

Partially expose the MCInst struct from the C Disassembler API to allow mechanized examination of opcodes and arguments.

[wanders]

I would find this to be a useful addition the the API. Especially if it could be extended with a function like LLVMMCInstIsFlowControl

include/llvm-c/MCInst.h

53–61

Can't this struct be kept opaque, like almost every other exposed type in the llvm-c api? Instead create accessor functions.

Does the API get too clunky if you get rid of the LLVMMCOperandRef type entirely? And instead have functions like LLVMMCInstGetOperandKind, LLVMMCInstGetOperandRegVal and so on?

lib/MC/MCInst.cpp

98–104

This looks like copy-paste error of isReg here.

tools/llvm-c-test/disassemble.c

46–49

It would be nice if the tests requested an MCInst here and dumped some information from it to make the new code at least run on tests. If you could add some checks on the output even better.

[echristo]

Can you give some background on motivation here? I can't see why we'd
like to do this right now.

-eric

[maurer]

@echristo: I'm currently working on a redesign of a framework for doing analysis of compiled code. Our new ARM support works by using LLVM's disassembly capabilities from within OCaml. OCaml cannot bind directly to C++, and must bind against C instead.

My lab is not the only group which does binary analysis, and the hope in adding bindings like this is to make it easier for people working in languages other than C++ to use LLVM to help them go from binary strings to an object they can use.

[maurer]

Is there anything further that I can do to try to get these features or something similar in? This patch has been sitting dead for a while, and it would be nice if my projects could depend on mainline LLVM instead of needing to direct everyone working with me to install a patched version.

[echristo]

Have you addressed Kevin's comments in the email review thread?

[maurer]

Fixed whitespace issue

include/llvm-c/Disassembler.h

 #include "llvm/Support/DataTypes.h"
 #include <stddef.h>
 
+#include "llvm-c/MCInst.h"
+
 /**
  * @defgroup LLVMCDisassembler Disassembler
  * @ingroup LLVMC

  * parameter Bytes, and contains at least BytesSize number of bytes.  The
  * instruction is at the address specified by the PC parameter.  If a valid
  * instruction can be disassembled, its string is returned indirectly in
- * OutString whose size is specified in the parameter OutStringSize.  This
- * function returns the number of bytes in the instruction or zero if there was
- * no valid instruction.
+ * OutString whose size is specified in the parameter OutStringSize.
+ * If a MCInstRef is provided, the MCInst generated during disassembly is
+ * written there. This function returns the number of bytes in the instruction
+ * or zero if there was no valid instruction.
  */
 size_t LLVMDisasmInstruction(LLVMDisasmContextRef DC, uint8_t *Bytes,
                              uint64_t BytesSize, uint64_t PC,
+                             LLVMMCInstRef* Inst,
                              char *OutString, size_t OutStringSize);
 
 /**

include/llvm-c/MCInst.h

+/*===-- llvm-c/MCInst.h - Disassembler Public C Interface ---*- C -*-===*\
+|*                                                                            *|
+|*                     The LLVM Compiler Infrastructure                       *|
+|*                                                                            *|
+|* This file is distributed under the University of Illinois Open Source      *|
+|* License. See LICENSE.TXT for details.                                      *|
+|*                                                                            *|
+|*===----------------------------------------------------------------------===*|
+|*                                                                            *|
+|* This header provides a public interface the MCInst type.                   *|
+|* LLVM provides an implementation of this interface.                         *|
+|*                                                                            *|
+\*===----------------------------------------------------------------------===*/
+
+#ifndef LLVM_C_MCINST_H
+#define LLVM_C_MCINST_H
+
+#include "llvm/Support/DataTypes.h"
+#include <stddef.h>
+
+/**
+ * @defgroup LLVMCInst MCInst
+ * @ingroup LLVMC
+ *
+ * @{
+ */
+
+/**
+ * An opaque reference to a native instruction.
+ */
+typedef void *LLVMMCInstRef;
+
+/**
+ * Opaque type for MCOperand.
+ */
+typedef void* LLVMMCOperandRef;
+
+/**
+ * Type tag for different kinds of operands.
+ */
+typedef enum {
+  LLVMOTInvalid,
+  LLVMOTReg,
+  LLVMOTImm,
+  LLVMOTFPImm,
+  LLVMOTExpr,
+  LLVMOTInst
+} LLVMMCOperandType;
+
+/**
+ * A native instruction operand, projected to C.
+ */
+typedef struct {
+  LLVMMCOperandType Kind;
+  union {
+    unsigned RegVal;
+    int64_t ImmVal;
+    double FPImmVal;
+    LLVMMCInstRef InstVal;
+  };
+} LLVMMCOperand;
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* !defined(__cplusplus) */
+
+/**
+ * Dispose of an instruction.
+ */
+void LLVMMCInstRefDispose(LLVMMCInstRef Inst);
+
+/**
+ * Get total number of operands for an instruction.
+ */
+unsigned LLVMMCInstGetNumOperands(LLVMMCInstRef Inst);
+
+/**
+ * Get an abstract form of the ith operand of Inst.
+ * You may want to chain this with LLVMMCOperandProject.
+ * Note that the lifetime of this LLVMMCOperandRef is the same as the
+ * LLVMMCInstRef you created it from - when you dispose the Inst, the
+ * operand becomes invalid as well.
+ */
+LLVMMCOperandRef LLVMMCInstGetOperand(LLVMMCInstRef Inst, unsigned i);
+
+/**
+ * Get the opcode of a particular MCInst.
+ * Reference tblgen files for actual values.
+ */
+unsigned LLVMMCInstGetOpcode(LLVMMCInstRef Inst);
+
+/**
+ * Project an MCOperand into a C-struct
+ */
+void LLVMMCOperandProject(LLVMMCOperandRef OperandCPP, LLVMMCOperand* Operand);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif /* !defined(__cplusplus) */
+
+#endif /* !defined(LLVM_C_MCINST_H) */

lib/MC/MCDisassembler/Disassembler.cpp

 // over by printing a .byte, .long etc. to continue.
 //
 size_t LLVMDisasmInstruction(LLVMDisasmContextRef DCR, uint8_t *Bytes,
-                             uint64_t BytesSize, uint64_t PC, char *OutString,
-                             size_t OutStringSize){
+                             uint64_t BytesSize, uint64_t PC,
+                             LLVMMCInstRef* InstOut,
+                             char *OutString, size_t OutStringSize){
   LLVMDisasmContext *DC = (LLVMDisasmContext *)DCR;
   // Wrap the pointer to the Bytes, BytesSize and PC in a MemoryObject.
   DisasmMemoryObject MemoryObject(Bytes, BytesSize, PC);

     std::memcpy(OutString, InsnStr.data(), OutputSize);
     OutString[OutputSize] = '\0'; // Terminate string.
 
+    if (InstOut) {
+      *(MCInst**)InstOut = new MCInst(Inst);
+    }
+
     return Size;
   }
   }

lib/MC/MCInst.cpp

 #include "llvm/Support/Debug.h"
 #include "llvm/Support/raw_ostream.h"
 
+#include "llvm-c/MCInst.h"
+
 using namespace llvm;
 
 void MCOperand::print(raw_ostream &OS, const MCAsmInfo *MAI) const {

   dbgs() << "\n";
 }
 #endif
+
+void LLVMMCInstRefDispose(LLVMMCInstRef InstR) {
+  MCInst* Inst = (MCInst*)InstR;
+  delete Inst;
+}
+
+unsigned LLVMMCInstGetNumOperands(LLVMMCInstRef InstR) {
+  MCInst* Inst = (MCInst*)InstR;
+  return Inst->getNumOperands();
+}
+
+LLVMMCOperandRef LLVMMCInstGetOperand(LLVMMCInstRef InstR, unsigned i) {
+  MCInst* Inst = (MCInst*)InstR;
+  return &(Inst->getOperand(i));
+}
+
+unsigned LLVMMCInstGetOpcode(LLVMMCInstRef InstR) {
+  MCInst* Inst = (MCInst*)InstR;
+  return Inst->getOpcode();
+}
+
+void LLVMMCOperandProject(LLVMMCOperandRef OperandR, LLVMMCOperand* OperandC) {
+  MCOperand* OperandCPP = (MCOperand*)OperandR;
+  if (OperandCPP->isReg()) {
+    OperandC->Kind     = LLVMOTReg;
+    OperandC->RegVal   = OperandCPP->getReg();
+  } else if (OperandCPP->isImm()) {
+    OperandC->Kind     = LLVMOTImm;
+    OperandC->ImmVal   = OperandCPP->getImm();
+  } else if (OperandCPP->isReg()) {
+    OperandC->Kind     = LLVMOTFPImm;
+    OperandC->FPImmVal = OperandCPP->getFPImm();
+  } else if (OperandCPP->isExpr()) {
+    OperandC->Kind     = LLVMOTExpr;
+    //XXX: Haven't modeled Expr yet as this is for disasm
+  } else if (OperandCPP->isInst()) {
+    OperandC->Kind     = LLVMOTInst;
+    OperandC->InstVal  = (LLVMMCInstRef)OperandCPP->getInst();
+  } else {
+    assert((!OperandCPP.isValid()) && "Unknown Operand Type");
+    OperandC->Kind     = LLVMOTInvalid;
+  }
+}

tools/llvm-c-test/disassemble.c

 
   pos = 0;
   while (pos < siz) {
-    size_t l = LLVMDisasmInstruction(D, buf + pos, siz - pos, 0, outline,
-                                     sizeof(outline));
+    size_t l = LLVMDisasmInstruction(D, buf + pos, siz - pos, 0, NULL,
+                                     outline, sizeof(outline));
     if (!l) {
       pprint(pos, buf + pos, 1, "\t???");
       pos++;