maestro-tool 0.1.0__py3-none-any.whl

maestro/assets/containers/yocto.def

@@ -0,0 +1,128 @@
+# SPDX-FileCopyrightText: 2026 Maestro authors and contributors
+# SPDX-FileContributor: Cedric Hirschi <cedr02@live.com>
+# SPDX-FileContributor: Tim Frey <timfreyb@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+Bootstrap: docker
+From: ubuntu:24.04
+
+%post
+    set -eux
+
+    # Remove default ubuntu user created by Ubuntu 24.04 base image
+    touch /var/mail/ubuntu && chown ubuntu /var/mail/ubuntu && userdel -r ubuntu || true
+
+    export DEBIAN_FRONTEND=noninteractive
+
+    # Use bash as /bin/sh (required by Yocto)
+    echo "dash dash/sh boolean false" | debconf-set-selections
+    dpkg-reconfigure dash
+
+    # libtinfo5 is needed by Xilinx tools but not available in Ubuntu 24.04 repos
+    # Add Ubuntu 22.04 (jammy) universe repo
+    cat >/etc/apt/sources.list.d/jammy-universe.list <<'EOF'
+deb [arch=amd64] http://archive.ubuntu.com/ubuntu jammy universe
+deb [arch=amd64] http://security.ubuntu.com/ubuntu jammy-security universe
+deb [arch=amd64] http://archive.ubuntu.com/ubuntu jammy-updates universe
+EOF
+
+    # Pin libtinfo5 to jammy version
+    cat >/etc/apt/preferences.d/pin-jammy-libtinfo5 <<'EOF'
+Package: *
+Pin: release n=jammy
+Pin-Priority: -10
+
+Package: libtinfo5
+Pin: release n=jammy
+Pin-Priority: 990
+EOF
+
+    apt-get update && apt-get install -y \
+        locales-all \
+        locales \
+        tofrodos \
+        iproute2 \
+        gawk \
+        xvfb \
+        git \
+        make \
+        net-tools \
+        libncurses5-dev \
+        update-inetd \
+        tftpd-hpa \
+        zlib1g-dev \
+        libssl-dev \
+        flex \
+        bison \
+        libselinux1 \
+        gnupg \
+        wget \
+        diffstat \
+        chrpath \
+        socat \
+        xterm \
+        autoconf \
+        libtool \
+        libtool-bin \
+        unzip \
+        texinfo \
+        gcc-multilib \
+        build-essential \
+        libsdl1.2-dev \
+        libglib2.0-dev \
+        screen \
+        pax \
+        gzip \
+        python3-gi \
+        less \
+        lsb-release \
+        fakeroot \
+        libgtk2.0-0 \
+        libgtk2.0-dev \
+        cpio \
+        rsync \
+        xorg \
+        expect \
+        dos2unix \
+        bc \
+        zlib1g \
+        libusb-dev
+
+    wget http://archive.ubuntu.com/ubuntu/pool/main/t/tar/tar_1.34+dfsg-1build3_amd64.deb \
+        && dpkg -i tar_1.34+dfsg-1build3_amd64.deb \
+        && apt-mark hold tar \
+        && rm tar_1.34+dfsg-1build3_amd64.deb
+
+    apt-get install -y \
+        google-perftools \
+        default-jre
+
+    apt-get install -y \
+        gawk wget git diffstat unzip texinfo \
+        gcc build-essential chrpath socat cpio \
+        python3 python3-pip python3-pexpect xz-utils \
+        debianutils iputils-ping python3-git python3-jinja2 \
+        libegl1-mesa-dev libsdl1.2-dev xterm python3-subunit \
+        mesa-common-dev zstd liblz4-tool lz4 \
+        repo
+
+    apt-get install -y --no-install-recommends libtinfo5
+
+    # Set locale
+    env LANG=en_US.UTF-8 locale-gen --purge en_US.UTF-8
+    echo -e 'LANG="en_US.UTF-8"\nLANGUAGE="en_US:en"\n' > /etc/default/locale
+
+    apt-get clean
+
+%environment
+    export LANG=en_US.UTF-8
+    export LANGUAGE=en_US:en
+    export LC_ALL=en_US.UTF-8
+
+%labels
+    Description Yocto 5.0 / Xilinx 2025.2 build environment
+
+%help
+    Yocto build environment for Xilinx ZynqMP targets.
+    Use run_apptainer.sh to launch an interactive shell with the correct bind mounts.

