C++: Update opcode QLDoc script to handle abstract base classes

Dave Bartolomeo · Dave Bartolomeo · commit bdf121f3b846 · 2020-06-26T16:04:33.000-04:00
This auto-generates even more QLDoc for `Opcode.qll`
diff --git a/config/opcode-qldoc.py b/config/opcode-qldoc.py
@@ -8,7 +8,8 @@
 end_qldoc_re = re.compile(r'\*/\s*$')  # End of a QLDoc comment
 blank_qldoc_line_re = re.compile(r'^\s*\*\s*$')  # A line in a QLDoc comment with only the '*'
 instruction_class_re = re.compile(r'^class (?P<name>[A-aa-z0-9]+)Instruction\s')  # Declaration of an `Instruction` class
-opcode_class_re = re.compile(r'^\s*class (?P<name>[A-aa-z0-9]+)\s')  # Declaration of an `Opcode` class
+opcode_base_class_re = re.compile(r'^abstract class (?P<name>[A-aa-z0-9]+)Opcode\s')  # Declaration of an `Opcode` base class
+opcode_class_re = re.compile(r'^  class (?P<name>[A-aa-z0-9]+)\s')  # Declaration of an `Opcode` class
 
 script_dir = path.realpath(path.dirname(__file__))
 instruction_path = path.realpath(path.join(script_dir, '../cpp/ql/src/semmle/code/cpp/ir/implementation/raw/Instruction.qll'))
@@ -63,17 +64,29 @@
                 if not end_qldoc_re.search(line):
                     in_qldoc = True
             else:
-                opcode_match = opcode_class_re.search(line)
-                if opcode_match:
-                    # Found an `Opcode` that matches a known `Instruction`. Replace the QLDoc with
-                    # a copy of the one from the `Instruction`.
-                    name = opcode_match.group('name')
-                    if instruction_comments.get(name):
+                name_without_suffix = None
+                name = None
+                indent = ''
+                opcode_base_match = opcode_base_class_re.search(line)
+                if opcode_base_match:
+                    name_without_suffix = opcode_base_match.group('name')
+                    name = name_without_suffix + 'Opcode'
+                else:
+                    opcode_match = opcode_class_re.search(line)
+                    if opcode_match:
+                        name_without_suffix = opcode_match.group('name')
+                        name = name_without_suffix
                         # Indent by two additional spaces, since opcodes are declared in the
                         # `Opcode` module.
+                        indent = '  '
+                
+                if name_without_suffix:
+                    # Found an `Opcode` that matches a known `Instruction`. Replace the QLDoc with
+                    # a copy of the one from the `Instruction`.
+                    if instruction_comments.get(name_without_suffix):
                         # Rename `instruction` to `operation`.
-                        qldoc_lines = [('  ' + qldoc_line.replace(' An instruction ', ' An operation '))
-                            for qldoc_line in instruction_comments[name]]
+                        qldoc_lines = [(indent + qldoc_line.replace(' An instruction ', ' An operation '))
+                            for qldoc_line in instruction_comments[name_without_suffix]]
                 output_lines.extend(qldoc_lines)
                 qldoc_lines = []
                 output_lines.append(line)
diff --git a/cpp/ql/src/semmle/code/cpp/ir/implementation/Opcode.qll b/cpp/ql/src/semmle/code/cpp/ir/implementation/Opcode.qll
@@ -139,53 +139,112 @@ class Opcode extends TOpcode {
   predicate hasOperandInternal(OperandTag tag) { none() }
 }
 
+/**
+ * An operation whose result is computed from a single operand.
+ */
 abstract class UnaryOpcode extends Opcode {
   final override predicate hasOperandInternal(OperandTag tag) { tag instanceof UnaryOperandTag }
 }
 
+/**
+ * An operation whose result is computed from two operands.
+ */
 abstract class BinaryOpcode extends Opcode {
   final override predicate hasOperandInternal(OperandTag tag) {
     tag instanceof LeftOperandTag or
     tag instanceof RightOperandTag
   }
 }
 
