opencos-eda 0.2.52__py3-none-any.whl → 0.2.53__py3-none-any.whl

opencos/commands/__init__.py

@@ -20,6 +20,7 @@ from .waves import CommandWaves
 from .shell import CommandShell
 from .targets import CommandTargets
 from .lec import CommandLec
+from .deps_help import CommandDepsHelp
 
 __all__ = [
     'CommandBuild',
@@ -38,4 +39,5 @@ __all__ = [
     'CommandShell',
     'CommandTargets',
     'CommandLec',
+    'CommandDepsHelp',
 ]

opencos/commands/build.py

@@ -31,7 +31,7 @@ class CommandBuild(CommandDesign):
             self, tokens=tokens, process_all=process_all, pwd=pwd
         )
 
-        if self.status_any_error():
+        if self.stop_process_tokens_before_do_it():
             return unparsed
 
         # add defines for this job type

opencos/commands/deps_help.py

@@ -0,0 +1,259 @@
+'''opencos.commands.deps_help - command handler for: eda deps_help [args]
+
+Note this command is handled differently than others (such as CommandSim),
+it is generally run as simply
+
+    > eda deps_help
+    > eda deps_help --verbose
+    > eda deps_help --help
+
+uses no tools and will print a help text regarding DEPS markup files to stdout.
+'''
+
+
+import os
+
+from opencos.eda_base import Command
+from opencos import util
+
+
+BASIC_DEPS_HELP = '''
+
+--------------------------------------------------------------------
+
+  What is a DEPS.yml file and why does `eda` use this?
+  - DEPS.yml is a fancy filelist.
+  - Used to organize a project into "targets", a tool can run on a "target".
+  - Allows for more than just source files attached to a "target".
+    -- incdirs, defines, and args can be applied to a "target".
+
+--------------------------------------------------------------------
+
+  Hello World example:
+
+  The following example is a DEPS.yml file example for a SystemVerilog simulation of
+  hello_world_tb.sv. DEPS.yml is, in short, a fancy filelist. We use them in the `eda`
+  app to organize projects.
+
+--- DEPS.yml: ---
+
+hello-world:           # <-- this is a named target that will be run
+
+  deps:                # <-- 'deps' is a list of SV, Verilog, VHDL files in compile order
+    - hello_world_tb.sv
+
+  top: hello_world_tb  # <-- For testbenches, it is good practice to specifiy the topmost
+                       #     module using using 'top'. This is not necessary for design
+                       #     files.
+
+
+--- hello_world_tb.sv: ---
+
+module hello_world_tb;
+
+  initial begin
+    #10ns;
+    $display("%t %m: Hello World!", $realtime);
+    $display("%t %m: Test finished", $realtime);
+    $finish;
+  end
+
+endmodule : hello_world_tb
+
+---
+
+
+  hello-world:
+    The target name in the DEPS.yml we named is hello-world. That is a valid target
+    that `eda` can use. Such as:
+
+       eda sim --tool=verilator hello-world
+
+
+--------------------------------------------------------------------
+
+   Beyond Hello World example:
+
+   The following example is a DEPS.yml file for a more complex module simulation.
+   It has two files in ./DEPS.yml and ./lib/DEPS.yml.
+
+--- ./DEPS.yml: ---
+
+my_fifo:                         # <-- this is a design
+  incdirs: . lib                 # <-- 'incdirs' define the paths searched to find `include files
+  defines:
+    FIFO_DEBUG                   # add a basic define
+    FIFO_IMPLEMENTATION=uram     # add a define with a value
+  deps:            # <-- 'deps' is a list of SV, Verilog, VHDL files in compile order
+    - my_fifo.sv                 # an SV file pulled in directly
+    - lib/bin_to_gray            # a target, in a subdirectory that has it's own DEPS
+
+my_fifo_test:                    # <-- this is a TEST
+  top: my_fifo_test              # the top will default to whatever target is provided
+                                 # by the user, so this could be optional
+  deps:
+    - my_fifo                    # the target that is defined above
+    - my_fifo_tb.sv              # an SV file pulled in directly
+
+my_fifo_stress_test:             # <-- this is another TEST
+  top: my_fifo_test              # not optional because top is not "my_fifo_stress_test"
+  defines:
+    STRESS_TEST                  # configures my_fifo_test to be more stressful
+  deps:
+    - my_fifo_test               # aside from the define, this is same as "my_fifo_test"
+
+--- lib/DEPS.yml: ---
+
+lib_pkg:                         # <-- this is a package required by bin_to_gray below
+  deps:
+    - assert_pkg.sv              # an SV package pulled in directly, before it's needed below
+    - lib_pkg.sv                 # an SV package pulled in directly
+
+bin_to_gray:                     # <-- this is the target that was required by ../my_fifo
+  deps:
+    - lib_pkg                    # a target package, listed first as SV requires packages
+                                 # to be read before the code that uses them
+    - bin_to_gray.sv             # an SV module pulled in directly
+
+--------------------------------------------------------------------
+'''
+
+
+FULL_DEPS_HELP = '''
+
+--------------------------------------------------------------------
+
+   Full DEPS.yml schema:
+
+```
+DEFAULTS: # <table> defaults applied to ALL targets in this file, local targets ** override ** the defaults.
+
+METADATA: # <table> unstructured data, any UPPERCASE first level key is not considered a target.
+
+target-spec:
+
+  args: # <array or | separated str>
+    - --waves
+    - --sim_plusargs="+info=500"
+
+  defines: # <table>
+    SOME_DEFINE: value
+    SOME_DEFINE_NO_VALUE:   # we just leave this blank, or use nil (yaml's None)
+
+  incdirs: # <array>
+    - some/relative/path
+
+  top: # <string>
+
+  deps: # <array or | space separated string>
+    - some_relative_target       # <string> aka, a target
+    - some_file.sv               # <string> aka, a file
+    - sv@some_file.txt           # <string> aka, ext@file where we'd like a file not ending in .sv to be
+                                 # treated as a .sv file for tools.
+                                 # Supported for sv@, v@, vhdl@, cpp@
+    - commands:                  # <table> with key 'commands' for a <array>:  support for built-in commands
+                                 # Note this cannot be confused for other targets or files.
+      - shell: # <string>
+        var-subst-args: # <bool> default false. If true, substitute vars in commands, such as {fpga}
+                        # substituted from eda arg --fpga=SomeFpga, such that {fpga} becomes SomeFpga
+        var-subst-os-env:  #<bool> default false. If true, substitute vars in commands using os.environ vars,
+                           # such as {FPGA} could get substituted by env value for $FPGA
+        tee: # <string> optional filename, otherwise shell commands write to {target-spec}__shell_0.log
+        run-from-work-dir: #<bool> default true. If false, runs from the directory of this DEPS file.
+        filepath-subst-target-dir: #<bool> default true. If false, disables shell file path
+	                               substituion on this target's directory (this DEPS file dir).
+        dirpath-subst-target-dir: #<bool> default false. If true, enables shell directory path
+	                              substituion on this target's directory (this DEPS file dir).
+      - shell: echo "Hello World!"
+      - work-dir-add-sources: # <array or | space separated string>, this is how to add generated files
+                              # to compile order list.
+      - peakrdl:              # <string>     ## peakrdl command to generate CSRs
+
+  reqs: # <array or | space separated string>
+    - some_file.mem           # <string> aka, a non-source file required for this target.
+                              # This file is checked for existence prior to invoking the tool involved, for example,
+                              # in a simulation this would be done prior to a compile step.
+
+  multi:
+    ignore-this-target:  # <array of tables> eda commands to be ignored in `eda multi <command>` for this target only
+                         # this is checked in the matching multi targets list, and is not inherited through dependencies.
+      - commands: synth  # space separated strings
+        tools: vivado    # space separated strings
+
+      - commands: sim # omit tools, ignores 'sim' commands for all tools, for this target only, when this target
+                      # is in the target list called by `eda multi`.
+
+      - tools: vivado # omit commands, ignores all commands if tool is vivado, for this target only, when this target
+                      # is in the target list called by `eda multi`.
+
+    args: # <array> additional args added to all multi commands of this target.
+          # Note that all args are POSIX with dashes, --sim-plusargs=value, etc.
+
+  <eda-command>: # key is one of sim, flist, build, synth, etc.
+                 # can be used instead of 'tags' to support different args or deps.
+    disable-tools: # Note: not implemented yet.
+    only-tools:    # Note: not implemented yet.
+    args: # <array or | space separated string>
+    deps: # <array or | space separated string> # Note: not implemented yet
+    defines: ## <table>
+    incdirs: ## <array>
+
+  tags: # <table> this is the currently support tags features in a target.
+    <tag-name>: # <string> key for table, can be anything, name is not used.
+      with-tools: <array or | space separated string>
+                  # If using one of these tools, apply these values.
+                  # entries can be in the form: vivado, or vivado:2024.1
+      with-commands: <array or | space separated string>
+                  # apply if this was the `eda` command, such as: sim
+      with-args: # <table> (optional) arg key/value pairs to match for this tag.
+                 # this would be an alternative to running eda with --tags=value
+                 # The existence of an argument with correct value would enable a tag.
+                 # And example would be:
+                 #   with-args:
+                 #     waves: true
+      args: <array or | space separated string> # args to be applied if this target is used, with a matching
+                                          # tool in 'with-tools'.
+      deps: <array or | space separated string, applied with tag>
+      defines: <table, applied with tag>
+      incdirs: <array, applied with tag>
+      replace-config-tools: <table>  # spec matching eda_config_defaults.yml::tools.<tool> (replace merge strategy)
+      additive-config-tools: <table> # spec matching eda_config_defaults.yml::tools.<tool> (additive merge strategy)
+
+
+```
+'''
+
+
+class CommandDepsHelp:
+    '''command handler for: eda deps-help'''
+
+    command_name = 'deps-help'
+
+    def __init__(self, config: dict):
+        # We don't inherit opencos.eda_base.Command, so we have to set a few
+        # member vars for Command.help to work.
+        self.args = {}
+        self.args_help = {}
+        self.config = config
+        self.status = 0
+
+    def process_tokens( # pylint: disable=unused-argument
+        self, tokens: list, process_all: bool = True,
+        pwd: str = os.getcwd()
+    ) -> list:
+        '''This is effectively our 'run' method, entrypoint from opencos.eda.main'''
+
+        print(BASIC_DEPS_HELP)
+        if util.args['verbose'] or util.args['debug']:
+            print()
+            print(FULL_DEPS_HELP)
+
+        return []
+
+    def help(self, tokens: list) -> None:
+        '''Since we don't inherit from opencos.eda_base.Command, need our own help
+        method
+        '''
+        Command.help(self, tokens=tokens, no_targets=True)
+        print()
+        print(FULL_DEPS_HELP)