maestro/assets/tcl/jtag_axi.tcl

@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: 2026 Maestro authors and contributors
+# SPDX-FileContributor: Cedric Hirschi <cedr02@live.com>
+# SPDX-FileContributor: Tim Frey <timfreyb@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# JTAG AXI batch. tclargs: <device> <hw_axi> <read|write> <addr_hex> ...
+#   read  <addr>
+#   write <addr> <data>
+# Prints "AXI_READ <hex>" after each read.
+# On a transaction error whose text contains "failed" or "timeout", exits with an error.
+
+set device [lindex $argv 0]
+if {$device eq ""} { set device xck26_0 }
+
+set hw_axi_name [lindex $argv 1]
+if {$hw_axi_name eq ""} { set hw_axi_name hw_axi_1}
+
+open_hw_manager
+connect_hw_server
+open_hw_target
+
+current_hw_device [get_hw_devices $device]
+refresh_hw_device [lindex [get_hw_devices $device] 0]
+
+set hw_axi [get_hw_axis $hw_axi_name]
+reset_hw_axi $hw_axi
+
+set i 2
+set n 0
+set order {}
+
+while {$i < [llength $argv]} {
+    set op [string tolower [lindex $argv $i]]
+    incr i
+    set addr [format %08x [scan [lindex $argv $i] %x]]
+    incr i
+
+    set name t$n
+    incr n
+
+    if {$op eq "read"} {
+        create_hw_axi_txn $name $hw_axi -type read -address $addr
+    } elseif {$op eq "write"} {
+        set data [lindex $argv $i]
+        incr i
+        create_hw_axi_txn $name $hw_axi -type write -address $addr -data $data
+    } else {
+        error "expected read or write, got: $op"
+    }
+    lappend order $name
+}
+
+foreach name $order {
+    set txn [get_hw_axi_txns $name]
+    if {[catch {run_hw_axi $txn} msg]} {
+        set detail "$msg\n$::errorInfo"
+        catch {close_hw_target}
+        # An unclocked or unreleased port shows up as "failed" or "timeout".
+        if {[string match -nocase *failed* $detail]
+            || [string match -nocase *timeout* $detail]} {
+            set addr ""
+            catch {set addr [get_property ADDRESS $txn]}
+            error "AXI transaction at $addr failed: clock or reset may not be configured correctly"
+        }
+        error $msg
+    }
+    if {[string tolower [get_property TYPE $txn]] eq "read"} {
+        puts "AXI_READ [get_property DATA $txn]"
+    }
+}
+
+close_hw_target

maestro/assets/tcl/package_verilog_ip.tcl

