diff --git a/hw/ip/otp_ctrl/util/LcStEnc.py b/hw/ip/otp_ctrl/util/LcStEnc.py
new file mode 100644
index 0000000..16256d1
--- /dev/null
+++ b/hw/ip/otp_ctrl/util/LcStEnc.py
@@ -0,0 +1,342 @@
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+r"""Contains life cycle state encoding class which is
+used to generate new life cycle encodings.
+"""
+import logging as log
+import random
+
+from common import check_int
+
+
+def _is_valid_codeword(config, codeword):
+    '''Checks whether the bitstring is a valid ECC codeword.'''
+
+    data_width = config['secded']['data_width']
+    ecc_width = config['secded']['ecc_width']
+    if len(codeword) != (data_width + ecc_width):
+        log.error("Invalid codeword length {}".format(len(codeword)))
+        exit(1)
+
+    # Build syndrome and check whether it is zero.
+    syndrome = [0 for k in range(ecc_width)]
+
+    # The bitstring must be formatted as "data bits[N-1:0]" + "ecc bits[M-1:0]".
+    for j, fanin in enumerate(config['secded']['ecc_matrix']):
+        syndrome[j] = int(codeword[ecc_width - 1 - j])
+        for k in fanin:
+            syndrome[j] ^= int(codeword[ecc_width + data_width - 1 - k])
+
+    return sum(syndrome) == 0
+
+
+def _ecc_encode(config, dataword):
+    '''Calculate and prepend ECC bits.'''
+    if len(dataword) != config['secded']['data_width']:
+        log.error("Invalid codeword length {}".format(len(dataword)))
+        exit(1)
+
+    # Build syndrome
+    eccbits = ""
+    for fanin in config['secded']['ecc_matrix']:
+        bit = 0
+        for k in fanin:
+            bit ^= int(dataword[config['secded']['data_width'] - 1 - k])
+        eccbits += format(bit, '01b')
+
+    return eccbits[::-1] + dataword
+
+
+def _is_incremental_codeword(word1, word2):
+    '''Test whether word2 is incremental wrt word1.'''
+    if len(word1) != len(word2):
+        log.error('Words are not of equal size')
+        exit(1)
+
+    _word1 = int(word1, 2)
+    _word2 = int(word2, 2)
+
+    # This basically checks that the second word does not
+    # clear any bits that are set to 1 in the first word.
+    return ((_word1 & _word2) == _word1)
+
+
+def _scatter_bits(mask, bits):
+    '''Scatter the bits into unset positions of mask.'''
+    j = 0
+    scatterword = ''
+    for b in mask:
+        if b == '1':
+            scatterword += '1'
+        else:
+            scatterword += bits[j]
+            j += 1
+
+    return scatterword
+
+
+def _get_hd(word1, word2):
+    '''Calculate Hamming distance between two words.'''
+    if len(word1) != len(word2):
+        log.error('Words are not of equal size')
+        exit(1)
+    return bin(int(word1, 2) ^ int(word2, 2)).count('1')
+
+
+def _get_incremental_codewords(config, base_ecc, existing_words):
+    '''Get all possible incremental codewords fulfilling the constraints.'''
+
+    base_data = base_ecc[config['secded']['ecc_width']:]
+
+    # We only need to spin through data bits that have not been set yet.
+    # Hence, we first count how many bits are zero (and hence still
+    # modifyable). Then, we enumerate all possible combinations and scatter
+    # the bits of the enumerated values into the correct bit positions using
+    # the _scatter_bits() function.
+    incr_cands = []
+    free_bits = base_data.count('0')
+    for k in range(1, 2**free_bits):
+        # Get incremental dataword by scattering the enumeration bits
+        # into the zero bit positions in base_data.
+        incr_cand = _scatter_bits(base_data,
+                                  format(k, '0' + str(free_bits) + 'b'))
+        incr_cand_ecc = _ecc_encode(config, incr_cand)
+
+        # Dataword is correct by construction, but we need to check whether
+        # the ECC bits are incremental.
+        if _is_incremental_codeword(base_ecc, incr_cand_ecc):
+            # Check whether the candidate fulfills the maximum
+            # Hamming weight constraint.
+            if incr_cand_ecc.count('1') <= config['max_hw']:
+                # Check Hamming distance wrt all existing words.
+                for w in existing_words + [base_ecc]:
+                    if _get_hd(incr_cand_ecc, w) < config['min_hd']:
+                        break
+                else:
+                    incr_cands.append(incr_cand_ecc)
+
+    return incr_cands
+
+
+def _get_new_state_word_pair(config, existing_words):
+    '''Randomly generate a new incrementally writable word pair'''
+    while 1:
+        # Draw a random number and check whether it is unique and whether
+        # the Hamming weight is in range.
+        width = config['secded']['data_width']
+        ecc_width = config['secded']['ecc_width']
+        base = random.getrandbits(width)
+        base = format(base, '0' + str(width) + 'b')
+        base_cand_ecc = _ecc_encode(config, base)
+        # disallow all-zero and all-one states
+        pop_cnt = base_cand_ecc.count('1')
+        if pop_cnt >= config['min_hw'] and pop_cnt <= config['max_hw']:
+
+            # Check Hamming distance wrt all existing words
+            for w in existing_words:
+                if _get_hd(base_cand_ecc, w) < config['min_hd']:
+                    break
+            else:
+                # Get encoded incremental candidates.
+                incr_cands_ecc = _get_incremental_codewords(
+                    config, base_cand_ecc, existing_words)
+                # there are valid candidates, draw one at random.
+                # otherwise we just start over.
+                if incr_cands_ecc:
+                    incr_cand_ecc = random.choice(incr_cands_ecc)
+                    log.info('word {}: {}|{} -> {}|{}'.format(
+                        int(len(existing_words) / 2),
+                        base_cand_ecc[ecc_width:], base_cand_ecc[0:ecc_width],
+                        incr_cand_ecc[ecc_width:], incr_cand_ecc[0:ecc_width]))
+                    existing_words.append(base_cand_ecc)
+                    existing_words.append(incr_cand_ecc)
+                    return (base_cand_ecc, incr_cand_ecc)
+
+
+def _validate_words(config, words):
+    '''Validate generated words (base and incremental).'''
+    for k, w in enumerate(words):
+        # Check whether word is valid wrt to ECC polynomial.
+        if not _is_valid_codeword(config, w):
+            log.error('Codeword {} at index {} is not valid'.format(w, k))
+            exit(1)
+        # Check that word fulfills the Hamming weight constraints.
+        pop_cnt = w.count('1')
+        if pop_cnt < config['min_hw'] or pop_cnt > config['max_hw']:
+            log.error(
+                'Codeword {} at index {} has wrong Hamming weight'.format(
+                    w, k))
+            exit(1)
+        # Check Hamming distance wrt to all other existing words.
+        # If the constraint is larger than 0 this implies uniqueness.
+        if k < len(words) - 1:
+            for k2, w2 in enumerate(words[k + 1:]):
+                if _get_hd(w, w2) < config['min_hd']:
+                    log.error(
+                        'Hamming distance between codeword {} at index {} '
+                        'and codeword {} at index {} is too low.'.format(
+                            w, k, w2, k + 1 + k2))
+                    exit(1)
+
+
+def _hist_to_bars(hist, m):
+    '''Convert histogramm list into ASCII bar plot'''
+    bars = []
+    for i, j in enumerate(hist):
+        bar_prefix = "{:2}: ".format(i)
+        spaces = len(str(m)) - len(bar_prefix)
+        hist_bar = bar_prefix + (" " * spaces)
+        for k in range(j * 20 // max(hist)):
+            hist_bar += "|"
+        hist_bar += " ({:.2f}%)".format(100.0 * j / sum(hist)) if j else "--"
+        bars += [hist_bar]
+    return bars
+
+
+def hd_histogram(existing_words):
+    '''Build Hamming distance histogram'''
+    minimum_hd = len(existing_words[0])
+    maximum_hd = 0
+    minimum_hw = len(existing_words[0])
+    maximum_hw = 0
+    hist = [0] * (len(existing_words[0]) + 1)
+    for i, j in enumerate(existing_words):
+        minimum_hw = min(j.count('1'), minimum_hw)
+        maximum_hw = max(j.count('1'), maximum_hw)
+        if i < len(existing_words) - 1:
+            for k in existing_words[i + 1:]:
+                dist = _get_hd(j, k)
+                hist[dist] += 1
+                minimum_hd = min(dist, minimum_hd)
+                maximum_hd = max(dist, maximum_hd)
+
+    stats = {}
+    stats["hist"] = hist
+    stats["bars"] = _hist_to_bars(hist, len(existing_words))
+    stats["min_hd"] = minimum_hd
+    stats["max_hd"] = maximum_hd
+    stats["min_hw"] = minimum_hw
+    stats["max_hw"] = maximum_hw
+    return stats
+
+
+class LcStEnc():
+    '''Life cycle state encoding generator class
+
+    The constructor expects the parsed configuration
+    hjson to be passed in.
+    '''
+
+    # This holds the config dict.
+    config = {}
+    # Holds generated life cycle words.
+    gen = {
+        'ab_words': [],
+        'cd_words': [],
+        'ef_words': [],
+        'stats': [],
+    }
+
+    def __init__(self, config):
+        '''The constructor validates the configuration dict.'''
+
+        log.info('')
+        log.info('Generate life cycle state')
+        log.info('')
+
+        if 'seed' not in config:
+            log.error('Missing seed in configuration')
+            exit(1)
+
+        if 'secded' not in config:
+            log.error('Missing secded configuration')
+            exit(1)
+
+        config['secded'].setdefault('data_width', 0)
+        config['secded'].setdefault('ecc_width', 0)
+        config['secded'].setdefault('ecc_matrix', [[]])
+        config.setdefault('num_ab_words', 0)
+        config.setdefault('num_cd_words', 0)
+        config.setdefault('num_ef_words', 0)
+        config.setdefault('min_hw', 0)
+        config.setdefault('max_hw', 0)
+        config.setdefault('min_hd', 0)
+
+        config['seed'] = check_int(config['seed'])
+
+        log.info('Seed: {0:x}'.format(config['seed']))
+        log.info('')
+
+        config['secded']['data_width'] = check_int(
+            config['secded']['data_width'])
+        config['secded']['ecc_width'] = check_int(
+            config['secded']['ecc_width'])
+        config['num_ab_words'] = check_int(config['num_ab_words'])
+        config['num_cd_words'] = check_int(config['num_cd_words'])
+        config['num_ef_words'] = check_int(config['num_ef_words'])
+        config['min_hw'] = check_int(config['min_hw'])
+        config['max_hw'] = check_int(config['max_hw'])
+        config['min_hd'] = check_int(config['min_hd'])
+
+        total_width = config['secded']['data_width'] + config['secded'][
+            'ecc_width']
+
+        if config['min_hw'] >= total_width or \
+           config['max_hw'] > total_width or \
+           config['min_hw'] >= config['max_hw']:
+            log.error('Hamming weight constraints are inconsistent.')
+            exit(1)
+
+        if config['max_hw'] - config['min_hw'] + 1 < config['min_hd']:
+            log.error('Hamming distance constraint is inconsistent.')
+            exit(1)
+
+        if config['secded']['ecc_width'] != len(
+                config['secded']['ecc_matrix']):
+            log.error('ECC matrix does not have correct number of rows')
+            exit(1)
+
+        log.info('SECDED Matrix:')
+        for i, l in enumerate(config['secded']['ecc_matrix']):
+            log.info('ECC Bit {} Fanin: {}'.format(i, l))
+            for j, e in enumerate(l):
+                e = check_int(e)
+                config['secded']['ecc_matrix'][i][j] = e
+
+        log.info('')
+
+        self.config = config
+
+        # Re-initialize with seed to make results reproducible.
+        random.seed(int(self.config['seed']))
+
+        # Generate new encoding words
+        word_types = ['ab_words', 'cd_words', 'ef_words']
+        existing_words = []
+        for w in word_types:
+            while len(self.gen[w]) < self.config['num_' + w]:
+                new_word = _get_new_state_word_pair(self.config,
+                                                    existing_words)
+                self.gen[w].append(new_word)
+
+        # Validate words (this must not fail at this point).
+        _validate_words(self.config, existing_words)
+
+        # Print out HD histogram
+        self.gen['stats'] = hd_histogram(existing_words)
+
+        log.info('')
+        log.info('Hamming distance histogram:')
+        log.info('')
+        for bar in self.gen['stats']["bars"]:
+            log.info(bar)
+        log.info('')
+        log.info('Minimum HD: {}'.format(self.gen['stats']['min_hd']))
+        log.info('Maximum HD: {}'.format(self.gen['stats']['max_hd']))
+        log.info('Minimum HW: {}'.format(self.gen['stats']['min_hw']))
+        log.info('Maximum HW: {}'.format(self.gen['stats']['max_hw']))
+
+        log.info('')
+        log.info('Successfully generated life cycle state.')
+        log.info('')
diff --git a/hw/ip/otp_ctrl/util/OtpMemMap.py b/hw/ip/otp_ctrl/util/OtpMemMap.py
new file mode 100644
index 0000000..d843437
--- /dev/null
+++ b/hw/ip/otp_ctrl/util/OtpMemMap.py
@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+r"""OTP memory map class, used to create the associated RTL and
+documentation, and to create OTP memory images for preloading.
+"""
+
+import logging as log
+import random
+from math import ceil, log2
+
+from tabulate import tabulate
+
+from common import check_bool, check_int
+
+DIGEST_SUFFIX = "_DIGEST"
+DIGEST_SIZE = 8
+
+
+class OtpMemMap():
+
+    # This holds the config dict.
+    config = {}
+
+    def __init__(self, config):
+
+        log.info('')
+        log.info('Parse and translate OTP memory map.')
+        log.info('')
+
+        if "seed" not in config:
+            log.error("Missing seed in configuration.")
+            exit(1)
+
+        config["seed"] = check_int(config["seed"])
+
+        # Initialize RNG.
+        random.seed(int(config['seed']))
+
+        offset = 0
+        num_part = 0
+        for part in config["partitions"]:
+            num_part += 1
+            # Defaults
+            part.setdefault("offset", offset)
+            part.setdefault("name", "unknown_name")
+            part.setdefault("variant", "Unbuffered")
+            part.setdefault("size", "0")
+            part.setdefault("secret", "false")
+            part.setdefault("sw_digest", "false")
+            part.setdefault("hw_digest", "false")
+            part.setdefault("write_lock", "none")
+            part.setdefault("read_lock", "none")
+            part.setdefault("key_sel", "NoKey")
+            log.info("Partition {} at offset {} with size {}".format(
+                part["name"], part["offset"], part["size"]))
+
+            # make sure these are boolean types (simplifies the mako templates)
+            part["secret"] = check_bool(part["secret"])
+            part["sw_digest"] = check_bool(part["sw_digest"])
+            part["hw_digest"] = check_bool(part["hw_digest"])
+            part["bkout_type"] = check_bool(part["bkout_type"])
+
+            # basic checks
+            if part["variant"] not in ["Unbuffered", "Buffered", "LifeCycle"]:
+                log.error("Invalid partition type {}".format(part["variant"]))
+                exit(1)
+
+            if part["key_sel"] not in [
+                    "NoKey", "Secret0Key", "Secret1Key", "Secret2Key"
+            ]:
+                log.error("Invalid key sel {}".format(part["key_sel"]))
+                exit(1)
+
+            if check_bool(part["secret"]) and part["key_sel"] == "NoKey":
+                log.error(
+                    "A secret partition needs a key select value other than NoKey"
+                )
+                exit(1)
+
+            if part["write_lock"].lower() not in ["digest", "csr", "none"]:
+                log.error("Invalid value for write_lock")
+                exit(1)
+
+            if part["read_lock"].lower() not in ["digest", "csr", "none"]:
+                log.error("Invalid value for read_lock")
+                exit(1)
+
+            if part["sw_digest"] and part["hw_digest"]:
+                log.error(
+                    "Partition cannot support both a SW and a HW digest at the same time."
+                )
+                exit(1)
+
+            if part["variant"] == "Unbuffered" and not part["sw_digest"]:
+                log.error(
+                    "Unbuffered partitions without digest are not supported at the moment."
+                )
+                exit(1)
+
+            if not part["sw_digest"] and not part["hw_digest"]:
+                if part["write_lock"].lower(
+                ) == "digest" or part["read_lock"].lower() == "digest":
+                    log.error(
+                        "A partition can only be write/read lockable if it has a hw or sw digest."
+                    )
+                    exit(1)
+
+            if check_int(part["offset"]) % 8:
+                log.error("Partition offset must be 64bit aligned")
+                exit(1)
+
+            if check_int(part["size"]) % 8:
+                log.error("Partition size must be 64bit aligned")
+                exit(1)
+
+            # Loop over items within a partition
+            for item in part["items"]:
+                item.setdefault("name", "unknown_name")
+                item.setdefault("size", "0")
+                item.setdefault("isdigest", "false")
+                item.setdefault("offset", offset)
+                # Generate random constant to be used when partition has
+                # not been initialized yet or when it is in error state.
+                if check_bool(item.setdefault("rand_inv_default", "false")):
+                    inv_default = random.getrandbits(
+                        check_int(item["size"]) * 8)
+                else:
+                    inv_default = 0
+                item.setdefault(
+                    "inv_default", "{}'h{:0X}".format(
+                        check_int(item["size"]) * 8, inv_default))
+                log.info("> Item {} at offset {} with size {}".format(
+                    item["name"], offset, item["size"]))
+                offset += check_int(item["size"])
+
+            # Place digest at the end of a partition.
+            if part["sw_digest"] or part["hw_digest"]:
+                part["items"].append({
+                    "name":
+                    part["name"] + DIGEST_SUFFIX,
+                    "size":
+                    DIGEST_SIZE,
+                    "offset":
+                    check_int(part["offset"]) + check_int(part["size"]) -
+                    DIGEST_SIZE,
+                    "isdigest":
+                    "True",
+                    "inv_default":
+                    "{256{1'b1}}"
+                })
+
+                log.info("> Adding digest {} at offset {} with size {}".format(
+                    part["name"] + DIGEST_SUFFIX, offset, DIGEST_SIZE))
+                offset += DIGEST_SIZE
+
+            if len(part["items"]) == 0:
+                log.warning("Partition does not contain any items.")
+
+            # check offsets and size
+            if offset > check_int(part["offset"]) + check_int(part["size"]):
+                log.error("Not enough space in partitition "
+                          "{} to accommodate all items. Bytes available "
+                          "= {}, bytes requested = {}".format(
+                              part["name"], part["size"],
+                              offset - part["offset"]))
+                exit(1)
+
+            offset = check_int(part["offset"]) + check_int(part["size"])
+
+        otp_size = check_int(config["otp"]["depth"]) * check_int(
+            config["otp"]["width"])
+        config["otp"]["size"] = otp_size
+        config["otp"]["addr_width"] = ceil(
+            log2(check_int(config["otp"]["depth"])))
+        config["otp"]["byte_addr_width"] = ceil(log2(check_int(otp_size)))
+
+        if offset > otp_size:
+            log.error(
+                "OTP is not big enough to store all partitions. "
+                "Bytes available {}, bytes required {}",
+                otp_size, offset)
+            exit(1)
+
+        log.info("Total number of partitions: {}".format(num_part))
+        log.info("Bytes available in OTP: {}".format(otp_size))
+        log.info("Bytes required for partitions: {}".format(offset))
+
+        self.config = config
+
+        log.info('')
+        log.info('Successfully parsed and translated OTP memory map.')
+        log.info('')
+
+
+    def create_partitions_table(self):
+        header = [
+            "Partition", "Secret", "Buffered", "WR Lockable", "RD Lockable",
+            "Description"
+        ]
+        table = [header]
+        colalign = ("center", ) * len(header)
+
+        for part in self.config["partitions"]:
+            is_secret = "yes" if check_bool(part["secret"]) else "no"
+            is_buffered = "yes" if part["variant"] in [
+                "Buffered", "LifeCycle"
+            ] else "no"
+            wr_lockable = "no"
+            if part["write_lock"].lower() in ["csr", "digest"]:
+                wr_lockable = "yes (" + part["write_lock"] + ")"
+            rd_lockable = "no"
+            if part["read_lock"].lower() in ["csr", "digest"]:
+                rd_lockable = "yes (" + part["read_lock"] + ")"
+            # remove newlines
+            desc = ' '.join(part["desc"].split())
+            row = [
+                part["name"], is_secret, is_buffered, wr_lockable, rd_lockable,
+                desc
+            ]
+            table.append(row)
+
+        return tabulate(table,
+                        headers="firstrow",
+                        tablefmt="pipe",
+                        colalign=colalign)
+
+    def create_mmap_table(self):
+        header = [
+            "Index", "Partition", "Size [B]", "Access Granule", "Item",
+            "Byte Address", "Size [B]"
+        ]
+        table = [header]
+        colalign = ("center", ) * len(header)
+
+        for k, part in enumerate(self.config["partitions"]):
+            for j, item in enumerate(part["items"]):
+                granule = "64bit" if check_bool(part["secret"]) else "32bit"
+
+                if check_bool(item["isdigest"]):
+                    granule = "64bit"
+                    name = "[{}](#Reg_{}_0)".format(item["name"],
+                                                    item["name"].lower())
+                else:
+                    name = item["name"]
+
+                if j == 0:
+                    row = [str(k), part["name"], str(part["size"]), granule]
+                else:
+                    row = ["", "", "", granule]
+
+                row.extend([
+                    name, "0x{:03X}".format(check_int(item["offset"])),
+                    str(item["size"])
+                ])
+
+                table.append(row)
+
+        return tabulate(table,
+                        headers="firstrow",
+                        tablefmt="pipe",
+                        colalign=colalign)
+
+    def create_digests_table(self):
+        header = ["Digest Name", " Affected Partition", "Calculated by HW"]
+        table = [header]
+        colalign = ("center", ) * len(header)
+
+        for part in self.config["partitions"]:
+            if check_bool(part["hw_digest"]) or check_bool(part["sw_digest"]):
+                is_hw_digest = "yes" if check_bool(part["hw_digest"]) else "no"
+                for item in part["items"]:
+                    if check_bool(item["isdigest"]):
+                        name = "[{}](#Reg_{}_0)".format(
+                            item["name"], item["name"].lower())
+                        row = [name, part["name"], is_hw_digest]
+                        table.append(row)
+                        break
+                else:
+                    log.error(
+                        "Partition with digest does not contain a digest item")
+                    exit(1)
+
+        return tabulate(table,
+                        headers="firstrow",
+                        tablefmt="pipe",
+                        colalign=colalign)
diff --git a/hw/ip/otp_ctrl/util/common.py b/hw/ip/otp_ctrl/util/common.py
new file mode 100644
index 0000000..6e482c3
--- /dev/null
+++ b/hw/ip/otp_ctrl/util/common.py
@@ -0,0 +1,53 @@
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+r"""Shared subfunctions.
+"""
+import logging as log
+import textwrap
+
+
+def wrapped_docstring():
+    '''Return a text-wrapped version of the module docstring'''
+    paras = []
+    para = []
+    for line in __doc__.strip().split('\n'):
+        line = line.strip()
+        if not line:
+            if para:
+                paras.append('\n'.join(para))
+                para = []
+        else:
+            para.append(line)
+    if para:
+        paras.append('\n'.join(para))
+
+    return '\n\n'.join(textwrap.fill(p) for p in paras)
+
+
+def check_bool(x):
+    """check_bool checks if input 'x' either a bool or
+       one of the following strings: ["true", "false"]
+
+        It returns value as Bool type.
+    """
+    if isinstance(x, bool):
+        return x
+    if not x.lower() in ["true", "false"]:
+        log.error("{} is not a boolean value.".format(x))
+        exit(1)
+    else:
+        return (x.lower() == "true")
+
+
+def check_int(x):
+    """check_int checks if input 'x' is decimal integer.
+
+        It returns value as an int type.
+    """
+    if isinstance(x, int):
+        return x
+    if not x.isdecimal():
+        log.error("{} is not a decimal number".format(x))
+        exit(1)
+    return int(x)
diff --git a/hw/ip/otp_ctrl/util/gen-lc-state-enc.py b/hw/ip/otp_ctrl/util/gen-lc-state-enc.py
new file mode 100755
index 0000000..d2284e3
--- /dev/null
+++ b/hw/ip/otp_ctrl/util/gen-lc-state-enc.py
@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+r"""Given an ECC encoding matrix, this script generates random life cycle
+state encodings that can be incrementally written to a memory protected with
+the ECC code specified.
+"""
+import argparse
+import logging as log
+import random
+from pathlib import Path
+
+import hjson
+from mako.template import Template
+
+from LcStEnc import LcStEnc
+from common import wrapped_docstring
+
+# State encoding definition
+LC_STATE_DEFINITION_FILE = "../../lc_ctrl/data/lc_ctrl_state.hjson"
+# Code templates to render
+TEMPLATES = ["../../lc_ctrl/rtl/lc_ctrl_state_pkg.sv.tpl"]
+
+
+def main():
+    log.basicConfig(level=log.INFO,
+                    format="%(asctime)s - %(message)s",
+                    datefmt="%Y-%m-%d %H:%M")
+
+    parser = argparse.ArgumentParser(
+        prog="gen-lc-state-enc",
+        description=wrapped_docstring(),
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
+    parser.add_argument('-s',
+                        '--seed',
+                        type=int,
+                        metavar='<seed>',
+                        help='Custom seed for RNG.')
+
+    args = parser.parse_args()
+
+    with open(LC_STATE_DEFINITION_FILE, 'r') as infile:
+        config = hjson.load(infile)
+
+        # If specified, override the seed for random netlist constant computation.
+        if args.seed:
+            log.warning('Commandline override of seed with {}.'.format(
+                args.seed))
+            config['seed'] = args.seed
+        # Otherwise, we either take it from the .hjson if present, or
+        # randomly generate a new seed if not.
+        else:
+            random.seed()
+            new_seed = random.getrandbits(64)
+            if config.setdefault('seed', new_seed) == new_seed:
+                log.warning(
+                    'No seed specified, setting to {}.'.format(new_seed))
+
+        # validate config and generate encoding
+        lc_st_enc = LcStEnc(config)
+
+        # render all templates
+        for template in TEMPLATES:
+            with open(template, 'r') as tplfile:
+                tpl = Template(tplfile.read())
+                with open(
+                        Path(template).parent.joinpath(Path(template).stem),
+                        'w') as outfile:
+                    outfile.write(tpl.render(lc_st_enc=lc_st_enc))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/hw/ip/otp_ctrl/util/gen-otp-mmap.py b/hw/ip/otp_ctrl/util/gen-otp-mmap.py
new file mode 100755
index 0000000..333fb57
--- /dev/null
+++ b/hw/ip/otp_ctrl/util/gen-otp-mmap.py
@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+r"""Generate RTL and documentation collateral from OTP memory
+map definition file (hjson).
+"""
+import argparse
+import logging as log
+import random
+from pathlib import Path
+
+import hjson
+from mako.template import Template
+
+from common import wrapped_docstring
+# Import OTP memory map generator.
+from OtpMemMap import OtpMemMap
+
+TABLE_HEADER_COMMENT = '''<!--
+DO NOT EDIT THIS FILE DIRECTLY.
+It has been generated with hw/ip/otp_ctrl/util/gen-otp-mmap.py
+-->
+
+'''
+
+# memory map source
+MMAP_DEFINITION_FILE = "../data/otp_ctrl_mmap.hjson"
+# documentation tables to generate
+PARTITIONS_TABLE_FILE = "../doc/otp_ctrl_partitions.md"
+DIGESTS_TABLE_FILE = "../doc/otp_ctrl_digests.md"
+MMAP_TABLE_FILE = "../doc/otp_ctrl_mmap.md"
+# code templates to render
+TEMPLATES = ["../data/otp_ctrl.hjson.tpl", "../rtl/otp_ctrl_part_pkg.sv.tpl"]
+
+
+def main():
+    log.basicConfig(level=log.INFO,
+                    format="%(asctime)s - %(message)s",
+                    datefmt="%Y-%m-%d %H:%M")
+
+    parser = argparse.ArgumentParser(
+        prog="gen-otp-mmap",
+        description=wrapped_docstring(),
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
+    # Generator options for compile time random netlist constants
+    parser.add_argument('--seed',
+                        type=int,
+                        metavar='<seed>',
+                        help='Custom seed for RNG to compute default values.')
+
+    args = parser.parse_args()
+
+    with open(MMAP_DEFINITION_FILE, 'r') as infile:
+        config = hjson.load(infile)
+
+        # If specified, override the seed for random netlist constant computation.
+        if args.seed:
+            log.warning('Commandline override of seed with {}.'.format(
+                args.seed))
+            config['seed'] = args.seed
+        # Otherwise, we either take it from the .hjson if present, or
+        # randomly generate a new seed if not.
+        else:
+            random.seed()
+            new_seed = random.getrandbits(64)
+            if config.setdefault('seed', new_seed) == new_seed:
+                log.warning(
+                    'No seed specified, setting to {}.'.format(new_seed))
+
+        otp_mmap = OtpMemMap(config)
+
+        with open(PARTITIONS_TABLE_FILE, 'w') as outfile:
+            outfile.write(TABLE_HEADER_COMMENT +
+                          otp_mmap.create_partitions_table())
+
+        with open(DIGESTS_TABLE_FILE, 'w') as outfile:
+            outfile.write(TABLE_HEADER_COMMENT +
+                          otp_mmap.create_digests_table())
+
+        with open(MMAP_TABLE_FILE, 'w') as outfile:
+            outfile.write(TABLE_HEADER_COMMENT + otp_mmap.create_mmap_table())
+
+        # render all templates
+        for template in TEMPLATES:
+            with open(template, 'r') as tplfile:
+                tpl = Template(tplfile.read())
+                with open(
+                        Path(template).parent.joinpath(Path(template).stem),
+                        'w') as outfile:
+                    outfile.write(tpl.render(otp_mmap=otp_mmap))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/hw/ip/otp_ctrl/util/translate-mmap.py b/hw/ip/otp_ctrl/util/translate-mmap.py
deleted file mode 100755
index c5f7d13..0000000
--- a/hw/ip/otp_ctrl/util/translate-mmap.py
+++ /dev/null
@@ -1,384 +0,0 @@
-#!/usr/bin/env python3
-# Copyright lowRISC contributors.
-# Licensed under the Apache License, Version 2.0, see LICENSE for details.
-# SPDX-License-Identifier: Apache-2.0
-r"""Convert mako template to Hjson register description
-"""
-import argparse
-import logging as log
-import textwrap
-import random
-from math import ceil, log2
-from pathlib import Path
-
-import hjson
-from mako.template import Template
-from tabulate import tabulate
-
-DIGEST_SUFFIX = "_DIGEST"
-DIGEST_SIZE = 8
-
-TABLE_HEADER_COMMENT = '''<!--
-DO NOT EDIT THIS FILE DIRECTLY.
-It has been generated with hw/ip/otp_ctrl/util/translate-mmap.py
--->
-
-'''
-
-# memory map source
-MMAP_DEFINITION_FILE = "../data/otp_ctrl_mmap.hjson"
-# documentation tables to generate
-PARTITIONS_TABLE_FILE = "../doc/otp_ctrl_partitions.md"
-DIGESTS_TABLE_FILE = "../doc/otp_ctrl_digests.md"
-MMAP_TABLE_FILE = "../doc/otp_ctrl_mmap.md"
-# code templates to render
-TEMPLATES = ["../data/otp_ctrl.hjson.tpl", "../rtl/otp_ctrl_part_pkg.sv.tpl"]
-
-
-def wrapped_docstring():
-    '''Return a text-wrapped version of the module docstring'''
-    paras = []
-    para = []
-    for line in __doc__.strip().split('\n'):
-        line = line.strip()
-        if not line:
-            if para:
-                paras.append('\n'.join(para))
-                para = []
-        else:
-            para.append(line)
-    if para:
-        paras.append('\n'.join(para))
-
-    return '\n\n'.join(textwrap.fill(p) for p in paras)
-
-
-def check_bool(x):
-    """check_bool checks if input 'x' either a bool or
-       one of the following strings: ["true", "false"]
-
-        It returns value as Bool type.
-    """
-    if isinstance(x, bool):
-        return x
-    if not x.lower() in ["true", "false"]:
-        log.error("{} is not a boolean value.".format(x))
-        exit(1)
-    else:
-        return (x.lower() == "true")
-
-
-def check_int(x):
-    """check_int checks if input 'x' is decimal integer.
-
-        It returns value as an int type.
-    """
-    if isinstance(x, int):
-        return x
-    if not x.isdecimal():
-        log.error("{} is not a decimal number".format(x))
-        exit(1)
-    return int(x)
-
-
-def validate(config):
-    offset = 0
-    num_part = 0
-    for part in config["partitions"]:
-        num_part += 1
-        # Defaults
-        part.setdefault("offset", offset)
-        part.setdefault("name", "unknown_name")
-        part.setdefault("variant", "Unbuffered")
-        part.setdefault("size", "0")
-        part.setdefault("secret", "false")
-        part.setdefault("sw_digest", "false")
-        part.setdefault("hw_digest", "false")
-        part.setdefault("write_lock", "none")
-        part.setdefault("read_lock", "none")
-        part.setdefault("key_sel", "NoKey")
-        log.info("Partition {} at offset {} with size {}".format(
-            part["name"], part["offset"], part["size"]))
-
-        # make sure these are boolean types (simplifies the mako templates)
-        part["secret"] = check_bool(part["secret"])
-        part["sw_digest"] = check_bool(part["sw_digest"])
-        part["hw_digest"] = check_bool(part["hw_digest"])
-        part["bkout_type"] = check_bool(part["bkout_type"])
-
-        # basic checks
-        if part["variant"] not in ["Unbuffered", "Buffered", "LifeCycle"]:
-            log.error("Invalid partition type {}".format(part["variant"]))
-            exit(1)
-
-        if part["key_sel"] not in [
-                "NoKey", "Secret0Key", "Secret1Key", "Secret2Key"
-        ]:
-            log.error("Invalid key sel {}".format(part["key_sel"]))
-            exit(1)
-
-        if check_bool(part["secret"]) and part["key_sel"] == "NoKey":
-            log.error(
-                "A secret partition needs a key select value other than NoKey")
-            exit(1)
-
-        if part["write_lock"].lower() not in ["digest", "csr", "none"]:
-            log.error("Invalid value for write_lock")
-            exit(1)
-
-        if part["read_lock"].lower() not in ["digest", "csr", "none"]:
-            log.error("Invalid value for read_lock")
-            exit(1)
-
-        if part["sw_digest"] and part["hw_digest"]:
-            log.error(
-                "Partition cannot support both a SW and a HW digest at the same time."
-            )
-            exit(1)
-
-        if part["variant"] == "Unbuffered" and not part["sw_digest"]:
-            log.error(
-                "Unbuffered partitions without digest are not supported at the moment."
-            )
-            exit(1)
-
-        if not part["sw_digest"] and not part["hw_digest"]:
-            if part["write_lock"].lower(
-            ) == "digest" or part["read_lock"].lower() == "digest":
-                log.error(
-                    "A partition can only be write/read lockable if it has a hw or sw digest."
-                )
-                exit(1)
-
-        if check_int(part["offset"]) % 8:
-            log.error("Partition offset must be 64bit aligned")
-            exit(1)
-
-        if check_int(part["size"]) % 8:
-            log.error("Partition size must be 64bit aligned")
-            exit(1)
-
-        # Loop over items within a partition
-        for item in part["items"]:
-            item.setdefault("name", "unknown_name")
-            item.setdefault("size", "0")
-            item.setdefault("isdigest", "false")
-            item.setdefault("offset", offset)
-            # Generate random constant to be used when partition has
-            # not been initialized yet or when it is in error state.
-            if check_bool(item.setdefault("rand_inv_default", "false")):
-                inv_default = random.getrandbits(check_int(item["size"])*8)
-            else:
-                inv_default = 0
-            item.setdefault("inv_default", "{}'h{:0X}".format(check_int(item["size"])*8, inv_default))
-            log.info("> Item {} at offset {} with size {}".format(
-                item["name"], offset, item["size"]))
-            offset += check_int(item["size"])
-
-        # Place digest at the end of a partition.
-        if part["sw_digest"] or part["hw_digest"]:
-            part["items"].append({
-                "name":
-                part["name"] + DIGEST_SUFFIX,
-                "size":
-                DIGEST_SIZE,
-                "offset":
-                check_int(part["offset"]) + check_int(part["size"]) -
-                DIGEST_SIZE,
-                "isdigest":
-                "True",
-                "inv_default":
-                "{256{1'b1}}"
-            })
-
-            log.info("> Adding digest {} at offset {} with size {}".format(
-                part["name"] + DIGEST_SUFFIX, offset, DIGEST_SIZE))
-            offset += DIGEST_SIZE
-
-        if len(part["items"]) == 0:
-            log.warning("Partition does not contain any items.")
-
-        # check offsets and size
-        if offset > check_int(part["offset"]) + check_int(part["size"]):
-            log.error("Not enough space in partitition "
-                      "{} to accommodate all items. Bytes available "
-                      "= {}, bytes requested = {}".format(
-                          part["name"], part["size"], offset - part["offset"]))
-            exit(1)
-
-        offset = check_int(part["offset"]) + check_int(part["size"])
-
-    otp_size = check_int(config["otp"]["depth"]) * check_int(
-        config["otp"]["width"])
-    config["otp"]["size"] = otp_size
-    config["otp"]["addr_width"] = ceil(log2(check_int(config["otp"]["depth"])))
-    config["otp"]["byte_addr_width"] = ceil(log2(check_int(otp_size)))
-
-    if offset > otp_size:
-        log.error(
-            "OTP is not big enough to store all partitions. Bytes available {}, bytes required {}",
-            otp_size, offset)
-        exit(1)
-
-    log.info("Total number of partitions: {}".format(num_part))
-    log.info("Bytes available in OTP: {}".format(otp_size))
-    log.info("Bytes required for partitions: {}".format(offset))
-
-
-def create_partitions_table(config):
-    header = [
-        "Partition", "Secret", "Buffered", "WR Lockable", "RD Lockable",
-        "Description"
-    ]
-    table = [header]
-    colalign = ("center", ) * len(header)
-
-    for part in config["partitions"]:
-        is_secret = "yes" if check_bool(part["secret"]) else "no"
-        is_buffered = "yes" if part["variant"] in ["Buffered", "LifeCycle"
-                                                   ] else "no"
-        wr_lockable = "no"
-        if part["write_lock"].lower() in ["csr", "digest"]:
-            wr_lockable = "yes (" + part["write_lock"] + ")"
-        rd_lockable = "no"
-        if part["read_lock"].lower() in ["csr", "digest"]:
-            rd_lockable = "yes (" + part["read_lock"] + ")"
-        # remove newlines
-        desc = ' '.join(part["desc"].split())
-        row = [
-            part["name"], is_secret, is_buffered, wr_lockable, rd_lockable,
-            desc
-        ]
-        table.append(row)
-
-    return tabulate(table,
-                    headers="firstrow",
-                    tablefmt="pipe",
-                    colalign=colalign)
-
-
-def create_mmap_table(config):
-    header = [
-        "Index", "Partition", "Size [B]", "Access Granule", "Item",
-        "Byte Address", "Size [B]"
-    ]
-    table = [header]
-    colalign = ("center", ) * len(header)
-
-    for k, part in enumerate(config["partitions"]):
-        for j, item in enumerate(part["items"]):
-            granule = "64bit" if check_bool(part["secret"]) else "32bit"
-
-            if check_bool(item["isdigest"]):
-                granule = "64bit"
-                name = "[{}](#Reg_{}_0)".format(item["name"],
-                                                item["name"].lower())
-            else:
-                name = item["name"]
-
-            if j == 0:
-                row = [str(k), part["name"], str(part["size"]), granule]
-            else:
-                row = ["", "", "", granule]
-
-            row.extend([
-                name, "0x{:03X}".format(check_int(item["offset"])),
-                str(item["size"])
-            ])
-
-            table.append(row)
-
-    return tabulate(table,
-                    headers="firstrow",
-                    tablefmt="pipe",
-                    colalign=colalign)
-
-
-def create_digests_table(config):
-    header = ["Digest Name", " Affected Partition", "Calculated by HW"]
-    table = [header]
-    colalign = ("center", ) * len(header)
-
-    for part in config["partitions"]:
-        if check_bool(part["hw_digest"]) or check_bool(part["sw_digest"]):
-            is_hw_digest = "yes" if check_bool(part["hw_digest"]) else "no"
-            for item in part["items"]:
-                if check_bool(item["isdigest"]):
-                    name = "[{}](#Reg_{}_0)".format(item["name"],
-                                                    item["name"].lower())
-                    row = [name, part["name"], is_hw_digest]
-                    table.append(row)
-                    break
-            else:
-                log.error(
-                    "Partition with digest does not contain a digest item")
-                exit(1)
-
-    return tabulate(table,
-                    headers="firstrow",
-                    tablefmt="pipe",
-                    colalign=colalign)
-
-
-def main():
-    log.basicConfig(level=log.INFO,
-                    format="%(asctime)s - %(message)s",
-                    datefmt="%Y-%m-%d %H:%M")
-
-    parser = argparse.ArgumentParser(
-        prog="translate-mmap",
-        description=wrapped_docstring(),
-        formatter_class=argparse.RawDescriptionHelpFormatter)
-
-    # Generator options for compile time random netlist constants
-    parser.add_argument(
-        '--seed',
-        type=int,
-        metavar='<seed>',
-        help='Custom seed for RNG to compute default values.')
-
-    args = parser.parse_args()
-
-    with open(MMAP_DEFINITION_FILE, 'r') as infile:
-        config = hjson.load(infile)
-
-        # If specified, override the seed for random netlist constant computation.
-        if args.seed:
-            log.warning('Commandline override of seed with {}.'.format(
-                args.seed))
-            config['seed'] = args.seed
-        # Otherwise, we either take it from the .hjson if present, or
-        # randomly generate a new seed if not.
-        else:
-            random.seed()
-            new_seed = random.getrandbits(64)
-            if config.setdefault('seed', new_seed) == new_seed:
-                log.warning(
-                    'No seed specified, setting to {}.'.format(new_seed))
-
-        # Initialize RNG.
-        random.seed(int(config['seed']))
-
-        validate(config)
-
-        with open(PARTITIONS_TABLE_FILE, 'w') as outfile:
-            outfile.write(TABLE_HEADER_COMMENT + create_partitions_table(config))
-
-        with open(DIGESTS_TABLE_FILE, 'w') as outfile:
-            outfile.write(TABLE_HEADER_COMMENT + create_digests_table(config))
-
-        with open(MMAP_TABLE_FILE, 'w') as outfile:
-            outfile.write(TABLE_HEADER_COMMENT + create_mmap_table(config))
-
-        # render all templates
-        for template in TEMPLATES:
-            with open(template, 'r') as tplfile:
-                tpl = Template(tplfile.read())
-                with open(
-                        Path(template).parent.joinpath(Path(template).stem),
-                        'w') as outfile:
-                    outfile.write(tpl.render(config=config))
-
-
-if __name__ == "__main__":
-    main()