| # Copyright lowRISC contributors. | |
| # Licensed under the Apache License, Version 2.0, see LICENSE for details. | |
| # SPDX-License-Identifier: Apache-2.0 | |
| import re | |
| import logging as log | |
| from typing import Dict, List, Sequence, Tuple | |
| from reggen.lib import check_keys, check_str, check_list | |
| # The documentation of assets and cm_types can be found here | |
| # https://docs.opentitan.org/doc/rm/comportability_specification/#countermeasures | |
| CM_ASSETS = [ | |
| 'KEY', | |
| 'ADDR', | |
| 'DATA_REG', | |
| 'DATA_REG_SW', | |
| 'CTRL_FLOW', | |
| 'CTRL', | |
| 'CONFIG', | |
| 'LFSR', | |
| 'RNG', | |
| 'CTR', | |
| 'FSM', | |
| 'MEM', | |
| 'CLK', | |
| 'RST', | |
| 'BUS', | |
| 'INTERSIG', | |
| 'MUX', | |
| 'CONSTANTS', | |
| 'STATE', | |
| 'TOKEN', | |
| 'LOGIC' | |
| ] | |
| CM_TYPES = [ | |
| 'MUBI', | |
| 'SPARSE', | |
| 'DIFF', | |
| 'REDUN', | |
| 'REGWEN', | |
| 'REGREN', | |
| 'SHADOW', | |
| 'SCRAMBLE', | |
| 'INTEGRITY', | |
| 'CONSISTENCY', | |
| 'DIGEST', | |
| 'LC_GATED', | |
| 'BKGN_CHK', | |
| 'GLITCH_DETECT', | |
| 'SW_UNREADABLE', | |
| 'SW_UNWRITABLE', | |
| 'SW_NOACCESS', | |
| 'SIDELOAD', | |
| 'SEC_WIPE', | |
| 'SCA', | |
| 'MASKING', | |
| 'LOCAL_ESC', | |
| 'GLOBAL_ESC', | |
| 'UNPREDICTABLE', | |
| 'TERMINAL', | |
| 'COUNT', | |
| 'CM' | |
| ] | |
| # Tag to look for when extracting RTL annotations. | |
| CM_RTL_TAG = 'SEC_CM:' | |
| class CounterMeasure: | |
| """Object holding details for one countermeasure within an IP block.""" | |
| def __init__(self, instance: str, asset: str, cm_type: str, desc: str): | |
| self.instance = instance | |
| self.asset = asset | |
| self.cm_type = cm_type | |
| self.desc = desc | |
| @staticmethod | |
| def from_raw(what: str, raw: object) -> 'CounterMeasure': | |
| """ | |
| Create a CounterMeasure object from a dict. | |
| The 'raw' dict must have the keys 'name' and 'desc', where 'name' has | |
| to follow the canonical countermeasure naming convention. | |
| """ | |
| rd = check_keys(raw, what, ['name', 'desc'], []) | |
| name = check_str(rd['name'], f'name field of {what}') | |
| desc = check_str(rd['desc'], f'desc field of {what}') | |
| try: | |
| # the format is [CM_INST_NAME].<CM_ASSET>.<CM_TYPE> | |
| # i.e., the countermeasure instance name is optional. | |
| fields = name.split('.') | |
| if len(fields) == 3: | |
| instance, asset, cm_type = fields | |
| else: | |
| asset, cm_type = fields | |
| instance = "" | |
| except ValueError: | |
| raise ValueError( | |
| f'Invalid countermeasure ID format: {name} ({what}).') | |
| if not re.fullmatch(r'^([a-zA-Z0-9_]*)', instance): | |
| raise ValueError( | |
| f'Invalid countermeasure instance name: {instance} ({what}).') | |
| if asset not in CM_ASSETS: | |
| raise ValueError( | |
| f'Invalid countermeasure asset: {asset} ({what}).') | |
| if cm_type not in CM_TYPES: | |
| raise ValueError( | |
| f'Invalid countermeasure type: {cm_type} ({what}).') | |
| return CounterMeasure(instance, asset, cm_type, desc) | |
| @staticmethod | |
| def from_raw_list(what: str, | |
| raw: object) -> List['CounterMeasure']: | |
| """ | |
| Create a list of CounterMeasure objects from a list of dicts. | |
| The dicts in 'raw' must have the keys 'name' and 'desc', where 'name' | |
| has to follow the canonical countermeasure naming convention. | |
| """ | |
| ret = [] | |
| for idx, entry in enumerate(check_list(raw, what)): | |
| entry_what = f'entry {idx} of {what}' | |
| cm = CounterMeasure.from_raw(entry_what, entry) | |
| ret.append(cm) | |
| return ret | |
| def _asdict(self) -> Dict[str, object]: | |
| """Returns a dict with 'name' and 'desc' fields""" | |
| return { | |
| 'name': str(self), | |
| 'desc': self.desc | |
| } | |
| def __str__(self) -> str: | |
| namestr = self.asset + '.' + self.cm_type | |
| return self.instance + '.' + namestr if self.instance else namestr | |
| @staticmethod | |
| def search_rtl_files(paths: Sequence[str]) -> Dict[str, | |
| List[Tuple[str, int]]]: | |
| """Find countermeasures in the given list of RTL files. | |
| The return value is a dictionary mapping countermeasure name to where | |
| that countermeasure is found (as a (path, line_number) pair). | |
| """ | |
| ret: Dict[str, List[Tuple[str, int]]] = {} | |
| # Match things like "// SEC_CM: FOO" or "// SEC_CM: FOO, BAR" | |
| regex = re.compile(r'//\s*' + CM_RTL_TAG + r'\s*(.*)') | |
| good_name = re.compile(r'[A-Za-z0-9_.]+$') | |
| for path in paths: | |
| with open(path) as fd: | |
| for idx, line in enumerate(fd): | |
| match = regex.search(line) | |
| if not match: | |
| continue | |
| # We've got a hit. The regex above is intentionally lax | |
| # because we want to see an error if someone writes | |
| # something horrible, rather than silently ignoring the | |
| # line. Split the match on commas to allow multiple entries | |
| # on a line. | |
| entries = match.group(1).split(',') | |
| for entry in entries: | |
| entry = entry.strip() | |
| if not good_name.match(entry): | |
| raise ValueError('Malformed countermeasure name, ' | |
| '{!r}, at {}, line {}.' | |
| .format(entry, path, idx + 1)) | |
| ret.setdefault(entry, []).append((path, idx + 1)) | |
| return ret | |
| @staticmethod | |
| def check_annotation_list(what: str, | |
| rtl_names: Dict[str, List[Tuple[str, int]]], | |
| hjson_list: List['CounterMeasure']) -> None: | |
| """Compare found list of countermeasures against list from Hjson | |
| This compares a dictionary of countermeasure names extracted from the | |
| RTL against the list defined in the IP Hjson and checks that they | |
| match: every name in the RTL should correspond to an entry in the Hjson | |
| and every entry in the Hjson should have at least one matching name in | |
| the RTL. | |
| """ | |
| hjson_set = {str(cm) for cm in hjson_list} | |
| rtl_set = set(rtl_names.keys()) | |
| # Is there anything in the RTL that doesn't correspond to an Hjson | |
| # entry? | |
| for name in rtl_set - hjson_set: | |
| # Print out an error message for each hit and then raise a | |
| # RuntimeError. | |
| for path, line in rtl_names[name]: | |
| log.error('Unknown countermeasure {!r} ' | |
| 'referenced at {}, line {}.' | |
| .format(name, path, line)) | |
| raise RuntimeError('One or more unknown countermeasures ' | |
| 'referenced in RTL.') | |
| # Is there anything in the Hjson that isn't described in the RTL? | |
| for name in hjson_set - rtl_set: | |
| log.warning("Countermeasure {} is referenced in the Hjson of the " | |
| "{}, but doesn't appear in the RTL." | |
| .format(name, what)) | |
| # TODO(#10071): Once all designs are annotated, generate a RuntimeError | |
| # if we saw anything in the loop above. |