@@ -0,0 +1,151 @@
+# SPDX-FileCopyrightText: 2026 Maestro authors and contributors
+# SPDX-FileContributor: Cedric Hirschi <cedr02@live.com>
+# SPDX-FileContributor: Tim Frey <timfreyb@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Package a Verilog/SystemVerilog top as a Vivado user IP (component.xml + xgui).
+#
+# Uses the built-in ipx:: packager (UG1118). Bus interfaces are inferred from
+# (* X_INTERFACE_INFO = "..." *) attributes on the top module ports.
+#
+# Tclargs (fixed order, then one path per RTL file):
+#   <ip_name> <top_module> <ip_out_dir> <work_dir> <vendor> <library> <version> \
+#     <part> <ip_repo_paths> <source_0> [<source_1> ...]
+#
+#   ip_repo_paths: semicolon-separated Vivado IP repository directories, or - for none
+#
+# Example:
+#   vivado -mode batch -notrace -source package_verilog_ip.tcl -tclargs \
+#     design design_top \
+#     design/ip \
+#     Projects/design user.org user 1.0 xck26-sfvc784-2LV-c \
+#     ip;src/ip \
+#     rtl/design_top.v ...
+
+set nargs [llength $argv]
+if {$nargs < 10} {
+    puts "Usage: vivado -mode batch -source package_verilog_ip.tcl -tclargs \\"
+    puts "         <ip_name> <top_module> <ip_out_dir> <work_dir> \\"
+    puts "         <vendor> <library> <version> <part> <ip_repo_paths> \\"
+    puts "         <source_0> \[<source_1> ...\]"
+    exit 1
+}
+
+set ip_name     [lindex $argv 0]
+set top_module  [lindex $argv 1]
+set ip_out_dir  [file normalize [lindex $argv 2]]
+set work_dir    [file normalize [lindex $argv 3]]
+set ip_vendor   [lindex $argv 4]
+set ip_library  [lindex $argv 5]
+set ip_version  [lindex $argv 6]
+set part        [lindex $argv 7]
+set ip_repo_paths [lindex $argv 8]
+set src_files   [lrange $argv 9 end]
+
+if {[llength $src_files] == 0} {
+    puts "ERROR: no source files"
+    exit 1
+}
+
+proc xgui_tcl_path {ip_root core_name core_version} {
+    set ver_suffix [string map {. _} $core_version]
+    return [file join $ip_root xgui ${core_name}_v${ver_suffix}.tcl]
+}
+
+proc remove_core_xgui_files {core} {
+    foreach group [ipx::get_file_groups -of_objects $core] {
+        if {![string match xilinx_xpgui* [get_property NAME $group]]} {
+            continue
+        }
+        foreach f [ipx::get_files -of_objects $group] {
+            ipx::remove_file $f $group
+        }
+    }
+}
+
+proc cleanup_stale_xgui_files {ip_root keep_path} {
+    set xgui_dir [file join $ip_root xgui]
+    if {![file isdirectory $xgui_dir]} {
+        return
+    }
+    set keep_norm [file normalize $keep_path]
+    foreach path [glob -nocomplain -directory $xgui_dir *.tcl] {
+        if {[file normalize $path] ne $keep_norm} {
+            file delete -force $path
+        }
+    }
+}
+
+puts "Packaging $top_module as $ip_name ([llength $src_files] files) -> $ip_out_dir"
+
+file mkdir $work_dir
+cd $work_dir
+
+set proj_name ip_package_$ip_name
+if {[file exists ${proj_name}.xpr]} {
+    file delete -force ${proj_name}.xpr ${proj_name}.cache ${proj_name}.runs ${proj_name}.srcs
+}
+
+create_project $proj_name . -part $part -force
+set_property target_language Verilog [current_project]
+
+if {$ip_repo_paths ne "-"} {
+    set repos {}
+    foreach r [split $ip_repo_paths ";"] {
+        if {$r ne ""} {
+            lappend repos [file normalize $r]
+        }
+    }
+    if {[llength $repos] > 0} {
+        set_property ip_repo_paths $repos [current_fileset]
+        puts "IP repo paths: $repos"
+    }
+}
+
+foreach f $src_files {
+    if {![file exists $f]} {
+        puts "ERROR: missing source $f"
+        exit 1
+    }
+    set ext [string tolower [file extension $f]]
+    if {$ext eq ".sv"} {
+        add_files -norecurse $f
+        set_property file_type SystemVerilog [get_files $f]
+    } else {
+        add_files -norecurse $f
+    }
+}
+update_compile_order -fileset sources_1
+set_property top $top_module [current_fileset]
+
+file mkdir $ip_out_dir
+ipx::package_project -root_dir $ip_out_dir -vendor $ip_vendor -library $ip_library -taxonomy /UserIP
+
+set core [ipx::current_core]
+# package_project creates xgui/<top>_v<ver>.tcl before VLNV is customized.
+set stale_xgui [xgui_tcl_path $ip_out_dir [get_property name $core] [get_property version $core]]
+
+set_property name $ip_name $core
+set_property version $ip_version $core
+set_property display_name $ip_name $core
+set_property description "Packaged IP $ip_name v$ip_version (top $top_module)" $core
+
+catch {ipx::infer_bus_interface -all $core}
+
+remove_core_xgui_files $core
+if {[file exists $stale_xgui]} {
+    file delete -force $stale_xgui
+}
+
+ipx::create_xgui_files $core
+set xgui_tcl [xgui_tcl_path $ip_out_dir $ip_name $ip_version]
+cleanup_stale_xgui_files $ip_out_dir $xgui_tcl
+
+ipx::update_checksums $core
+ipx::save_core $core
+ipx::unload_core $core
+
+puts "Done: [file join $ip_out_dir component.xml]"
+close_project
+exit 0

