Merge pull request #3 from imaginationtech/fixes

Create documentation, address code concerns

Author: will-keen

.gitignore

@@ -1 +1,5 @@
-__pycache__/
+__pycache__/
+docs/_build
+docs/_static
+docs/_templates
+

README.md

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

constrainedrandom/__init__.py

@@ -0,0 +1,29 @@
+import sys
+import os
+sys.path.insert(0, os.path.abspath('../'))
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'constrainedrandom'
+copyright = '2023, Imagination Technologies Ltd.'
+author = 'Will Keen'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx.ext.autodoc']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = []

docs/Makefile

@@ -0,0 +1,34 @@
+The ``constrainedrandom`` package
+=================================
+
+This is the documentation generated from the code. It is intended as developer-facing documentation.
+
+User-facing classes
+-------------------
+
+These classes are user-facing and the API should remain the same.
+
+.. autoclass:: constrainedrandom.Random
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: constrainedrandom.RandObj
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Internal classes
+----------------
+
+These classes are internal-facing and the design can change if required.
+
+.. autoclass:: constrainedrandom.RandVar
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: constrainedrandom.MultiVarProblem
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -0,0 +1,77 @@
+Examples
+========
+
+Here are some realistic examples implemented with ``constrainedrandom``.
+
+Load instruction
+----------------
+
+The following example makes use of all of ``constrainedrandom``'s features to randomise a fictional load instruction opcode.
+
+..  code-block:: python
+
+    from constrainedrandom import RandObj, Random
+
+    class ldInstr(RandObj):
+        '''
+        A made-up load instruction has the following fields (starting at LSB):
+        - imm0 (11 bits): immediate offset for memory address
+        - src0 ( 5 bits): source register for memory address
+        - dst0 ( 5 bits): destination register for load data
+        - wb   ( 1 bit ): enable for writeback of the address to the src0 register.
+        - enc  (10 bits): fixed encoding to signify this kind of load instruction.
+
+        And the following rules:
+        - If writeback (wb) is set, src0 is written back with memory offset. In
+        this case, do not allow dst0 to be the same register as src0.
+        - The sum of the current contents of src0 and imm0 should be word-aligned.
+        - The sum of the current contents of src0 and imm0 should not overflow 32
+        bits.
+        '''
+        ENC = 0xfa800000
+
+        def __init__(self, random, *args, **kwargs):
+            super().__init__(random, *args, **kwargs)
+
+            self.add_rand_var('src0', bits=5, order=0)
+            def read_model_for_src0_value():
+                # Pretend getter for src0 current value
+                return 0xfffffbcd
+            self.add_rand_var('src0_value', fn=read_model_for_src0_value, order=0)
+            self.add_rand_var('wb', bits=1, order=0)
+            self.add_rand_var('dst0', bits=5, order=1)
+            self.add_rand_var('imm0', bits=11, order=2)
+            def wb_dst_src(wb, dst0, src0):
+                if wb:
+                    return dst0 != src0
+                return True
+            self.add_multi_var_constraint(wb_dst_src, ('wb', 'dst0', 'src0'))
+            def sum_src0_imm0(src0_value, imm0):
+                address = src0_value + imm0
+                return (address & 3 == 0) and (address < 0xffffffff)
+            self.add_multi_var_constraint(sum_src0_imm0, ('src0_value', 'imm0'))
+
+        def post_randomize(self):
+            self.opcode = self.get_opcode()
+
+        def get_opcode(self):
+            opcode = self.ENC
+            opcode = opcode | self.imm0
+            opcode = opcode | (self.src0 << 11)
+            opcode = opcode | (self.dst0 << 5)
+            opcode = opcode | (self.wb << 5)
+            return opcode
+
+
+    if __name__ == "__main__":
+        # Use a seed of 0 so our results are repeatable
+        random = Random(0)
+        ld_instr = ldInstr(random)
+        # Produce 5 random valid opcodes for this load instruction
+        for _ in range(5):
+            ld_instr.randomize()
+            print(hex(ld_instr.opcode))
+
+The user is free to either inherit from ``RandObj`` (for more complex cases like this one above), or just to instance it directly and use it (for more straightforward cases like those in :doc:`howto` and in the ``tests/`` directory).
+
+In local testing, the instruction above can be randomized at a rate of approximately 2000Hz, which is 'fast enough' for most pre-silicon verification simulations.