Documentation updates (#31)

* Update kergen README.md

* fix spaces

* improve wording of third field

* Update README.md

Remove trailing spaces

* Update kerngen/README.md

---------

Co-authored-by: Hamish Hunt <[email protected]>

README.md

@@ -17,7 +17,7 @@ by the regulated industries and government.
 Most of the FHE schemes of today perform the computation using very large
 polynomial rings, thus requiring considerable compute power and data
 movement between main memory and the CPU's registers. HERACLES improves
-the performance of FHE by accelerating the computation over the large 
+the performance of FHE by accelerating the computation over the large
 polynomials and optimizing the data movement involved in the computation.
 
 HERACLES introduces a new Polynomial Data type which does not exist in
@@ -30,10 +30,10 @@ new implementations of FHE schemes and also integrate with existing libraries.
 
 <p>
 <img src="docs/images/HERACLES_SDK_Integration_3rd_Party.png" align="left" width="600" />
-  
+
 The Encrypted Computing SDK (or HERACLES SDK) will realize a multistage
 transformation (compiler) pipeline, inspired by the
-[LLVM Compiler Infrastructure](https://llvm.org/). We have adopted a 
+[LLVM Compiler Infrastructure](https://llvm.org/). We have adopted a
 modular approach based on language independent intermediate
 representations (IR) that promotes the separation of concerns at each
 stage of the pipeline and allowing for dedicated transformations and
@@ -64,21 +64,21 @@ transpilers.
 
 We are currently at Phase 1, more specifically developing the P-ISA Tools
 component which comprises three main tools, a) Kernel Generator, b) Program
-Mapper, and c) Functional Modeler Simulator. 
+Mapper, and c) Functional Modeler Simulator.
 Each tool in this repo is self contained and has its own local README.
 
 Current development is focussed on the Kernel Generator.
 Follow the instructions [here](./kerngen) to start experimenting with it.
 
 # Contributing
-Intel P-ISA Tools project welcomes external contributions through pull 
+Intel P-ISA Tools project welcomes external contributions through pull
 requests to the `main` branch.
 
 Please refer to the [Contributing](CONTRIBUTING.md) and
 [Code of Conduct](CODE_OF_CONDUCT) documents for additional information on
 the contribution acceptance guidelines.
 
-We use signed commits, please remember to sign your commits before making a 
+We use signed commits, please remember to sign your commits before making a
 pull request.  See instructions
 [here](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/signing-commits)
 for how to sign commits.
@@ -90,7 +90,7 @@ pre-commit install
 pre-commit run --all-files
 ```
 
-Please run the tests provided in each of the components and make sure 
+Please run the tests provided in each of the components and make sure
 the tests pass.
 
 # Feedback

kerngen/README.md

@@ -3,7 +3,7 @@
 This is the kernel generator (`kerngen`) responsible for producing HERACLES ISA
 kernels for various polynomial operations that occur in cryptography (or
 elsewhere) such as in homomorphic encryption (HE). A kernel is a code snippet
-of p-ISA instructions with the purpose of implementing some high level
+of P-ISA instructions with the purpose of implementing some high level
 polynomial operation.
 
 
@@ -18,7 +18,7 @@ installed,
 To install the python dependencies and development tools simply run,
 
 ```bash
-pip -r requirements.txt
+pip install -r requirements.txt
 ```
 
 
@@ -31,8 +31,8 @@ defined as a 'kernel language' is received as input to the kernel generator.
 This kernel language describes (which can be used for HE schemes) operations on
 polynomials with given context parameters. This language is interpreted as a
 `high level instruction` which is then mapped to its corresponding `low level
-p-ISA instruction`. `kerngen` uses a common unix command line utility
-convention and the resulting p-ISA kernel is sent to `stdout`.
+P-ISA instruction`. `kerngen` uses a common unix command line utility
+convention and the resulting P-ISA kernel is sent to `stdout`.
 
 ## Internals
 
@@ -116,12 +116,14 @@ Context defines the global properties `(scheme, poly_order, max_rns,
 key_rns(optional))` of the input script.
 `CONTEXT` sets a global context for properties required by the kernels.
 - first field defines what we call scheme. In reality, it specifies the set of
-kernel instructions given in the manifest file, see []().
-- second field defines the polynomial size. This is required to when generating
-kernels how many units (multiples of the native polynomial size) are required
-and handled.
-- third field defines the max RNS, the global max number of how many moduli that
-the kernels can have or need to handle.
+kernel instructions given in the manifest file, see
+[manifest.json](./pisa_generators/manifest.json).
+- second field defines the native polynomial size that a given HW implementation
+supports (8192 in HERACLES silicon case). This is required by the generating
+kernels to define how many units (multiples of the native polynomial size) are
+required and handled.
+- third field defines the max RNS, the global max number of how many 32 bit prime number moduli
+(HERACLES silicon case) are in the modulus chain that the kernels can have or need to handle.
 - (optional) fourth field defines the key RNS, the number of additional moduli
 that the relinearization key has relative to the third field. i.e. If `max_rns`
 is 3 and `key_rns` is 1 the total max RNS of the relinearization key will be 4.
@@ -148,7 +150,7 @@ where `addition.data` is a text file containing the high language for an `ADD`
 operation.
 
 The kernel generator prints two comments, a context and kernel descriptor
-respectively, followed by the p-ISA kernel. If desired, the comments can be
+respectively, followed by the P-ISA kernel. If desired, the comments can be
 disabled by passing the `-q` or `--quiet` flag to the kernel generator, i.e.,
 ```bash
 ./kerngen.py -q < addition.data
@@ -159,7 +161,7 @@ disabled by passing the `-q` or `--quiet` flag to the kernel generator, i.e.,
 
 You can add new kernel generators that you have developed by creating a class
 that inherits from the `HighOp` abstract class (interface) and implementing the
-`to_pisa` method; turning this instruction into a p-ISA instruction class.
+`to_pisa` method; turning this instruction into a P-ISA instruction class.
 Examples can be seen in the simpler implementations given in
 [basic.py](./pisa_generators/basic.py). Also, provide a class method
 `from_string` that will be passed the args for that command.
@@ -208,7 +210,7 @@ represent the inputs and outputs of the operation. This type represents the
 polynomials and holds information such as the `name` of symbol that represents
 the polynomial, the number of `parts`, and the `rns`.
 
-At a high level kernels convert high-level operations into low-level p-ISA
+At a high level kernels convert high-level operations into low-level P-ISA
 operations, thus all kernels will need to inherit from `HighOp` and define the
 conversion function `to_pisa` as follows
 ```python
@@ -239,7 +241,7 @@ see [square.py](./pisa_generators/square.py) for a complete example of this.
 
 # Mixed operations
 You will find that during kernel writing, you will end up with a collection of
-either p-ISA operation objects, other kernel objects, or a mixture of both. For
+either P-ISA operation objects, other kernel objects, or a mixture of both. For
 your convenience a useful function `mixed_to_pisa_ops` is provided that can
 take all of these sequentially and outputs the required `list[PIsaOp]`.