opencos/commands/export.py

@@ -40,7 +40,7 @@ class CommandExport(CommandDesign):
         unparsed = CommandDesign.process_tokens(
             self, tokens=tokens, process_all=process_all, pwd=pwd
         )
-        if self.status_any_error():
+        if self.stop_process_tokens_before_do_it():
             return unparsed
         if self.args['top']:
             # create our work dir, b/c top is set. We do this so any shell or peakrdl style

opencos/commands/flist.py

@@ -63,6 +63,9 @@ class CommandFList(CommandDesign):
         unparsed = CommandDesign.process_tokens(
             self, tokens=tokens, process_all=process_all, pwd=pwd
         )
+        if self.stop_process_tokens_before_do_it():
+            return unparsed
+
         self.do_it()
         return unparsed
 

opencos/commands/lec.py

@@ -66,7 +66,7 @@ class CommandLec(CommandDesign):
             self, tokens=tokens, process_all=process_all, pwd=pwd
         )
 
-        if self.status_any_error():
+        if self.stop_process_tokens_before_do_it():
             return unparsed
 
         # we require there to be two --designs set.

opencos/commands/open.py

@@ -23,5 +23,7 @@ class CommandOpen(CommandDesign):
         unparsed = CommandDesign.process_tokens(
             self, tokens=tokens, process_all=process_all, pwd=pwd
         )
