{"id":24550866,"url":"https://github.com/meiniki/logip","last_synced_at":"2026-01-03T05:14:13.166Z","repository":{"id":145318893,"uuid":"431909577","full_name":"meiniKi/logIP","owner":"meiniKi","description":"Logic Analyzer IP Core","archived":false,"fork":false,"pushed_at":"2022-07-23T16:43:10.000Z","size":313,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-01-23T01:14:44.496Z","etag":null,"topics":["amd","asic","basys3","digital","formal-verification","fpga","hardware-description-language","hdl","ip","logicanalyzer","logip","measurements","ols","sump","symbiyosys","systemverilog","verilog","vivado","xilinx"],"latest_commit_sha":null,"homepage":"","language":"SystemVerilog","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meiniKi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-11-25T16:24:58.000Z","updated_at":"2024-05-09T03:12:15.000Z","dependencies_parsed_at":"2023-12-26T05:43:05.466Z","dependency_job_id":null,"html_url":"https://github.com/meiniKi/logIP","commit_stats":{"total_commits":152,"total_committers":4,"mean_commits":38.0,"dds":0.493421052631579,"last_synced_commit":"d605ad54193c56a2857e27225a16144851acbad6"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meiniKi%2FlogIP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meiniKi%2FlogIP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meiniKi%2FlogIP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meiniKi%2FlogIP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meiniKi","download_url":"https://codeload.github.com/meiniKi/logIP/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243874173,"owners_count":20361778,"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":["amd","asic","basys3","digital","formal-verification","fpga","hardware-description-language","hdl","ip","logicanalyzer","logip","measurements","ols","sump","symbiyosys","systemverilog","verilog","vivado","xilinx"],"created_at":"2025-01-23T01:14:49.281Z","updated_at":"2026-01-03T05:14:13.124Z","avatar_url":"https://github.com/meiniKi.png","language":"SystemVerilog","funding_links":[],"categories":[],"sub_categories":[],"readme":"# logIP\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/doc_internal/logIP.svg\" width=\"380\"/\u003e\n\u003c/p\u003e\n\nlogIP is a utilization-aware logic analyzer IP core the can be synthesized along the actual design to trace signals in operation. E.g., internal signals of an FPGA design can be observed in regular operation without modifying the design files. logIP is based on the [SUMP](https://sump.org/projects/analyzer/protocol/) protocol and already prepares all required interfaces to implement the fully-featured [OLS extensions](http://dangerousprototypes.com/docs/Logic_Analyzer_core:_Background). While implementations of the [SUMP](https://sump.org/projects/analyzer/protocol/) protocol already exist, the main focus is to adapt the logic analyzer core to specific needs.\n\nThis project was originally developed as part of the Design of Real-Time Systems Laboratory at the [Institute of Technical Informatics](https://www.tugraz.at/en/institutes/iti/home/) at Graz University of Technology. \n\n\n# Usage\n## Instantiation\nThe following snippet shows an instantiation template of the logIP logic analyzer IP. `CHLS` sets the number of input channels to be synthesized. `MEM_DEPTH` adjusts the size of the sampling memory in bits (`10 = 2^10` samples per channel) and `UART_CLK_PER_BIT` sets the UART baud-rate relative to the system clock.\n\n```\nlogIP #(.CHLS(32),\n        .MEM_DEPTH(10),\n        .UART_CLK_PER_BIT(CLK_PER_BIT)) i_logIP (\n  .clk_i    (clk), \n  .rst_in   (rst),\n  .chls_i   (chls),\n  .rx_i     (uart_rx_i),  \n  .tx_o     (uart_tx_o)\n);\n```\n## Block Diagram \nThis section aims to illustrate the architecture of the logIP implementation. The block diagrams depict the main interactions between the modules. Please note that many signals are not explicitly drawn due to clarity.\n### Top Level View\nThe top-level instantiates the receiver, transmitter, the RAM, and the logIP core. The core implements the architecture independent logic.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/block_top.svg\" width=\"300\"/\u003e\n\u003c/p\u003e\n\n### Core Level View\nIn the following diagram, the instantiations within the core are depicted.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/block_core.svg\" width=\"550\"/\u003e\n\u003c/p\u003e\n\n## Input Channels\nUp to 32 input channels are available that can be connected to design signals. The number of channels can be decreased in multiples of eight to save sampling memory. _Important_: De-activation of channel groups are not yet suported. Even when not all channels are synthesized, all channel groups must be activated in the client.\n\n## Sampling Memory\nSamples are stored in a sampling memory (RAM) accessed by an interface layer. The handshaking is kept simple to ease modification and extensions. Currently, the RAM can be synthesized of LUT's or (Xilinx) block ram (BRAM). However, changes to use external RAM are also possible. Memory size (in the number of samples) can be set by module parameters.\n\n## Folder Structure\nThe folder structure is given as follows: `demo` holds demonstration projects that can be synthesized and tested out-of-the-box. `doc` contains all documentation files of logIP. `fv` contains files for formally verifying the design. All generated files, such as the bitstream, reports, etc., are collected in `out`. All scripts to, e.g., run the simulation are located in `scripts`. The design files themselves are placed in `src`. The repository contains an extensive testbench framework put in `tb` along with the design. Finally, `utils` have submodules and the test-pattern generator.\n\n```\n.\n├── demo            Demo projects\n|   └── basys3\n├── doc             Documentation\n├── fv              Formal scripts\n├── out             Generated files like bitstreams\n├── README.md\n├── scripts         Scripts to build, analyze, report, ...\n├── sim             Simulation files\n├── src             RTL source files and IP cores\n├── tb              Testbenches\n└── utils           External utils like git submodules\n    └── tpg\n\n```\n\n# Design Documentation\nThe following table provides a link to the documentation of each module. Note: The HDL itself is documented verbose and meaningful fashion and might help further understand the design.\n\n| Module Name | Usage                     | Documentation                                 |\n| ----------- | ------------------------- | --------------------------------------------  |\n| logIP       | Top Level, logIP          | [logIP ](./doc/doc_internal/logIP.md)         |\n| logIP_pkg   | Package                   | [logIP_pkg ](./doc/doc_internal/logIP_pkg.md) |\n| core        | logIP Core                | [core ](./doc/doc_internal/core.md)           |\n| ctrl        | Controller, Main FSM      | [ctrl ](./doc/doc_internal/ctrl.md)           |\n| indec       | Instruction Decoder       | [indec ](./doc/doc_internal/indec.md)         |\n| ramif       | RAM Interface Memory      | [ramif ](./doc/doc_internal/ramif.md)         |\n| lutram      | LUT RAM Memory            | [lutram ](./doc/doc_internal/lutram.md)       |\n| rdback      | Readback (ID, Metadata)   | [rdback ](./doc/doc_internal/rdback.md)       |\n| sampler     | Sampler of Input Channels | [sampler ](./doc/doc_internal/sampler.md)     |\n| stage       | Single Trigger Stage      | [stage ](./doc/doc_internal/stage.md)         |\n| trigger     | Trigger: 4 Stages         | [trigger ](./doc/doc_internal/trigger.md)     |\n| tuart_rx    | (Tiny) UART receiver      | [tuart_rx ](./doc/doc_internal/tuart_rx.md)   |\n| tuart_tx    | (Tiny) UART transmitter   | [tuart_tx ](./doc/doc_internal/tuart_tx.md)   |\n| syncro      | Synchronizer, legacy      | [syncro ](./doc/doc_internal/syncro.md)       |\n\n\n# Verification\nLogIP has been developed with verification in mind from the early beginning. To achieve desirable confidence of functional correctness, verification is based on two pillars: dynamic verification and formal verification to thoroughly verify critical aspects of the design. \n\nLogIP shall be considered an easy-to-use logic analyzer block that students may use to debug educational projects. Thus, one requirement is to keep the burden of running verification low. A self-contained simulation framework has been developed to ease simulation runs and avoid further dependencies. Most modules are tested independently using the verification framework and carefully crafted test cases.\n\nAs with dynamic verification, the goal was to keep the accessibility of the required tools high and minimize the burden of running verification. However, due to the lack of freely available SVA formal verification tools, the formal flow is split into two parts: one is entirely based on freely available tools and the second one requires a license.\n\n## Simulation\n\nIn `/tb` almost all modules come with an individual testbench to verify their behavior. One folder (`frwk`) is reserved for the framework itself. The framework provides helper functions/macros and models a fully-featured client to simulate the end-to-end behavior. In addition, the test framework offers a mailbox-based system to get a summary report of failed assertions.\n```\ntb/\n├── core\n├── ctrl\n├── frwk       \u003c-- Testbench framework\n├── indec\n├── logIP\n├── sampler\n├── stage\n├── trigger\n├── tuart_rx\n└── tuart_tx\n```\n\nThe structure of each testbench is similar and consists of (at least) four files. \n```\ntb/\u003cmodule\u003e/\n├── dut_if.sv\n├── dut_tester.sv\n├── dut_wrapper.sv\n└── \u003cmodule\u003e_tb.sv\n```\n\n`dut_if.sv` provides the interface to the device under test (DUT) and sets the modport and clocking block accordingly. In `dut_wrapper.sv`, the DUT is instantiated and connected to its interface. `dut_tester.sv` applies the test stimuli and monitors the behavior. In `\u003cmodule\u003e_tb.sv` all parts are instantiated and the main system clock is generated.\n\n\n\nA script is provided for convenience to run the testbench for a particular module.\n```\ncd \u003crepo\u003e/scripts\n./run_sim.sh -d \u003cmodule_name\u003e\n./run_again.sh\n```\n\n## Formal Verification\n\nSVA model checking is based on the extensions of [yosys](https://github.com/YosysHQ/yosys) by [YosysHQ](https://www.yosyshq.com/). The (mostly) concurrent assertions are placed right before the `endmodule` of each module if properties are present in that module. Placing the assertions in a separate checker that can be bound to the design files has been considered but was omitted as just a few properties exist. `run_formal.sh` in its default configuration runs BMC with a depth of 120 and may be modified and extended.\n\n```\ncd \u003crepo\u003e/fv/verific\n./run_formal.sh -d \u003cmodule_name\u003e\n```\n\nThe (experimental) alternative formal run converts the SystemVerilog files to pure Verilog code using [sv2v](https://github.com/zachjs/sv2v) and afterward runs yosys on the generated output. Thus, verifying properties is currently limited to immediate assertions. However, tools might arise that convert (a subset of) SVA properties to an equivalent Verilog representation.\n\n```\ncd \u003crepo\u003e/fv/yosys\n./run_formal.sh -d \u003cmodule_name\u003e\n```\n\n\n# Demos\nDemos are placed in `\u003crepo\u003e/demo`.\n## Basys3\nIn this demo, logIP is instantiated and connected to the test-pattern generator. The incoming and outgoing Uart signals are repeated at two I/O pins for debugging.\n\nThe following script can start synthesis and implementation. After the script has successfully finished, the bitstream and reports are copied to `\u003crepo\u003e/demo/basys3/out`.\n```\ncd \u003crepo\u003e/demo/basys3/scripts\n./run_impl.sh\n```\n\nAnother script can be run to program the bitstream into volatile configuration memory.\n```\n./run_prog.sh\n```\n\n# Clients\nThe following is a non-extensive list of available clients that support the SUMP protocol.\n* [Original SUMP Client](https://sump.org/projects/analyzer/)\n* [Pulseview / Sigrok](https://sigrok.org/)\n* [Open Logic Sniffer](https://github.com/jawi/ols)\n\n\n# Authors\n+ [Meinhard Kissich](https://github.com/meiniKi)\n+ [Klaus Weinbauer](https://github.com/klausweinbauer)\n\n\n# Status\nThe project was started as part of a university course and was extended to a stable state for educational usage. However, more effort is required to make the IP more versatile, more robust and support the OLS extensions. We are open to interested people who want to contribute to logIP.\n\n\n# Issues\nThe [Original SUMP Client](https://sump.org/projects/analyzer/) depends on the RXTX library that can be found [here](http://rxtx.qbang.org/wiki/index.php/Download). Please make sure to use version [rxtx-2.2pre2.zip](http://rxtx.qbang.org/pub/rxtx/rxtx-2.2pre2.zip) and `openjdk-8-jre`. The default java version can be changed by `sudo update-alternatives --config java`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeiniki%2Flogip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeiniki%2Flogip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeiniki%2Flogip/lists"}