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

opencos/deps/deps_processor.py

@@ -5,15 +5,17 @@ CommandDesign ref object
 '''
 
 import argparse
+import copy
 import os
 
 from opencos import files
 from opencos import eda_config
-from opencos.util import debug, info, warning, error, read_tokens_from_dot_f, \
+from opencos.util import Colors, debug, info, warning, error, read_tokens_from_dot_f, \
     patch_args_for_dir, load_env_file
 from opencos.utils.str_helpers import dep_str2list
 from opencos.deps.deps_file import deps_target_get_deps_list
 from opencos.deps.deps_commands import deps_commands_handler
+from opencos.utils.dict_helpers import dict_diff
 
 from opencos.deps.defaults import SUPPORTED_TARGET_TABLE_KEYS, SUPPORTED_TAG_KEYS, \
     SUPPORTED_DEP_KEYS_BY_TYPE
@@ -53,6 +55,14 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
         self.deps_dir, _ = os.path.split(deps_file)
         self.caller_info = caller_info
 
+        # Check if it's a Command instead of CommandDesign:
+        self.is_command_design = bool(
+            getattr(command_design_ref, 'process_plusarg', None) and \
+            getattr(command_design_ref, 'set_parameter', None) and \
+            isinstance(getattr(command_design_ref, 'incdirs', None), list)
+        )
+
+
         assert isinstance(deps_entry, dict), \
             f'{deps_entry=} for {target_node=} in {deps_file=} must be a dict'
         assert command_design_ref is not None, \
@@ -79,6 +89,8 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
 
     def apply_defines(self, defines_dict: dict) -> None:
         '''Given defines_dict, applies them to our self.command_design_ref obj'''
+        if not self.is_command_design:
+            return
         if not isinstance(defines_dict, dict):
             self.error(f"{defines_dict=} is not type dict, can't apply defines,",
                        f"in {self.caller_info}")
@@ -97,6 +109,8 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
 
     def apply_plusargs(self, plusargs_dict: dict) -> None:
         '''Given plusarsg_dict, applies them to our self.command_design_ref obj'''
+        if not self.is_command_design:
+            return
         if not isinstance(plusargs_dict, dict):
             self.error(f"{plusargs_dict=} is not type dict, can't apply plusargs,",
                        f"in {self.caller_info}")
@@ -109,6 +123,8 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
 
     def apply_parameters(self, parameters_dict: dict) -> None:
         '''Given parameters_dict, applies them to our self.command_design_ref obj'''
+        if not self.is_command_design:
+            return
         if not isinstance(parameters_dict, dict):
             self.error(f"{parameters_dict=} is not type dict, can't apply defines,",
                        f"in {self.caller_info}")
@@ -124,6 +140,8 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
 
     def apply_incdirs(self, incdirs_list:list) -> None:
         '''Given incdirs_list, applies them to our self.command_design_ref obj'''
+        if not self.is_command_design:
+            return
         if not isinstance(incdirs_list, (str, list)):
             self.error(f"{incdirs_list=} is not type str/list, can't apply incdirs",
                        f"in {self.caller_info}")
@@ -135,38 +153,59 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
                 debug(f'Added include dir {abspath} from {self.caller_info}')
 
 
-    def _apply_args_check_tools(self, tokens: list) -> list:
-        '''Helper for apply_args(list), returns list strips --tool args under certain conditions'''
+    def _apply_args_check_tools(self, tokens: list, tagname: str) -> list:
+        '''Helper for apply_args(list), returns list strips --tool args under certain conditions
+
+        Basically, we want to see if a DEPS target want to set arg --tool, if so:
+        Accept it:
+          - this is not a tool class
+          - tool was automatically chosen by eda.py's auto-tool-order (--tool not set at
+             CLI)
+          - accepting means set self.args['tool'], so we can respawn with this.
+        Reject/Warn if:
+          - previous tool was not automatically applied (--tool was set at CLI)
+            and you're trying to change the --tool value.
+          - This can happen if you have complicated DEPS targets trying to set the
+            tool to different values.
+        '''
 
+        parser = argparse.ArgumentParser(
+            prog='deps_processor --tool', add_help=False, allow_abbrev=False
+        )
+        parser.add_argument('--tool', default='')
+        try:
+            parsed, unparsed = parser.parse_known_args(tokens + [''])
+            tokens2 = list(filter(None, unparsed))
+        except argparse.ArgumentError:
+            error('deps_processor --tool problem attempting to parse_known_args for:',
+                  f'{tokens}, {self.caller_info} {tagname}')
+            tokens2 = tokens
+
+        _tool_class = 'tool' in self.args
         _orig_tool = self.args.get('tool', '')
-        if not self.command_design_ref.auto_tool_applied and \
-           any(x.startswith('--tool') for x in tokens) and _orig_tool:
-            warn_tool = ''
-            for i, item in enumerate(list(tokens)):
-                if item == '--tool':
-                    if tokens[i + 1] != _orig_tool:
-                        warn_tool = tokens[i + 1]
-                    tokens[i : i+2] = ['', ''] # remove this and next arg
-                elif item.startswith('--tool='):
-                    if item[7:] != _orig_tool:
-                        warn_tool = item
-                    tokens[i] = '' # remove just this arg.
-
-            if warn_tool:
-                warning(
-                    f'Attempting to set --tool {warn_tool} from DEPS',
-                    f'(file={self.deps_file}:{self.target_node})',
-                    f'however the tool was already chosen as: {_orig_tool}. The --tool arg will',
-                    f'not be applied from: {tokens}'
-                )
 
-            tokens = [item for item in tokens if item != ''] # remove blanks
+        if not self.command_design_ref.auto_tool_applied and \
+           _tool_class and parsed.tool and _orig_tool \
+           and parsed.tool != _orig_tool:
+            # tool arg present, --tool in this DEPS args, and tool already set.
+            warning(
+                f'Attempting to set --tool {parsed.tool} from DEPS',
+                f'(file={self.deps_file}:{self.target_node})',
+                f'however the tool was already chosen as: {_orig_tool}. The --tool arg will',
+                f'not be applied from: {tokens}'
+            )
+        elif (self.command_design_ref.auto_tool_applied or not _tool_class) and parsed.tool:
+            # tool arg wasn't present (not a Tool class), or it was auto-applied,
+            # then add the arg anyway so we can later respawn with the correct tool.
+            self.args['tool'] = parsed.tool
+            debug(f'setting arg.tool to {parsed.tool=} from {self.caller_info}')
 
-        return tokens
+        # remove blanks, '--tool[=value| value]' removed.
+        return [item for item in tokens2 if item != '']
 
 
-    def apply_args( # pylint: disable=too-many-locals,too-many-branches
-            self, args_list:list
+    def apply_args( # pylint: disable=too-many-locals,too-many-branches,too-many-statements
+            self, args_list:list, tagname: str = ''
     ) -> list:
         '''Given args_list, applies them to our self.command_design_ref obj
 
