opencos-eda 0.3.9__py3-none-any.whl → 0.3.11__py3-none-any.whl

opencos/docs/eda.md

@@ -0,0 +1,147 @@
+# EDA Tool
+
+## Install
+
+Using `uv` (recommended):
+
+From PyPI:
+```
+uv tool install opencos-eda
+```
+
+OR, from the repo:
+```
+uv tool install /path/to/your/checkout/dir/of/opencos
+```
+
+This makes the `eda` and `oc_cli` commands available in your environment.
+
+## Basic Recipes
+
+Run a single simulation using the default simulator (of those installed).
+`oclib_fifo_test` is target in `./lib/tests/DEPS.yml`
+```
+eda sim lib/tests/oclib_fifo_test
+```
+
+Run the same single simulation, but use `verilator`, dump waves
+```
+eda sim --waves --tool verilator lib/tests/oclib_fifo_test
+```
+
+Run the same single simulation, but use `vivado` XSim, and run in GUI mode
+```
+eda sim --gui --tool vivado lib/tests/oclib_fifo_test
+```
+
+Run a compile + elab without a DEPS.yml file or target involved for dependencies
+```
+eda elab --tool verilator +incdir+. ./lib/oclib_assert_pkg.sv ./lib/oclib_simple_reset_sync.sv
+
+## Basic CLI usage:
+eda <command> [--args] [+incdir+DIR|+define+KEY=VALUE|+plusarg=value] file1.sv file2.sv file3.sv
+```
+
+## Example Regression testing
+
+```
+eda multi sim '.../*_test' --parallel 16
+eda multi elab 'lib/*' --parallel 16
+eda multi elab 'sim/*' --parallel 16
+eda multi elab 'top/*' --parallel 16
+```
+
+If you'd like output to stdout, which is how our github Actions are run, use `--verbose` with `eda multi`
+```
+eda multi sim --verbose lib/tests/oc*test
+```
+
+## Example "sweep"
+
+Sweeping a build across a range of parameters
+
+```
+eda sweep build u200 --seed=SEED "SEED=(1,2)" +define+OC_MEMORY_BIST_PORT_COUNT=PORTS "PORTS=[1,4,8,16,32]" +define+TARGET_PLL0_CLK_HZ=MHZ000000 "MHZ=(200,400,50)" --parallel 12
+```
+
+## Example for building treating non .sv file(s) as systemverilog
+
+```
+eda sim --tool verilator sv@several_modules.txt --top=my_module
+```
+
+Note that you can prefix source files with `sv@`, `v@`, `vhdl@` or `cpp@` if the file contents do not match their filename extension, and you would like `eda` to force use that file as, for example, systemverilog.
+
+
+# Help
+
+```
+eda help
+```
+
+```
+$ eda help
+INFO: [EDA] eda: version X.Y.Z
+INFO: [EDA] eda_config: --config-yml=eda_config_defaults.yml observed
+INFO: [EDA] eda_config: using config: ..../site-packages/opencos/eda_config_defaults.yml
+INFO: [EDA] *** OpenCOS EDA ***
+INFO: [EDA] Detected slang (/usr/local/bin/slang), auto-setting up tool slang
+INFO: [EDA] Detected verilator (/usr/local/bin/verilator), auto-setting up tool verilator
+INFO: [EDA] Detected surelog (/usr/local/bin/surelog), auto-setting up tool surelog
+INFO: [EDA] Detected gtkwave (/usr/bin/gtkwave), auto-setting up tool gtkwave
+INFO: [EDA] Detected vivado (/tools/Xilinx/Vivado/VVVV.v/bin/vivado), auto-setting up tool vivado
+INFO: [EDA] Detected slang_yosys (/usr/local/bin/yosys), auto-setting up tool slang_yosys
+INFO: [EDA] Detected iverilog (/usr/local/bin/iverilog), auto-setting up tool iverilog
+
+Usage:
+    eda [<options>] <command> [options] <files|targets, ...>
+
+Where <command> is one of:
+
+    sim          - Simulates a DEPS target
+    elab         - Elaborates a DEPS target (sort of sim based LINT)
+    synth        - Synthesizes a DEPS target
+    flist        - Create dependency from a DEPS target
+    proj         - Create a project from a DEPS target for GUI sim/waves/debug
+    multi        - Run multiple DEPS targets, serially or in parallel
+    tools-multi  - Same as 'multi' but run on all available tools, or specfied using --tools
+    sweep        - Sweep one or more arguments across a range, serially or in parallel
+    build        - Build for a board, creating a project and running build flow
+    waves        - Opens waveform from prior simulation
+    upload       - Uploads a finished design into hardware
+    open         - Opens a project
+    export       - Export files related to a target, tool independent
+    help         - This help (without args), or i.e. "eda help sim" for specific help
+
+And <files|targets, ...> is one or more source file or DEPS markup file target,
+    such as .v, .sv, .vhd[l], .cpp files, or a target key in a DEPS.[yml|yaml|toml|json].
+    Note that you can prefix source files with `sv@`, `v@`, `vhdl@` or `cpp@` to
+    force use that file as systemverilog, verilog, vhdl, or C++, respectively.
+
+
+opencos common options:
+  --version
+  --color, --no-color   Use shell colors for info/warning/error messaging (default: True)
+  --quiet, --no-quiet   Do not display info messaging
+  --verbose, --no-verbose
+                        Display additional messaging level 2 or higher
+  --fancy, --no-fancy
+  --debug, --no-debug   Display additional debug messaging level 1 or higher
+  --debug-level DEBUG_LEVEL
+                        Set debug level messaging (default: 0)
+  --logfile LOGFILE     Write eda messaging to logfile (default disabled)
+  --force-logfile FORCE_LOGFILE
+                        Set to force overwrite the logfile
+  --no-respawn          Legacy mode (default respawn disabled) for respawning eda.py using $OC_ROOT/bin
+
+opencos eda config options:
+  --config-yml CONFIG_YML
+                        YAML filename to use for configuration (default eda_config_defaults.yml)
+
+eda options:
+  -q, --quit   For interactive mode (eda called with no options, command, or targets)
+  --exit       same as --quit
+  -h, --help
+  --tool TOOL  Tool to use for this command, such as: modelsim_ase, verilator, modelsim_ase=/path/to/bin/vsim, verilator=/path/to/bin/verilator
+  --eda-safe   disable all DEPS file deps shell commands, overrides values from --config-yml
+```