+        if self.stop_process_tokens_before_do_it():
+            return unparsed
         self.do_it()
         return unparsed

opencos/commands/proj.py

@@ -28,7 +28,7 @@ class CommandProj(CommandDesign):
             self, tokens=tokens, process_all=process_all, pwd=pwd
         )
 
-        if self.status_any_error():
+        if self.stop_process_tokens_before_do_it():
             return unparsed
 
         # add defines for this job type

opencos/commands/shell.py

@@ -50,7 +50,7 @@ class CommandShell(CommandDesign):
             self, tokens=tokens, process_all=process_all, pwd=pwd
         )
 
-        if self.status_any_error():
+        if self.stop_process_tokens_before_do_it():
             return unparsed
 
         if self.args['top']:

opencos/commands/sim.py

@@ -72,6 +72,8 @@ class CommandSim(CommandDesign):
             'waves': 'Include waveforms, if possible for tool',
             'waves-start': 'Starting time of waveform capture, if possible for tool',
             'work-dir': 'Optional override for working directory, defaults to ./eda.work/<top>.sim',
+            'test-mode': ('stops the command early without executing, if --gui is present will'
+                          ' instead test without spawning gui')
 
         })
 
@@ -97,7 +99,7 @@ class CommandSim(CommandDesign):
             self, tokens=tokens, process_all=process_all, pwd=pwd
         )
 