maestro/assets/tcl/program.tcl

@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: 2026 Maestro authors and contributors
+# SPDX-FileContributor: Cedric Hirschi <cedr02@live.com>
+# SPDX-FileContributor: Tim Frey <timfreyb@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# TCL script to program an FPGA using Vivado Hardware Manager
+# Arguments:
+# 1. bitfile path
+# 2. device name (optional, default: xck26_0)
+
+# Get the bitfile from command line arguments
+puts $argv
+set file [lindex $argv 0]
+
+# Get the device name from command line arguments
+set device [lindex $argv 1]
+if {![info exists device]} {
+    set device {xck26_0}
+}
+
+open_hw_manager
+connect_hw_server
+open_hw_target
+puts [get_hw_devices]
+
+# Connect to device
+puts "Connecting to device $device"
+
+current_hw_device [get_hw_devices $device]
+refresh_hw_device -update_hw_probes false [lindex [get_hw_devices $device] 0]
+
+
+# check if file exists
+if {![file exists $file]} {
+    puts "Error: File $file does not exist."
+
+    set file bin/${file}/${file}.bit
+    if {![file exists $file]} {
+        puts "Error: File $file does not exist."
+        exit 1
+    } else {
+        puts "Using alternative file path: $file"
+    }
+}
+
+# .ltx file ??
+set ltx_file [file rootname $file].ltx
+if {[file exists $ltx_file]} {
+    puts "Found LTX file: $ltx_file"
+    set_property PROBES.FILE $ltx_file [get_hw_devices $device]
+} else {
+    puts "No LTX file found for $file"
+    set_property PROBES.FILE {} [get_hw_devices $device]
+}
+
+set_property PROGRAM.FILE $file [get_hw_devices $device]
+
+program_hw_devices [get_hw_devices $device]
+refresh_hw_device [lindex [get_hw_devices $device] 0]
+close_hw_target
+
+puts ""
+puts "Done programming $file"
+puts "  to $device"

maestro/assets/verible/format.flags

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 Maestro authors and contributors
+# SPDX-FileContributor: Cedric Hirschi <cedr02@live.com>
+# SPDX-FileContributor: Tim Frey <timfreyb@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Default verible-verilog-format flags (one flag per line).
+--assignment_statement_alignment=align
+--case_items_alignment=align
+--class_member_variable_alignment=align
+--compact_indexing_and_selections=true
+--distribution_items_alignment=align
+--enum_assignment_statement_alignment=align
+--expand_coverpoints=true
+--formal_parameters_alignment=align
+--formal_parameters_indentation=indent
+--module_net_variable_alignment=align
+--named_parameter_alignment=align
+--named_parameter_indentation=indent
+--named_port_alignment=align
+--named_port_indentation=indent
+--port_declarations_alignment=align
+--port_declarations_indentation=indent
+--port_declarations_right_align_packed_dimensions=true
+--port_declarations_right_align_unpacked_dimensions=true
+--struct_union_members_alignment=align
+--try_wrap_long_lines=false

