Task 788: .VQM File Format

Specifications for the .VQM File Format

The .VQM (Verilog Quartus Mapping) file format is a node-level netlist representation generated by Intel Quartus Prime software for FPGA designs. It is used to describe the mapped hardware implementation after logic synthesis, focusing on core logic elements. The format is based on standard structural Verilog RTL, but includes Quartus-specific primitives and attributes for FPGA mapping. It is text-based and does not include behavioral code, periphery logic, or post-fit optimizations. The netlist is flattened, with preserved hierarchy in module names, and is legal Verilog RTL suitable for third-party EDA tools or resynthesis in Quartus.

List of all the properties of this file format intrinsic to its file system:

• File extension: .vqm
• Content type: Text (ASCII/UTF-8 encoded)
• Syntax: Structural Verilog HDL (no behavioral constructs)
• Hierarchy: Flattened representation of the design, with original hierarchy preserved in module and instance names (using backslashes \ for paths and pipes | for submodules)
• Primitives: Quartus-specific FPGA atoms, such as cyclonev_lcell_comb (for LUT-based logic), dffeas (for flip-flops), cyclonev_ram_block (for block RAM), cyclonev_mac (for DSP multipliers), cyclonev_mlab_cell (for distributed memory), and wrappers like altera_syncram or altsyncram
• Parameters: Configured via defparam statements, including is_wysiwyg (preserves structure during synthesis), power_up (initial flip-flop state), lut_mask (LUT truth table as hex string), shared_arith (arithmetic sharing), extended_lut (LUT mode), logical_ram_depth/logical_ram_width (RAM dimensions), init_file (path to .hex initialization file), ram_block_type (e.g., "M10K" for block RAM), and mixed_port_feed_through_mode (RAM behavior)
• Signal naming: Hierarchical with special prefixes/suffixes (e.g., __ALT_INV__ for inverted signals, ~I for internal nodes, ~feeder for routing, ~DUPLICATE for duplicated logic)
• Initialization: RAM and ROM primitives reference external .hex files for data loading (e.g., fp_pow_0002_memoryC0_uid419_expTabGen_lutmem.hex)
• Target device family: Inferred from primitive prefixes (e.g., cyclonev_ for Cyclone V family)
• Constants: Includes vcc (logic high) and gnd (logic low) as built-in signals
• Limitations: Supports only core logic (flip-flops, LUTs, DSPs, memory); excludes periphery (transceivers, I/O); no post-fit atoms like wire-LUTs

Two direct download links for files of format .VQM:

• https://raw.githubusercontent.com/AmeerAbdelhadi/Verilog-Quartus-Mapping-VQM-Netlist-Parser/master/fp_pow.vqm
• Extensive searches across web sources, including GitHub and Intel documentation, yielded only one publicly available .VQM file for direct download. A second example could not be located, as .VQM files are typically generated during FPGA synthesis workflows and are not commonly distributed as standalone samples.

Ghost blog embedded HTML JavaScript for drag-and-drop .VQM file dumping:
The following is an HTML snippet with embedded JavaScript that can be embedded in a Ghost blog post. It creates a drop zone for .VQM files, reads the file content, parses key properties using regular expressions, and displays them on the screen in a structured format.

Python class for .VQM file handling:

import re

class VQMParser:
    def __init__(self, filename):
        with open(filename, 'r') as f:
            self.content = f.read()
        self.properties = self.parse()

    def parse(self):
        properties = {}
        # Similar parsing as in JS
        properties['File Extension'] = '.vqm'
        properties['Content Type'] = 'Text'
        properties['Syntax'] = 'Structural Verilog HDL' if re.search(r'module', self.content) else 'Unknown'
        hierarchy = re.findall(r'\\[\\w:]+', self.content)
        properties['Hierarchy Examples'] = ', '.join(hierarchy[:5]) + '...' if hierarchy else 'None found'
        primitives = set(re.findall(r'(\w+)\s+\w+\s*\(', self.content))
        properties['Primitives'] = ', '.join(primitives) if primitives else 'None found'
        params = re.findall(r'defparam\s+[\w\\|~.]+\.(\w+)\s*=', self.content)
        properties['Parameters'] = ', '.join(set(params)) if params else 'None found'
        signals = re.findall(r'__ALT_INV__[\w~]+', self.content)
        properties['Special Signals'] = ', '.join(signals[:5]) + '...' if signals else 'None found'
        inits = re.findall(r'init_file\s*=\s*"([^"]+\.hex)"', self.content)
        properties['Initialization Files'] = ', '.join(inits) if inits else 'None found'
        device = re.search(r'(cyclonev_|stratix_|\w+)_', self.content)
        properties['Target Device Family'] = device.group(1).replace('_', '') if device else 'Unknown'
        constants = []
        if 'vcc' in self.content: constants.append('vcc')
        if 'gnd' in self.content: constants.append('gnd')
        properties['Constants'] = ', '.join(constants) if constants else 'None found'
        return properties

    def print_properties(self):
        for key, value in self.properties.items():
            print(f"{key}: {value}")

    def write(self, filename):
        with open(filename, 'w') as f:
            f.write(self.content)

