{"id":18352732,"url":"https://github.com/chipsalliance/uhdm","last_synced_at":"2025-05-16T05:04:22.120Z","repository":{"id":37851529,"uuid":"227755581","full_name":"chipsalliance/UHDM","owner":"chipsalliance","description":"Universal Hardware Data Model. A complete modeling of the IEEE SystemVerilog Object Model with VPI Interface, Elaborator, Serialization, Visitor and Listener. Used as a compiled interchange format in between SystemVerilog tools. Compiles on Linux gcc, Windows msys2-gcc \u0026 msvc, OsX","archived":false,"fork":false,"pushed_at":"2025-05-09T04:03:52.000Z","size":4554,"stargazers_count":218,"open_issues_count":18,"forks_count":42,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-09T05:19:40.602Z","etag":null,"topics":["ieee-standard","listener","serialization","systemverilog","vpi-api","vpi-interface"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chipsalliance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-12-13T04:25:50.000Z","updated_at":"2025-05-09T04:03:57.000Z","dependencies_parsed_at":"2023-09-23T20:07:49.920Z","dependency_job_id":"d5625fcb-21c8-4b3b-aa77-27549ab0e2ee","html_url":"https://github.com/chipsalliance/UHDM","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2FUHDM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2FUHDM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2FUHDM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipsalliance%2FUHDM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chipsalliance","download_url":"https://codeload.github.com/chipsalliance/UHDM/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471060,"owners_count":22076585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ieee-standard","listener","serialization","systemverilog","vpi-api","vpi-interface"],"created_at":"2024-11-05T21:37:05.276Z","updated_at":"2025-05-16T05:04:22.113Z","avatar_url":"https://github.com/chipsalliance.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Universal Hardware Data Model (UHDM)\n\n\n![UHDM Overview](/images/UHDM.png)\n\n![UHDM Roadmap](/images/UHDM_future.png)\n\n# Presentation\n* [WOSET 2020 Paper and Presentation](https://woset-workshop.github.io/WOSET2020.html#article-10)\n* [UHDM Presentation](https://docs.google.com/presentation/d/1evu8aBWMFwi_UrK-DfWXowfsXM4Bp9knQuHV24lwkPc/edit#slide=id.p)\n\n# Purpose\n\n * Auto generate a concrete C++ implementation of the SystemVerilog (VHDL in future) Object Model following the IEEE standard object model\n * Auto generate a standard VPI interface as a facade to the C++ model\n * Auto generate a serialization/deserialization of the data model\n * Auto generate a Visitor (Walker) function that exercise the entire VPI interface (used in uhdm-dump executable)\n * Auto generate a C++ Listener Design Pattern that traverse the entire VPI data model (used in uhdm-listener executable)\n * Auto generate an Elaborator that uniquifies nets, variables...\n * The generated Object Model can, for a given design, be:\n    * Populated by parsers like [Surelog](https://github.com/alainmarcel/Surelog/) or [Verible](https://github.com/google/verible)\n    * Consumed by tools like Yosys or Verilator\n\n# HowTo\n\n```bash\n * git clone https://github.com/alainmarcel/UHDM.git\n * cd UHDM\n * git submodule update --init --recursive\n * make\n```\n\n# Features\n * All SystemVerilog models are expressed in a Yaml type syntax (One file per Verilog Object Model)\n * From this Yaml description, all the code (C++ headers, VPI Interface, Serialization) is automatically generated.\n * Model inheritance and object/class grouping is supported (To follow the IEEE standard)\n * Supports the concept of \"design\" on top of the IEEE standard to support partitioning and multi-language (SystemVerilog - VHDL)\n * Any deviation/addition from the standard is cleary indicated by a uhdm prefix, IEEE standard API is either prefixed by vpi (Verilog) or vhpi (VHDL).\n\n\n# Model Concepts\n * The model is captured in .yaml files, one per object models detailed pages 976-1050 of the SystemVerilog 2017 IEEE standard.\n * To match the standard, several concepts are observed in the model:\n    * obj_def: A leaf object specification (Object can be allocated and persisted)\n    * class_def: A virtual class specification (Class is used either with inheritance - extends:, or as composition of a - class_ref)\n    * property: Typically an int, bool, string property with a name and a vpi access type (ie: vpiModule) accessed by the vpi_get function\n    * obj_ref: A reference to one (accessed by vpi_handle) or many (accessed by vpi_iterate) leaf objects\n    * class_ref: A reference to one or many virtual class, actual objects returned will be of a leaf type\n    * extends: Class inheritance specified by the extends keyword\n    * group_def: Grouping of objects in a named or unnamed group (We actually give a representative name to unnamed groups)\n    * group_ref: A reference to one or many members of a group of objects\n * Keywords used to capture the model in Yaml\n    * all of the above keywords (obj_def...group_ref),\n    * For each reference (obj_def, class_def, group_def) and property, the following sub fields:\n    * name: the name of the field (spaces accepted), verbatim from the standard\n    * vpi: the name of the VPI access type to access this object member (Has to match a defined value in vpi_user.h or sv_vpi_user.h)\n    * type: the formal type of the field:\n      * obj_ref\n      * class_ref\n      * group_ref\n      * int\n      * unsigned int\n      * bool\n      * string\n      * value (VPI s_vpi_value)\n      * delay (VPI s_vpi_delay)\n    * card: cardinality of the field\n      * 1\n      * any (0 or more)\n * The Standard VPI Data Model is Fully Elaborated, in contrast:\n * When created by Surelog, the UHDM/VPI Data Model is a Folded Model that we found most suitable for applications like Yosys and Verilator:\n    * The Instance tree contains the Design Hierarchy and Elaborated Nets/Ports with High conn and Low conn connections done.\n    * The module definitions contain the logic elements (non-elaborated, and only outside generate statements)\n    * Generate statements and underlying logic are only visible in the elaborated model (topModules)\n    * To get the complete picture of the design one has to use both views (Example in [`listener_elab_test.cpp`](tests/listener_elab_test.cpp))\n    * Applications where the UHDM data model is used as a precursor to another internal datastructure like a Synthesis or Simulator tool will prefer using the Folded Model.\n    * Nets, Ports, Variables in the flat module list (allModules) don't necessary have the correct data type as not enough elaboration steps were performed on them\n    * On the other hand, Nets, Ports, Variables have the correct type in the elaborated view (topModules)\n    * Lhs vs Rhs expression padding is not performed at this point (We welcome PR contributions)\n * UHDM offers an optional Elaboration step that uniquifies nets, ports, variables and function by performing a deep cloning and ref_obj binding.\n    * See [`full_elab_test.cpp`](tests/full_elab_test.cpp) and [`uhdm-dump.cpp`](util/uhdm-dump.cpp)\n    * Applications where the UHDM data model is free standing and is the sole data structure for the design representation will prefer the Fully Elaborated Data Model, examples: Linters or Code Analyzers.\n    * At this point, UHDM does not offer:\n       * the full bit blasted model available in the commercial EDA applications (We welcome contributions).\n       * an expression evaluator that operates on the UHDM expression tree (We welcome contribuitons).\n    * [Issue 319](https://github.com/chipsalliance/UHDM/issues/319) discusses more on the topic of elaboration\n    \n# Model creation\n * The model creation task consists in converting the Object Model diagrams into their Yaml representation and invoking the creation of the concrete\n C++ classes, iterators, serialization code by invoking \"make\"\n * [How to create the model (presentation)](https://docs.google.com/presentation/d/1SGpgeeWmxJ-1AU8EKABrTyKwcfHOe-pfK8yXArTKIz8/edit?usp=sharing)\n\n\n# Actual Design creation\n * The design creation task consists in invoking:\n   * the proper concrete object factory methods to get serializable objects\n   * populate the properties to the obtained objects\n   * assemble the model by creating legal object relations (compile time and runtime checking) following the IEEE standard\n   * invoking the serialization call\n * Read [`module-port_test.cpp`](tests/module-port_test.cpp)\n\n\n# Design Navigation\n * After Deserialization of the persisted design (elaborated or not) (Read [`module-port_test.cpp`](tests/module-port_test.cpp))\n * Client applications can elaborate optionally and use the VPI interface to navigate the Object Model and create their own internal data structures (Read [`tests/listener_elab_test.cpp`](tests/listener_elab_test.cpp))\n * Or use the Visitor (More like a Walker)\n   * An example Visitor is auto-generated to print the content of the data model [`vpi_visitor.cpp`](templates/vpi_visitor.cpp)\n * Or use the Listener Design Pattern\n   * Examples can be found in tests/vpi_listener.cpp or tests/uhdm_listener.cpp\n   * The listener enables client application development with minimum disruption while the data model evolves.\n   * An Custom Elaborator example code uses the Listener Design Pattern in [`listener_elab_test.cpp`](tests/listener_elab_test.cpp)\n   * A Full Elaboration example is demonstrated in [`full_elab_test.cpp`](tests/full_elab_test.cpp) and [`uhdm-dump.cpp`](util/uhdm-dump.cpp)\n * The uhdm-dump [`uhdm-dump`](util/uhdm-dump.cpp) executable creates a human readable view of the UHDM serialized data model using the visitor [`visitor.cpp`](templates/vpi_visitor.cpp).\n * An optional linter (Listener) that warns about non-Synthesizable constructs can be found here: [`SynthSubset.cpp`](templates/SynthSubset.cpp)\n * An optional linter (Listener) that warns about diverse Verilog compliances post-elaboration can be found here: [`UhdmLint.cpp`](templates/UhdmLint.cpp)\n * An optionnal expression evaluator can be found here: [`ExprEval.cpp`](templates/ExprEval.cpp)\n * The Yosys-UHDM plugin code (most comprehensive open-source usage of UHDM) can be found here: https://github.com/chipsalliance/yosys-f4pga-plugins/tree/main/systemverilog-plugin\n * The Verilator-UHDM plugin code can be found here: https://github.com/antmicro/verilator/blob/uhdm-verilator/src/UhdmAst.cpp\n\n# Linking libuhdm.a to your application\n * After instaling (`make install`), create your own executable (Read [`Makefile`](Makefile)) , ie:\n * `$(CXX) -std=c++17 tests/test1.cpp -I/usr/local/include/uhdm -I/usr/local/include/uhdm/include /usr/local/lib/libuhdm.a /usr/local/lib/libcapnp.a /usr/local/lib/libkj.a -ldl -lutil -lm -lrt -lpthread -o test_inst`\n\n\n# Generating uhdm databases\n * Surelog generates natively UHDM databases (surelog.uhdm)\n * Other parsers are welcome to generate UHDM databases\n\n# Python API\n * When uhdm is compiled as a shared library and the UHDM_WITH_PYTHON is set, it also builds a swig wrapper for python (`-DUHDM_WITH_PYTHON=ON` using `cmake` command, or `make release-shared UHDM_WITH_PYTHON=ON`, also make sure your python executable is built with shared libraries enabled: env PYTHON_CONFIGURE_OPTS=\"--enable-shared\" pyenv install -verbose 3.9.11). The python wrapper implements almost all the VPI getter API from systemVerilog. See chapter *38. VPI routine definitions* of Ieee1800-2017 for details.\n * Find here a short example that assumes an existing database. It will print all module names existing in the first design :\n```python\nfrom uhdm import uhdm\nfrom uhdm import util\n\n#build uhdm Serializer object\ns = uhdm.Serializer()\n#Read and uhdm database\ndata = s.Restore('surelog.uhdm')\n\n#Your specific application\n#Here create an iterator on all module in the first design\nmodule_iterator = uhdm.vpi_iterate(uhdm.uhdmallModules,data[0])\n\n#iterate on all module\nwhile(True):\n   vpiObj_module = uhdm.vpi_scan(module_iterator)\n   if vpiObj_module is None:\n       break\n   #print the string pointed by vpiName attribut of vpiObj_module\n   print(uhdm.vpi_get_str(uhdm.vpiName,vpiObj_module))\n\n#Or use a generator wrapper\nfor vpiObj_module in util.vpi_iterate_gen(uhdm.uhdmallModules,data[0]):\n   #print the string pointed by vpiName attribut of vpiObj_module\n   print(uhdm.vpi_get_str(uhdm.vpiName,vpiObj_module))\n```\n\n\n# Useful links\n* [Verilog_Object_Model.pdf](third_party/Verilog_Object_Model.pdf) - Object Model section of the IEEE_Std1800-2017_8299595.pdf (Practical for searches)\n* [SystemVerilog 2017](http://ecee.colorado.edu/~mathys/ecen2350/IntelSoftware/pdf/IEEE_Std1800-2017_8299595.pdf) - System Verilog Standard\n* [Surelog](https://github.com/chipsalliance/Surelog) - Surelog parser\n* [Verible](https://github.com/chipsalliance/verible) - Verible linter\n* [capnproto](https://capnproto.org/) - Cap'n Proto serialization\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchipsalliance%2Fuhdm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchipsalliance%2Fuhdm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchipsalliance%2Fuhdm/lists"}