From cef32999a4132795c73ec5e89d347f6a8a84f089 Mon Sep 17 00:00:00 2001
From: Jordan Wiens <jordan@psifertex.com>
Date: Mon, 20 Feb 2023 17:43:19 -0500
Subject: cookbook ssa example

---
 docs/dev/cookbook.md | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

(limited to 'docs/dev')

diff --git a/docs/dev/cookbook.md b/docs/dev/cookbook.md
index 80f1af88..c9787ddb 100644
--- a/docs/dev/cookbook.md
+++ b/docs/dev/cookbook.md
@@ -50,7 +50,7 @@ Is that memcpy length a bit too big?
 for ref in current_function.caller_sites:
 	if isinstance(ref.hlil, Call) and len(ref.hlil.params) >= 3:
 		print(ref.hlil.params[2])
-		# For bonus points, query the range analysis
+		# For bonus points, query the range analysis using .possible_values
 ```
 
 ### Search for a good nop-slide?
@@ -66,3 +66,39 @@ Make sure to check out the much more in-depth [type guide](../guide/type.md#usin
 ```python
 current_function.function_type = Type.function(Type.void(), [])
 ```
+
+### Find a variable's definition and all uses using SSA
+
+```python
+>>> print(current_il_instruction)
+x0_2 = 0x100007750(x0_1)
+>>> findMe = current_il_instruction.params[0]
+>>> findMe.ssa_form.function.get_ssa_var_definition(findMe.ssa_form.src)
+<mlil: x0_1#5 = ϕ(x0_1#1, x0_1#2, x0_1#4)>
+>>> findMe.ssa_form.function.get_ssa_var_uses(findMe.ssa_form.src)
+[<mlil: x0_2#6, mem#3 = 0x100007750(x0_1#5) @ mem#2>]
+```
+
+If the result is a PHI, you'll want to either recursively search each version as well, or (more likely) use a queue to process all parameters until you find the source which could be an argument, global variable, immediate, or some other transformed data (which would require handling more types of IL instructions such as math operations, etc):
+
+```python
+>>> findMe.ssa_form.function.get_ssa_var_definition(findMe.ssa_form.src).src
+[<ssa x0_1 version 1>, <ssa x0_1 version 2>, <ssa x0_1 version 4>]
+>>> findMe2 = findMe.ssa_form.function.get_ssa_var_definition(findMe.ssa_form.src).src[0]
+>>> current_il_function.get_ssa_var_definition(findMe2)
+<mlil: x0_1#1 = "%*lld ">
+```
+
+Note, don't forget the difference between an MLIL Variable Instruction and the actual variable itself (use .src to get the later from the former)
+
+```python
+>>> findMe.ssa_form
+<mlil: x0#3>
+>>> findMe.ssa_form.src
+<ssa x0 version 3>
+>>> type(findMe.ssa_form.src)
+<class 'binaryninja.mediumlevelil.SSAVariable'>
+>>> type(findMe.ssa_form)
+<class 'binaryninja.mediumlevelil.MediumLevelILVarSsa'>
+```
+
-- 
cgit v1.3.1