update advaned usage doc for vector

Author: Mangpo Phothilimthana

Diff for: .gitignore

@@ -2,3 +2,4 @@ compiled
 *~
 vpe
 path.rkt
+.DS_Store

Diff for: TODO

@@ -1,9 +1,8 @@
 TODO
-- document #:structure, get-sym-inst
+- check that vector class has corresponding scalar version
 
 Features
 - vector
-  = point-wise vector
   = shuffle, extract, insert (exercise)
 - various data type, i32, i16, i8
 - aggregate type

Diff for: documentation/advanced-usage.md

@@ -33,22 +33,65 @@ Notice that the second operand of `'ldr#` is `'reg-sp`.
 
 <a name="vector"></a>
 ### Vector Instructions
-Typically, when define a program state element is a primitive entity with the same number of bits as the define bitwidth ([Step 1.1 of Extending GreenThumb to a New ISA](new-isa.md#step1.1)). In this section, we describe how to define a program state element as a collection of primitive entities. For example, we will define a program state element type `vec4` to be a vector of four primitive entities. To do so, we simply pass an additional argument when calling `define-progstate-type` ([Step 1.3 of Extending GreenThumb to a New ISA](new-isa.md#step1.1)) as follows:
+Typically, we define a program state element as a primitive entity with the same number of bits as the defined bitwidth ([Step 1.1 of Extending GreenThumb to a New ISA](new-isa.md#step1.1)). In this section, we describe how to define a program state element as a collection of primitive entities. For example, we will define a program state element type `vec4` (vector register with 4 lanes) to be a vector of 4 primitive entities. To do so, we simply pass an additional argument `#:structure` when calling `define-progstate-type` ([Step 1.3 of Extending GreenThumb to a New ISA](new-isa.md#step1.1)) as follows:
 ```
  (define-progstate-type
       'vec4
-      #:structure (for/vector ([i 4]) 'x) ;; a vector contains 4 primitive elements
+      #:structure (for/vector ([i 4]) 'x) ;; a vector contains 4 primitive entities
       #:get ...
       #:set ...)
 ```
-The expression passed to `#:structure` should evaluate to a collection of `'x` where `'x` represents a primitive entity. 
+The expression passed to `#:structure` should evaluate to a collection of `'x`, where `'x` represents a primitive entity.
 
-TODO: 
-- define-instruction-class
- - #:scalar (groups-of-opcodes = 1 only)
- - backward if no scalar
-- const-vec4
-- see llvm as an example
+Now we can define an intruction class for vector add `vadd` and vector multiply `vmul` as follows:
+```
+(define-instruction-class
+ 'rrr-commute-vec4
+ '(vadd vmul)
+ #:scalar '(add mul) #:vector-width 4
+ #:args '(vec4 vec4 vec4)
+ #:ins '(1 2) #:outs '(0) #:commute '(1 . 2))
+```
+This is similar to defining instruction classes for scalar instructions except the additional arguments `#:scalar` and `#:vector-width`. When defining vector instructions, we have to inform GreenThumb their corresponding scalar version and vector width. If developers do not provide such information, the backward search part of the enumerative will not work. If a vector instruction has no corresponding scalar instruction, developers must create a fake scalar instruction, and set the cost of such instruction to be very high to prevent the superoptimizer from using it to synthesize output programs.
+
+**Important note:** This vector support only works when there is one opcode per instruction (i.e. `(init-machine-description 1)`). If there are more than one opcodes per instruction, please contact [email protected]
+
+##### Vector Constants
+A scalar instruction may contain constants, while a vector instruction may contain vector constants. Therefore, we may need another type of instruction operand type. For example, in LLVM, we can add a vector variable to a vector of ones: `%out = add <4 x i32> %in, <i32 1, i32 1, i32 1, i32 1>`. In this case, we define an operand type for vector constants as:
+```
+(define-arg-type 'const-vec4
+  (lambda (config) (list (vector 0 0 0 0)
+                         (vector 1 1 1 1))))
+```
+Recall that the stochastic search and enumerative search will try to construct instructions from the values from this list, but the symbolic search is not.
+
+##### Instruction Skeleton (For Symbolic Search)
+Typically, the framework automatically infers an instruction skeleton from the defined instruction classes by treating all instruction operands to be primitive numbers. However, vector instructions may contain non-primitive numbers as operands, such as vector constants; a register/variable (either scalar or vector) is considered to be a primitive number because we use a single ID which is a number to represent a register/variable. Becase of vector constants, we have to manually provide the instruction skeleton by overriding the method `(gen-sym-inst)` of the class `symbolic%`. The skeleton can be constructed by using the provided lambda functions `sym-op` and `sym-arg`. The framework expects a program skeleton to be an `inst` with `(sym-op)` as its opcode and `(sym-arg)` as its arguments.
+
+For example, the default `(gen-sym-inst)` for scalar instructions may look like:
+```
+(define/override (gen-sym-inst)
+  (define n (get-field max-number-of-args machine))
+  (inst (sym-op)
+        (for/vector ([i n]) (sym-arg))))
+```
+However, `(sym-arg)` represents a privitive number. Since we know that the first operand cannot be is always a register/variable (either scalar or vector), vector constants cannot be the first operand. Therefore, we define the first entry of operands (or arguments) to be `(sym-arg)` as before, but the rest are `(sym-arg-vec)`; we define `(sym-arg-vec)` to either be `(sym-arg)` or a vector of four `(sym-arg)`s.
+```
+(define/override (gen-sym-inst)
+  (define n (get-field max-number-of-args machine))
+  (inst (sym-op)
+        (vector-append (vector (sym-arg))
+                       (for/vector ([i (sub1 n)]) (sym-arg-vec)))))
+                       
+(define (sym-arg-vec) ;; either sym-arg or 4 x sym-arg
+  (define-symbolic* is-num boolean?) ;; decision variable
+  (if is-num          
+      (sym-arg)
+      (vector (sym-arg) (sym-arg) (sym-arg) (sym-arg))))
+```
+
+##### Working Example
+Our LLVM IR superoptimizer supports a few vector instructions. See `llvm/llvm-machine.rkt` on how to define vector instructions and `llvm/llvm-symbolic.rkt` on how to define the instruction skeleton.
 
 <a name="multiple-opcodes"></a>
 ### Instruction with Multiple Opcodes