maestro/assets/verible/lint.rules

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 Maestro authors and contributors
+# SPDX-FileContributor: Cedric Hirschi <cedr02@live.com>
+# SPDX-FileContributor: Tim Frey <timfreyb@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Allow localparam/parameter names like TEST_WIDTH (SCREAMING_SNAKE_CASE).
+parameter-name-style=localparam_style:ALL_CAPS;parameter_style:ALL_CAPS

maestro/assets/vitis/rpu_build.py

@@ -0,0 +1,90 @@
+# SPDX-FileCopyrightText: 2026 Maestro authors and contributors
+# SPDX-FileContributor: Cedric Hirschi <cedr02@live.com>
+# SPDX-FileContributor: Tim Frey <timfreyb@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+from pathlib import Path
+
+import vitis
+from rpu_create import (
+    COMPILE_SOURCE_SUFFIXES,
+    link_app_sources,
+    update_user_compile_sources,
+)
+
+
+def get_app_sources(root_dir: Path) -> list[Path]:
+    app_sources = os.environ.get("RPU_APP_SOURCES")
+    if not app_sources:
+        print("Error: RPU_APP_SOURCES environment variable not set.")
+        exit(1)
+
+    app_source_patterns = [src.strip() for src in app_sources.split(":") if src.strip()]
+    if not app_source_patterns:
+        print("Error: RPU_APP_SOURCES environment variable is empty.")
+        exit(1)
+
+    resolved_sources = []
+    for src_pattern in app_source_patterns:
+        matched_files = [path for path in root_dir.glob(src_pattern) if path.is_file()]
+        if not matched_files:
+            print(
+                f"Error: No files matched the pattern {src_pattern!r} in RPU_APP_SOURCES."
+            )
+            exit(1)
+        resolved_sources.extend(matched_files)
+        print(f"- Pattern {src_pattern!r} matched {len(matched_files)} files.")
+
+    return resolved_sources
+
+
+def main():
+    app_name = os.environ.get("RPU_APP_NAME")
+    if not app_name:
+        print("Error: RPU_APP_NAME environment variable not set.")
+        exit(1)
+
+    root_dir = os.environ.get("RPU_ROOT_DIR")
+    if not root_dir:
+        print("Error: RPU_ROOT_DIR environment variable not set.")
+        exit(1)
+    root_dir = Path(root_dir).resolve()
+    print(f"Using root directory: {root_dir.as_posix()!r}")
+
+    print("Creating Vitis client...")
+    client = vitis.create_client()
+
+    workspace = root_dir / "workspace"
+    if not workspace.is_dir():
+        print(f"Error: Workspace '{workspace}' does not exist. Run setup first.")
+        exit(1)
+
+    client.set_workspace(workspace)
+
+    print("Getting app...")
+    app = client.get_component(name=app_name)
+    if not app:
+        print(f"Error: App '{app_name}' does not exist. Create the app first.")
+        exit(1)
+
+    print("Syncing app sources...")
+    app_sources = get_app_sources(root_dir)
+    linked_sources = link_app_sources(app.component_location, app_sources)
+    compile_sources = [
+        source
+        for source in linked_sources
+        if Path(source).suffix in COMPILE_SOURCE_SUFFIXES
+    ]
+    if compile_sources:
+        user_config_path = Path(app.component_location) / "src" / "UserConfig.cmake"
+        update_user_compile_sources(user_config_path, compile_sources)
+
+    print("Cleaning and building app...")
+    app.clean()
+    app.build(target="hw")
+
+
+if __name__ == "__main__":
+    main()