Merge pull request #4 from cryspen/readme-addendum

Readme addendum

Author: karthikbhargavan

testable-simd-models/README.md

@@ -185,12 +185,26 @@ sometimes need to add more type annotations in our defined models. We also remov
 since our models are always in safe Rust. Otherwise, our code for the defined intrinsics looks very
 similar to the upstream code in `core::arch`.
 
-3. Next, we add a test for this intrinsic. For this, we navigate to `core_arch/avx2/tests/avx2.rs`. Since the value of
-   `IMM8` can be up to 8 bits, we want to test constant arguments up to 255. Thus, we write the following macro invocation.
+3. Next, we add a test for this intrinsic in `core_arch/avx2/tests/avx2.rs`. For convenience purposes, we have defined a `mk!` macro, which can be used to automatically generate
+   tests. The test generated by the macro generates a number of random inputs (by default, 1000), and compares the output generated by the model
+   and that generated by the intrinsic in upstream `core::arch`.  A valid test of the intrinsic above looks like this.
    ```rust
 	   mk!([100]_mm256_bsrli_epi128{<0>,<1>,<2>,<3>,...,<255>}(a: BitVec));
+	   //    i.          ii.                  iii.                 iv.
    ```
-   Here, the `[100]` means we test 100 random inputs for each constant value. This concludes the necessary steps for implementing an intrinsic.
+   The macro invocation has four parts. 
+   1. By default the macro tests for a thousand randomly generated inputs. If needed, this can be modified, such as here, where the `[100]` is used so that
+      only 100 inputs are generated. 
+   2. This is the name of the intrinsic being tested, and is necessary in all cases.
+   3. This is relevant because of the constant `IMM8` argument used by the intrinsic. We can gleam from the name the constant argument is supposed
+      to be at most 8 bits wide. We can confirm this by looking at the `core::arch` implementation, and spotting the `static_assert_uimm_bits!(IMM8, 8);`
+      line, which asserts the constant argument fits in at most 8 bits. Thus, we add `{<0>,<1>,<2>,<3>,...,<255>}` to test for each possible constant
+      value of the constant argument. If the intrinsic does not have a constant argument, then this part must be ignored.
+   4. This signifies the arguments that the intrinsics take, and is also necessary.
+   
+   This surmises the steps needed to use the `mk!` macro to generate a test. There is a caveat however. In the case that the output of an intrinsic is _not_
+   a bit-vector (and is instead say, an integer like `i32`), then the macro will not work, and a manual test has to be written. 
+   
 
 
 ## Contributing Models