Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs fixes #1478

Merged
merged 10 commits into from
Mar 28, 2024
2 changes: 2 additions & 0 deletions docs/docs/CPG/specs/dfg-function-summaries.md
Original file line number Diff line number Diff line change
@@ -107,12 +107,14 @@ An example of a file could look as follows:
```

This file configures the following edges:

* For a method declaration in Java `java.util.List.addAll(int, java.util.Object)`, the parameter 1 flows to the base (i.e., the list object)
* For a method declaration in Java `java.util.List.addAll(java.util.Object)`, the parameter 0 flows to the base (i.e., the list object)
* For a function declaration in C `memcpy` (and thus also CXX `std::memcpy`), the parameter 1 flows to parameter 0.


Note: If multiple function summaries match a method/function declaration (after the normal matching considering the language, local name of the function/method, signature if applicable and type hierarchy of the base object), we use the following routine to identify ideally a single entry:

1. We filter for existing signatures since it's more precisely specified than the generic "catch all" without a signature-element.
2. We filter for the most precise class of the base.
3. If there are still multiple options, we take the longest signature.
17 changes: 11 additions & 6 deletions docs/docs/CPG/specs/dfg.md
Original file line number Diff line number Diff line change
@@ -91,7 +91,7 @@ flowchart LR
```mermaid
flowchart LR
A[assignment.rhs] -- DFG --> assignment.lhs;
subgraph S[If the ast parent is not a Block
subgraph S[If the ast parent is not a Block]
direction LR
assignment.rhs -- DFG --> assignment;
end
@@ -162,6 +162,7 @@ Scheme:
## NewExpression

Interesting fields:

* `initializer: Expression`: The initializer of the expression.

The `initializer` flows to the whole expression.
@@ -207,7 +208,7 @@ Scheme:
thenExpression -.- node;
elseExpression -.- node;
elseExpression -- DFG --> node;
```
```

## Reference

@@ -269,7 +270,7 @@ The `ControlFlowSensitiveDFGPass` completely changes this behavior and accounts
input -- DFG 4 --> R[/Node/];
R == next read of ==> refersTo;
```
* For compound operators such as `+=, -=, *=, /=`, we have an incoming flow from the last writes to reference on the left hand side of the expression to the lhs. The lhs then flows to the whole expression. Also, the right hand side flows to the whole expression (if it's a read, this is processed separately). The data flows back to the lhs which is marked as the last write to the variable. *Attention: This potentially adds loops and can look like a branch. Needs to be handled with care in subsequent passes/analyses!*
* For compound operators such as `+=, -=, *=, /=`, we have an incoming flow from the last writes to reference on the left hand side of the expression to the lhs. The lhs then flows to the whole expression. Also, the right hand side flows to the whole expression (if it's a read, this is processed separately). The data flows back to the lhs which is marked as the last write to the variable. *Attention: This potentially adds loops and can look like a branch. Needs to be handled with care in subsequent passes/analyses!* Scheme:
```mermaid
flowchart LR
node -.- rhs;
@@ -283,9 +284,9 @@ The `ControlFlowSensitiveDFGPass` completely changes this behavior and accounts
node -- DFG 3 --> lhs;
R[/Node/] == next read of ==> refersTo;
```
* If the variable is assigned a value (a binary operator `var = rhs`), the right hand side flows to the variable. This is considered as a write operation.
* If the variable is assigned a value (a binary operator `var = rhs`), the right hand side flows to the variable. This is considered as a write operation. Scheme:
```mermaid
flowchart LR
flowchart LR
node -.- rhs;
node -.- lhs;
lhs -.- refersTo;
@@ -462,8 +463,8 @@ Scheme:
### DoStatement

Interesting fields:
* `condition: Statement`: The condition that is evaluated before making the branching decision

* `condition: Statement`: The condition that is evaluated before making the branching decision

Scheme:
```mermaid
@@ -475,6 +476,7 @@ Scheme:
### WhileStatement

Interesting fields:

* `condition: Statement`: The condition that is evaluated before making the branching decision
* `conditionDeclaration: Statement`: A declaration containing the condition in the initializer, used instead of the condition

@@ -490,6 +492,7 @@ Scheme:
### ForStatement

Interesting fields:

* `condition: Statement`: The condition that is evaluated before making the branching decision
* `conditionDeclaration: Statement`: A declaration containing the condition in the initializer, used instead of the condition.

@@ -506,6 +509,7 @@ Scheme:
### IfStatement

Interesting fields:

* `condition: Statement`: The condition that is evaluated before making the branching decision
* `conditionDeclaration: Statement`: A declaration containing the condition in the initialize, used instead of the condition.

@@ -521,6 +525,7 @@ Scheme:

### SwitchStatement
Interesting fields:

* `selector: Statement`: The expression that is evaluated before making the branching decision
* `selectorDeclaration: Statement`: A declaration containing the selector in the initializer, used instead of the selector.

5 changes: 3 additions & 2 deletions docs/docs/CPG/specs/eog.md
Original file line number Diff line number Diff line change
@@ -365,6 +365,7 @@ flowchart LR
Throwing of exceptions is modelled as unary operation. The EOG continues at an exception catching structure or a function that does a re-throw.

Interesting fields:

* `input: Expression`: Exception to be thrown for exception handling.

Scheme:
@@ -501,7 +502,7 @@ Interesting fields:

* `initializer: Expression`: To be evaluated before creating a new object.

* Scheme:
Scheme:
```mermaid
flowchart LR
classDef outer fill:#fff,stroke:#ddd,stroke-dasharray:5 5;
@@ -527,7 +528,7 @@ flowchart LR
```

## ExpressionList
List of several expressions that aer evaluated sequentially. The resulting value is the last evaluated expression.
List of several expressions that are evaluated sequentially. The resulting value is the last evaluated expression.

Interesting fields: