Clarify control flow operations

Add pseudo-code for the control flow operations
in terms of TOSA sub-graphs.

Signed-off-by: Dominic Symes <dominic.symes@arm.com>
Change-Id: I1712e8297a0010a4e68a34df16fcbcf47fc41dd2

2 files changed, 92 insertions, 29 deletions

diff --git a/chapters/control_flow.adoc b/chapters/control_flow.adoc
index 9efa3e7..b5e305d 100644
--- a/chapters/control_flow.adoc
+++ b/chapters/control_flow.adoc
@@ -1,7 +1,7 @@
 //
 // This confidential and proprietary software may be used only as
 // authorised by a licensing agreement from ARM Limited
-// (C) COPYRIGHT 2020 ARM Limited
+// (C) COPYRIGHT 2020-2021 ARM Limited
 // ALL RIGHTS RESERVED
 // The entire notice above must be reproduced on all authorised
 // copies and copies may only be made to the extent permitted
@@ -9,40 +9,74 @@
 
 === Control Flow Operators
 
-TOSA implements two control flow operators, for conditional branching and loop based transfer of control. Both refer to region labels, which express the address of another operator in the TOSA program, to which control transfers.
+TOSA implements two control flow operators, for conditional branching and loop based control. Both have attributes that are TOSA sub-graphs.
 
 ==== COND_IF
 
-Evaluates a Boolean condition and then takes one of two distinct execution paths. This implements the semantic If-then-else structure.
+Evaluates a Boolean condition and then takes one of two distinct execution paths. This implements the semantic if-then-else structure.
 
-*Input Operands:*
+*Arguments:*
 
-* List of Input tensors – up to 4D tensor of any data layout.
-* A Boolean condition.
+|===
+|Argument|Type|Name|Description
 
-*Output Operands:*
+|Input |tensor_list_t  |input_list |List of input tensors
+|Input |bool_t         |condition  |Input condition as rank-0 tensor
+|Attribute|tosa_graph_t|then_graph |TOSA graph to execute if condition is true
+|Attribute|tosa_graph_t|else_graph |TOSA graph to execute if condition is false
+|Output|tensor_list_t  |output_list|List of output tensors
+|===
 
-* List of Input tensors – up to 4D tensor of any data layout. These need not have the same shapes as the list of input tensors.
+*Operation Function:*
 
-*Region Labels:*
+[source,c]
+----
+assert(tensor_list_shape(input_list)==tosa_input_shape(then_graph));
+assert(tensor_list_shape(input_list)==tosa_input_shape(else_graph));
+assert(tensor_list_shape(output_list)==tosa_output_shape(then_graph));
+assert(tensor_list_shape(output_list)==tosa_output_shape(else_graph));
 
-* Then: a reference to an operator that execution control transfers to if the Boolean condition is TRUE.
-* Else: a reference to an operator that execution control transfers to if the Boolean condition is FALSE.
+if (condition) {
+    tosa_execute_graph(then_graph, input_list, output_list)
+} else {
+    tosa_execute_graph(else_graph, input_list, output_list)
+}
+----
 
 ==== WHILE_LOOP
 
