| # Copyright lowRISC contributors. | |
| # Licensed under the Apache License, Version 2.0, see LICENSE for details. | |
| # SPDX-License-Identifier: Apache-2.0 | |
| import datetime | |
| import logging as log | |
| import os | |
| import pprint | |
| import subprocess | |
| import sys | |
| from shutil import which | |
| import hjson | |
| from CfgJson import set_target_attribute | |
| from LauncherFactory import get_launcher_cls | |
| from Scheduler import Scheduler | |
| from utils import (VERBOSE, clean_odirs, find_and_substitute_wildcards, md_results_to_html, | |
| mk_path, mk_symlink, rm_path, subst_wildcards) | |
| # Interface class for extensions. | |
| class FlowCfg(): | |
| '''Base class for the different flows supported by dvsim.py | |
| The constructor expects some parsed hjson data. Create these objects with | |
| the factory function in CfgFactory.py, which loads the hjson data and picks | |
| a subclass of FlowCfg based on its contents. | |
| ''' | |
| # Set in subclasses. This is the key that must be used in an hjson file to | |
| # tell dvsim.py which subclass to use. | |
| flow = None | |
| # Can be overridden in subclasses to configure which wildcards to ignore | |
| # when expanding hjson. | |
| ignored_wildcards = [] | |
| def __str__(self): | |
| return pprint.pformat(self.__dict__) | |
| def __init__(self, flow_cfg_file, hjson_data, args, mk_config): | |
| # Options set from command line | |
| self.items = args.items | |
| self.list_items = args.list | |
| self.select_cfgs = args.select_cfgs | |
| self.flow_cfg_file = flow_cfg_file | |
| self.args = args | |
| self.scratch_root = args.scratch_root | |
| self.branch = args.branch | |
| self.job_prefix = args.job_prefix | |
| self.gui = args.gui | |
| # Options set from hjson cfg. | |
| self.project = "" | |
| self.scratch_path = "" | |
| self.scratch_base_path = "" | |
| # Add exports using 'exports' keyword - these are exported to the child | |
| # process' environment. | |
| self.exports = [] | |
| # Add overrides using the overrides keyword - existing attributes | |
| # are overridden with the override values. | |
| self.overrides = [] | |
| # List of cfgs if the parsed cfg is a primary cfg list | |
| self.cfgs = [] | |
| # Add a notion of "primary" cfg - this is indicated using | |
| # a special key 'use_cfgs' within the hjson cfg. | |
| self.is_primary_cfg = False | |
| # For a primary cfg, it is the aggregated list of all deploy objects | |
| # under self.cfgs. For a non-primary cfg, it is the list of items | |
| # slated for dispatch. | |
| self.deploy = [] | |
| # Timestamp | |
| self.timestamp_long = args.timestamp_long | |
| self.timestamp = args.timestamp | |
| # Results | |
| self.errors_seen = False | |
| self.rel_path = "" | |
| self.results_title = "" | |
| self.revision = "" | |
| self.results_server_prefix = "" | |
| self.results_server_url_prefix = "" | |
| self.results_server_cmd = "" | |
| self.css_file = os.path.join( | |
| os.path.dirname(os.path.realpath(__file__)), "style.css") | |
| # `self.results_path` will be updated after `self.rel_path` and | |
| # `self.scratch_base_root` variables are updated. | |
| self.results_path = "" | |
| self.results_server_path = "" | |
| self.results_server_dir = "" | |
| self.results_server_html = "" | |
| self.results_server_page = "" | |
| self.results_summary_server_html = "" | |
| self.results_summary_server_page = "" | |
| # Full results in md text | |
| self.results_md = "" | |
| # Selectively sanitized md results to be mailed out or published | |
| self.email_results_md = "" | |
| self.publish_results_md = "" | |
| self.sanitize_email_results = False | |
| self.sanitize_publish_results = False | |
| # Summary results, generated by over-arching cfg | |
| self.email_summary_md = "" | |
| self.results_summary_md = "" | |
| # Merge in the values from the loaded hjson file. If subclasses want to | |
| # add other default parameters that depend on the parameters above, | |
| # they can override _merge_hjson and add their parameters at the start | |
| # of that. | |
| self._merge_hjson(hjson_data) | |
| # Is this a primary config? If so, we need to load up all the child | |
| # configurations at this point. If not, we place ourselves into | |
| # self.cfgs and consider ourselves a sort of "degenerate primary | |
| # configuration". | |
| self.is_primary_cfg = 'use_cfgs' in hjson_data | |
| if not self.is_primary_cfg: | |
| self.cfgs.append(self) | |
| else: | |
| for entry in self.use_cfgs: | |
| self._load_child_cfg(entry, mk_config) | |
| if self.rel_path == "": | |
| self.rel_path = os.path.dirname(self.flow_cfg_file).replace( | |
| self.proj_root + '/', '') | |
| self.results_path = os.path.join(self.scratch_base_path, "reports", self.rel_path, | |
| self.timestamp) | |
| self.symlink_path = os.path.join(self.scratch_base_path, "reports", self.rel_path, | |
| "latest") | |
| # Process overrides before substituting wildcards | |
| self._process_overrides() | |
| # Expand wildcards. If subclasses need to mess around with parameters | |
| # after merging the hjson but before expansion, they can override | |
| # _expand and add the code at the start. | |
| self._expand() | |
| # Run any final checks | |
| self._post_init() | |
| def _merge_hjson(self, hjson_data): | |
| '''Take hjson data and merge it into self.__dict__ | |
| Subclasses that need to do something just before the merge should | |
| override this method and call super()._merge_hjson(..) at the end. | |
| ''' | |
| for key, value in hjson_data.items(): | |
| set_target_attribute(self.flow_cfg_file, self.__dict__, key, value) | |
| def _expand(self): | |
| '''Called to expand wildcards after merging hjson | |
| Subclasses can override this to do something just before expansion. | |
| ''' | |
| # If this is a primary configuration, it doesn't matter if we don't | |
| # manage to expand everything. | |
| partial = self.is_primary_cfg | |
| self.__dict__ = find_and_substitute_wildcards(self.__dict__, | |
| self.__dict__, | |
| self.ignored_wildcards, | |
| ignore_error=partial) | |
| def _post_init(self): | |
| # Run some post init checks | |
| if not self.is_primary_cfg: | |
| # Check if self.cfgs is a list of exactly 1 item (self) | |
| if not (len(self.cfgs) == 1 and self.cfgs[0].name == self.name): | |
| log.error("Parse error!\n%s", self.cfgs) | |
| sys.exit(1) | |
| def create_instance(self, mk_config, flow_cfg_file): | |
| '''Create a new instance of this class for the given config file. | |
| mk_config is a factory method (passed explicitly to avoid a circular | |
| dependency between this file and CfgFactory.py). | |
| ''' | |
| new_instance = mk_config(flow_cfg_file) | |
| # Sanity check to make sure the new object is the same class as us: we | |
| # don't yet support heterogeneous primary configurations. | |
| if type(self) is not type(new_instance): | |
| log.error("{}: Loading child configuration at {!r}, but the " | |
| "resulting flow types don't match: ({} vs. {}).".format( | |
| self.flow_cfg_file, flow_cfg_file, | |
| type(self).__name__, | |
| type(new_instance).__name__)) | |
| sys.exit(1) | |
| return new_instance | |
| def _load_child_cfg(self, entry, mk_config): | |
| '''Load a child configuration for a primary cfg''' | |
| if type(entry) is str: | |
| # Treat this as a file entry. Substitute wildcards in cfg_file | |
| # files since we need to process them right away. | |
| cfg_file = subst_wildcards(entry, self.__dict__, ignore_error=True) | |
| self.cfgs.append(self.create_instance(mk_config, cfg_file)) | |
| elif type(entry) is dict: | |
| # Treat this as a cfg expanded in-line | |
| temp_cfg_file = self._conv_inline_cfg_to_hjson(entry) | |
| if not temp_cfg_file: | |
| return | |
| self.cfgs.append(self.create_instance(mk_config, temp_cfg_file)) | |
| # Delete the temp_cfg_file once the instance is created | |
| log.log(VERBOSE, "Deleting temp cfg file:\n%s", temp_cfg_file) | |
| rm_path(temp_cfg_file, ignore_error=True) | |
| else: | |
| log.error( | |
| "Type of entry \"%s\" in the \"use_cfgs\" key is invalid: %s", | |
| entry, str(type(entry))) | |
| sys.exit(1) | |
| def _conv_inline_cfg_to_hjson(self, idict): | |
| '''Dump a temp hjson file in the scratch space from input dict. | |
| This method is to be called only by a primary cfg''' | |
| if not self.is_primary_cfg: | |
| log.fatal("This method can only be called by a primary cfg") | |
| sys.exit(1) | |
| name = idict["name"] if "name" in idict.keys() else None | |
| if not name: | |
| log.error("In-line entry in use_cfgs list does not contain a " | |
| "\"name\" key (will be skipped!):\n%s", idict) | |
| return None | |
| # Check if temp cfg file already exists | |
| temp_cfg_file = (self.scratch_root + "/." + self.branch + "__" + name + | |
| "_cfg.hjson") | |
| # Create the file and dump the dict as hjson | |
| log.log(VERBOSE, "Dumping inline cfg \"%s\" in hjson to:\n%s", name, | |
| temp_cfg_file) | |
| try: | |
| with open(temp_cfg_file, "w") as f: | |
| f.write(hjson.dumps(idict, for_json=True)) | |
| except Exception as e: | |
| log.error("Failed to hjson-dump temp cfg file\"%s\" for \"%s\"" | |
| "(will be skipped!) due to:\n%s", temp_cfg_file, name, e) | |
| return None | |
| # Return the temp cfg file created | |
| return temp_cfg_file | |
| def _process_overrides(self): | |
| # Look through the dict and find available overrides. | |
| # If override is available, check if the type of the value for existing | |
| # and the overridden keys are the same. | |
| overrides_dict = {} | |
| if hasattr(self, "overrides"): | |
| overrides = getattr(self, "overrides") | |
| if type(overrides) is not list: | |
| log.error("The type of key \"overrides\" is %s - it should be " | |
| "a list", type(overrides)) | |
| sys.exit(1) | |
| # Process override one by one | |
| for item in overrides: | |
| if type(item) is dict and set( | |
| item.keys()) == {"name", "value"}: | |
| ov_name = item["name"] | |
| ov_value = item["value"] | |
| if ov_name not in overrides_dict.keys(): | |
| overrides_dict[ov_name] = ov_value | |
| self._do_override(ov_name, ov_value) | |
| else: | |
| log.error("Override for key \"%s\" already exists!\n" | |
| "Old: %s\nNew: %s", ov_name, | |
| overrides_dict[ov_name], ov_value) | |
| sys.exit(1) | |
| else: | |
| log.error("\"overrides\" is a list of dicts with " | |
| "{\"name\": <name>, \"value\": <value>} pairs. " | |
| "Found this instead:\n%s", str(item)) | |
| sys.exit(1) | |
| def _do_override(self, ov_name, ov_value): | |
| # Go through self attributes and replace with overrides | |
| if hasattr(self, ov_name): | |
| orig_value = getattr(self, ov_name) | |
| if type(orig_value) == type(ov_value): | |
| log.debug("Overriding \"%s\" value \"%s\" with \"%s\"", | |
| ov_name, orig_value, ov_value) | |
| setattr(self, ov_name, ov_value) | |
| else: | |
| log.error("The type of override value \"%s\" for \"%s\" " | |
| "mismatches the type of original value \"%s\"", | |
| ov_value, ov_name, orig_value) | |
| sys.exit(1) | |
| else: | |
| log.error("Override key \"%s\" not found in the cfg!", ov_name) | |
| sys.exit(1) | |
| def _purge(self): | |
| '''Purge the existing scratch areas in preperation for the new run.''' | |
| return | |
| def purge(self): | |
| '''Public facing API for _purge().''' | |
| for item in self.cfgs: | |
| item._purge() | |
| def _print_list(self): | |
| '''Print the list of available items that can be kicked off.''' | |
| return | |
| def print_list(self): | |
| '''Public facing API for _print_list().''' | |
| for item in self.cfgs: | |
| item._print_list() | |
| def prune_selected_cfgs(self): | |
| '''Prune the list of configs for a primary config file.''' | |
| # This should run after self.cfgs has been set | |
| assert self.cfgs | |
| # If the user didn't pass --select-cfgs, we don't do anything. | |
| if self.select_cfgs is None: | |
| return | |
| # If the user passed --select-cfgs, but this isn't a primary config | |
| # file, we should probably complain. | |
| if not self.is_primary_cfg: | |
| log.error('The configuration file at {!r} is not a primary ' | |
| 'config, but --select-cfgs was passed on the command ' | |
| 'line.'.format(self.flow_cfg_file)) | |
| sys.exit(1) | |
| # Filter configurations | |
| self.cfgs = [c for c in self.cfgs if c.name in self.select_cfgs] | |
| def _create_deploy_objects(self): | |
| '''Create deploy objects from items that were passed on for being run. | |
| The deploy objects for build and run are created from the objects that | |
| were created from the create_objects() method. | |
| ''' | |
| return | |
| def create_deploy_objects(self): | |
| '''Public facing API for _create_deploy_objects(). | |
| ''' | |
| self.prune_selected_cfgs() | |
| # GUI mode is allowed only for one cfg. | |
| if self.gui and len(self.cfgs) > 1: | |
| log.fatal("In GUI mode, only one cfg can be run.") | |
| sys.exit(1) | |
| for item in self.cfgs: | |
| item._create_deploy_objects() | |
| def deploy_objects(self): | |
| '''Public facing API for deploying all available objects. | |
| Runs each job and returns a map from item to status. | |
| ''' | |
| deploy = [] | |
| for item in self.cfgs: | |
| deploy.extend(item.deploy) | |
| if not deploy: | |
| log.error("Nothing to run!") | |
| sys.exit(1) | |
| return Scheduler(deploy, get_launcher_cls()).run() | |
| def _gen_results(self, results): | |
| ''' | |
| The function is called after the regression has completed. It collates | |
| the status of all run targets and generates a dict. It parses the | |
| testplan and maps the generated result to the testplan entries to | |
| generate a final table (list). It also prints the full list of failures | |
| for debug / triage. The final result is in markdown format. | |
| results should be a dictionary mapping deployed item to result. | |
| ''' | |
| return | |
| def gen_results(self, results): | |
| '''Public facing API for _gen_results(). | |
| results should be a dictionary mapping deployed item to result. | |
| ''' | |
| for item in self.cfgs: | |
| result = item._gen_results(results) | |
| item.write_results_html("results.html", item.results_md) | |
| log.info("[results]: [%s]:\n%s\n", item.name, result) | |
| log.info("[scratch_path]: [%s] [%s]", item.name, item.scratch_path) | |
| log.log(VERBOSE, "[results_path]: [%s] [%s]", item.name, item.results_path) | |
| self.errors_seen |= item.errors_seen | |
| if self.is_primary_cfg: | |
| self.gen_results_summary() | |
| self.write_results_html("summary.html", self.results_summary_md) | |
| self.gen_email_html_summary() | |
| def gen_results_summary(self): | |
| '''Public facing API to generate summary results for each IP/cfg file | |
| ''' | |
| return | |
| def write_results_html(self, filename, text_md): | |
| '''Convert given text_md to html format and write it to file with given filename. | |
| ''' | |
| # Prepare workspace to generate reports. | |
| # Keep up to 2 weeks results. | |
| # If path exists, skip clean_odirs and directly update the files in the existing path. | |
| if not (os.path.exists(self.results_path)): | |
| clean_odirs(odir=self.results_path, max_odirs=14) | |
| mk_path(self.results_path) | |
| mk_path(self.symlink_path) | |
| # Prepare results and paths. | |
| text_html = md_results_to_html(self.results_title, self.css_file, text_md) | |
| result_path = os.path.join(self.results_path, filename) | |
| symlink_path = os.path.join(self.symlink_path, filename) | |
| # Write results to the report area. | |
| with open(result_path, "w") as results_file: | |
| results_file.write(text_html) | |
| log.log(VERBOSE, "[results page]: [%s][%s], self.name, results_path") | |
| # Link the `/latest` folder with the latest reports. | |
| mk_symlink(result_path, symlink_path) | |
| def _get_results_page_link(self, link_text): | |
| if not self.args.publish: | |
| return link_text | |
| results_page_url = self.results_server_page.replace( | |
| self.results_server_prefix, self.results_server_url_prefix) | |
| return "[%s](%s)" % (link_text, results_page_url) | |
| def gen_email_html_summary(self): | |
| if self.is_primary_cfg: | |
| # user can customize email content by using email_summary_md, | |
| # otherwise default to send out results_summary_md | |
| gen_results = self.email_summary_md or self.results_summary_md | |
| else: | |
| gen_results = self.email_results_md or self.results_md | |
| results_html = md_results_to_html(self.results_title, self.css_file, | |
| gen_results) | |
| results_html_file = self.scratch_root + "/email.html" | |
| f = open(results_html_file, 'w') | |
| f.write(results_html) | |
| f.close() | |
| log.info("[results:email]: [%s]", results_html_file) | |
| def _publish_results(self): | |
| '''Publish results to the opentitan web server. | |
| Results are uploaded to {results_server_path}/latest/results. | |
| If the 'latest' directory exists, then it is renamed to its 'timestamp' | |
| directory. If the list of directories in this area is > 14, then the | |
| oldest entry is removed. Links to the last 7 regression results are | |
| appended at the end if the results page. | |
| ''' | |
| if which('gsutil') is None or which('gcloud') is None: | |
| log.error("Google cloud SDK not installed! Cannot access the " | |
| "results server") | |
| return | |
| # Construct the paths | |
| results_page_url = self.results_server_page.replace( | |
| self.results_server_prefix, self.results_server_url_prefix) | |
| # Timeformat for moving the dir | |
| tf = "%Y.%m.%d_%H.%M.%S" | |
| # Extract the timestamp of the existing self.results_server_page | |
| cmd = self.results_server_cmd + " ls -L " + self.results_server_page + \ | |
| " | grep \'Creation time:\'" | |
| log.log(VERBOSE, cmd) | |
| cmd_output = subprocess.run(cmd, | |
| shell=True, | |
| stdout=subprocess.PIPE, | |
| stderr=subprocess.DEVNULL) | |
| log.log(VERBOSE, cmd_output.stdout.decode("utf-8")) | |
| old_results_ts = cmd_output.stdout.decode("utf-8") | |
| old_results_ts = old_results_ts.replace("Creation time:", "") | |
| old_results_ts = old_results_ts.strip() | |
| # Move the 'latest' to its timestamp directory if lookup succeeded | |
| if cmd_output.returncode == 0: | |
| try: | |
| if old_results_ts != "": | |
| ts = datetime.datetime.strptime( | |
| old_results_ts, "%a, %d %b %Y %H:%M:%S %Z") | |
| old_results_ts = ts.strftime(tf) | |
| except ValueError as e: | |
| log.error( | |
| "%s: \'%s\' Timestamp conversion value error raised!", e) | |
| old_results_ts = "" | |
| # If the timestamp conversion failed - then create a dummy one with | |
| # yesterday's date. | |
| if old_results_ts == "": | |
| log.log(VERBOSE, | |
| "Creating dummy timestamp with yesterday's date") | |
| ts = datetime.datetime.now( | |
| datetime.timezone.utc) - datetime.timedelta(days=1) | |
| old_results_ts = ts.strftime(tf) | |
| old_results_dir = self.results_server_path + "/" + old_results_ts | |
| cmd = (self.results_server_cmd + " mv " + self.results_server_dir + | |
| " " + old_results_dir) | |
| log.log(VERBOSE, cmd) | |
| cmd_output = subprocess.run(cmd, | |
| shell=True, | |
| stdout=subprocess.PIPE, | |
| stderr=subprocess.DEVNULL) | |
| log.log(VERBOSE, cmd_output.stdout.decode("utf-8")) | |
| if cmd_output.returncode != 0: | |
| log.error("Failed to mv old results page \"%s\" to \"%s\"!", | |
| self.results_server_dir, old_results_dir) | |
| # Do an ls in the results root dir to check what directories exist. | |
| results_dirs = [] | |
| cmd = self.results_server_cmd + " ls " + self.results_server_path | |
| log.log(VERBOSE, cmd) | |
| cmd_output = subprocess.run(args=cmd, | |
| shell=True, | |
| stdout=subprocess.PIPE, | |
| stderr=subprocess.DEVNULL) | |
| log.log(VERBOSE, cmd_output.stdout.decode("utf-8")) | |
| if cmd_output.returncode == 0: | |
| # Some directories exist. Check if 'latest' is one of them | |
| results_dirs = cmd_output.stdout.decode("utf-8").strip() | |
| results_dirs = results_dirs.split("\n") | |
| else: | |
| log.log(VERBOSE, "Failed to run \"%s\"!", cmd) | |
| # Start pruning | |
| log.log(VERBOSE, "Pruning %s area to limit last 7 results", | |
| self.results_server_path) | |
| rdirs = [] | |
| for rdir in results_dirs: | |
| dirname = rdir.replace(self.results_server_path, '') | |
| dirname = dirname.replace('/', '') | |
| if dirname == "latest": | |
| continue | |
| rdirs.append(dirname) | |
| rdirs.sort(reverse=True) | |
| rm_cmd = "" | |
| history_txt = "\n## Past Results\n" | |
| history_txt += "- [Latest](" + results_page_url + ")\n" | |
| if len(rdirs) > 0: | |
| for i in range(len(rdirs)): | |
| if i < 7: | |
| rdir_url = self.results_server_path + '/' + rdirs[ | |
| i] + "/" + self.results_server_html | |
| rdir_url = rdir_url.replace(self.results_server_prefix, | |
| self.results_server_url_prefix) | |
| history_txt += "- [{}]({})\n".format(rdirs[i], rdir_url) | |
| elif i > 14: | |
| rm_cmd += self.results_server_path + '/' + rdirs[i] + " " | |
| if rm_cmd != "": | |
| rm_cmd = self.results_server_cmd + " -m rm -r " + rm_cmd + "; " | |
| # Append the history to the results. | |
| publish_results_md = self.publish_results_md or self.results_md | |
| publish_results_md = publish_results_md + history_txt | |
| # Publish the results page. | |
| # First, write the results html file to the scratch area. | |
| self.write_results_html("publish.html", publish_results_md) | |
| results_html_file = os.path.join(self.results_path, "publish.html") | |
| log.info("Publishing results to %s", results_page_url) | |
| cmd = (self.results_server_cmd + " cp " + results_html_file + " " + | |
| self.results_server_page) | |
| log.log(VERBOSE, cmd) | |
| try: | |
| cmd_output = subprocess.run(args=cmd, | |
| shell=True, | |
| stdout=subprocess.PIPE, | |
| stderr=subprocess.STDOUT) | |
| log.log(VERBOSE, cmd_output.stdout.decode("utf-8")) | |
| except Exception as e: | |
| log.error("%s: Failed to publish results:\n\"%s\"", e, str(cmd)) | |
| def publish_results(self): | |
| '''Public facing API for publishing results to the opentitan web | |
| server. | |
| ''' | |
| for item in self.cfgs: | |
| item._publish_results() | |
| if self.is_primary_cfg: | |
| self.publish_results_summary() | |
| def publish_results_summary(self): | |
| '''Public facing API for publishing md format results to the opentitan | |
| web server. | |
| ''' | |
| results_page_url = self.results_summary_server_page.replace( | |
| self.results_server_prefix, self.results_server_url_prefix) | |
| # Publish the results page. | |
| log.info("Publishing results summary to %s", results_page_url) | |
| result_summary_path = os.path.join(self.results_path, "summary.html") | |
| cmd = (self.results_server_cmd + " cp " + result_summary_path + " " + | |
| self.results_summary_server_page) | |
| log.log(VERBOSE, cmd) | |
| try: | |
| cmd_output = subprocess.run(args=cmd, | |
| shell=True, | |
| stdout=subprocess.PIPE, | |
| stderr=subprocess.STDOUT) | |
| log.log(VERBOSE, cmd_output.stdout.decode("utf-8")) | |
| except Exception as e: | |
| log.error("%s: Failed to publish results:\n\"%s\"", e, str(cmd)) | |
| def has_errors(self): | |
| return self.errors_seen |