# Example usage:
# parser = VQMParser('example.vqm')
# parser.print_properties()
# parser.write('output.vqm')

Java class for .VQM file handling:

import java.io.BufferedReader;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class VQMParser {
    private String content;
    private Map<String, String> properties;

    public VQMParser(String filename) throws IOException {
        StringBuilder sb = new StringBuilder();
        try (BufferedReader br = new BufferedReader(new FileReader(filename))) {
            String line;
            while (line = br.readLine() != null) {
                sb.append(line).append("\n");
            }
        }
        content = sb.toString();
        properties = parse();
    }

    private Map<String, String> parse() {
        Map<String, String> props = new HashMap<>();
        props.put("File Extension", ".vqm");
        props.put("Content Type", "Text");
        props.put("Syntax", content.contains("module") ? "Structural Verilog HDL" : "Unknown");
        Pattern hierarchyPat = Pattern.compile("\\\\[\\\\w:]+");
        Matcher hierarchyMat = hierarchyPat.matcher(content);
        StringBuilder hierarchy = new StringBuilder();
        int count = 0;
        while (hierarchyMat.find() && count < 5) {
            if (count > 0) hierarchy.append(", ");
            hierarchy.append(hierarchyMat.group());
            count++;
        }
        if (count > 0) hierarchy.append("...");
        props.put("Hierarchy Examples", hierarchy.length() > 0 ? hierarchy.toString() : "None found");
        Pattern primitivePat = Pattern.compile("(\\w+)\\s+\\w+\\s*\\(");
        Matcher primitiveMat = primitivePat.matcher(content);
        Set<String> primitives = new HashSet<>();
        while (primitiveMat.find()) {
            primitives.add(primitiveMat.group(1));
        }
        props.put("Primitives", String.join(", ", primitives).isEmpty() ? "None found" : String.join(", ", primitives));
        Pattern paramPat = Pattern.compile("defparam\\s+[\\w\\\\|~.]+\\.(\\w+)\\s*=");
        Matcher paramMat = paramPat.matcher(content);
        Set<String> params = new HashSet<>();
        while (paramMat.find()) {
            params.add(paramMat.group(1));
        }
        props.put("Parameters", String.join(", ", params).isEmpty() ? "None found" : String.join(", ", params));
        Pattern signalPat = Pattern.compile("__ALT_INV__[\\w~]+");
        Matcher signalMat = signalPat.matcher(content);
        StringBuilder signals = new StringBuilder();
        count = 0;
        while (signalMat.find() && count < 5) {
            if (count > 0) signals.append(", ");
            signals.append(signalMat.group());
            count++;
        }
        if (count > 0) signals.append("...");
        props.put("Special Signals", signals.length() > 0 ? signals.toString() : "None found");
        Pattern initPat = Pattern.compile("init_file\\s*=\\s*\"([^\"]+\\.hex)\"");
        Matcher initMat = initPat.matcher(content);
        StringBuilder inits = new StringBuilder();
        while (initMat.find()) {
            if (inits.length() > 0) inits.append(", ");
            inits.append(initMat.group(1));
        }
        props.put("Initialization Files", inits.length() > 0 ? inits.toString() : "None found");
        Pattern devicePat = Pattern.compile("(cyclonev_|stratix_|\\w+)_");
        Matcher deviceMat = devicePat.matcher(content);
        String device = deviceMat.find() ? deviceMat.group(1).replace("_", "") : "Unknown";
        props.put("Target Device Family", device);
        StringBuilder constants = new StringBuilder();
        if (content.contains("vcc")) constants.append("vcc");
        if (content.contains("gnd")) {
            if (constants.length() > 0) constants.append(", ");
            constants.append("gnd");
        }
        props.put("Constants", constants.length() > 0 ? constants.toString() : "None found");
        return props;
    }

    public void printProperties() {
        for (Map.Entry<String, String> entry : properties.entrySet()) {
            System.out.println(entry.getKey() + ": " + entry.getValue());
        }
    }

    public void write(String filename) throws IOException {
        try (FileWriter fw = new FileWriter(filename)) {
            fw.write(content);
        }
    }

    // Example usage:
    // public static void main(String[] args) throws IOException {
    //     VQMParser parser = new VQMParser("example.vqm");
    //     parser.printProperties();
    //     parser.write("output.vqm");
    // }
}