-Generates and evaluates a Bool condition and either executes a loop body or exits to another control point. This action is performed repeatedly after updating and re-evaluating the Boolean condition every iteration. This implements the semantic foreach or while iterative loop structure.
-
-*Input Operands:*
-
-* List of Input tensors – up to 4D tensor of any data layout. The list comprises both the tensors that are used to compute each iteration of the Bool condition, and the inputs to the body of the loop.
-
-*Output Operands:*
-
-* List of Input tensors – up to 4D tensor of any data layout. These must have the same dynamic shapes as the list of input tensors.
-
-*Region Labels:*
-
-* Cond: a reference to an operator that execution control transfers to in order to evaluate the current iteration of the Bool condition, and to update the condition for the next iteration.
-* Body: a reference to an operator that execution control transfers to in order to begin executing the body of the loop.
-
+Generates and evaluates a Bool condition and either executes a loop body or exits the loop. This action is performed repeatedly after updating and re-evaluating the Boolean condition every iteration. This implements the semantic foreach or while iterative loop structure.
+
+*Arguments:*
+
+|===
+|Argument|Type|Name|Description
+
+|Input |tensor_list_t  |input_list |List of input tensors
+|Attribute|tosa_graph_t|cond_graph |TOSA graph to evaluate the condition
+|Attribute|tosa_graph_t|body_graph |TOSA graph to execute the loop body
+|Output|tensor_list_t  |output_list|List of output tensors
+|===
+
+*Operation Function:*
+
+[source,c]
+----
+assert(tensor_list_shape(input_list)==tosa_list_shape(output_list));
+assert(tensor_list_shape(input_list)==tosa_input_shape(cond_graph));
+assert(tensor_list_shape(input_list)==tosa_input_shape(body_graph));
+assert(tensor_list_shape(input_list)==tosa_output_shape(body_graph));
+assert(tosa_output_shape(cond_graph)==tosa_list_shape([bool_t]));
+
+// The iteration number 'i' is included to give unique names to variables
+// in each iteration of the loop and is not required by implementations
+int i=0                 // iteration number
+list[i] = input_list    // copy input data as list[0]
+tosa_execute_graph(cond_graph, list[i], [condition[i]])   // initial condition
+while (condition[i]) {
+    tosa_execute_graph(body_graph, list[i], list[i+1])
+    i = i+1
+    tosa_execute_graph(cond_graph, list[i], [condition[i]])
+}
+output_list = list[i]
+----
diff --git a/chapters/operators.adoc b/chapters/operators.adoc
index db252c2..fa8cd47 100644
--- a/chapters/operators.adoc
+++ b/chapters/operators.adoc
@@ -1,7 +1,7 @@
 //
 // This confidential and proprietary software may be used only as
 // authorised by a licensing agreement from ARM Limited
-// (C) COPYRIGHT 2020 ARM Limited
+// (C) COPYRIGHT 2020-2021 ARM Limited
 // ALL RIGHTS RESERVED
 // The entire notice above must be reproduced on all authorised
 // copies and copies may only be made to the extent permitted
@@ -11,8 +11,37 @@
 
 === Operator Parameters
 
-Each operator has a set of input and output operands. The operands will be referenced during operator execution. Operators may also have a set of operator attributes. Operator attributes are expected to be constant values during compilation and may not be provided at execution time.
-For elementwise operations, the scaling of the output can be independent from the data type of the input. Thus 8-bit operations may output 16-bit data values.
+An operator processes input operands to produce output operands. An operator can have three types of parameters:
+
+* An input operand. This must be a tensor or a list of tensors and data is read by the operation.
+* An output operand. This must be a tensor or a list of tensors and data is written by the operation.
+* An attribute. This is a parameter that is constant for a particular instance of the operator. It may have any data type supported by TOSA. It is expected to be set at compile time.
+
+=== Operator Graphs
+
+Some operators, such as control flow operators, take a graph of other operators as an attribute. The type tosa_graph_t will denote a graph of operators and the following functions define the tensor shape list for the graph input and outputs:
+
+....
+shape_list_t tosa_input_shape(tosa_graph_t graph);
+shape_list_t tosa_output_shape(tosa_graph_t graph);
+....
+
+Similarly the type tensor_list_t will be used for a list of tensors and the following function returns the shape of a tensor list:
+....
+shape_list_t tensor_list_shape(tosa_list_t tensor_list);
+....
+
+The following function denotes the execution of a TOSA graph, on an input tensor list to produce an output tensor list.
+
+....
+tosa_execute_graph(tosa_graph_t graph, tosa_list_t input_list, tosa_list_t output_list) {
+    assert(tensor_list_shape(input_list)==tosa_input_shape(graph));
+    assert(tensor_list_shape(output_list)==tosa_output_shape(graph));
+    <Execute TOSA graph operators as defined in this specification>
+}
+....
+
+Note that within the graph, each input operand is instantiated as a PLACEHOLDER operator.
 
 include::tensor_ops.adoc[]