Skip to content

Commit cec73e6

Browse files
jbjjbj
authored
Merge pull request github#3393 from dbartol/codeql-c-analysis-team/40/1
C++: A few IR QLDoc comments
2 parents 3369453 + e435484 commit cec73e6

File tree

16 files changed

+189
-41
lines changed

16 files changed

+189
-41
lines changed

‎cpp/ql/src/semmle/code/cpp/ir/implementation/EdgeKind.qll

Lines changed: 46 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ private newtype TEdgeKind =
1717
* `EdgeKind`.
1818
*/
1919
abstract class EdgeKind extends TEdgeKind {
20+
/** Gets a textual representation of this edge kind. */
2021
abstract string toString();
2122
}
2223

@@ -28,8 +29,6 @@ class GotoEdge extends EdgeKind, TGotoEdge {
2829
final override string toString() { result = "Goto" }
2930
}
3031

31-
GotoEdge gotoEdge() { result = TGotoEdge() }
32-
3332
/**
3433
* A "true" edge, representing the successor of a conditional branch when the
3534
* condition is non-zero.
@@ -38,8 +37,6 @@ class TrueEdge extends EdgeKind, TTrueEdge {
3837
final override string toString() { result = "True" }
3938
}
4039

41-
TrueEdge trueEdge() { result = TTrueEdge() }
42-
4340
/**
4441
* A "false" edge, representing the successor of a conditional branch when the
4542
* condition is zero.
@@ -48,8 +45,6 @@ class FalseEdge extends EdgeKind, TFalseEdge {
4845
final override string toString() { result = "False" }
4946
}
5047

51-
FalseEdge falseEdge() { result = TFalseEdge() }
52-
5348
/**
5449
* An "exception" edge, representing the successor of an instruction when that
5550
* instruction's evaluation throws an exception.
@@ -58,8 +53,6 @@ class ExceptionEdge extends EdgeKind, TExceptionEdge {
5853
final override string toString() { result = "Exception" }
5954
}
6055

61-
ExceptionEdge exceptionEdge() { result = TExceptionEdge() }
62-
6356
/**
6457
* A "default" edge, representing the successor of a `Switch` instruction when
6558
* none of the case values matches the condition value.
@@ -68,8 +61,6 @@ class DefaultEdge extends EdgeKind, TDefaultEdge {
6861
final override string toString() { result = "Default" }
6962
}
7063

71-
DefaultEdge defaultEdge() { result = TDefaultEdge() }
72-
7364
/**
7465
* A "case" edge, representing the successor of a `Switch` instruction when the
7566
* the condition value matches a correponding `case` label.
@@ -91,4 +82,48 @@ class CaseEdge extends EdgeKind, TCaseEdge {
9182
string getMaxValue() { result = maxValue }
9283
}
9384

94-
CaseEdge caseEdge(string minValue, string maxValue) { result = TCaseEdge(minValue, maxValue) }
85+
/**
86+
* Predicates to access the single instance of each `EdgeKind` class.
87+
*/
88+
module EdgeKind {
89+
/**
90+
* Gets the single instance of the `GotoEdge` class.
91+
*/
92+
GotoEdge gotoEdge() { result = TGotoEdge() }
93+
94+
/**
95+
* Gets the single instance of the `TrueEdge` class.
96+
*/
97+
TrueEdge trueEdge() { result = TTrueEdge() }
98+
99+
/**
100+
* Gets the single instance of the `FalseEdge` class.
101+
*/
102+
FalseEdge falseEdge() { result = TFalseEdge() }
103+
104+
/**
105+
* Gets the single instance of the `ExceptionEdge` class.
106+
*/
107+
ExceptionEdge exceptionEdge() { result = TExceptionEdge() }
108+
109+
/**
110+
* Gets the single instance of the `DefaultEdge` class.
111+
*/
112+
DefaultEdge defaultEdge() { result = TDefaultEdge() }
113+
114+
/**
115+
* Gets the `CaseEdge` representing a `case` label with the specified lower and upper bounds.
116+
* For example:
117+
* ```
118+
* switch (x) {
119+
* case 1: // Edge kind is `caseEdge("1", "1")`
120+
* return x;
121+
* case 2...8: // Edge kind is `caseEdge("2", "8")`
122+
* return x - 1;
123+
* default: // Edge kind is `defaultEdge()`
124+
* return 0;
125+
* }
126+
* ```
127+
*/
128+
CaseEdge caseEdge(string minValue, string maxValue) { result = TCaseEdge(minValue, maxValue) }
129+
}