+/**
+ * An operation that performs a binary arithmetic operation involving at least one pointer
+ * operand.
+ */
 abstract class PointerArithmeticOpcode extends BinaryOpcode { }
 
+/**
+ * An operation that adds or subtracts an integer offset from a pointer.
+ */
 abstract class PointerOffsetOpcode extends PointerArithmeticOpcode { }
 
+/**
+ * An operation that computes the result of an arithmetic operation.
+ */
 abstract class ArithmeticOpcode extends Opcode { }
 
+/**
+ * An operation that performs an arithmetic operation on two numeric operands.
+ */
 abstract class BinaryArithmeticOpcode extends BinaryOpcode, ArithmeticOpcode { }
 
+/**
+ * An operation whose result is computed by performing an arithmetic operation on a single
+ * numeric operand.
+ */
 abstract class UnaryArithmeticOpcode extends UnaryOpcode, ArithmeticOpcode { }
 
+/**
+ * An operation that computes the result of a bitwise operation.
+ */
 abstract class BitwiseOpcode extends Opcode { }
 
+/**
+ * An operation that performs a bitwise operation on two integer operands.
+ */
 abstract class BinaryBitwiseOpcode extends BinaryOpcode, BitwiseOpcode { }
 
+/**
+ * An operation that performs a bitwise operation on a single integer operand.
+ */
 abstract class UnaryBitwiseOpcode extends UnaryOpcode, BitwiseOpcode { }
 
+/**
+ * An operation that compares two numeric operands.
+ */
 abstract class CompareOpcode extends BinaryOpcode { }
 
+/**
+ * An operation that does a relative comparison of two values, such as `<` or `>=`.
+ */
 abstract class RelationalOpcode extends CompareOpcode { }
 
+/**
+ * An operation that returns a copy of its operand.
+ */
 abstract class CopyOpcode extends Opcode { }
 
+/**
+ * An operation that converts from the address of a derived class to the address of a base class.
+ */
 abstract class ConvertToBaseOpcode extends UnaryOpcode { }
 
+/**
+ * An operation that returns control to the caller of the function.
+ */
 abstract class ReturnOpcode extends Opcode { }
 
+/**
+ * An operation that throws an exception.
+ */
 abstract class ThrowOpcode extends Opcode { }
 
+/**
+ * An operation that starts a `catch` handler.
+ */
 abstract class CatchOpcode extends Opcode { }
 
 abstract private class OpcodeWithCondition extends Opcode {
   final override predicate hasOperandInternal(OperandTag tag) { tag instanceof ConditionOperandTag }
 }
 
+/**
+ * An operation representing a built-in operation.
+ */
 abstract class BuiltInOperationOpcode extends Opcode { }
 
