| #!/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 datetime | |
| import logging as log | |
| import random | |
| import re | |
| from pathlib import Path | |
| import hjson | |
| from lib.common import wrapped_docstring | |
| from lib.OtpMemImg import OtpMemImg | |
| # Get the memory map definition. | |
| MMAP_DEFINITION_FILE = 'hw/ip/otp_ctrl/data/otp_ctrl_mmap.hjson' | |
| # Life cycle state and ECC poly definitions. | |
| LC_STATE_DEFINITION_FILE = 'hw/ip/lc_ctrl/data/lc_ctrl_state.hjson' | |
| # Default image file definition (can be overridden on the command line). | |
| IMAGE_DEFINITION_FILE = 'hw/ip/otp_ctrl/data/otp_ctrl_img_dev.hjson' | |
| # Default output path (can be overridden on the command line). Note that | |
| # "BITWIDTH" will be replaced with the architecture's bitness. | |
| MEMORY_MEM_FILE = 'otp-img.BITWIDTH.vmem' | |
| def _override_seed(args, name, config): | |
| '''Override the seed key in config with value specified in args''' | |
| arg_seed = getattr(args, name) | |
| # An override seed of 0 will not trigger the override, which is intended, as | |
| # the OTP-generation Bazel rule sets the default seed values to 0. | |
| if arg_seed: | |
| log.warning('Commandline override of {} with {}.'.format( | |
| name, arg_seed)) | |
| config['seed'] = arg_seed | |
| # Otherwise, we either take it from the .hjson if present, or | |
| # randomly generate a new seed if not. | |
| else: | |
| new_seed = random.getrandbits(64) | |
| if config.setdefault('seed', new_seed) == new_seed: | |
| log.warning('No {} specified, setting to {}.'.format( | |
| name, new_seed)) | |
| def _permutation_string(data_perm): | |
| '''Check permutation format and expand the ranges''' | |
| if not isinstance(data_perm, str): | |
| TypeError() | |
| if not data_perm: | |
| return '' | |
| # Check the format first | |
| pattern = r'^((?:\[[0-9]+:[0-9]+\])+(?:,\[[0-9]+:[0-9]+\])*)' | |
| match = re.fullmatch(pattern, data_perm) | |
| if match is None: | |
| raise ValueError() | |
| # Expand the ranges | |
| expanded_perm = [] | |
| groups = match.groups() | |
| for group in groups[0].split(','): | |
| k1, k0 = [int(x) for x in group[1:-1].split(':')] | |
| if k1 > k0: | |
| expanded_perm = list(range(k0, k1 + 1)) + expanded_perm | |
| else: | |
| expanded_perm = list(range(k0, k1 - 1, -1)) + expanded_perm | |
| return expanded_perm | |
| # TODO: this can be removed when we have moved to Python 3.8 | |
| # in all regressions, since the extend action is only available | |
| # from that version onward. | |
| # This workaround solution has been taken verbatim from | |
| # https://stackoverflow.com/questions/41152799/argparse-flatten-the-result-of-action-append | |
| class ExtendAction(argparse.Action): | |
| '''Extend action for the argument parser''' | |
| def __call__(self, parser, namespace, values, option_string=None): | |
| items = getattr(namespace, self.dest) or [] | |
| items.extend(values) | |
| setattr(namespace, self.dest, items) | |
| def main(): | |
| log.basicConfig(level=log.INFO, format="%(levelname)s: %(message)s") | |
| # Make sure the script can also be called from other dirs than | |
| # just the project root by adapting the default paths accordingly. | |
| proj_root = Path(__file__).parent.joinpath('../../') | |
| lc_state_def_file = Path(proj_root).joinpath(LC_STATE_DEFINITION_FILE) | |
| mmap_def_file = Path(proj_root).joinpath(MMAP_DEFINITION_FILE) | |
| img_def_file = Path(proj_root).joinpath(IMAGE_DEFINITION_FILE) | |
| parser = argparse.ArgumentParser( | |
| prog="gen-otp-img", | |
| description=wrapped_docstring(), | |
| formatter_class=argparse.RawDescriptionHelpFormatter) | |
| parser.register('action', 'extend', ExtendAction) | |
| parser.add_argument('--quiet', | |
| '-q', | |
| action='store_true', | |
| help='''Don't print out progress messages.''') | |
| parser.add_argument('--seed', | |
| type=int, | |
| metavar='<seed>', | |
| help="Custom seed used for randomization.") | |
| parser.add_argument('--img-seed', | |
| type=int, | |
| metavar='<seed>', | |
| help=''' | |
| Custom seed for RNG to compute randomized items in OTP image. | |
| Can be used to override the seed value specified in the image | |
| config Hjson. | |
| ''') | |
| parser.add_argument('--lc-seed', | |
| type=int, | |
| metavar='<seed>', | |
| help=''' | |
| Custom seed for RNG to compute randomized life cycle netlist constants. | |
| Note that this seed must coincide with the seed used for generating | |
| the LC state encoding (gen-lc-state-enc.py). | |
| This value typically does not need to be specified as it is taken from | |
| the LC state encoding definition Hjson. | |
| ''') | |
| parser.add_argument('--otp-seed', | |
| type=int, | |
| metavar='<seed>', | |
| help=''' | |
| Custom seed for RNG to compute randomized OTP netlist constants. | |
| Note that this seed must coincide with the seed used for generating | |
| the OTP memory map (gen-otp-mmap.py). | |
| This value typically does not need to be specified as it is taken from | |
| the OTP memory map definition Hjson. | |
| ''') | |
| parser.add_argument('-o', | |
| '--out', | |
| type=str, | |
| metavar='<path>', | |
| default=MEMORY_MEM_FILE, | |
| help=''' | |
| Custom output path for generated MEM file. | |
| Defaults to {} | |
| '''.format(MEMORY_MEM_FILE)) | |
| parser.add_argument('--lc-state-def', | |
| type=Path, | |
| metavar='<path>', | |
| default=lc_state_def_file, | |
| help=''' | |
| Life cycle state definition file in Hjson format. | |
| ''') | |
| parser.add_argument('--mmap-def', | |
| type=Path, | |
| metavar='<path>', | |
| default=mmap_def_file, | |
| help=''' | |
| OTP memory map file in Hjson format. | |
| ''') | |
| parser.add_argument('--img-cfg', | |
| type=Path, | |
| metavar='<path>', | |
| default=img_def_file, | |
| help=''' | |
| Image configuration file in Hjson format. | |
| Defaults to {} | |
| '''.format(img_def_file)) | |
| parser.add_argument('--add-cfg', | |
| type=Path, | |
| metavar='<path>', | |
| action='extend', | |
| nargs='+', | |
| default=[], | |
| help=''' | |
| Additional image configuration file in Hjson format. | |
| This switch can be specified multiple times. | |
| Image configuration files are parsed in the same | |
| order as they are specified on the command line, | |
| and partition item values that are specified multiple | |
| times are overridden in that order. | |
| Note that seed values in additional configuration files | |
| are ignored. | |
| ''') | |
| parser.add_argument('--data-perm', | |
| type=_permutation_string, | |
| metavar='<map>', | |
| default='', | |
| help=''' | |
| This is a post-processing option and allows permuting | |
| the bit positions before writing the memfile. | |
| The bit mapping needs to be supplied as a comma separated list | |
| of bit slices, where the numbers refer to the bit positions in | |
| the original data word before remapping, for example: | |
| "[7:0],[16:8]". | |
| The mapping must be bijective - otherwise this will generate | |
| an error. | |
| ''') | |
| args = parser.parse_args() | |
| if args.quiet: | |
| log.getLogger().setLevel(log.WARNING) | |
| log.info('Loading LC state definition file {}'.format(args.lc_state_def)) | |
| with open(args.lc_state_def, 'r') as infile: | |
| lc_state_cfg = hjson.load(infile) | |
| log.info('Loading OTP memory map definition file {}'.format(args.mmap_def)) | |
| with open(args.mmap_def, 'r') as infile: | |
| otp_mmap_cfg = hjson.load(infile) | |
| log.info('Loading main image configuration file {}'.format(args.img_cfg)) | |
| with open(args.img_cfg, 'r') as infile: | |
| img_cfg = hjson.load(infile) | |
| # Set the initial random seed so that the generated image is | |
| # deterministically randomized. | |
| random.seed(args.seed) | |
| # If specified, override the seeds. | |
| _override_seed(args, 'lc_seed', lc_state_cfg) | |
| _override_seed(args, 'otp_seed', otp_mmap_cfg) | |
| _override_seed(args, 'img_seed', img_cfg) | |
| try: | |
| otp_mem_img = OtpMemImg(lc_state_cfg, otp_mmap_cfg, img_cfg, | |
| args.data_perm) | |
| for f in args.add_cfg: | |
| log.info( | |
| 'Processing additional image configuration file {}'.format(f)) | |
| log.info('') | |
| with open(f, 'r') as infile: | |
| cfg = hjson.load(infile) | |
| otp_mem_img.override_data(cfg) | |
| log.info('') | |
| except RuntimeError as err: | |
| log.error(err) | |
| exit(1) | |
| # Print all defined args into header comment for reference | |
| argstr = '' | |
| for arg, argval in sorted(vars(args).items()): | |
| if argval: | |
| if not isinstance(argval, list): | |
| argval = [argval] | |
| for a in argval: | |
| argname = '-'.join(arg.split('_')) | |
| # Get absolute paths for all files specified. | |
| a = a.resolve() if isinstance(a, Path) else a | |
| argstr += ' \\\n// --' + argname + ' ' + str(a) + '' | |
| dt = datetime.datetime.now(datetime.timezone.utc) | |
| dtstr = dt.strftime("%a, %d %b %Y %H:%M:%S %Z") | |
| memfile_header = '// Generated on {} with\n// $ gen-otp-img.py {}\n//\n'.format( | |
| dtstr, argstr) | |
| memfile_body, bitness = otp_mem_img.streamout_memfile() | |
| # If the out argument does not contain "BITWIDTH", it will not be changed. | |
| memfile_path = Path(args.out.replace('BITWIDTH', str(bitness))) | |
| with open(memfile_path, 'w') as outfile: | |
| outfile.write(memfile_header) | |
| outfile.write(memfile_body) | |
| if __name__ == "__main__": | |
| main() |