‎cpp/ql/src/semmle/code/cpp/ir/implementation/TempVariableTag.qll

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
1+
/**
2+
* Defines the public interface to temporary variable tags, which describe the reason a particular
3+
* `IRTempVariable` was generated.
4+
*/
5+
16
private import internal.TempVariableTagInternal
27
private import Imports::TempVariableTag
38

9+
/**
10+
* A reason that a particular IR temporary variable was generated. For example, it could be
11+
* generated to hold the return value of a function, or to hold the result of a `?:` operator
12+
* computed on each branch. The set of possible `TempVariableTag`s is language-dependent.
13+
*/
414
class TempVariableTag extends TTempVariableTag {
515
string toString() { result = getTempVariableTagId(this) }
616
}

‎cpp/ql/src/semmle/code/cpp/ir/implementation/aliased_ssa/Instruction.qll

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -585,9 +585,9 @@ class ConditionalBranchInstruction extends Instruction {
585585

586586
final Instruction getCondition() { result = getConditionOperand().getDef() }
587587

588-
final Instruction getTrueSuccessor() { result = getSuccessor(trueEdge()) }
588+
final Instruction getTrueSuccessor() { result = getSuccessor(EdgeKind::trueEdge()) }
589589

590-
final Instruction getFalseSuccessor() { result = getSuccessor(falseEdge()) }
590+
final Instruction getFalseSuccessor() { result = getSuccessor(EdgeKind::falseEdge()) }
591591
}
592592