opencos/docs/oc_cli.md

@@ -0,0 +1,135 @@
+
+USAGE
+=====
+
+[sudo] oc_cli --serial <port>
+
+<port> can be COM<x> (Windows) or /dev/ttyUSB<x> (Linux).  Depending on permissions for /dev/ttyUSB<x>, sudo maybe required.
+
+<port> can also be "tcp:<ip>:<port>:<device>" for connecting via TCP-to-UART bridge.
+
+GLOBAL COMMANDS
+===============
+
+info
+^^ prints compile-time info (UUID, build time/date, included userspace, etc)
+
+scan
+^^ scans the top level (ring) interfaces and reports the type of IP on each channel
+
+perf (NOT PORTED YET)
+^^ does a performance test of the comms channel
+
+debug <n>
+^^ set debug level <n>.  without argument, reports debug level.
+
+ping
+^^ sends <CR> and checks for a prompt, sends "^" and checks for a syntax error response.
+
+reset
+^^ sends 64x '!' characters, which initiates a full chip reset regardless of the state of the device.
+
+source <script file>
+^^ reads in a script with oc_cli commands
+
+import <python file>
+^^ reads in Python code to extend the commands oc_cli understands.  Typically used to pull in a userspace "driver".  Can also be used to "live patch" oc_cli during development work.
+
+set <var> <value>
+^^ sets a variable for use in oc_cli commands.  Refer to variables with $<var> syntax.  Typically used to enable scripts (see 'source') that are independent of channel allocation in the target (for example, 'set user_ch 4' and then a script doing 'memtest $user_ch xxx')
+
+read|rd|r <address> [<channel> <address space>]
+^^ reads a CSR in the device.  <channel> and <address space> are optional after the first rd/wr command; if not provided, the prior values will be used.
+
+write|wr|w <address> <data> [<channel> <address space>]
+^^ writes a CSR in the device.  <channel> and <address space> are optional after the first rd/wr command; if not provided, the prior values will be used.
+
+quit|q
+^^ exit oc_cli
+
+PLL COMMANDS
+============
+
+PLL commands are valid for channels that have a PLL IP (use 'scan' if not sure)
+
+pll <channel>
+^^ dumps the state of the PLL
+
+pll <channel> measure
+^^ measure clock 0 (for now) of the PLL on <channel>
+
+pll <channel> reset
+^^ reset PLL on <channel>.  Generally required after changing multipliers, dividers, etc.
+
+pll <channel> all_up (or all_down)
+^^ move all clocks on PLL up (or down) in frequency, by changing the feedback divider.  does not bounds check.
+
+pll <channel> clk0_up (or clk0_down)
+^^ move CLK0 on PLL up (or down) in frequency, by changing the fractional divider.  does not bounds check.
+
+pll <channel> throttle <level>
+^^ throttles the output clock 0 (for now).  <level> is 0-8, in 12.5% steps, with 0 meaning "no throttling" and 8 meaning "complete stop".
+
+pll <channel> freq <mhz>
+^^ attempts to set the clock of PLL <channel> to <mhz>.  NOT IMPLEMENTED YET!!!  (it's non-trivial)
+
+pll <channel> ramp <command list>
+^^ runs <command list> (an arbitrary oc_cli command line) at the current clock speeds, then ramps up the speed by reducing the fractional divider on the clock.  This will test some limited range (for example 350-410MHz).  To go beyond this, manually changing VCO freq, dividers, etc, will be required.
+
+
+CHIPMON COMMANDS
+================
+
+CHIPMON commands are valid for channels that have a CHIPMON IP (use 'scan' if not sure)
+
+chipmon <channel>
+^^ dumps the state of the CHIPMON
+
+
+PROTECT COMMANDS
+================
+
+PROTECT commands are valid for channels that have a PROTECT IP (use 'scan' if not sure)
+
+protect <channel>
+^^ dumps the state of the PROTECT, including the bitstream ID and the FPGA's unique DNA fingerprint (both of which usually required to get a license)
+
+protect <channel> unlock <key>
+^^ unlocks the bitstream protection using <key>
+
+MEMTEST COMMANDS
+================
+
+MEMTEST is available in the default userspace, and will not be in other userspaces unless specifically included (in which case, there maybe other commands needed to configure the userspace to connect memtest to the memory channels being tested).
+
+memtest <channel>
+^^ dumps the state of the MEMTEST
+
+memtest <channel> <args>
+^^ <args> is:
+   write               - enables writing memory
+   read                - enables reading memory
+   verbose=<x>         - set verbosity to <n> (default 1)
+   ops=<x>             - run <x> operations per port under test (default 1)
+   addr=<x>            - <x> is the base address in memory (default 0)
+   addr_incr=<x>       - <x> as the amount to increment per op (default 0x20, 32 Bytes)
+   addr_incr_mask=<x>  - <x> is a bitmask applied to the increment value before ORing with addr (default 0xffffffffffffffff)
+   addr_rand_mask=<x>  - <x> is a bitmask applied to a random value before ORing with addr (default 0)
+   addr_port_shift=<x> - <x> is the amount to shift the port number to the left before ORing with addr (default 0)
+   addr_port_mask=<x>  - <x> is a bitmask applied to the shifted port number before ORing with addr (default 0)
+   waits=<x>           - <x> is the number of waitstates between ops (default 0)
+   burst=<x>           - <x> is the number of words in each op (default 1).  Note the CSR actually will hold (burst-1).
+   pattern=<x>         - <x> is a 32-bit seed for pattern generation (used to generate write data) (default 0x11111111).
+   signature=<x>       - <x> is the expected signature (which is a combination of all read data)
+   write_max_id        - <x> is the highest AXI ID used for issuing writes (default 0)
+   read_max_id         - <x> is the highest AXI ID used for issuing reads (default 0)
+   prescale            - sets the counter prescaler, will divide counters by N so that they can be sampled at the end of long tests
+   write_len_rand      - enables random write length
+   read_len_rand       - enables random read length
+   write_data_rotate   - enables write data rotation, ensures bus toggling without random data (which can be harder to make sense of in waves)
+   write_data_random   - enables write data randomization (still 'pseudorandom' and will be repeatable in terms of read signature)
+   measure             - report AXI-Lite and AXI3 clock speeds, cycles under reset, and cycles since reset
+   nopoll              - kick off the MEMTEST engine, but don't wait for completion, so oc_cli can be used to monitor temps, etc
+   stats               - report stats (latency, contexts) in summary, or per-port (verbose>1)
+   get_sigs            - report per-port signatures
+   signature_<p>=<x>   - set port <p> expected signature to <x> (default for all ports is -1, which means don't check)

opencos/eda.py

@@ -9,7 +9,6 @@ markup files
 import subprocess
 import os
 import sys
-import shutil
 import re
 import signal
 import argparse
@@ -20,10 +19,10 @@ from pathlib import Path
 
 import opencos
 from opencos import util, eda_config, eda_base
+from opencos.eda_base import Command, Tool, which_tool, print_eda_usage_line
+from opencos.files import safe_shutil_which
 from opencos.util import safe_emoji, Colors
-from opencos.eda_base import Tool, which_tool, get_eda_exec, print_eda_usage_line
 from opencos.utils import vsim_helper, vscode_helper
-from opencos.utils.subprocess_helpers import subprocess_run_background
 from opencos.utils import status_constants, str_helpers, subprocess_helpers
 
 # Configure util:
@@ -44,7 +43,8 @@ util.global_log.default_log_disable_with_args.extend([
 # These are also overriden depending on the tool, for example --tool verilator sets
 # "sim": CommandSimVerilator.
 def init_config(
-        config: dict,  quiet: bool = False, tool=None, run_auto_tool_setup: bool = True
+        config: dict,  quiet: bool = False, tool=None, command: str = '',
+        run_auto_tool_setup: bool = True
 ) -> dict:
     '''Sets or clears entries in config (dict) so tools can be re-loaded.'''
 
@@ -64,7 +64,7 @@ def init_config(
     config['auto_tools_found'] = {}
     config['tools_loaded'] = set()
     if run_auto_tool_setup:
-        config = auto_tool_setup(config=config, quiet=quiet, tool=tool)
+        config = auto_tool_setup(config=config, quiet=quiet, tool=tool, command=command)
     return config
 
 
@@ -137,7 +137,11 @@ def interactive(config: dict) -> int:
     '''
     rc = 0
     while True:
-        line = input('EDA->')
+        try:
+            line = input('EDA->')
+        except EOFError:
+            util.info('End of input reached unexpectedly, exiting')
+            return 0
         m = re.match(r'^([^\#]*)\#.*$', line)
         if m:
             line = m.group(1)
@@ -154,7 +158,8 @@ def interactive(config: dict) -> int:
 
 
 def auto_tool_setup( # pylint: disable=too-many-locals,too-many-branches,too-many-statements
-        warnings: bool = True, config = None, quiet: bool = False, tool: str = ''
+        warnings: bool = True, config = None, quiet: bool = False, tool: str = '',
+        command: str = ''
 ) -> dict:
     '''Returns an updated config, uses config['auto_tools_order'][0] dict, calls tool_setup(..)
 
@@ -172,9 +177,26 @@ def auto_tool_setup( # pylint: disable=too-many-locals,too-many-branches,too-man
     assert isinstance(config['auto_tools_order'], list)
     assert isinstance(config['auto_tools_order'][0], dict)
 
+    if command:
+        util.info(f'Auto tool setup for command: {Colors.byellow}{command}')
+
     for name, value in config['auto_tools_order'][0].items():
         if tool and tool != name:
-            continue # if called with tool=(some_name), then only load that tool.
+            # if called with tool=(some_name), then only load that tool (which is not
+            # this one)
+            continue
+
+        if command and command not in value.get('handlers', {}) and \
+           command not in config.get('command_has_subcommands', []):
+            # Skip tool_setup(..) if the tool handlers can't support command,
+            # this is a time-saving feature, but if the comman is multi, tools-multi,
+            # sweep, then don't skip this (we don't know what tools we need so load them
+            # all.
+            # We could figure this out if we went looking for all command(s)
+            # multi + sub-command, but that's slightly dangerous if we grab a 'command'
+            # from another arg.
+            util.debug(f"Skipping tool {name} because it cannot handle {command=}")
+            continue
 
         util.debug(f"Checking for ability to run tool: {name}")
         exe = value.get('exe', str())
@@ -204,9 +226,12 @@ def auto_tool_setup( # pylint: disable=too-many-locals,too-many-branches,too-man
 
         has_all_exe = True
         has_all_in_exe_path = True
+        exe_path = None
         for exe in exe_list:
             assert exe != '', f'{name=} {value=} value missing "exe" {exe=}'
-            p = shutil.which(exe)
+            p = safe_shutil_which(exe)
+            if not exe_path:
+                exe_path = p # set on first required exe
             if not p:
                 has_all_exe = False
                 util.debug(f"... No, missing exe {exe}")
@@ -217,10 +242,11 @@ def auto_tool_setup( # pylint: disable=too-many-locals,too-many-branches,too-man
 
         has_vsim_helper = True
         if value.get('requires_vsim_helper', False):
-            # This tool name must be in opencos.utils.vsim_helper.TOOL_IS[name].
+            # This tool name must be in opencos.utils.vsim_helper.TOOL_PATH[name].
             # Special case for vsim being used by a lot of tools.
             vsim_helper.init() # only runs checks once internally
-            has_vsim_helper = vsim_helper.TOOL_IS.get(name, False)
+            exe_path = vsim_helper.TOOL_PATH[name]
+            has_vsim_helper = bool(exe_path)
 
         has_vscode_helper = True
         needs_vscode_extensions = value.get('requires_vscode_extension', None)
@@ -254,18 +280,28 @@ def auto_tool_setup( # pylint: disable=too-many-locals,too-many-branches,too-man
 
         if all((has_all_py, has_all_env, has_all_exe, has_all_in_exe_path,
                 has_vsim_helper, has_vscode_helper)):
-            exe = exe_list[0]
-            p = shutil.which(exe)
-            config['auto_tools_found'][name] = exe # populate key-value pairs w/ first exe in list
+            if exe_path:
+                p = exe_path
+            else:
+                p = safe_shutil_which(exe_list[0])
+            config['auto_tools_found'][name] = p # populate key-value pairs w/ first exe in list
             if not quiet:
                 util.info(f"Detected {name} ({p})")
-            tool_setup(tool=name, quiet=True, auto_setup=True, warnings=warnings, config=config)
+            tool_setup(
+                tool=name, quiet=True, auto_setup=(not tool), warnings=warnings, config=config
+            )
+        else:
+            util.debug(f'Tool {name} is missing one of: {has_all_py=} {has_all_env=}',
+                       f'{has_all_exe=} {has_all_in_exe_path=} {has_vsim_helper=}',
+                       f'{has_vscode_helper=}')
 
     return config
 
 
-def tool_setup(tool: str, config: dict, quiet: bool = False, auto_setup: bool = False,
-               warnings: bool = True):
+def tool_setup( # pylint: disable=too-many-branches
+        tool: str, config: dict, quiet: bool = False, auto_setup: bool = False,
+        warnings: bool = True
+):
     ''' Adds items to config["tools_loaded"] (set) and updates config['command_handler'].
 
     config is potentially updated for entry ['command_handler'][command] with a Tool class.
@@ -322,10 +358,22 @@ def tool_setup(tool: str, config: dict, quiet: bool = False, auto_setup: bool =
 
         cls = util.import_class_from_string(str_class_name)
 
-        assert issubclass(cls, Tool), \
-            f'{str_class_name=} is does not have Tool class associated with it'
-        util.debug(f'Setting {cls=} for {command=} in config.command_handler')
-        config['command_handler'][command] = cls
+        if command in config.get('command_determines_tool', []) + \
+           config.get('command_tool_is_optional', []):
+            # we don't need to confirm the handler parent is a Tool class.
+            pass
+        else:
+            assert issubclass(cls, Tool), \
+                f'{str_class_name=} is does not have Tool class associated with it'
+
+        if not auto_setup or \
+           command not in config.get('command_determines_tool', []):
+            # If not auto_setup - then someone called this --tool by name on the command line,
+            # then update the command handler
+            # otherwise, if --tool was not set, and command determines tool, leave it with
+            # the default handler.
+            util.debug(f'Setting {cls=} for {command=} in config.command_handler')
+            config['command_handler'][command] = cls
 
     config['tools_loaded'].add(tool)
 
@@ -348,7 +396,6 @@ def process_tokens( # pylint: disable=too-many-branches,too-many-statements,too-
     deferred_tokens = []
     command = ""
     run_auto_tool_setup = True
-    process_tokens_cwd = os.getcwd()
 
     parser = eda_base.get_argparser()
     try:
@@ -375,6 +422,8 @@ def process_tokens( # pylint: disable=too-many-branches,too-many-statements,too-
 
     # Attempt to get the 'command' in the unparsed args before we've even
     # set the command handlers (some commands don't use tools).
+    # Note that we only grab the first command, and for multi, tools-multi,
+    # or sweep we do NOT get the subcommand.
     for value in unparsed:
         if value in config['DEFAULT_HANDLERS'].keys():
             command = value
@@ -390,7 +439,7 @@ def process_tokens( # pylint: disable=too-many-branches,too-many-statements,too-
         # This will handle any --tool=<name>=/path/to/bin also, so don't have to
         # run tool_setup(..) on its own.
         config = init_config(
-            config, tool=parsed.tool,
+            config, tool=parsed.tool, command=command,
             run_auto_tool_setup=run_auto_tool_setup
         )
         if not config:
@@ -457,26 +506,82 @@ def process_tokens( # pylint: disable=too-many-branches,too-many-statements,too-
     util.debug(f'Return from main process_tokens({tokens=}), {rc=}, {type(sco)=}, {unparsed=}')
 
     if rc == 0 and not parsed.tool and getattr(sco, 'tool_changed_respawn', False):
-        use_tool = sco.args.get('tool', '')
-        if not use_tool:
-            util.error(f'Unable to change tool from {parsed.tool}, internal eda problem.')
-            return status_constants.EDA_DEFAULT_ERROR
-
-        # close the util.log:
-        util.stop_log()
-        # respawn the original job, but with --tool=<use_tool> applied:
-        _command_list = [get_eda_exec(command), f"--tool={use_tool}"] + original_args
-        util.info(f'eda: respawn for tool change: {" ".join(_command_list)};',
-                  f' (running from: {process_tokens_cwd})')
-        subprocess_run_background(
-            work_dir=process_tokens_cwd,
-            command_list=_command_list,
-            background=util.args.get('quiet', False)
+        return respawn_new_sub_command_object(
+            sco=sco, parsed=parsed, config=config, command=command, tokens=tokens,
+            deferred_tokens=deferred_tokens
         )
 
     return rc
 
 
+def respawn_new_sub_command_object(
+        sco: Command, parsed: argparse.Namespace, config: dict, command: str,
+        tokens: list, deferred_tokens: list
+) -> int:
+    '''Returns retcode (int). Creates a new Command object, presumably using a different tool,
+
+    due to args changes from DEPS parsing that led to --tool=<different value> vs the automatic
+    value if --tool was not originally set. Will run process_tokens(..) on the new sub commmand
+    object.
+    '''
+
+    use_tool = sco.args.get('tool', '')
+
+    if not use_tool:
+        util.error(f'Unable to change tool from {parsed.tool}, internal eda problem.')
+        return status_constants.EDA_DEFAULT_ERROR
+
+    util.info(f'Changing {Colors.bcyan}--tool{Colors.normal}{Colors.green} --->',
+              f'{Colors.bcyan}{use_tool}{Colors.normal}{Colors.green} for command:',
+              f'{Colors.byellow}{command}')
+
+    # Update the command handler(s) with this new tool. We don't really respawn, just
+    # try to swap out the sco (Command obj handle)
+    entry = config['auto_tools_order'][0].get(use_tool, {})
+    tool_cmd_handler_dict = entry.get('handlers', {})
+
+    for _command, str_class_name in tool_cmd_handler_dict.items():
+        if _command and command and _command != command:
+            # This isn't the command we care about (it's just one of the commands
+            # this tool supports, so don't bother loading a handler for it:
+            continue
+
+        cls = util.import_class_from_string(str_class_name)
+        if _command in config.get('command_determines_tool', []) + \
+           config.get('command_tool_is_optional', []):
+            # we don't need to confirm the handler parent is a Tool class.
+            pass
+        else:
+            assert issubclass(cls, Tool), \
+                f'command {_command} {str_class_name=} does not have Tool class associated with it'
+
+        util.debug(f'Setting {cls=} for command={_command} in config.command_handler')
+        config['command_handler'][_command] = cls
+
+    old_sco = sco
+    sco = config['command_handler'][command](config=config) # sub command object
+    util.debug(f'No longer using handler: {type(old_sco)}; now using: {type(sco)}')
+    sco.config['eda_original_args'] = old_sco.config['eda_original_args']
+    del old_sco
+
+    rc = check_command_handler_cls(command_obj=sco, command=command, parsed_args=parsed)
+    if rc > 0:
+        util.debug(f'Return from main process_tokens({tokens=}), {rc=}, {type(sco)=},'
+                   f'unparsed={deferred_tokens}')
+        return rc
+
+    setattr(sco, 'command_name', command) # as a safeguard, 'command' set in 'sco'
+    util.info(f'--tool={use_tool}: running command: {Colors.byellow}eda {command} ',
+              ' '.join(deferred_tokens))
+    unparsed = sco.process_tokens(tokens=deferred_tokens, pwd=os.getcwd())
+
+    # query the status from the Command object (0 is pass, > 0 is fail, but we'd prefer to
+    # avoid rc=1 because that's the python exception rc)
+    rc = getattr(sco, 'status', 2)
+    util.debug(f'Return from main process_tokens({tokens=}), {rc=}, {type(sco)=}, {unparsed=}')
+    return rc
+
+
 def check_command_handler_cls(command_obj:object, command:str, parsed_args) -> int:
     '''Returns bash/sh return code, checks that a command handling class has all
 
@@ -514,7 +619,7 @@ def check_command_handler_cls(command_obj:object, command:str, parsed_args) -> i
                     if k == 'exe' or k.startswith('requires_cmd'):
                         util.warning(
                             f"tool '{parsed_tool}' has requirements that may not have been met --",
-                            f"{k}: {v}"
+                            f"{k}: {v} (Perhaps not in PATH?)"
                         )
                     if k == 'requires_vsim_helper':
                         if found_tool := vsim_helper.found():
@@ -585,7 +690,8 @@ def main(*args):
     if not util.args['quiet']:
         util.info(f'eda: version {opencos.__version__}', color=Colors.bcyan)
         # And show the command that was run (all args):
-        util.info(f"main: eda {' '.join(args)}; (run from {os.getcwd()})")
+        util.info(f"main: {Colors.byellow}eda {' '.join(args)}{Colors.normal}{Colors.green};",
+                  f"(run from {os.getcwd()})")
 
     # Handle --config-yml= arg
     config, unparsed = eda_config.get_eda_config(unparsed)
@@ -613,13 +719,41 @@ def main(*args):
     util.global_log.stop()
     return main_ret
 
+def main_show_autocomplete_instructions() -> None:
+    ''' Executable script entry point - eda_show_autocomplete
+
+    from pyproject.toml::project.scripts. Shows instructions on how to enable bash autocomplete
+    '''
+    source_filepath = opencos.__file__.replace(
+        '__init__.py', 'eda_deps_bash_completion.bash'
+    )
+    if os.path.exists(source_filepath):
+        print(
+            f"{Colors.yellow}To enable bash autocompletion with"
+            f" {Colors.bold}eda{Colors.normal}{Colors.yellow} script (uv not equired):"
+        )
+        print(f"{Colors.normal}")
+        print(f"    source {source_filepath}")
+        print("")
+        print(f"{Colors.yellow}Feel free to inspect this script prior to sourcing.")
+        print(f"{Colors.normal}")
+        sys.exit(0)
+    else:
+        util.error(f"It appears the following file(s) doe not exist: {source_filepath}")
+        sys.exit(1)
+
 
 def main_cli() -> None:
-    ''' Returns None, will exit with return code. Entry point for package script or __main__.'''
+    ''' Executable script entry point - eda
+
+    from pyproject.tom::project.scripts, or from __main__.
+    Returns None, will exit with return code.
+    '''
     signal.signal(signal.SIGINT, signal_handler)
     util.global_exit_allowed = True
     # Strip eda or eda.py from sys.argv, we know who we are if called from __main__:
     rc = main()
+    subprocess_helpers.cleanup_all()
     util.exit(rc)