+/**
+ * An operation representing a side effect of a function call.
+ */
 abstract class SideEffectOpcode extends Opcode { }
 
 /**
@@ -321,7 +380,8 @@ abstract class OpcodeWithLoad extends IndirectReadOpcode {
 }
 
 /**
- * An opcode that reads from a set of memory locations as a side effect.
+ * An operation representing a read side effect of a function call on a
+ * specific parameter.
  */
 abstract class ReadSideEffectOpcode extends SideEffectOpcode {
   final override predicate hasOperandInternal(OperandTag tag) {
@@ -330,7 +390,8 @@ abstract class ReadSideEffectOpcode extends SideEffectOpcode {
 }
 
 /**
- * An opcode that writes to a set of memory locations as a side effect.
+ * An operation representing a write side effect of a function call on a
+ * specific parameter.
  */
 abstract class WriteSideEffectOpcode extends SideEffectOpcode { }
 
diff --git a/csharp/ql/src/experimental/ir/implementation/Opcode.qll b/csharp/ql/src/experimental/ir/implementation/Opcode.qll
@@ -139,53 +139,112 @@ class Opcode extends TOpcode {
   predicate hasOperandInternal(OperandTag tag) { none() }
 }
 
+/**
+ * An operation whose result is computed from a single operand.
+ */
 abstract class UnaryOpcode extends Opcode {
   final override predicate hasOperandInternal(OperandTag tag) { tag instanceof UnaryOperandTag }
 }
 
+/**
+ * An operation whose result is computed from two operands.
+ */
 abstract class BinaryOpcode extends Opcode {
   final override predicate hasOperandInternal(OperandTag tag) {
     tag instanceof LeftOperandTag or
     tag instanceof RightOperandTag
   }
 }
 
+/**
+ * An operation that performs a binary arithmetic operation involving at least one pointer
+ * operand.
+ */
 abstract class PointerArithmeticOpcode extends BinaryOpcode { }
 
+/**
+ * An operation that adds or subtracts an integer offset from a pointer.
+ */
 abstract class PointerOffsetOpcode extends PointerArithmeticOpcode { }
 
+/**
+ * An operation that computes the result of an arithmetic operation.
+ */
 abstract class ArithmeticOpcode extends Opcode { }
 
+/**
+ * An operation that performs an arithmetic operation on two numeric operands.
+ */
 abstract class BinaryArithmeticOpcode extends BinaryOpcode, ArithmeticOpcode { }
 
+/**
+ * An operation whose result is computed by performing an arithmetic operation on a single
+ * numeric operand.
+ */
 abstract class UnaryArithmeticOpcode extends UnaryOpcode, ArithmeticOpcode { }
 
+/**
+ * An operation that computes the result of a bitwise operation.
+ */
 abstract class BitwiseOpcode extends Opcode { }
 
+/**
+ * An operation that performs a bitwise operation on two integer operands.
+ */
 abstract class BinaryBitwiseOpcode extends BinaryOpcode, BitwiseOpcode { }
 
+/**
+ * An operation that performs a bitwise operation on a single integer operand.
+ */
 abstract class UnaryBitwiseOpcode extends UnaryOpcode, BitwiseOpcode { }
 
+/**
+ * An operation that compares two numeric operands.
+ */
 abstract class CompareOpcode extends BinaryOpcode { }
 
+/**
+ * An operation that does a relative comparison of two values, such as `<` or `>=`.
+ */
 abstract class RelationalOpcode extends CompareOpcode { }
 
+/**
+ * An operation that returns a copy of its operand.
+ */
 abstract class CopyOpcode extends Opcode { }
 
+/**
+ * An operation that converts from the address of a derived class to the address of a base class.
+ */
 abstract class ConvertToBaseOpcode extends UnaryOpcode { }
 
+/**
+ * An operation that returns control to the caller of the function.
+ */
 abstract class ReturnOpcode extends Opcode { }
 
+/**
+ * An operation that throws an exception.
+ */
 abstract class ThrowOpcode extends Opcode { }
 
+/**
+ * An operation that starts a `catch` handler.
+ */
 abstract class CatchOpcode extends Opcode { }
 
 abstract private class OpcodeWithCondition extends Opcode {
   final override predicate hasOperandInternal(OperandTag tag) { tag instanceof ConditionOperandTag }
 }
 
+/**
+ * An operation representing a built-in operation.
+ */
 abstract class BuiltInOperationOpcode extends Opcode { }
 
+/**
+ * An operation representing a side effect of a function call.
+ */
 abstract class SideEffectOpcode extends Opcode { }
 
 /**
@@ -321,7 +380,8 @@ abstract class OpcodeWithLoad extends IndirectReadOpcode {
 }
 
 /**
- * An opcode that reads from a set of memory locations as a side effect.
+ * An operation representing a read side effect of a function call on a
+ * specific parameter.
  */
 abstract class ReadSideEffectOpcode extends SideEffectOpcode {
   final override predicate hasOperandInternal(OperandTag tag) {
@@ -330,7 +390,8 @@ abstract class ReadSideEffectOpcode extends SideEffectOpcode {
 }
 
 /**
- * An opcode that writes to a set of memory locations as a side effect.
+ * An operation representing a write side effect of a function call on a
+ * specific parameter.
  */
 abstract class WriteSideEffectOpcode extends SideEffectOpcode { }
 