593593
class ExitFunctionInstruction extends Instruction {
@@ -907,7 +907,7 @@ class SwitchInstruction extends Instruction {
907907

908908
final Instruction getACaseSuccessor() { exists(CaseEdge edge | result = getSuccessor(edge)) }
909909

910-
final Instruction getDefaultSuccessor() { result = getSuccessor(defaultEdge()) }
910+
final Instruction getDefaultSuccessor() { result = getSuccessor(EdgeKind::defaultEdge()) }
911911
}
912912

913913
/**

‎cpp/ql/src/semmle/code/cpp/ir/implementation/internal/OperandTag.qll

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
/**
2+
* Defines the set of possible `OperandTag`s, which are used to identify the role each `Operand`
3+
* plays in the evaluation of its `Instruction`.
4+
*/
5+
16
private import OperandTagInternal
27

38
private newtype TOperandTag =
@@ -24,10 +29,18 @@ private newtype TOperandTag =
2429
* an `Instruction` is determined by the instruction's opcode.
2530
*/
2631
abstract class OperandTag extends TOperandTag {
32+
/** Gets a textual representation of this operand tag */
2733
abstract string toString();
2834

35+
/**
36+
* Gets an integer that represents where this this operand will appear in the operand list of an
37+
* instruction when the IR is printed.
38+
*/
2939
abstract int getSortOrder();
3040

41+
/**
42+
* Gets a label that will appear before the operand when the IR is printed.
43+
*/
3144
string getLabel() { result = "" }
3245
}
3346

@@ -47,7 +60,7 @@ abstract class RegisterOperandTag extends OperandTag { }
4760
abstract class TypedOperandTag extends MemoryOperandTag { }
4861

4962
// Note: individual subtypes are listed in the order that the operands should
50-
// appear in the operand list of the instruction when printing.
63+
// appear in the operand list of the instruction when the IR is printed.
5164
/**
5265
* The address operand of an instruction that loads or stores a value from
5366
* memory (e.g. `Load`, `Store`, `InitializeParameter`, `IndirectReadSideEffect`).

‎cpp/ql/src/semmle/code/cpp/ir/implementation/raw/Instruction.qll

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -585,9 +585,9 @@ class ConditionalBranchInstruction extends Instruction {
585585

586586
final Instruction getCondition() { result = getConditionOperand().getDef() }
587587

588-
final Instruction getTrueSuccessor() { result = getSuccessor(trueEdge()) }
588+
final Instruction getTrueSuccessor() { result = getSuccessor(EdgeKind::trueEdge()) }
589589

590-
final Instruction getFalseSuccessor() { result = getSuccessor(falseEdge()) }
590+
final Instruction getFalseSuccessor() { result = getSuccessor(EdgeKind::falseEdge()) }
591591
}
592592

593593
class ExitFunctionInstruction extends Instruction {
@@ -907,7 +907,7 @@ class SwitchInstruction extends Instruction {
907907

908908
final Instruction getACaseSuccessor() { exists(CaseEdge edge | result = getSuccessor(edge)) }
909909

910-
final Instruction getDefaultSuccessor() { result = getSuccessor(defaultEdge()) }
910+
final Instruction getDefaultSuccessor() { result = getSuccessor(EdgeKind::defaultEdge()) }
911911
}
912912

913913
/**

‎cpp/ql/src/semmle/code/cpp/ir/implementation/raw/internal/TranslatedCall.qll

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -375,7 +375,7 @@ class TranslatedAllocationSideEffects extends TranslatedSideEffects,
375375

376376
override Instruction getInstructionSuccessor(InstructionTag tag, EdgeKind kind) {
377377
tag = OnlyInstructionTag() and
378-
kind = gotoEdge() and
378+
kind = EdgeKind::gotoEdge() and
379379
if exists(getChild(0))
380380
then result = getChild(0).getFirstInstruction()
381381
else result = getParent().getChildSuccessor(this)

‎cpp/ql/src/semmle/code/cpp/ir/implementation/raw/internal/TranslatedFunction.qll

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -720,7 +720,7 @@ class TranslatedReadEffect extends TranslatedElement, TTranslatedReadEffect {
720720

721721
override Instruction getInstructionSuccessor(InstructionTag tag, EdgeKind edge) {
722722
tag = OnlyInstructionTag() and
723-
edge = gotoEdge() and
723+
edge = EdgeKind::gotoEdge() and
724724
result = getParent().getChildSuccessor(this)
725725
}
726726

‎cpp/ql/src/semmle/code/cpp/ir/implementation/unaliased_ssa/Instruction.qll

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -585,9 +585,9 @@ class ConditionalBranchInstruction extends Instruction {
585585

586586
final Instruction getCondition() { result = getConditionOperand().getDef() }
587587

588-
final Instruction getTrueSuccessor() { result = getSuccessor(trueEdge()) }
588+
final Instruction getTrueSuccessor() { result = getSuccessor(EdgeKind::trueEdge()) }
589589

590-
final Instruction getFalseSuccessor() { result = getSuccessor(falseEdge()) }
590+
final Instruction getFalseSuccessor() { result = getSuccessor(EdgeKind::falseEdge()) }
591591
}
592592

593593
class ExitFunctionInstruction extends Instruction {
@@ -907,7 +907,7 @@ class SwitchInstruction extends Instruction {
907907

908908
final Instruction getACaseSuccessor() { exists(CaseEdge edge | result = getSuccessor(edge)) }
909909

910-
final Instruction getDefaultSuccessor() { result = getSuccessor(defaultEdge()) }
910+
final Instruction getDefaultSuccessor() { result = getSuccessor(EdgeKind::defaultEdge()) }
911911
}
912912

913913
/**

‎cpp/ql/src/semmle/code/cpp/ir/internal/CppType.qll

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,7 @@ private newtype TCppType =
203203
* of a `VariableAddress` where the variable is of reference type)
204204
*/
205205
class CppType extends TCppType {
206+
/** Gets a textual representation of this type. */
206207
string toString() { none() }
207208

208209
/** Gets a string used in IR dumps */
@@ -224,6 +225,10 @@ class CppType extends TCppType {
224225
*/
225226
predicate hasType(Type type, boolean isGLValue) { none() }
226227

228+
/**
229+
* Holds if this type represents the C++ type `type`. If `isGLValue` is `true`, then this type
230+
* represents a glvalue of type `type`. Otherwise, it represents a prvalue of type `type`.
231+
*/
227232
final predicate hasUnspecifiedType(Type type, boolean isGLValue) {
228233
exists(Type specifiedType |
229234
hasType(specifiedType, isGLValue) and
@@ -540,6 +545,9 @@ string getOpaqueTagIdentityString(Type tag) {
540545
}
541546

542547
module LanguageTypeSanity {
548+
/**
549+
* Sanity query to detect C++ `Type` objects which have no corresponding `CppType` object.
550+
*/
543551
query predicate missingCppType(Type type, string message) {
544552
not exists(getTypeForPRValue(type)) and
545553
exists(type.getSize()) and

‎cpp/ql/src/semmle/code/cpp/ir/internal/IntegerConstant.qll

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
1+
/**
2+
* Provides predicates for manipulating integer constants that are tracked by constant folding and
3+
* similar analyses.
4+
*/
5+
6+
/**
7+
* An alias used to represent the constant value of an integer, if one can be determined. If no
8+
* single constant value can be determined, or if the constant value is out of the representable
9+
* range, it will be represented as the special value `unknown()`. This allows `IntValue` to be used
10+
* in contexts where there must always be a value for the `IntValue`, even if no constant value is
11+
* known.
12+
*/
113
class IntValue = int;
214

315
/**

0 commit comments

Comments
 (0)