-        if self.status_any_error():
+        if self.stop_process_tokens_before_do_it():
             return unparsed
 
         # add defines for this job type
@@ -176,8 +178,13 @@ class CommandSim(CommandDesign):
             )
 
             if check_logs and log_fname:
+                # Note this call will check on stdout if not GUI, not opening the log_fname,
+                # but if this is GUI we normally lose stdout and have to open the log.
+                gui_mode = self.args.get('gui', False)
+                file_contents_str = '' if gui_mode else stdout
                 self.check_logs_for_errors(
-                    filename='', file_contents_str=stdout,
+                    filename=os.path.join(self.args['work-dir'], log_fname),
+                    file_contents_str=file_contents_str,
                     bad_strings=bad_strings, must_strings=must_strings,
                     use_bad_strings=use_bad_strings, use_must_strings=use_must_strings
                 )
@@ -285,6 +292,9 @@ class CommandSim(CommandDesign):
         '''Returns None, checks logs using args bad_strings, must_strings,
 
         and internals self.args["log-[bad|must]-strings"] (lists).
+
+        file_contents_str will take precedence over opening filename, but filename is still
+        used in messaging.
         '''
 
         _bad_strings = bad_strings
@@ -304,13 +314,27 @@ class CommandSim(CommandDesign):
         hit_must_string_dict = dict.fromkeys(_must_strings)
 
         lines = []
-        fname = ''
+
+        log_fpath = ''
+        if os.path.exists(filename):
+            log_fpath = filename
+
         if file_contents_str:
             lines = file_contents_str.split('\n')
+            log_fname = log_fpath + '(STDOUT)'
+            util.debug(f'Checking log for errors: {log_fpath=} but checking from STDOUT string...')
         elif filename:
-            fname = os.path.join(self.args['work-dir'], filename)
-            with open(fname, 'r', encoding='utf-8') as f:
-                lines = f.readl.splitlines()
+            log_fname = log_fpath
+            util.debug(f'Checking log for errors: {log_fpath=} opening file...')
+            if not os.path.exists(log_fname):
+                self.error(f'sim.check_logs_for_errors: log {log_fpath} does not exist, cannot',
+                           'check it for errors or passing strings')
+                return
+            with open(log_fpath, 'r', encoding='utf-8') as f:
+                lines = f.read().splitlines()
+        else:
+            self.error(f'sim.check_logs_for_errors: {log_fpath=} does not exist, and no',
+                       'file_contents_str exists to check')
 
         if lines:
             for lineno, line in enumerate(lines):
@@ -320,13 +344,13 @@ class CommandSim(CommandDesign):
                             hit_must_string_dict[k] = True
                 if any(bad_str in line for bad_str in _bad_strings):
                     self.error(
-                        f"log {fname}:{lineno} contains one of {_bad_strings=}",
+                        f"log {log_fname}:{lineno} contains one of {_bad_strings=}",
                         error_code=status_constants.EDA_SIM_LOG_HAS_BAD_STRING
                     )
 
         if any(x is None for x in hit_must_string_dict.values()):
             self.error(
-                f"Didn't get all passing patterns in log {fname}: {_must_strings=}",
+                f"Didn't get all passing patterns in log {log_fname}: {_must_strings=}",
                 f" {hit_must_string_dict=}",
                 error_code=status_constants.EDA_SIM_LOG_MISSING_MUST_STRING
             )

opencos/commands/synth.py

@@ -64,7 +64,7 @@ class CommandSynth(CommandDesign):
             self, tokens=tokens, process_all=process_all, pwd=pwd
         )
 
-        if self.status_any_error():
+        if self.stop_process_tokens_before_do_it():
             return unparsed
 
         # add defines for this job type

opencos/commands/upload.py

@@ -25,6 +25,9 @@ class CommandUpload(Command):
         self.unparsed_args = Command.process_tokens(
             self, tokens=tokens, process_all=False, pwd=pwd
         )
+        if self.stop_process_tokens_before_do_it():
+            return []
+
         self.create_work_dir()
         self.do_it()
         return []

opencos/commands/waves.py

@@ -95,6 +95,7 @@ class CommandWaves(CommandDesign):
                     self.error(f"Was already given {wave_file=}, not sure what",
                                f"to do with {tokens[0]}")
                 wave_dirs.append(tokens[0])
