3 files changed, 24 insertions, 3 deletions
diff --git a/docs/dev/archplatform-platform.md b/docs/dev/archplatform-platform.md
index 4a5a8086..3d078624 100644
--- a/docs/dev/archplatform-platform.md
+++ b/docs/dev/archplatform-platform.md
@@ -55,6 +55,16 @@ Other fields that Quark did not need, but you can specify:
 * `implicitly_defined_regs` - Certain calling conventions pass registers to calls which are not included in type signatures (such as how MIPS on Linux sets `$t9` to the address of the called function, but this should not clutter up the type signature).
 * `required_arg_regs` - If specified, heuristic calling convention detection will only consider this calling convention if all the registers specified here are used before they are defined.
 * `required_clobbered_regs` - If specified, heuristic calling convention detection will only consider this calling convention if the function clobbers all the registers specified here.
+* `stack_args_naturally_aligned` - For stack arguments, set this to True if the convention pads each stack slot up to the natural alignment of its type rather than the address-size word. Defaults to False.
+* `is_return_type_reg_compatible` — Returns True if a return value of a type fits in the convention's return register(s). Override when your ABI accepts only a subset of widths or excludes structures/arrays even when they would technically fit. Used by analysis to decide whether to use an indirect return.
+* `is_arg_type_reg_compatible` — Returns True if a parameter value of a type fits in the convention's parameter register(s).
+* `is_non_reg_arg_indirect` — Returns True if a parameter that does not fit in registers should be passed by pointer instead of pushed on the stack.
+* `get_indirect_return_value_location` — Returns the `Variable` that holds the caller-supplied pointer to the return value storage when the return value is too big for registers. Defaults to the first integer argument register.
+* `get_returned_indirect_return_value_pointer` — Returns the `Variable` that the *callee* uses to give the indirect return pointer back to the caller, or `None` if the convention does not return it.
+* `get_return_value_location` — Compute the return value location for a given `ReturnValue`.
+* `get_parameter_locations` — Compute the location for each parameter given the already resolved return value location (which the convention may need to skip past).
+* `get_stack_adjustment_for_locations` — Returns the number of bytes of stack adjustment performed by the called function on return. The default returns zero (caller cleans the stack).
+* `get_call_layout` — Compute a complete `CallLayout` (parameter locations, return value location, stack adjustment, register stack adjustments) for a function with the given signature. The default implementation composes the answer from `get_return_value_location`, `get_parameter_locations` and the stack adjustment helpers. Override only when the layout has interactions you can't express component-wise (Go's stack-after-args return slot is an example).
 
 Then, we need to register the Calling Convention and tell the Platform and Architecture to use it:
 
diff --git a/docs/dev/bnil-hlil.md b/docs/dev/bnil-hlil.md
index ea006547..7443f192 100644
--- a/docs/dev/bnil-hlil.md
+++ b/docs/dev/bnil-hlil.md
@@ -79,6 +79,8 @@ There are a number of properties that can be queried on the [`HighLevelILInstruc
 * `HLIL_SPLIT` - A split pair of variables `high`:`low` which can be used a single expression
 * `HLIL_DEREF` - Dereferences `src`
 * `HLIL_DEREF_FIELD` -
+* `HLIL_PASS_BY_REF` - Wraps `src` to indicate that the calling convention is passing a parameter by reference. The inner expression has the reference taken and has a pointer type. Only appears as a parameter expression on a call instruction.
+* `HLIL_RETURN_BY_REF` - Wraps `src` to indicate that the value is being returned indirectly through a caller-supplied pointer. The inner expression is the destination of the return value, not a pointer to it. Only appears on the left side of an assignment for the result of a call instruction.
 
 ### Arithmetic Operations
 
diff --git a/docs/dev/bnil-mlil.md b/docs/dev/bnil-mlil.md
index 9a6aa6a3..15fb836d 100644
--- a/docs/dev/bnil-mlil.md
+++ b/docs/dev/bnil-mlil.md
@@ -277,9 +277,8 @@ The parameter list can be accessed through the `params` property:
 
 * `MLIL_JUMP` - Branch to the `dest` expression's address
 * `MLIL_JUMP_TO` - A jump table dispatch instruction. Uses the `dest` expression to calculate the MLIL instruction target `targets` to branch to
-* `MLIL_CALL` - Branch to the `dest` expression function, saving the return address, with the list of parameters `params` and returning the list of return values `output`
+* `MLIL_CALL` - Branch to the `dest` expression function, saving the return address, with the list of parameters `params` and a list of output expressions `output_exprs` describing how each return value is delivered
 * `MLIL_CALL_UNTYPED` - This is a call instruction where stack resolution could not be determined, and thus a list of parameters and return values do not exist
-* `MLIL_CALL_OUTPUT` - This expression holds a set of return values `dest` from a call
 * `MLIL_CALL_PARAM` - This expression holds the set of parameters `src` for a call instruction
 * `MLIL_RET` - Return to the calling function.
 * `MLIL_RET_HINT` - Indirect jump to `dest` expression (only used in internal analysis passes.)
@@ -318,7 +317,7 @@ The parameter list can be accessed through the `params` property:
 * `MLIL_FLOAT_CONST` - A floating point constant `constant`
 * `MLIL_IMPORT` - A `constant` integral value representing an imported address
 * `MLIL_LOW_PART` - `size` bytes from the low end of `src` expression
-
+* `MLIL_PASS_BY_REF` - Wraps `src` to indicate that the calling convention is passing a parameter by reference. The inner expression has the reference taken and has a pointer type. Only appears as a parameter expression on a call instruction.
 
 ### Arithmetic Operations
 
@@ -401,4 +400,14 @@ The parameter list can be accessed through the `params` property:
 * `MLIL_UNIMPL` - The expression is not implemented
 * `MLIL_UNIMPL_MEM` - The expression is not implemented but does access `src` memory
 
+### Function Call Outputs
+
+Prior to version 5.4, a function call could only return a list of variables as output. The `output` property on call instructions remains a list of variables, but a function call's `output_exprs` is a list of expressions that describe in more detail how each return value is delivered to the caller, and also adds support for indirect stores. The expressions in the list are one of:
+
+* `MLIL_VAR_OUTPUT` - a whole variable is written. The simplest, most common case.
+* `MLIL_VAR_OUTPUT_FIELD` - a field of a variable (at byte `offset`) is written. Used when the return value is placed into part of a larger structure.
+* `MLIL_STORE_OUTPUT` - the return value is stored to memory at the given destination expression. Used for indirect returns that do not target a local variable.
+
+Additionally, a return value can be the following expression, wrapping one of the above:
 
+* `MLIL_RETURN_BY_REF` - Wraps `src` to indicate that the value is being returned indirectly through a caller-supplied pointer. The inner expression will be one of the `MLIL_VAR_OUTPUT`, `MLIL_VAR_OUTPUT_FIELD`, or `MLIL_STORE_OUTPUT` instructions.