labview-fpga-hdl-tools 2.0.0.dev4__tar.gz → 2.0.0.dev6__tar.gz

{labview_fpga_hdl_tools-2.0.0.dev4 → labview_fpga_hdl_tools-2.0.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: labview-fpga-hdl-tools
-Version: 2.0.0.dev4
+Version: 2.0.0.dev6
 Summary: LabVIEW FPGA HDL Tools
 License: MIT
 Author: Salvador Santolucito
@@ -39,6 +39,12 @@ run Vivado in the end — they differ in what compiles the bitfile:
   target (`gen-target` → `install-target`), then write a VI and let LabVIEW FPGA
   compile the bitfile (it runs Vivado under the hood).
 
+> **Host-side note:** to communicate with the compiled `.lvbitx` from a LabVIEW FPGA
+> host VI, open it with **Open Dynamic Bitfile Reference** (wire in the bitfile path and
+> a matching FPGA Interface Dynamic Refnum) — the standard **Open FPGA VI Reference**
+> node does **not** work with these custom targets. See
+> [Vivado Compile Flow → Opening the bitfile from a LabVIEW FPGA host VI](docs/VivadoCompileFlow.md#opening-the-bitfile-from-a-labview-fpga-host-vi).
+
 In short: in the **Vivado flow** you drive Vivado; in the **LabVIEW FPGA flow**
 LabVIEW FPGA drives Vivado for you. See
 [Theory of Operation](docs/TheoryOfOperation.md) for the full story.
@@ -48,9 +54,13 @@ LabVIEW FPGA drives Vivado for you. See
 | Doc | What's in it |
 | --- | --- |
 | [Theory of Operation](docs/TheoryOfOperation.md) | The architecture, the supported workflows, and how the pieces fit together. Start here. |
+| [Vivado Compile Flow](docs/VivadoCompileFlow.md) | End-to-end walkthrough: extend the HDL, generate a Vivado project, and compile a `.lvbitx` directly in Vivado. |
+| [LabVIEW FPGA Target and Compile Flow](docs/LabVIEWFpgaTargetFlow.md) | End-to-end walkthrough: build and install a custom LabVIEW FPGA target, then compile in LabVIEW FPGA. |
+| [ModelSim Simulation Flow](docs/ModelSimSimulationFlow.md) | End-to-end walkthrough: build the Xilinx sim libraries, create the ModelSim project, and run a testbench. |
 | [Command Reference](docs/CommandReference.md) | Every `nihdl` command, its options, the command flow, and per-command required settings. |
 | [Settings Reference](docs/SettingsReference.md) | The `nihdlsettings.py` model: hooks, context, `--set` overrides, and the full list of setters. |
 | [LVTargetCustomIO Reference](docs/LVTargetCustomIO-Reference.md) | The custom I/O CSV format used to define HDL ↔ LabVIEW FPGA signals. |
+| [Generated VHDL](docs/GeneratedVHDL.md) | What VHDL the tools generate (window wrappers, `PkgNiHdlSettings`) and why — single-sourcing the facts shared by the HDL and the LabVIEW FPGA target. |
 | [Window Netlist and Constraints](docs/WindowNetlistAndConstraints.md) | How the LabVIEW Window netlist is produced/consumed and how XDC constraints are processed for each compile flow (including the `current_instance` scoping rules). |
 
 ## Prerequisites
@@ -142,6 +152,8 @@ nihdl compile-vivado
 
 Open the project interactively at any point with `nihdl launch-vivado`.
 
+> **Full walkthrough:** [Vivado Compile Flow](docs/VivadoCompileFlow.md).
+
 ### The LabVIEW FPGA compile flow (custom target)
 
 To expose your HDL to LabVIEW FPGA as a custom target, define your I/O in the
@@ -151,23 +163,26 @@ To expose your HDL to LabVIEW FPGA as a custom target, define your I/O in the
 # Generate target support files (BoardIO/Clock XML, Window VHDL, plugin content)
 nihdl gen-target
 
-# Install the generated plugin into your LabVIEW FPGA install
+# Close ALL LabVIEW instances, then install the generated plugin into your LabVIEW FPGA install
 nihdl install-target
 ```
 
+> **Close LabVIEW around `install-target`.** Close all LabVIEW instances before running it, and
+> (re)start LabVIEW afterward — LabVIEW only scans for target plugins at startup.
+
+> **Full walkthrough:** [LabVIEW FPGA Target and Compile Flow](docs/LabVIEWFpgaTargetFlow.md).
+
 ### Simulating with ModelSim
 
 ```bash
-# Create the ModelSim project and compile all VHDL (vcom -autoorder -2008)
-# When XilinxSimLibFolder is configured, this also compiles the Xilinx
-# simulation libraries (unisim, secureip, ...) on the first run, which can
-# take several minutes. Run it standalone with: nihdl compile-modelsim-lib
-nihdl gen-modelsim
-
-# Launch the GUI, or run headless with --batch
-nihdl launch-modelsim
+# Create the ModelSim project and compile all VHDL, then run the testbench
+nihdl gen-modelsim --overwrite
+nihdl sim-modelsim        # or: nihdl launch-modelsim  (GUI; --batch for headless)
 ```
 
+> **Full walkthrough:** [ModelSim Simulation Flow](docs/ModelSimSimulationFlow.md)
+> — including the Xilinx simulation libraries and how the pass/fail verdict works.
+
 For the complete command list, options, and required settings, see the
 [Command Reference](docs/CommandReference.md).
 

{labview_fpga_hdl_tools-2.0.0.dev4 → labview_fpga_hdl_tools-2.0.0.dev6}/README.md

@@ -18,6 +18,12 @@ run Vivado in the end — they differ in what compiles the bitfile:
   target (`gen-target` → `install-target`), then write a VI and let LabVIEW FPGA
   compile the bitfile (it runs Vivado under the hood).
 
+> **Host-side note:** to communicate with the compiled `.lvbitx` from a LabVIEW FPGA
+> host VI, open it with **Open Dynamic Bitfile Reference** (wire in the bitfile path and
+> a matching FPGA Interface Dynamic Refnum) — the standard **Open FPGA VI Reference**
+> node does **not** work with these custom targets. See
+> [Vivado Compile Flow → Opening the bitfile from a LabVIEW FPGA host VI](docs/VivadoCompileFlow.md#opening-the-bitfile-from-a-labview-fpga-host-vi).
+
 In short: in the **Vivado flow** you drive Vivado; in the **LabVIEW FPGA flow**
 LabVIEW FPGA drives Vivado for you. See
 [Theory of Operation](docs/TheoryOfOperation.md) for the full story.
@@ -27,9 +33,13 @@ LabVIEW FPGA drives Vivado for you. See
 | Doc | What's in it |
 | --- | --- |
 | [Theory of Operation](docs/TheoryOfOperation.md) | The architecture, the supported workflows, and how the pieces fit together. Start here. |
+| [Vivado Compile Flow](docs/VivadoCompileFlow.md) | End-to-end walkthrough: extend the HDL, generate a Vivado project, and compile a `.lvbitx` directly in Vivado. |
+| [LabVIEW FPGA Target and Compile Flow](docs/LabVIEWFpgaTargetFlow.md) | End-to-end walkthrough: build and install a custom LabVIEW FPGA target, then compile in LabVIEW FPGA. |
+| [ModelSim Simulation Flow](docs/ModelSimSimulationFlow.md) | End-to-end walkthrough: build the Xilinx sim libraries, create the ModelSim project, and run a testbench. |
 | [Command Reference](docs/CommandReference.md) | Every `nihdl` command, its options, the command flow, and per-command required settings. |
 | [Settings Reference](docs/SettingsReference.md) | The `nihdlsettings.py` model: hooks, context, `--set` overrides, and the full list of setters. |
 | [LVTargetCustomIO Reference](docs/LVTargetCustomIO-Reference.md) | The custom I/O CSV format used to define HDL ↔ LabVIEW FPGA signals. |
+| [Generated VHDL](docs/GeneratedVHDL.md) | What VHDL the tools generate (window wrappers, `PkgNiHdlSettings`) and why — single-sourcing the facts shared by the HDL and the LabVIEW FPGA target. |
 | [Window Netlist and Constraints](docs/WindowNetlistAndConstraints.md) | How the LabVIEW Window netlist is produced/consumed and how XDC constraints are processed for each compile flow (including the `current_instance` scoping rules). |
 
 ## Prerequisites
@@ -121,6 +131,8 @@ nihdl compile-vivado
 
 Open the project interactively at any point with `nihdl launch-vivado`.
 
+> **Full walkthrough:** [Vivado Compile Flow](docs/VivadoCompileFlow.md).
+
 ### The LabVIEW FPGA compile flow (custom target)
 
 To expose your HDL to LabVIEW FPGA as a custom target, define your I/O in the
@@ -130,23 +142,26 @@ To expose your HDL to LabVIEW FPGA as a custom target, define your I/O in the
 # Generate target support files (BoardIO/Clock XML, Window VHDL, plugin content)
 nihdl gen-target
 
-# Install the generated plugin into your LabVIEW FPGA install
+# Close ALL LabVIEW instances, then install the generated plugin into your LabVIEW FPGA install
 nihdl install-target
 ```
 
+> **Close LabVIEW around `install-target`.** Close all LabVIEW instances before running it, and
+> (re)start LabVIEW afterward — LabVIEW only scans for target plugins at startup.
+
+> **Full walkthrough:** [LabVIEW FPGA Target and Compile Flow](docs/LabVIEWFpgaTargetFlow.md).
+
 ### Simulating with ModelSim
 
 ```bash
-# Create the ModelSim project and compile all VHDL (vcom -autoorder -2008)
-# When XilinxSimLibFolder is configured, this also compiles the Xilinx
-# simulation libraries (unisim, secureip, ...) on the first run, which can
-# take several minutes. Run it standalone with: nihdl compile-modelsim-lib
-nihdl gen-modelsim
-
-# Launch the GUI, or run headless with --batch
-nihdl launch-modelsim
+# Create the ModelSim project and compile all VHDL, then run the testbench
+nihdl gen-modelsim --overwrite
+nihdl sim-modelsim        # or: nihdl launch-modelsim  (GUI; --batch for headless)
 ```
 
+> **Full walkthrough:** [ModelSim Simulation Flow](docs/ModelSimSimulationFlow.md)
+> — including the Xilinx simulation libraries and how the pass/fail verdict works.
+
 For the complete command list, options, and required settings, see the
 [Command Reference](docs/CommandReference.md).
 

{labview_fpga_hdl_tools-2.0.0.dev4 → labview_fpga_hdl_tools-2.0.0.dev6}/labview_fpga_hdl_tools/install_labview_target_plugin.py

@@ -34,11 +34,20 @@ def _run_as_admin():
       privileges live and die with that child process. The elevated instance
       performs the install and then exits, so admin rights are never retained
       by any process after installation completes.
-    - The executable is always resolved to a fully-qualified path before being
-      handed to ShellExecuteW. Passing a bare program name (e.g. "nihdl") would
-      let Windows resolve it against the working directory / PATH in the
-      elevated context, allowing an attacker-planted binary to run as admin
+    - Re-launch through the current Python interpreter (``sys.executable``, an
+      absolute, trusted path) running the tool as a module (``-m
+      labview_fpga_hdl_tools``). We deliberately do NOT re-invoke ``sys.argv[0]``
+      (the console-script launcher, e.g. nihdl.exe): those launcher stubs are
+      resolved for the *current* user's environment (venv / pyenv shims) and do
+      not reliably re-bootstrap their interpreter under the elevated (admin)
+      account, so the elevated child would exit without doing any work. Passing
+      a bare program name (e.g. "nihdl") is likewise avoided because Windows
+      would resolve it against the working directory / PATH in the elevated
+      context, allowing an attacker-planted binary to run as admin
       (CWE-426/CWE-427, untrusted search path).
+    - The elevated child is launched with its working directory pinned to the
+      current working directory so it discovers the same ``nihdlsettings.py``
+      the user invoked against (config is resolved relative to the cwd).
     """
     import ctypes
     import subprocess
@@ -49,23 +58,21 @@ def _run_as_admin():
         reporter.detail("Admin elevation only supported on Windows")
         return
 
-    # Resolve the launcher to an absolute, trusted path. Never pass a bare
-    # program name to ShellExecuteW "runas".
-    launcher = os.path.abspath(sys.argv[0])
-    if launcher.lower().endswith(".exe") and os.path.isfile(launcher):
-        # pip-installed console entry point (e.g. nihdl.exe)
-        command = launcher
-        arguments = subprocess.list2cmdline(sys.argv[1:])
-    else:
-        # Running as a .py script under the current interpreter
-        command = os.path.abspath(sys.executable)
-        arguments = subprocess.list2cmdline([launcher, *sys.argv[1:]])
+    # Re-launch via the real interpreter running the package as a module. This
+    # is both trusted (absolute interpreter path, module named explicitly) and
+    # robust across launchers (venv exe, pyenv shim, editable install).
+    command = os.path.abspath(sys.executable)
+    arguments = subprocess.list2cmdline(["-m", "labview_fpga_hdl_tools", *sys.argv[1:]])
+
+    # Pin the elevated child's working directory to the current directory so it
+    # finds the same nihdlsettings.py the user invoked against.
+    working_dir = os.getcwd()
 
     reporter.detail("Requesting administrator privileges...")
 
     # Execute with elevation
     result = ctypes.windll.shell32.ShellExecuteW(  # type: ignore
-        None, "runas", command, arguments, None, 1
+        None, "runas", command, arguments, working_dir, 1
     )
 
     # Check if the elevation was successful
@@ -160,6 +167,14 @@ def install_lv_target_support(config=None):
 
     # If we need admin and don't have it, relaunch with elevated privileges
     if needs_admin and not _is_admin():
+        # Always-visible notice: the actual install runs in a separate elevated
+        # process (a UAC prompt will appear). Without this, the command appears
+        # to do nothing because the elevated child owns the success output.
+        reporter.success(
+            f"Installing '{config.lv_target_name}' to '{install_folder}' requires "
+            "administrator rights. Approve the Windows UAC prompt; the install "
+            "completes in a separate elevated window."
+        )
         _run_as_admin()
         return  # Exit current instance as the elevated instance will continue
 
@@ -200,6 +215,11 @@ def install_lv_target_support(config=None):
         reporter.success(
             f"Successfully installed LabVIEW Target '{config.lv_target_name}' to {install_folder}"
         )
+        reporter.success(
+            "Reminder: close ALL open LabVIEW instances before installing, and (re)start "
+            "LabVIEW afterward. LabVIEW FPGA only scans for target plugins at startup, so a "
+            "running instance will not see this newly installed or updated target."
+        )
 
     except PermissionError:
         reporter.error("Error: Permission denied. Administrator privileges are required.")

{labview_fpga_hdl_tools-2.0.0.dev4 → labview_fpga_hdl_tools-2.0.0.dev6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "labview-fpga-hdl-tools"
-version = "2.0.0.dev4"
+version = "2.0.0.dev6"
 description = "LabVIEW FPGA HDL Tools"
 authors = [
   "Salvador Santolucito <salvador.santolucito@gmail.com>"

{labview_fpga_hdl_tools-2.0.0.dev4 → labview_fpga_hdl_tools-2.0.0.dev6}/labview_fpga_hdl_tools/launch_modelsim.py

@@ -71,6 +71,10 @@ def launch_modelsim(batch=False, config=None):
         )
         return 1
 
+    if config.skip_modelsim:
+        reporter.success("SKIP MODELSIM: Validation successful, skipping ModelSim launch")
+        return 0
+
     vsim_exe = _get_vsim_executable(config.modelsim_tools_folder)
     if not vsim_exe or not os.path.exists(vsim_exe):
         reporter.error(f"Error: vsim executable not found at {vsim_exe}")
@@ -80,10 +84,6 @@ def launch_modelsim(batch=False, config=None):
     reporter.detail(f"Do file: {do_file}")
     reporter.detail(f"Working directory: {project_dir}")
 
-    if config.skip_modelsim:
-        reporter.success("SKIP MODELSIM: Validation successful, skipping ModelSim launch")
-        return 0
-
     if batch:
         # Batch mode: run vsim -c -do <script> and wait for completion
         cmd = [vsim_exe, "-c", "-do", do_file]

{labview_fpga_hdl_tools-2.0.0.dev4 → labview_fpga_hdl_tools-2.0.0.dev6}/labview_fpga_hdl_tools/sim_modelsim.py

@@ -90,6 +90,10 @@ def sim_modelsim(do_file=None, config=None):
             )
             return 1
 
+    if config.skip_modelsim:
+        reporter.success("SKIP MODELSIM: Validation successful, skipping simulation")
+        return 0
+
     vsim_exe = _get_vsim_executable(config.modelsim_tools_folder)
     if not vsim_exe or not os.path.exists(vsim_exe):
         reporter.error(f"Error: vsim executable not found at {vsim_exe}")
@@ -101,10 +105,6 @@ def sim_modelsim(do_file=None, config=None):
     reporter.detail(f"  Working dir:  {project_dir}")
     reporter.detail(f"  Top entity:   {entity_name}")
 
-    if config.skip_modelsim:
-        reporter.success("SKIP MODELSIM: Validation successful, skipping simulation")
-        return 0
-
     # Build command: vsim in batch/command-line mode. Force the project
     # modelsim.ini so unisim/Xilinx library mappings are honored; an external
     # MODELSIM env var would otherwise override the local .ini.