Improve usability of error handling

Author: robtaylor

chipflow_lib/__init__.py

@@ -68,4 +68,4 @@ def _parse_config() -> 'Config':
     except FileNotFoundError:
        raise ChipFlowError(f"Config file not found. I expected to find it at {config_file}")
     except tomli.TOMLDecodeError as e:
-        raise ChipFlowError(f"TOML Error found when loading {config_file}: {e.msg} at line {e.lineno}, column {e.colno}")
+        raise ChipFlowError(f"{config_file} has a formatting error: {e.msg} at line {e.lineno}, column {e.colno}")

chipflow_lib/cli.py

@@ -113,4 +113,6 @@ def run(argv=sys.argv[1:]):
         if hasattr(args, "action"):
             cmd += f" {args.action}"
         print(f"Error while executing `{cmd}`: {e}")
+        print("Caused by:")
+        traceback.print_exception(e.__cause__)
         exit(1)

chipflow_lib/platforms/_utils.py

@@ -1104,7 +1104,7 @@ def top_components(config: 'Config') -> Dict[str, wiring.Component]:
             logger.debug(f"Config {param} = {conf} found for {name}")
             component_configs[param] = conf
         if name.startswith('_'):
-            raise ChipFlowError(f"Top components cannot start with '_': {name}")
+            raise ChipFlowError(f"Top components cannot start with '_' character, these are reserved for internal use: {name}")
 
     # Second pass: instantiate components
     for name, ref in config.chipflow.top.items():
@@ -1114,7 +1114,7 @@ def top_components(config: 'Config') -> Dict[str, wiring.Component]:
                 result[name] = cls(component_configs[name])
             else:
                 result[name] = cls()
-            logger.debug(f"top members for {name}:\n{pformat(result[name].metadata.origin.signature.members)}")
+            logger.debug(f"Top members for {name}:\n{pformat(result[name].metadata.origin.signature.members)}")
 
     return result
 

chipflow_lib/platforms/silicon.py

@@ -488,9 +488,16 @@ def _prepare(self, elaboratable, name="top"):
         return fragment.prepare(ports)
 
     def build(self, elaboratable, name="top"):
+        # hide Amaranth `UnusedElaboratable` warnings
         warnings.simplefilter(action="ignore", category=UnusedElaboratable)
-        fragment = self._prepare(elaboratable, name)
-        rtlil_text, _ = rtlil.convert_fragment(fragment, name)
+        try:
+            fragment = self._prepare(elaboratable, name)
+            rtlil_text, _ = rtlil.convert_fragment(fragment, name)
+        except Exception as e:
+            raise ChipFlowError("Error found when building design.") from e
+
+        # Enable warnings when an exception hasn't occured
+        warnings.filterwarnings("default", category=UnusedElaboratable)
 
         # Integrate Amaranth design with external Verilog
         yosys_script = [

chipflow_lib/steps/__init__.py

@@ -53,7 +53,6 @@ def _wire_up_ports(m: Module, top, platform):
     for n, t in top.items():
         logger.debug(f"    > {n}, {t}")
         setattr(m.submodules, n, t)
-    print("Wiring up ports:")
     for component, iface in platform._pinlock.port_map.ports.items():
         if component.startswith('_'):
             logger.debug(f"Ignoring special component {component}")

chipflow_lib/steps/silicon.py

@@ -82,10 +82,12 @@ def build_cli_parser(self, parser):
         submit_subparser = action_argument.add_parser(
             "submit", help=inspect.getdoc(self.submit).splitlines()[0])  # type: ignore
         submit_subparser.add_argument(
-            "--dry-run", help=argparse.SUPPRESS,
+            "--dry-run",
+            help="Build but do not submit design to cloud. Will output `rtlil` and `config` files.",
             default=False, action="store_true")
         submit_subparser.add_argument(
-            "--wait", help=argparse.SUPPRESS,
+            "--wait",
+            help="Maintain connection to cloud and trace build messages. Filtering is based on the log level (see `verbose` option).",
             default=False, action="store_true")
 
     def run_cli(self, args):
@@ -172,10 +174,11 @@ def submit(self, rtlil_path, args):
                 logger.debug(f"data=\n{json.dumps(data, indent=2)}")
                 logger.debug(f"files['config']=\n{config}")
                 shutil.copyfile(rtlil_path, 'rtlil')
-                with open("data", 'w') as f:
+                with open("rtlil", 'w') as f:
                     json.dump(data, f)
                 with open("config", 'w') as f:
                     f.write(config)
+                sp.info(f"Compiled design and configuration can be found in in `rtlil` and `config`")
                 return
 
             def network_err(e):