+            self.warning_show_known_args()
             self.error(f"Didn't understand command arg/token: '{tokens[0]}'",
                        "in CommandWaves")
 

opencos/deps/defaults.py

@@ -46,6 +46,7 @@ SUPPORTED_DEP_KEYS_BY_TYPE = {
 
 SUPPORTED_TAG_KEYS = set([
     'with-tools',
+    'with-commands',
     'with-args',
     'args',
     'deps',

opencos/deps/deps_file.py

@@ -15,7 +15,8 @@ from opencos.deps.defaults import DEPS_FILE_EXTS, ROOT_TABLE_KEYS_NOT_TARGETS
 from opencos.util import debug, error
 from opencos.utils.markup_helpers import yaml_safe_load, toml_load_only_root_line_numbers, \
     markup_writer, markup_dumper
-from opencos.utils.str_helpers import fnmatch_or_re, dep_str2list
+from opencos.utils.str_helpers import fnmatch_or_re, dep_str2list, pretty_list_columns_manual, \
+    is_valid_target_name, VALID_TARGET_INFO_STR
 from opencos.utils.subprocess_helpers import subprocess_run_background
 from opencos.utils.status_constants import EDA_DEPS_FILE_NOT_FOUND, EDA_DEPS_TARGET_NOT_FOUND
 
@@ -24,7 +25,8 @@ def deps_data_get_all_targets(data: dict) -> list:
     '''Given extracted DEPS data (dict) get all the root level keys that aren't defaults'''
     if data is None:
         return []
-    return [x for x in data.keys() if x not in ROOT_TABLE_KEYS_NOT_TARGETS]
+    return [x for x in data.keys() if (x not in ROOT_TABLE_KEYS_NOT_TARGETS and
+                                       is_valid_target_name(x))]
 
 
 def get_deps_markup_file(base_path: str) -> str:
@@ -272,6 +274,19 @@ class DepsFile:
             self.get_approx_line_number_str(target)
         ])
 
+
+    def warning_show_available_targets(self) -> None:
+        '''call warning showing available targets (pretty column printed)'''
+        if not self.data or not self.rel_deps_file:
+            return
+        pretty_possible_targets = pretty_list_columns_manual(
+            data=deps_data_get_all_targets(self.data)
+        )
+        targets_str = "  " + "\n  ".join(pretty_possible_targets).strip()
+        util.warning((f'Targets available in deps_file={self.rel_deps_file}:\n'
+                      f'{targets_str}'))
+
+
     def lookup(self, target_node: str, caller_info: str) -> bool:
         '''Returns True if the target_node is in the DEPS markup file. If not, error with
 
@@ -284,6 +299,15 @@ class DepsFile:
             t_path = os.path.relpath(self.target_path) + os.path.sep
             t_node = target_node
             t_full = os.path.join(t_path, t_node)
+
+            if target_node.startswith('-'):
+                # likely an unparsed arg that made it this far.
+                util.warning(f"Ignoring unparsed argument '{target_node}'")
+                return False
+
+            if not is_valid_target_name(target_node):
+                util.warning(f"In file {self.rel_deps_file}, {target_node} {VALID_TARGET_INFO_STR}")
+
             if not caller_info:
                 # If we don't have caller_info, likely came from command line (or DEPS JSON data):
                 if '.' in target_node:
@@ -297,10 +321,11 @@ class DepsFile:
                                f'but path {t_path} has no DEPS markup file (DEPS.yml)',
                                error_code=EDA_DEPS_FILE_NOT_FOUND)
                 else:
+                    self.warning_show_available_targets()
                     self.error(f'Trying to resolve command-line target={t_full}:',
-                               f'was not found in deps_file={self.rel_deps_file},',
-                               f'possible targets in deps file = {list(self.data.keys())}',
+                               f'was not found in deps_file={self.rel_deps_file}',
                                error_code=EDA_DEPS_TARGET_NOT_FOUND)
+
             else:
                 # If we have caller_info, then this was a recursive call from another
                 # DEPS file. It should already have the useful error messaging:
@@ -318,6 +343,7 @@ class DepsFile:
                                f'but {t_path} has no DEPS markup file (DEPS.yml)',
                                error_code=EDA_DEPS_FILE_NOT_FOUND)
                 else:
+                    self.warning_show_available_targets()
                     self.error(f'Trying to resolve target={t_full}:',
                                f'called from {caller_info},',
                                f'Target not found in deps_file={self.rel_deps_file}',