JavaScript class for .VQM file handling:

class VQMParser {
    constructor(content) {  // Content is string, as JS file reading is async; use with FileReader
        this.content = content;
        this.properties = this.parse();
    }

    parse() {
        const properties = {};
        properties['File Extension'] = '.vqm';
        properties['Content Type'] = 'Text';
        properties['Syntax'] = this.content.includes('module') ? 'Structural Verilog HDL' : 'Unknown';
        const hierarchy = this.content.match(/\\[\\w:]+/g) || [];
        properties['Hierarchy Examples'] = hierarchy.slice(0, 5).join(', ') + (hierarchy.length > 5 ? '...' : '') || 'None found';
        const primitivesMatch = this.content.match(/(\w+)\s+\w+\s*\(/g) || [];
        const primitives = [...new Set(primitivesMatch.map(m => m.trim().split(' ')[0]))];
        properties['Primitives'] = primitives.join(', ') || 'None found';
        const params = this.content.match(/defparam\s+[\w\\|~.]+\.(\w+)\s*=/g)?.map(p => p.match(/\.(\w+)/)[1]) || [];
        properties['Parameters'] = [...new Set(params)].join(', ') || 'None found';
        const signals = this.content.match(/__ALT_INV__[\w~]+/g) || [];
        properties['Special Signals'] = signals.slice(0, 5).join(', ') + (signals.length > 5 ? '...' : '') || 'None found';
        const inits = this.content.match(/init_file\s*=\s*"([^"]+\.hex)"/g)?.map(i => i.match(/"([^"]+)"/)[1]) || [];
        properties['Initialization Files'] = inits.join(', ') || 'None found';
        const device = this.content.match(/(cyclonev_|stratix_|\w+)_/);
        properties['Target Device Family'] = device ? device[1].replace('_', '') : 'Unknown';
        const constants = [];
        if (this.content.includes('vcc')) constants.push('vcc');
        if (this.content.includes('gnd')) constants.push('gnd');
        properties['Constants'] = constants.join(', ') || 'None found';
        return properties;
    }

    printProperties() {
        for (const [key, value] of Object.entries(this.properties)) {
            console.log(`${key}: ${value}`);
        }
    }

    write(filename) {
        // JS cannot directly write to file system; use Blob for download
        const blob = new Blob([this.content], { type: 'text/plain' });
        const url = URL.createObjectURL(blob);
        const a = document.createElement('a');
        a.href = url;
        a.download = filename;
        a.click();
        URL.revokeObjectURL(url);
    }
}

// Example usage:
// const parser = new VQMParser(fileContentString);
// parser.printProperties();
// parser.write('output.vqm');

C class for .VQM file handling (implemented in C++ for class support and regex):

#include <iostream>
#include <fstream>
#include <string>
#include <regex>
#include <set>
#include <vector>
#include <map>

class VQMParser {
private:
    std::string content;
    std::map<std::string, std::string> properties;

