= Verilator XML Output
:toc: right

// Github doesn't render unless absolute URL
image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"]

== Introduction

This document describes Verilator's XML output. For more general information
please see https://verilator.org[verilator.org].

== General

Verilator's XML output is enabled with the `--xml-only` flag. It contains
limited information about the elaborated design including files, modules,
instance hierarchy, logic and data types. There is no formal schema since part
of the structure of the XML document matches the compiled code which would
require the schema to describe legal SystemVerilog structure. The intended
usage is to enable other downstream tools to take advantage of Verilator's
parser.

== Structure

The XML document is consists of 4 sections within the top level `verilator_xml`
element:

`<files>`...`</files>`::

This section contains a list of all design files read, including the
built-in constructs and the command line as their own entries.  Each
`<file>` has an attribute `id` which is a short ASCII string unique to that
file. Other elements' `loc` attributes use this id to refer to a particular
file.

`<module_files>`...`</module_files>`::

All files containing Verilog module definitions are listed in this section.
This element's contents is a subset of the `<files>` element's contents.

`<cells>`...`</cells>`::

The cells section of the XML document contains the design instance
hierarchy.  Each instance is represented with the `<cell>` element with the
following attributes:

* `fl` (deprecated): The file id and line number where the module was
  instanced.  Use `loc` instead.

* `loc`: The file id, first line number, last line number, first column
   number and last column number of the identifier where the module was
   instanced, separated by commas.

* `name`: The instance name.

* `submodname`: The module name uniquified with particular parameter values (if any).

* `hier`: The full hierarchy path.

`<netlist>`...`</netlist>`::

The netlist section contains a number of `<module>`...`</module>` elements,
each describing the contents of that module, and a single `<typetable>`...
`</typetable>` element which lists all used types used within the
modules. Each type has a numeric `id` attribute that is referred to by
elements in the `<module>` elements using the `dtype_id` attribute.

== Distribution

Copyright 2020-2020 by Wilson Snyder.  Verilator is free software; you can
redistribute it and/or modify it under the terms of either the GNU Lesser
General Public License Version 3 or the Perl Artistic License Version 2.0.
// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