@@ -174,9 +213,15 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
         unparsed args will show up as eda.py warnings, but will not fail. Most callers do not
         use the unparsed args from this method.
         '''
+        if tagname:
+            tagname = f'{tagname=}'
+
         if not isinstance(args_list, (str, list)):
             self.error(f"{args_list=} is not type str/list, can't apply args",
-                       f"in {self.caller_info}")
+                       f"in {self.caller_info} {tagname}")
+
+        prev_args = copy.deepcopy(self.args)
+
         tokens = dep_str2list(args_list)
 
         # patch args relative to the DEPS (if self.deps_dir exists) so things like
@@ -211,7 +256,7 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
             tokens2 = list(filter(None, unparsed))
         except argparse.ArgumentError:
             error('deps_processor -f/--input-file, problem attempting to parse_known_args for:',
-                  f'{tokens}')
+                  f'{tokens}, {self.caller_info} {tagname}')
             tokens2 = tokens
 
         if parsed.input_file:
@@ -242,13 +287,12 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
         # the user may think they were allowed to set --tool, but in our flow the Command handler
         # (self.command_design_ref) has already been chosen, so setting the tool can have
         # strange side-effects.
+        _tool_class = 'tool' in self.args
         _orig_tool = self.args.get('tool', '')
-        tokens = self._apply_args_check_tools(tokens=tokens)
-        if not tokens:
-            return []
+        tokens = self._apply_args_check_tools(tokens=tokens, tagname=tagname)
 
         debug(f'deps_processor - custom apply_args with {tokens=}',
-              f'from {self.caller_info}')
+              f'from {self.caller_info} {tagname}')
         _, unparsed = self.command_design_ref.run_argparser_on_list(
             tokens=tokens
         )
@@ -256,7 +300,7 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
         # Annoying, but check for plusargs in unparsed, and have referenced CommandDesign
         # or CommandSim class handle it with process_plusarg.
         for arg in list(unparsed):
-            if arg.startswith('+'):
+            if arg.startswith('+') and self.is_command_design:
                 self.command_design_ref.process_plusarg(plusarg=arg, pwd=self.target_path)
                 unparsed.remove(arg)
 
@@ -264,10 +308,7 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
         for arg in list(unparsed):
             # Since this isn't command line, we have to assume for files, the path is relative
             # to this DEPS file.
-            if os.path.isabs(arg):
-                target = arg
-            else:
-                target = os.path.join(self.deps_dir, arg)
+            target = self.correct_a_deps_target(target=arg, deps_dir=self.deps_dir)
 
             file_exists, fpath, forced_extension = files.get_source_file(target)
             if file_exists:
@@ -279,6 +320,7 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
 
             else:
                 if not os.path.isdir(target) and \
+                   self.is_command_design and \
                    self.command_design_ref.resolve_target_core(
                        target=target, no_recursion=False, caller_info=self.caller_info,
                        error_on_not_found=False
@@ -293,7 +335,10 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
             warning(f'For {self.command_design_ref.command_name}:' \
                     + f' in {self.caller_info} has unknown args {unparsed=}')
 
-        if self.command_design_ref.auto_tool_applied and _orig_tool != self.args.get('tool', ''):
+        if (self.command_design_ref.auto_tool_applied or not _tool_class) and \
+            _orig_tool != self.args.get('tool', ''):
+            # If there was an auto tool applied (tool class or not) then attempt to pick
+            # a new sub-command-object with that tool.
             debug(f'deps_processor.apply_args: tool changed, {self.args["tool"]=}, will attempt',
                   f'to respawn the job using original args: {self.config["eda_original_args"]}')
             self.command_design_ref.tool_changed_respawn = {
@@ -302,6 +347,12 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
                 'from': self.caller_info,
             }
 
+        diff_args = dict_diff(prev_args, self.args)
+        if diff_args:
+            args_list = [item for item in args_list if item != ''] # remove blanks
+            info(f'{Colors.yellow}{self.caller_info} {tagname}{Colors.green}:',
+                 f'applying args for {args_list}: {Colors.cyan}{diff_args}')
+
         return unparsed
 
     def apply_reqs(self, reqs_list:list) -> None:
@@ -551,9 +602,9 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
                                     ' skipped args due to args disabled.')
                         if args_list:
                             # This will apply knowns args to the target dep:
-                            info(f'{tagname=} in {self.caller_info=}:',
+                            debug(f'{tagname=} in {self.caller_info=}:',
                                  f'applying args for {args_list=}')
-                            self.apply_args(args_list)
+                            self.apply_args(args_list, tagname=tagname)
 
                     elif key == 'reqs':
                         reqs_list = deps_target_get_deps_list(entry=value,
@@ -578,11 +629,16 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
                 # apply replace-config-tools
                 # This will replace lists (compile-waivers).
                 tool_config = value.get('replace-config-tools', {}).get(tool, None)
-                if tool_config and not deps_tags_enables.get('replace-config-tools', None):
+                ref_has_tool_config = isinstance(
+                    getattr(self.command_design_ref, 'tool_config', None), dict
+                )
+                if tool_config and (not deps_tags_enables.get('replace-config-tools', None) or \
+                                    not ref_has_tool_config):
                     tool_config = None
                     warning(f'{tagname=} in {self.caller_info}:',
-                            ' skipped replace-config-tools b/c it is disabled.')
-                if tool_config and isinstance(tool_config, dict):
+                            'skipped replace-config-tools b/c it is disabled or not present for',
+                            'this tool and command')
+                if ref_has_tool_config and tool_config and isinstance(tool_config, dict):
                     # apply it to self.tool_config:
                     info(f'{tagname=} in {self.caller_info}:',
                          f'applying replace-config-tools for {tool=}: {tool_config}')
@@ -595,11 +651,13 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
                 # apply additive-config-tools
                 # This will append to lists (compile-waivers)
                 tool_config = value.get('additive-config-tools', {}).get(tool, None)
-                if tool_config and not deps_tags_enables.get('additive-config-tools', None):
+                if tool_config and (not deps_tags_enables.get('additive-config-tools', None) or \
+                                    not ref_has_tool_config):
                     tool_config = None
                     warning(f'{tagname=} in {self.caller_info}:',
-                            ' skipped additive-config-tools b/c it is disabled.')
-                if tool_config and isinstance(tool_config, dict):
+                            ' skipped additive-config-tools b/c it is disable or not present for',
+                            'this tool and command')
+                if ref_has_tool_config and tool_config and isinstance(tool_config, dict):
                     # apply it to self.tool_config:
                     info(f'{tagname=} in {self.caller_info}:',
                          f'applying additive-config-tools for {tool=}: {tool_config}')
@@ -774,6 +832,12 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
 
         shell_commands_list, work_dir_add_srcs_list = self.get_commands(commands=commands, dep=dep)
 
+        if shell_commands_list and \
+           not self.is_command_design:
+            warning(f'Not applying shell commands from {self.caller_info}, not supported',
+                    'for this tool and command')
+            return
+
         # add these commands lists to self.command_design_ref:
         # Process all shell_commands_list:
         # This will track each shell command with its target_node and target_path
@@ -850,7 +914,8 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
 
 
             elif isinstance(dep, str) and \
-                 any(dep.startswith(x) for x in ['+define+', '+incdir+']):
+                 any(dep.startswith(x) for x in ['+define+', '+incdir+']) and \
+                 self.is_command_design:
                 # Note: we still support +define+ and +incdir in the deps list.
                 # check for compile-time Verilog style plusarg, which are supported under targets
                 # These are not run-time Verilog style plusargs comsumable from within the .sv:
@@ -860,10 +925,11 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
             else:
                 # If we made it this far, dep better be a str type.
                 assert isinstance(dep, str), f'{dep=} {type(dep)=} must be str'
-                dep_path = os.path.join(self.target_path, dep)
+                dep_path = self.correct_a_deps_target(target=dep, deps_dir=self.target_path)
                 debug(f"Got dep {dep_path=} for in {self.caller_info}")
 
-                if dep_path in self.command_design_ref.targets_dict or \
+                if self.is_command_design and \
+                   dep_path in self.command_design_ref.targets_dict or \
                    dep_path in deps_targets_to_resolve:
                     debug(" - already processed, skipping")
                 else:
@@ -888,3 +954,16 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
         #    dep3: 'command_tuple',
         #  }
         return deps_targets_to_resolve
+
+
+    def correct_a_deps_target(self, target: str, deps_dir: str) -> str:
+        '''Give a target/file in a deps: list, return a patched version
+
+        - $VAR replacment
+        - relative to current DEPS file dir (or not if it was abspath)
+        '''
+        if self.config['deps_expandvars_enable']:
+            target = os.path.expandvars(target)
+        if not os.path.isabs(target):
+            target = os.path.join(deps_dir, target)
+        return target

opencos/docs/Architecture.md

@@ -0,0 +1,45 @@
+# Architecture
+
+Looking at it roughly bottom up.
+
+## oc_user.sv
+
+A "userspace" app is loaded, via pointing a build to a DEPS target that pulls in an oc_user.sv.
+
+There is an associated oc_user.vh which contains:
+- `defines which configure the internals of the user-space app, and can be whatever is required by the application. They don't need OC_* prefixes, etc
+- `defines which configure the interface to the operating system, and are defined by OpenCOS.  These OC_USER_* defines configure the ports of oc_user and it's instantiation in oc_cos.
+
+Userspace apps which "ship" with OpenCOS are in the <oc>/user directory, but they can be located anywhere (TBD: document how that is done)
+
+TODO: define a userspace testbench.  The OC_COS and above levels are implemented behaviorally for flexible testing at the userspace API level.
+
+## oc_cos.sv
+
+The "operating system", which instantiates the userspace app, as well as a collection of top level modules.  It is stores in <oc>/top
+
+oc_cos configures itself via two sets of defines:
+- OC_COS_* defines which enable services from the operating system.  For example the userspace could request that ethernet bridging is enabled between 4 external and 4 userspace ports, instead of direct connection.  The board may setup features such as fan and LED controls.  Meanwhile the integrator may enable things like bitstream licensing.
+- OC_BOARD_* defines which are set by the board target DEPS, and configure the ports of oc_cos.  The goal is for OC_BOARD defines to setup the defaults for the parameters of oc_cos, not for them to be used repeatedly internally.  Some things cannot be done that way (for example setting module names).
+
+Testing is performed via <oc>/top/tests/oc_cos_*test targets, which should aim to instantiate as much as possible, while testing the subset that the testbench knows how to test.  Practically speaking, the kinds of tests run at this level should consider not duplicating the tests that operate at the next stage up (board level).
+
+TODO: do we require board target to use DEPS?  what if they just want to have defines in a file, how do we ensure it's read before oc_cos (we could add a way for oc_cos to pull in a header file)
+
+## oc_chip_top.sv
+
+This is the typical (but not mandatory) name of the top level for a given target.  This is stored in a <oc>/boards/<board> directory.
+
+The concept of oc_chip_top is like a "board support package" for an operating system, the thin shim that connects the shared code with the unique target.  It likely instantiates I/O buffers, maybe connects some pins that are unique to the board (things to do with bringup sequence, custom thermal solutions, etc).  Basically, anything that OC_COS cannot handle, needs to be put up here.
+
+It's entirely optional for oc_chip_top to configure oc_cos via parameter.  oc_cos will setup it's ports based on OC_BOARD defines, and overriding the parameters so they don't match the defaults could result in inconsistent state if the design looks at the OC_BOARD defines again.  oc_chip_top
+
+TODO: work on the naming.  it's called a target, a board, oc_chip_top, etc, and it's confusing.
+
+## oc_chip_harness.sv
+
+The purpose of oc_chip_harness is to "reverse" the transformation between oc_cos ports (ledOut[1:0], pciRxP[15:0], etc) and oc_chip_top ports (LED_GREEN, LED_RED, PCI_RXP_15, PCI_RXP_14, etc).  It terminates any custom interface coming out of oc_chip_top in a way that makes sense.  Upwards, it shows ports that look like oc_cos.  In this way, oc_cos tests (including those that test userspace apps) can be run on oc_chip_top (i.e. including all board customizations).
+
+The upward facing ports need to match the upward facing oc_cos ports.  This can be done "with care", or can be done by examining OC_BOARD_* defines and setting up params and ports to match.
+
+oc_chip_harness does not accept params, and oc_cos_test runs in a mode where it doesn't push params.  Instead it is expected that OC_BOARD_* defines from the board DEPS will configure oc_cos (definitely) and oc_chip_top/oc_chip_harness (optionally).

opencos/docs/ConnectingApps.md

@@ -0,0 +1,29 @@
+# Connecting Apps
+
+The API between oc_top and oc_user is perhaps the area where OpenCOS diverges the most from the OS/Userspace parallel in the software world. 
+
+Similarities:
+- In both cases, we desire to give a stable API to our userspace apps.  Existing APIs should not change.
+- As new APIs are made available, they shouldn't break existing applications.
+Differences:
+- The OS can add new APIs and expose them to userspace, without significant cost, and without changes to userspace.  In hardware, connectivity between OS and userspace is in the form of physical wires that must be connected.
+
+Furthermore, module ports (and connections to instance ports) cannot be made dependent on parameters.  Either all ports are always there, or they must be made conditional on `defines.  
+
+We desire to not burden userspace with unnecessary complexity.  For example, if it does not require networking, it shouldn't have to declare network ports. 
+
+We desire that the userspace can be flexible.  For example, if it is a memory tester, it would be nice if it could scale the number, width, and type of interfaces (for example, connecting to four 512-bit AXI-3 interfaces, or thirty-two 256-bit AXI-4 interfaces).  
+
+We desire that the top level (`oc_top`) only contains logic required to meet user-space requests.  We don't "build everything in" and then just connect what we need. 
+
+The following methodology is used: 
+
+- Userspace declares via a header (`oc_user_defines.vh`) what types of interfaces it can connect to.
+    - This includes a class (local memory), an interface type (AXI-4), a width (512-bit), and a count (4)
+    - This file is not expected to be edited by the integrator.  But it may note defines that can be set in `oc_board_defines.vh` to configure functionality within the userspace app.  
+- The board comes with a header file that (`oc_board_defines.vh`) that the integrator edits to constrain which external interfaces are connected.  This file will also set the defines which activate `oc_top` ports connecting out to the chip interfaces.  It can also hint to `oc_top` about internal features to enable, when they can't be inferred just from the interfaces (for example, a define could enable Ethernet switching functionality between external network interfaces and userspace)
+- The board-specific `oc_chip_top` will take the `oc_board_defines.vh` and drive parameters into `oc_top`
+    - do we need this?
+- `oc_top` will read `oc_board_defines.vh` to enable ports out to chip interfaces. 
+- `oc_top` will read `oc_user_defines.vh` to know what interfaces must be connected to userspace.
+- `oc_top` will infer what internal functions are needed based on board and user defines.  

opencos/docs/DEPS.md

@@ -0,0 +1,199 @@
+# DEPS.yml schema:
+
+(Note this information, DEPS.md, is also available via: eda deps-help --verbose)
+
+```
+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)
+
+  plusargs: # <table>
+    variable0: value
+    variable1:              # blank for no value, or use nil (yaml's None)
+
+  parameters: # <table>
+    SomeParameter: value
+    SOME_OTHER_PARAMETER: value
+
+  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@, sdc@, f@, py@, makefile@
+    - 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 it.
+        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).
+        run-after-tool: # <bool> default false. Set to true to run after any EDA tools, or
+	                # any command handlers have completed.
+      - 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.
+    args: # <array or | space separated string>
+    defines: ## <table>
+    plusargs: ## <table>
+    parameters: ## <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>
+      plusargs: <table, applied with tag>
+      parameters: <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)
+
+```
+
+## Examples
+
+### Target with tag-mode:
+
+```
+target-foo-with-tags:
+   deps: some_file1.sv some_file2.sv
+   tags:
+
+     # This can be invoked with eda --tool=vivado --gui
+     xilinx_mode:
+       with-args:
+         gui: true
+       with-tools: vivado
+       deps: <some_deps_for_this_fpga>
+       defines:
+         XILINX_GUI_MODE: 1
+
+     defaults:
+       deps: some_dummy_dep_not_fpga
+
+```
+
+
+### Simple Target, with deps as an explicit list
+
+This is the basic, common format for a target. target - deps - (array of files or other relative targets). The file order is compile order, top to bottom.
+
+```
+some-target:
+  deps:
+    - ../foo/some_prev_target
+    - some_other_target
+    - some_file.sv
+```
+
+### Simple Target, with deps as a string with \n separators
+
+This is more terse variant ` deps: |` followed by a string of targets and source files.
+
+```
+some-target2:
+  deps: |
+    ../bar/some_prev_target2
+    some_file2.sv
+    some_other_target2
+```
+
+### Simple Target, non-table (strings)
+
+The most terse variant for a target is a array or \n separated string, not a table, with no `deps` key, then it is assumed that all entries are other targets or sources.
+
+```
+some-target3: |
+  ../bar/some_prev_target3
+  some_file3.sv
+  some_other_target3
+```
+
+You could also explicitly make a list without a `deps` key:
+```
+## target entry is an explicit list
+some-target4:
+  - ../bar/some_prev_target4
+  - some_file4.sv
+  - some_other_target4
+```
+
+You can also have space separated in a string:
+```
+some-target5: ../bar/some_prev_target5  some_file5.sv
+```
+
+### Defines with relative path
+
+Defines with file path information relative to a DEPS.yml file are supported with special words `%PWD%` as a replacement for ./ in defines only. This is necessary because we do not do path substituion on defines.
+
+Example:
+
+```
+my_define_target:
+  deps:
+    - my_dut.sv
+    - my_testbench.sv
+  defines:
+    SOME_FILE: >
+      "%PWD%/my_pcap.pcap"
+```