    void parse() {
        properties["File Extension"] = ".vqm";
        properties["Content Type"] = "Text";
        properties["Syntax"] = std::regex_search(content, std::regex("module")) ? "Structural Verilog HDL" : "Unknown";

        std::smatch matches;
        std::regex hierarchyRegex("\\\\[\\\\w:]+");
        std::string hierarchyStr;
        int count = 0;
        auto words_begin = std::sregex_iterator(content.begin(), content.end(), hierarchyRegex);
        auto words_end = std::sregex_iterator();
        for (std::sregex_iterator i = words_begin; i != words_end && count < 5; ++i) {
            if (count > 0) hierarchyStr += ", ";
            hierarchyStr += (*i).str();
            count++;
        }
        if (count > 0) hierarchyStr += "...";
        properties["Hierarchy Examples"] = !hierarchyStr.empty() ? hierarchyStr : "None found";

        std::regex primitiveRegex("(\\w+)\\s+\\w+\\s*\\(");
        std::set<std::string> primitives;
        for (std::sregex_iterator i = std::sregex_iterator(content.begin(), content.end(), primitiveRegex); i != std::sregex_iterator(); ++i) {
            primitives.insert((*i)[1].str());
        }
        std::string primStr;
        for (auto it = primitives.begin(); it != primitives.end(); ++it) {
            if (!primStr.empty()) primStr += ", ";
            primStr += *it;
        }
        properties["Primitives"] = !primStr.empty() ? primStr : "None found";

        std::regex paramRegex("defparam\\s+[\\w\\\\|~.]+\\.(\\w+)\\s*=");
        std::set<std::string> params;
        for (std::sregex_iterator i = std::sregex_iterator(content.begin(), content.end(), paramRegex); i != std::sregex_iterator(); ++i) {
            params.insert((*i)[1].str());
        }
        std::string paramStr;
        for (auto it = params.begin(); it != params.end(); ++it) {
            if (!paramStr.empty()) paramStr += ", ";
            paramStr += *it;
        }
        properties["Parameters"] = !paramStr.empty() ? paramStr : "None found";

        std::regex signalRegex("__ALT_INV__[\\w~]+");
        std::string signalStr;
        count = 0;
        for (std::sregex_iterator i = std::sregex_iterator(content.begin(), content.end(), signalRegex); i != std::sregex_iterator() && count < 5; ++i) {
            if (count > 0) signalStr += ", ";
            signalStr += (*i).str();
            count++;
        }
        if (count > 0) signalStr += "...";
        properties["Special Signals"] = !signalStr.empty() ? signalStr : "None found";

        std::regex initRegex("init_file\\s*=\\s*\"([^\"]+\\.hex)\"");
        std::vector<std::string> inits;
        for (std::sregex_iterator i = std::sregex_iterator(content.begin(), content.end(), initRegex); i != std::sregex_iterator(); ++i) {
            inits.push_back((*i)[1].str());
        }
        std::string initStr;
        for (auto& init : inits) {
            if (!initStr.empty()) initStr += ", ";
            initStr += init;
        }
        properties["Initialization Files"] = !initStr.empty() ? initStr : "None found";

        std::regex deviceRegex("(cyclonev_|stratix_|\\w+)_");
        std::smatch deviceMatch;
        if (std::regex_search(content, deviceMatch, deviceRegex)) {
            std::string dev = deviceMatch[1].str();
            dev.erase(std::remove(dev.begin(), dev.end(), '_'), dev.end());
            properties["Target Device Family"] = dev;
        } else {
            properties["Target Device Family"] = "Unknown";
        }

        std::string constStr;
        if (content.find("vcc") != std::string::npos) constStr += "vcc";
        if (content.find("gnd") != std::string::npos) {
            if (!constStr.empty()) constStr += ", ";
            constStr += "gnd";
        }
        properties["Constants"] = !constStr.empty() ? constStr : "None found";
    }

public:
    VQMParser(const std::string& filename) {
        std::ifstream file(filename);
        if (file) {
            std::string line;
            while (std::getline(file, line)) {
                content += line + "\n";
            }
            parse();
        } else {
            throw std::runtime_error("Failed to open file");
        }
    }

    void printProperties() const {
        for (const auto& prop : properties) {
            std::cout << prop.first << ": " << prop.second << std::endl;
        }
    }

    void write(const std::string& filename) const {
        std::ofstream out(filename);
        if (out) {
            out << content;
        } else {
            throw std::runtime_error("Failed to write file");
        }
    }
};

// Example usage:
// int main() {
//     try {
//         VQMParser parser("example.vqm");
//         parser.printProperties();
//         parser.write("output.vqm");
//     } catch (const std::exception& e) {
//         std::cerr << e.what() << std::endl;
//     }
//     return 0;
// }