### Setup Python Virtual Environment and Dependencies

Source: https://github.com/llvm/circt/blob/main/lib/Dialect/ESI/runtime/AGENTS.md

Create and activate a Python virtual environment, then install necessary development dependencies for the ESI runtime and CIRCT integration.

```bash
# Create a venv with matching Python version and install test deps.
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools nanobind pytest numpy psutil executing
```

--------------------------------

### Install CIRCT Python Bindings

Source: https://context7.com/llvm/circt/llms.txt

Instructions for installing the CIRCT Python bindings, either from source or via a pre-release wheel.

```sh
# Install Python bindings from source
cd circt
pip install lib/Bindings/Python
```

```sh
# Or install the nightly pre-release wheel
pip install circt --pre
```

--------------------------------

### Install Cosimulation Collateral Files

Source: https://github.com/llvm/circt/blob/main/lib/Dialect/ESI/runtime/cosim_dpi_server/CMakeLists.txt

Installs SystemVerilog and C++ files required for cosimulation. The destination directory varies based on the WHEEL_BUILD flag.

```cmake
set(cosim_collateral
  Cosim_DpiPkg.sv
  Cosim_Endpoint.sv
  Cosim_Manifest.sv
  Cosim_CycleCount.sv

  driver.sv
  driver.cpp
)
if (WHEEL_BUILD)
  install(FILES
    ${cosim_collateral}
    DESTINATION cosim
    COMPONENT ESIRuntime
  )
else()
  install(FILES
    ${cosim_collateral}
    DESTINATION esiaccel/cosim
    COMPONENT ESIRuntime
  )
endif()
```

--------------------------------

### Install Python Runtime Files

Source: https://github.com/llvm/circt/blob/main/lib/Dialect/ESI/runtime/python/CMakeLists.txt

Installs Python source files to the specified destination with the ESIRuntime component.

```cmake
install(FILES ${pysrc}
        DESTINATION ${DEST}
        COMPONENT ESIRuntime)
    endforeach()
```

--------------------------------

### Create and Print a CIRCT HW Module in Python

Source: https://github.com/llvm/circt/blob/main/docs/PythonBindings.md

Demonstrates creating a hardware module named 'magic' with specific input and output ports using CIRCT's Python bindings. This example requires the CIRCT Python bindings to be installed or accessible via PYTHONPATH.

```python
# silicon.py
import circt
from circt.ir import Context, InsertionPoint, IntegerType, Location, Module
from circt.dialects import hw, comb

with Context() as ctx, Location.unknown():
  circt.register_dialects(ctx)
  i42 = IntegerType.get_signless(42)
  m = Module.create()
  with InsertionPoint(m.body):

    def magic(module):
      xor = comb.XorOp.create(module.a, module.b)
      return {"c": xor}

    hw.HWModuleOp(name="magic",
                  input_ports=[("a", i42), ("b", i42)],
                  output_ports=[("c", i42)],
                  body_builder=magic)
  print(m)
```

--------------------------------

### Inspect Scheduling Solution Programmatically

Source: https://github.com/llvm/circt/blob/main/docs/Scheduling.md

Iterate through operations in a scheduling problem instance and print their computed start times. Assumes start times have been verified and are set.

```c++
for (auto &op : prob.getOperations())
  llvm::dbgs() << *prob.getStartTime(&op) << "\n";
```

--------------------------------

### Install CIRCT Python Bindings

Source: https://github.com/llvm/circt/blob/main/docs/PythonBindings.md

Installs the CIRCT Python bindings using pip. Ensure you are in the circt directory.

```bash
cd circt
pip install lib/Bindings/Python
```

--------------------------------

### Build esitester Executable

Source: https://github.com/llvm/circt/blob/main/lib/Dialect/ESI/runtime/CMakeLists.txt

Adds the esitester executable, which serves as an example and test driver. It is not intended for production use and is not installed by default.

```cmake
add_executable(esitester
  ${CMAKE_CURRENT_SOURCE_DIR}/cpp/tools/esitester.cpp
)
# Set debug postfix for Windows executables
if(WIN32)
  set_target_properties(esitester PROPERTIES DEBUG_POSTFIX "_d")
endif()
target_link_libraries(esitester PRIVATE
  ESICppRuntime
  CLI11::CLI11
)
add_dependencies(ESIRuntime esitester)
install(TARGETS esitester
  DESTINATION ${ESIRT_INSTALL_BINDIR}
  COMPONENT ESIRuntime
)
```

--------------------------------

### Install PyCDE

Source: https://github.com/llvm/circt/blob/main/docs/PyCDE/_index.md

Install the latest pre-release version of PyCDE using pip. Nightly builds are available if there have been updates.

```bash
pip install pycde --pre
```

--------------------------------

### Install PyCDE Pre-release

Source: https://context7.com/llvm/circt/llms.txt

Install the latest nightly pre-release of PyCDE using pip.

```sh
pip install pycde --pre   # latest nightly pre-release
```

--------------------------------

### Verify and Dump Scheduling Solution

Source: https://github.com/llvm/circt/blob/main/docs/Scheduling.md

Verify the computed start times of a scheduling solution and dump the instance to a DOT file for visualization. Asserts that the verification succeeded.

```c++
auto verifRes = prob.verify();
assert(succeeded(verifRes));
dumpAsDOT(prob, "sched-solution.dot");
```

--------------------------------

### Verilog Instantiation of External Parameterized Module

Source: https://github.com/llvm/circt/blob/main/docs/PyCDE/basics.md

Example of SystemVerilog instantiation for an external parameterized module, showing how parameters are applied.

```verilog
AddInts #(
    .width(64'd32)
  ) AddInts (
    .a (a),
    .b (b),
    .c (c)
  );
```

--------------------------------

### BMC Tool Logic Example

Source: https://github.com/llvm/circt/blob/main/docs/Tools/circt-bmc.md

Illustrates a portion of the BMC tool's logic, showing SMT checks and state transitions within a cycle.

```mlir
smt.check sat {} unknown {} unsat {}
    %next_cycle_state0 = func.call @helper(%i, %clk, %clk_nxt, %new_state0)
      : (i32, !smt.bv<1>, !smt.bv<1>, !smt.bv<32>) -> !smt.bv<32>
    smt.check sat {} unknown {} unsat {}
    scf.yield %next_cycle_state0 : !smt.bv<32>
  }
  smt.yield
}
```

--------------------------------

### Install ESI Cosim Runner Script

Source: https://github.com/llvm/circt/blob/main/lib/Dialect/ESI/runtime/cosim_dpi_server/CMakeLists.txt

Installs the 'esi-cosim.py' script to the runtime binary directory with specific execute, write, and read permissions for owner, group, and world.

```cmake
install(FILES
  esi-cosim.py
  DESTINATION ${ESIRT_INSTALL_BINDIR}
  PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
              GROUP_EXECUTE GROUP_READ
              WORLD_EXECUTE WORLD_READ
  COMPONENT ESIRuntime
)
add_dependencies(ESIRuntime esi-cosim)
```

--------------------------------

### JSON Annotation File Example

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/FIRRTL/FIRRTLAnnotations.md

This is an example of a JSON file used to define annotations. It specifies a target and associated data.

```json
[
  {
    "target": "~Foo|Foo",
    "hello": "world"
  }
]
```

--------------------------------

### Install PDB Files for Windows Debug Builds

Source: https://github.com/llvm/circt/blob/main/lib/Dialect/ESI/runtime/CMakeLists.txt

Installs PDB files for Windows Debug builds of the esiquery target. This is an optional component of the ESI Runtime.

```cmake
if(WIN32 AND MSVC)
  install(FILES $<TARGET_PDB_FILE:esiquery>
    DESTINATION ${ESIRT_INSTALL_BINDIR}
    COMPONENT ESIRuntime
    OPTIONAL
  )
endif()
```

--------------------------------

### Install esitester PDB Files for Windows Debug Builds

Source: https://github.com/llvm/circt/blob/main/lib/Dialect/ESI/runtime/CMakeLists.txt

Installs PDB files for the esitester executable on Windows Debug builds. This is an optional component.

```cmake
if(WIN32 AND MSVC)
  install(FILES $<TARGET_PDB_FILE:esitester>
    DESTINATION ${ESIRT_INSTALL_BINDIR}
    COMPONENT ESIRuntime
    OPTIONAL
  )
endif()
```

--------------------------------

### FIRRTL Target Examples

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/FIRRTL/FIRRTLAnnotations.md

Illustrates various FIRRTL target expressions and their corresponding descriptions, showing how to refer to circuits, modules, and specific instances.

```FIRRTL
~ Foo
```

```FIRRTL
~ Foo| Foo
```

```FIRRTL
~ Foo| Bar
```

```FIRRTL
~ Foo| Foo/a:Bar
```

```FIRRTL
~ Foo| Foo/b:Bar/c:Baz
```

```FIRRTL
~ Foo| Bar/d:Baz
```

--------------------------------

### Copy VS Code Workspace File

Source: https://github.com/llvm/circt/blob/main/docs/GettingStarted.md

Copy the example VS Code workspace configuration file to a new location to customize it for your project.

```shell
cp .vscode/Unified.code-workspace.jsonc .vscode/circt.code-workspace
```

--------------------------------

### Install PyCDE using Pip

Source: https://github.com/llvm/circt/blob/main/docs/PyCDE/compiling.md

Install PyCDE locally using pip. The `--use-feature=in-tree-build` flag is required for building from the source tree. Run this command from the CIRCT repository root.

```bash
cd circt
pip install frontends/PyCDE --use-feature=in-tree-build
```

--------------------------------

### HWArith Cast Examples

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/HWArith/RationaleHWArith.md

Demonstrates casting between different signedness and bitwidths. Note that multiple casts can often be combined into a single equivalent cast.

```mlir
%1 = hwarith.cast %10 : (ui3) -> ui5
%2 = hwarith.cast %1 : (ui5) -> si5
// ^-- both casts can be combined into one equivalent cast:
%0 = hwarith.cast %10 : (ui3) -> si5
// ^-- this would be lowered to something like this:
%zero_padding = hw.constant 0 : i2
%0_lowered = comb.concat %zero_padding, %10 : i2, i3
```

```mlir
%0 = hwarith.cast %10 : (ui3) -> si5 // (U)
%1 = hwarith.cast %11 : (si3) -> si4 // (S)
%2 = hwarith.cast %12 : (si7) -> ui4 // (S)
%3 = hwarith.cast %13 : (i7) -> si5  // (I)
%3 = hwarith.cast %13 : (si14) -> i4 // (S)
```

--------------------------------

### DPI Module Type Example

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/SimDPI.md

Represents a DPI module type with input, output, and return ports.

```mlir
!sim.dpi_modty<in "a" : i32, out "b" : i32, return "ret" : i8>
```

--------------------------------

### Example: FIRRTL Register with Asynchronous Reset

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/Seq/RationaleSeq.md

Illustrates a FIRRTL register with an asynchronous reset, input, clock, symbol, and reset value.

```mlir
%reg_async_reset = seq.firreg %input clock %clk sym @sym
    reset async %reset, %value : i1f
```

--------------------------------

### Example: FIRRTL Register with Synchronous Reset

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/Seq/RationaleSeq.md

Shows a FIRRTL register configured with a synchronous reset, input, clock, symbol, and reset value.

```mlir
%reg_sync_reset_rand  = seq.firreg %input clock %clk sym @sym
    reset sync %reset, %value : i64
```

--------------------------------

### Debug Port Example

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/Seq/RationaleSeq.md

Demonstrates how a debug port could be specified, either as an additional read port or attached directly to the memory symbol for specialized debugging needs.

```mlir
%mem = seq.debug @myMemory : !seq.hlmem<4xi32>
```

--------------------------------

### Using Verilog Exporter in PassManager Pipeline

Source: https://github.com/llvm/circt/blob/main/docs/VerilogGeneration.md

This example demonstrates how to integrate the Verilog exporter into a PassManager pipeline, including optional cleanup passes and required legalization steps.

```c++
  // Optional: perform general cleanups and structure the modules in a
  // consistent way.
  auto &modulePM = pm.nest<hw::HWModuleOp>();
  modulePM.addPass(sv::createHWCleanupPass());
  modulePM.addPass(createCSEPass());
  modulePM.addPass(createSimpleCanonicalizerPass());

  // Required: Legalize unsupported operations within modules.  Do not run
  // passes after this that aren't aware of LoweringOptions.
  modulePM.addPass(sv::createHWLegalizeModulesPass());

  // Optional: Tidy up the IR to improve Verilog emission quality.
  modulePM.addPass(sv::createPrettifyVerilogPass());

  // Actually export the module.
  exportVerilog(theModule, ...);
```

--------------------------------

### Seq State Initialization with `seq.initial`

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/Seq/RationaleSeq.md

Demonstrates how to initialize stateful components like `seq.compreg` using `seq.initial` for simulation and FPGA targets. The `!seq.immutable` type wrapper ensures initial values are time-invariant.

```mlir
%r_init, %u_init = seq.initial {
  %rand = sv.macro.ref.se @RANDOM() : () -> i32
  %c0_i32 = hw.constant 0 : i32
  seq.yield %rand, %c0_i32 : i32, i32
} : !seq.immutable<i32>, !seq.immutable<i32>

%r = seq.compreg %i, %clk initial %r_init : i32
%u = seq.compreg %i, %clk initial %u_init : i32
```

```verilog
reg [31:0] r;
initial
  r = `RANDOM;
reg [31:0] u = 32'h0;
```

--------------------------------

### Pipelined Loop Example

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/LoopSchedule/LoopSchedule.md

Represents a pipelined loop using the `loopschedule.pipeline` op. It defines iteration arguments, an initiation interval (II), and stages with start times. Values are registered at the end of each stage and passed to subsequent stages or the terminator.

```mlir
func.func @test1(%arg0: memref<10xi32>) -> i32 {
  %c0 = arith.constant 0 : index
  %c1 = arith.constant 1 : index
  %c10 = arith.constant 10 : index
  %c0_i32 = arith.constant 0 : i32
  %0 = loopschedule.pipeline II = 1 iter_args(%arg1 = %c0, %arg2 = %c0_i32) : (index, i32) -> i32 {
    %1 = arith.cmpi ult, %arg1, %c10 : index
    loopschedule.register %1 : i1
  } do {
    %1:2 = loopschedule.pipeline.stage start = 0 {
      %3 = arith.addi %arg1, %c1 : index
      %4 = memref.load %arg0[%arg1] : memref<10xi32>
      loopschedule.register %3, %4 : index, i32
    } : index, i32
    %2 = loopschedule.pipeline.stage start = 1 {
      %3 = arith.addi %1#1, %arg2 : i32
      pipeline.register %3 : i32
    } : i32
    loopschedule.terminator iter_args(%1#0, %2), results(%2) : (index, i32) -> i32
  }
  return %0 : i32
}
```

--------------------------------

### Build and Test CIRCT and PyCDE

Source: https://github.com/llvm/circt/blob/main/docs/PyCDE/compiling.md

Build the project using Ninja and run the test suites for CIRCT, PyCDE, and PyCDE integration tests. Replace `<path_to_your_circt_build>` with the actual path to your build directory.

```bash
ninja -C <path_to_your_circt_build> check-circt
ninja -C <path_to_your_circt_build> check-pycde
ninja -C <path_to_your_circt_build> check-pycde-integration
```

--------------------------------

### Apply Contract to ShiftLeft Module

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/Verif.md

This example shows how to inline the contract into the `ShiftLeft` module, transforming `verif.require` into `verif.assert` and `verif.ensure_equal` into `verif.assume_equal`. This simplifies the module by replacing the original implementation with symbolic values and assertions, allowing for further optimization.

```mlir
hw.module @ShiftLeft_ApplyContract(in %a: i8, in %b: i8, out z: i8) {
  // The original implementation has become unused since the contract results
  // have been replaced with symbolic values. Dead code elimination will clean
  // this up.
  %c4_i8 = hw.constant 4 : i8
  %c2_i8 = hw.constant 2 : i8
  %c1_i8 = hw.constant 1 : i8
  %b2 = comb.extract %b, 2 : i8 -> i1
  %b1 = comb.extract %b, 1 : i8 -> i1
  %b0 = comb.extract %b, 0 : i8 -> i1
  %0 = comb.shl %a, %c4_i8 : i8
  %1 = comb.mux %b2, %0, %a : i8
  %2 = comb.shl %1, %c2_i8 : i8
  %3 = comb.mux %b1, %2, %1 : i8
  %4 = comb.shl %3, %c1_i8 : i8
  %5 = comb.mux %b0, %4, %3 : i8

  // Results of the contract are replaced with symbolic values.
  // Contract inlined with ensure -> assume, require -> assert, %z -> %any
  // assume(eq(any, x)) can be canonicalized to an any -> x replacement.
  %any = verif.symbolic_value : i8
  %c8_i8 = hw.constant 8 : i8
  %blt8 = comb.icmp ult %b, %c8_i8 : i8
  verif.assert %blt8
  %ashl = comb.shl %a, %b : i8
  verif.assume_equal %any, %ashl : i42

  hw.output %any : i8
}
```

```mlir
// ----- after canonicalization, CSE, and DCE -----

hw.module @ShiftLeft_ApplyContract_Simplified(in %a: i8, in %b: i8, out z: i8) {
  %c8_i8 = hw.constant 8 : i8
  %blt8 = comb.icmp ult %b, %c8_i8 : i8
  verif.assert %blt8
  %ashl = comb.shl %a, %b : i8
  hw.output %ashl : i8
}
```

--------------------------------

### Install CIRCT CMake Exports and Configuration

Source: https://github.com/llvm/circt/blob/main/cmake/modules/CMakeLists.txt

Installs the CIRCT CMake export files and configuration scripts. This allows other projects to easily include and use CIRCT targets and configurations. It is conditional on not installing only the toolchain.

```cmake
install(EXPORT CIRCTTargets DESTINATION ${CIRCT_INSTALL_PACKAGE_DIR}
          COMPONENT circt-cmake-exports)

install(FILES
    ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/CIRCTConfig.cmake
    ${CMAKE_CURRENT_SOURCE_DIR}/AddCIRCT.cmake
    DESTINATION ${CIRCT_INSTALL_PACKAGE_DIR}
    COMPONENT circt-cmake-exports)

```

--------------------------------

### Build CIRCT with Verilog Front-End Enabled

Source: https://github.com/llvm/circt/blob/main/docs/Tools/circt-verilog.md

Configure and build CIRCT with the slang Verilog front-end enabled. Ensure MLIR and LLVM directories are correctly specified.

```bash
cd circt
$ mkdir build
$ cd build
$ cmake -G Ninja .. \
    -DMLIR_DIR=$PWD/../llvm/build/lib/cmake/mlir \
    -DLLVM_DIR=$PWD/../llvm/build/lib/cmake/llvm \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DCMAKE_BUILD_TYPE=DEBUG \
    -DLLVM_USE_SPLIT_DWARF=ON \
    -DLLVM_ENABLE_LLD=ON  \
    -DCIRCT_SLANG_FRONTEND_ENABLED=ON
$ ninja circt-verilog
```

--------------------------------

### circt-opt Command-Line Driver Examples

Source: https://context7.com/llvm/circt/llms.txt

Use `circt-opt` to run CIRCT passes and pipelines on MLIR files. It supports individual pass invocation, pass pipelines, and exporting to SystemVerilog.

```shell
# Run a single hw pass on an MLIR file (renames all wires to foo_<n>)
circt-opt --hw-foo-wires input.mlir

# Run a CSE + canonicalization pipeline
circt-opt --cse --canonicalize input.mlir

# Export to SystemVerilog using ExportVerilog
circt-opt --export-verilog input.mlir -o output.sv

# Run FIRRTL lowering pipeline: FIRRTL -> HW/Comb/Seq -> SV -> Verilog
circt-opt \
  --firrtl-lower-types \
  --firrtl-expand-whens \
  --lower-firrtl-to-hw \
  --hw-cleanup \
  --export-verilog \
  input.fir.mlir -o output.sv

# Check pass output with FileCheck (standard CIRCT test pattern)
# RUN: circt-opt --hw-foo-wires %s | FileCheck %s
# hw.module @foo(in %a: i32, ...) {
#   // CHECK: %foo_0 = hw.wire %a : i32

```

--------------------------------

### MLIR Function for Scheduling Example

Source: https://github.com/llvm/circt/blob/main/docs/Scheduling.md

This MLIR code defines a function with arithmetic and custom operations, serving as an example for static scheduling.

```mlir
func @foo(%a1 : i32, %a2 : i32, %a3 : i32, %a4 : i32) -> i32 {
  %0 = arith.addi %a1, %a2 : i32
  %1 = arith.addi %0, %a3 : i32
  %2:3 = "more.results"(%0, %1) : (i32, i32) -> (i32, i32, i32)
  %3 = arith.addi %a4, %2#1 : i32
  %4 = arith.addi %2#0, %2#2 : i32
  %5 = arith.addi %3, %3 : i32
  %6 = "more.operands"(%3, %4, %5) : (i32, i32, i32) -> i32
  return %6 : i32
}
```

--------------------------------

### Build LLVM/MLIR Separately, Then CIRCT

Source: https://context7.com/llvm/circt/llms.txt

First, build LLVM/MLIR in release mode. Then, build CIRCT against the built LLVM/MLIR in debug mode for faster iteration. Ensure MLIR_DIR and LLVM_DIR are correctly set.

```sh
# Step 1: Build LLVM/MLIR
cd llvm
cmake -G Ninja llvm -B build \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DLLVM_ENABLE_PROJECTS=mlir \
    -DLLVM_TARGETS_TO_BUILD=host
ninja -C build
ninja -C build check-mlir
cd ..

# Step 2: Build CIRCT
cmake -G Ninja . -B build \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DMLIR_DIR=$PWD/llvm/build/lib/cmake/mlir \
    -DLLVM_DIR=$PWD/llvm/build/lib/cmake/llvm
ninja -C build
ninja -C build check-circt
ninja -C build check-circt-integration
```

--------------------------------

### Example FIRRTL Circuit

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/FIRRTL/FIRRTLAnnotations.md

An example FIRRTL circuit structure used to illustrate target expressions. It includes nested modules and instances.

```FIRRTL
circuit Foo:
  module Foo:
    inst a of Bar
    inst b of Bar
  module Bar:
    inst c of Baz
    inst d of Baz
  module Baz:
    skip
```

--------------------------------

### Scheduler Entry Points

Source: https://github.com/llvm/circt/blob/main/docs/Scheduling.md

Shows how schedulers should opt-in to specific problems by providing overloaded entry points. The scheduler can expect input invariants to be enforced and must ensure its solution complies with output constraints.

```C++
LogicalResult awesomeScheduler(Problem &prob);
LogicalResult awesomeScheduler(CyclicProblem &prob);
```

--------------------------------

### Control Verilog Lowering Options via Command Line

Source: https://context7.com/llvm/circt/llms.txt

Demonstrates how to control Verilog lowering options using `firtool` and `circt-opt` for different target tools like Yosys, Verilator, and Questa.

```sh
# Control LoweringOptions from the command line (e.g. firtool)
firtool --lowering-options=emittedLineLength=120,disallowPackedArrays input.fir

# Target-specific recommended options:
# Yosys (no automatic variables, no packed arrays):
circt-opt --export-verilog \
  --mlir-print-op-attrs \
  'builtin.module {circt.loweringOptions = "disallowLocalVariables,disallowPackedArrays"}' \
  input.mlir

# Verilator (wrap location info in @[..]):
firtool --lowering-options=locationInfoStyle=wrapInAtSquareBracket,disallowLocalVariables input.fir

# Questa (emit wire keyword in port lists):
firtool --lowering-options=emitWireInPorts input.fir
```

--------------------------------

### Handle Division by Zero with Mux

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/Comb/RationaleComb.md

Illustrates how to handle division by zero using a multiplexer for SystemVerilog semantics, returning 'x' when the denominator is zero.

```mlir
mux(denominator == 0, sv.constantx, divu(numerator,denominator))
```

--------------------------------

### Install Python Requirements

Source: https://github.com/llvm/circt/blob/main/docs/PyCDE/compiling.md

Install the Python requirements for PyCDE development. This ensures all necessary Python packages are available. Run from the CIRCT repository root.

```bash
python -m pip install -r frontends/PyCDE/python/requirements.txt
```

--------------------------------

### Configure and Build CIRCT with Ninja on Windows

Source: https://github.com/llvm/circt/blob/main/docs/GettingStarted.md

This comprehensive command configures the build using CMake with specific LLVM and CIRCT options, then builds the project using Ninja. Ensure you are in a VS Developer Command shell.

```powershell
> cd <circt clone>
> cmake -B<build_dir> llvm/llvm \
    -GNinja \
    -DLLVM_ENABLE_PROJECTS=mlir \
    -DCMAKE_BUILD_TYPE=Debug \
    -DLLVM_TARGETS_TO_BUILD=X86 \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DMLIR_ENABLE_BINDINGS_PYTHON=ON \
    -DLLVM_EXTERNAL_PROJECTS=circt \
    -DLLVM_EXTERNAL_CIRCT_SOURCE_DIR="$(PWD)" \
    -DCIRCT_BINDINGS_PYTHON_ENABLED=ON \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
    -DLLVM_USE_SPLIT_DWARF=ON 
    -DLLVM_ENABLE_LLD=ON
> ninja -C<build_dir> check-circt
```

--------------------------------

### Build CIRCT with LLVM/MLIR (Unified Build)

Source: https://context7.com/llvm/circt/llms.txt

Clone the repository, configure CMake with LLVM and MLIR projects, and build. Use 'ninja -C build check-circt' to run all tests or 'ninja -C build bin/<tool>' to build specific tools.

```sh
git clone git@github.com:llvm/circt.git --recursive
cd circt

cmake -G Ninja llvm/llvm -B build \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DLLVM_TARGETS_TO_BUILD=host \
    -DLLVM_ENABLE_PROJECTS=mlir \
    -DLLVM_EXTERNAL_PROJECTS=circt \
    -DLLVM_EXTERNAL_CIRCT_SOURCE_DIR=$PWD \
    -DLLVM_ENABLE_LLD=ON

# Build and run all tests
ninja -C build check-circt

# Build only specific tools
ninja -C build bin/firtool
ninja -C build bin/circt-opt
ninja -C build bin/circt-lec
ninja -C build bin/circt-bmc
```

--------------------------------

### Install Python Dependencies for CIRCT Build

Source: https://github.com/llvm/circt/blob/main/docs/GettingStarted.md

Install necessary Python packages using pip, which are required for certain build configurations, especially Python bindings.

```powershell
> python -m pip install psutil pyyaml numpy pybind11
```

--------------------------------

### MLIR Module Example for handshake-runner

Source: https://github.com/llvm/circt/blob/main/docs/Tools/handshake-runner.md

This MLIR module defines a function that allocates memory, stores a value, and then loads and returns that value. It serves as an example input for the handshake-runner tool.

```mlir
module {
  func @main(%arg0: index) -> (i8) {
    %0 = alloc() : memref<10xi8>
    %c1 = constant 1 : i8
         store %c1, %0[%arg0] : memref<10xi8>
         %1 = load %0[%arg0] : memref<10xi8>
         return %1 : i8
  }
}
```

--------------------------------

### Build and Test LLVM/MLIR

Source: https://github.com/llvm/circt/blob/main/docs/GettingStarted.md

Configure and build LLVM and MLIR using CMake and Ninja. Essential for CIRCT development. Use -DLLVM_ENABLE_LLD=ON to leverage the LLD linker for reduced memory usage.

```bash
cd circt
mkdir llvm/build
cd llvm/build
cmake -G Ninja ../llvm \
    -DLLVM_ENABLE_PROJECTS="mlir" \
    -DLLVM_TARGETS_TO_BUILD="host" \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DCMAKE_BUILD_TYPE=DEBUG \
    -DLLVM_USE_SPLIT_DWARF=ON \
    -DLLVM_ENABLE_LLD=ON
ninja
ninja check-mlir
```

--------------------------------

### High-Level Memory Allocation and Access Example

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/Seq/RationaleSeq.md

Demonstrates the allocation of a high-level memory and subsequent read/write operations with specified latencies. Ensure the encapsulating IR accounts for any non-zero port latencies.

```mlir
  %myMemory = seq.hlmem @myMemory %clk : <4xi32>
  %c0_i2 = hw.constant 0 : i2
  %c1_i1 = hw.constant 1 : i1
  %c42_i32 = hw.constant 42 : i32
  %myMemory_rdata = seq.read %myMemory[%c0_i2] rden %c1_i1 { latency = 0} : !seq.hlmem<4xi32>
  seq.write %myMemory[%c0_i2] %c42_i32 wren %c1_i1 { latency = 1 } : !seq.hlmem<4xi32>
```

--------------------------------

### Configure CIRCT Installation Paths

Source: https://github.com/llvm/circt/blob/main/cmake/modules/CMakeLists.txt

Sets variables to define installation directories for CIRCT components, including configuration files, libraries, binaries, and include directories. This is typically used during the CMake configuration phase.

```cmake
string(REGEX REPLACE "/" ";" _count "${CIRCT_INSTALL_PACKAGE_DIR}")
foreach(p ${_count})
  set(CIRCT_CONFIG_CODE "${CIRCT_CONFIG_CODE}
get_filename_component(CIRCT_INSTALL_PREFIX \"${CIRCT_INSTALL_PREFIX}\" PATH)")
endforeach(p)
set(CIRCT_CONFIG_CMAKE_DIR "${CIRCT_INSTALL_PREFIX}/${CIRCT_INSTALL_PACKAGE_DIR}")
set(CIRCT_CONFIG_LLVM_CMAKE_DIR "${CIRCT_INSTALL_PREFIX}/${LLVM_INSTALL_PACKAGE_DIR}")
set(CIRCT_CONFIG_MLIR_CMAKE_DIR "${CIRCT_INSTALL_PREFIX}/${MLIR_INSTALL_PACKAGE_DIR}")
set(CIRCT_CONFIG_LIBRARY_DIRS "${CIRCT_INSTALL_PREFIX}/lib")
set(CIRCT_CONFIG_BINARY_DIR "${CIRCT_INSTALL_PREFIX}")
set(CIRCT_CONFIG_TOOLS_DIR "${CIRCT_INSTALL_PREFIX}/bin")
set(CIRCT_CONFIG_INCLUDE_EXPORTS "include(\"${CIRCT_CMAKE_DIR}/CIRCTTargets.cmake\")")
set(CIRCT_CONFIG_INCLUDE_DIRS
  "${CIRCT_INSTALL_PREFIX}/include"
  )
```

--------------------------------

### SystemVerilog Frontend with Slang

Source: https://context7.com/llvm/circt/llms.txt

Parses SystemVerilog source files using the slang library to generate CIRCT MLIR IR. Requires `-DCIRCT_SLANG_FRONTEND_ENABLED=ON` at build time.

```sv
// counter.sv — input SystemVerilog
module counter (
    input  logic       clk,
    input  logic       reset,
    output logic [7:0] count
);
    always_ff @(posedge clk or posedge reset) begin
        if (reset)
            count <= 8'b0;
        else
            count <= count + 9'd1;
    end
endmodule
```

--------------------------------

### CIRCT Pass Test Example

Source: https://context7.com/llvm/circt/llms.txt

A CIRCT lit test demonstrating the usage of the `hw-foo-wires` pass.

```mlir
// test/Dialect/HW/foo.mlir  — CIRCT lit test
// RUN: circt-opt --hw-foo-wires %s | FileCheck %s

hw.module @foo(in %a: i32, in %b: i32, out out: i32) {
  %c1 = hw.constant 1 : i32
  // CHECK: %foo_0 = hw.wire %c1_i32 : i32
  %wire_1 = hw.wire %c1 : i32
  // CHECK: %foo_1 = hw.wire %a : i32
  %wire_a = hw.wire %a : i32
  %ap1 = comb.add bin %wire_a, %wire_1 : i32
  // CHECK: %foo_2 = hw.wire %0 : i32
  %wire_res = hw.wire %ap1 : i32
  hw.output %wire_res : i32
}
```

--------------------------------

### FIRRTL Circuit Example

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/FIRRTL/RationaleFIRRTL.md

This FIRRTL circuit demonstrates nodes with and without leading underscores, which are affected by name preservation modes.

```firrtl
circuit Foo:
  module Foo:
    input a: UInt<1>
    output b: UInt<1>

    node named = a
    node _unnamed = named

    b <= _unnamed

```

--------------------------------

### Check Contract for ShiftLeft Module

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/Verif.md

This example demonstrates how to check the contract defined in the `ShiftLeft` module. It replaces `verif.require` with `verif.assume` and `verif.ensure_equal` with `verif.assert_equal`, using symbolic values for inputs to verify the contract's properties.

```mlir
verif.formal @ShiftLeft_CheckContract {
  %a = verif.symbolic_value : i8
  %b = verif.symbolic_value : i8

  %c4_i8 = hw.constant 4 : i8
  %c2_i8 = hw.constant 2 : i8
  %c1_i8 = hw.constant 1 : i8
  %b2 = comb.extract %b, 2 : i8 -> i1
  %b1 = comb.extract %b, 1 : i8 -> i1
  %b0 = comb.extract %b, 0 : i8 -> i1
  %0 = comb.shl %a, %c4_i8 : i8
  %1 = comb.mux %b2, %0, %a : i8
  %2 = comb.shl %1, %c2_i8 : i8
  %3 = comb.mux %b1, %2, %1 : i8
  %4 = comb.shl %3, %c1_i8 : i8
  %5 = comb.mux %b0, %4, %3 : i8

  // Contract inlined with ensure -> assert, require -> assume, %z -> %5.
  %c8_i8 = hw.constant 8 : i8
  %blt8 = comb.icmp ult %b, %c8_i8 : i8
  verif.assume %blt8
  %ashl = comb.shl %a, %b : i8
  verif.assert_equal %5, %ashl : i42
}
```

--------------------------------

### SystemVerilog Type Declaration Example

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/HW/RationaleHW.md

Illustrates how a type declaration is emitted as a SystemVerilog `typedef` statement. This is used for user-defined types.

```systemverilog
typedef logic mytype;
```

--------------------------------

### Build and Test CIRCT with Ninja

Source: https://github.com/llvm/circt/blob/main/AGENTS.md

Build all CIRCT targets using Ninja. For tool-specific builds, use the provided commands.

```bash
ninja -C build check-circt
```

```bash
ninja -C build bin/circt-opt
```

```bash
ninja -C build bin/firtool
```

--------------------------------

### Execute MLIR Function with handshake-runner

Source: https://github.com/llvm/circt/blob/main/docs/Tools/handshake-runner.md

This example shows how to convert an MLIR module to Handshake IR using circt-opt and then execute the converted module with handshake-runner. Provide the filename and any necessary arguments for the function.

```bash
circt-opt -create-dataflow <file-name>
handshake-runner <file-name> 2
```

--------------------------------

### Example: FIRRTL Register without Reset

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/Seq/RationaleSeq.md

Demonstrates a basic FIRRTL register with an input, clock, and symbol, but no reset or preset.

```mlir
%reg_no_reset = seq.firreg %input clock %clk sym @sym : i32
```

--------------------------------

### Example DontTouchAnnotation in JSON

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/FIRRTL/FIRRTLAnnotations.md

This JSON structure represents a DontTouchAnnotation, used to prevent compiler optimizations on a specific FIRRTL wire.

```json
{
  "class":"firrtl.transforms.DontTouchAnnotation",
  "target":"~MyCircuit|MyModule>foo"
}
```

--------------------------------

### Fetch and Configure CaDiCaL SAT Solver

Source: https://github.com/llvm/circt/blob/main/CMakeLists.txt

Fetches the CaDiCaL SAT solver from GitHub using FetchContent and configures it to be built as a static library. It also sets specific compile definitions and C++ standard.

```cmake
include(FetchContent)
  FetchContent_Declare(
    cadical
    GIT_REPOSITORY https://github.com/arminbiere/cadical.git
    GIT_TAG 7b99c07f0bcab5824a5a3ce62c7066554017f641
  )
  set(FETCHCONTENT_TRY_FIND_PACKAGE_MODE "NEVER")

  # Force CaDiCaL to be built as a static library.
  set(ORIGINAL_CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS})
  set(ORIGINAL_BUILD_SHARED_LIBS ${BUILD_SHARED_LIBS})

  set(BUILD_SHARED_LIBS OFF)
  FetchContent_GetProperties(cadical)
  if(NOT cadical_POPULATED)
    FetchContent_Populate(cadical)
  endif()
  file(STRINGS "${cadical_SOURCE_DIR}/VERSION" cadical_version LIMIT_COUNT 1)

  file(GLOB cadical_cpp_sources CONFIGURE_DEPENDS
    "${cadical_SOURCE_DIR}/src/*.cpp"
  )
  file(GLOB cadical_c_sources CONFIGURE_DEPENDS
    "${cadical_SOURCE_DIR}/src/*.c"
  )
  file(GLOB cadical_contrib_sources CONFIGURE_DEPENDS
    "${cadical_SOURCE_DIR}/contrib/*.cpp"
  )
  # Match upstream libcadical.a, which excludes the standalone solver and
  # model-based tester frontends from the library.
  list(REMOVE_ITEM cadical_cpp_sources
    "${cadical_SOURCE_DIR}/src/cadical.cpp"
    "${cadical_SOURCE_DIR}/src/mobical.cpp"
  )

  add_library(cadical STATIC
    ${cadical_cpp_sources}
    ${cadical_c_sources}
    ${cadical_contrib_sources}
  )

  # CaDiCaL supports non-make builds with NBUILD, which avoids generating
  # build.hpp and lets consumers include only cadical.hpp.
  target_compile_definitions(cadical PRIVATE
    NBUILD
    VERSION="${cadical_version}"
    DATE="reproducible build"
  )
  target_compile_features(cadical PUBLIC cxx_std_11)

  # Expose cadical.hpp under third_party/cadical/cadical.hpp for consumers.
  file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/include/third_party/cadical")
  file(COPY "${cadical_SOURCE_DIR}/src/cadical.hpp"
        DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/include/third_party/cadical")

  target_include_directories(cadical
    PUBLIC
      "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>"
    PRIVATE
      "${cadical_SOURCE_DIR}/src"
  )

  set(CMAKE_CXX_FLAGS ${ORIGINAL_CMAKE_CXX_FLAGS})
  set(BUILD_SHARED_LIBS ${ORIGINAL_BUILD_SHARED_LIBS})

  if(BUILD_SHARED_LIBS)
    set_target_properties(cadical PROPERTIES POSITION_INDEPENDENT_CODE ON)
  endif()

  set_property(GLOBAL APPEND PROPERTY CIRCT_EXPORTS cadical)
  install(TARGETS cadical EXPORT CIRCTTargets)
endif()
```

--------------------------------

### Add Python Packages to PYTHONPATH

Source: https://github.com/llvm/circt/blob/main/docs/PythonBindings.md

Configures the PYTHONPATH environment variable to allow Python to find generated modules without installation.

```bash
export PYTHONPATH="$PWD/llvm/build/tools/circt/python_packages/circt_core"
```

--------------------------------

### Unsigned Multiplication Example

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/HWArith/RationaleHWArith.md

Illustrates unsigned multiplication. The result type is the sum of the operand bitwidths to ensure all possible results are covered.

```mlir
%0 = hwarith.mul %10, %11 : (ui3, ui4) -> ui7
```

--------------------------------

### Run Tests with ninja

Source: https://github.com/llvm/circt/blob/main/docs/GettingStarted.md

Execute the project's test suite using `ninja check-mlir` or an alternative target that suits your changes. This step is crucial for verifying the integrity of your patch.

```bash
ninja check-mlir
```

--------------------------------

### FSM Transition Guard Example

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/FSM/RationaleFSM.md

Demonstrates how to use a guard region in an fsm.transition. The guard must return a boolean to indicate if the transition is taken. Guards cannot have side effects and are evaluated as true if empty.

```mlir
fsm.machine @foo(%arg0: i1) -> i1 attributes {stateType = i1} {
  fsm.state "IDLE" output  {
    %true = constant true
    fsm.output %true : i1
  }
  transitions  {
    fsm.transition @BUSY guard  {
      fsm.return %arg0 : i1
    }
  }
  ...
}
```

--------------------------------

### Mixed Subtraction Examples

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/HWArith/RationaleHWArith.md

Shows mixed-sign subtraction operations. The result type is signed and widened to accommodate the mixed operand types.

```mlir
%2 = hwarith.sub %14, %15 : (ui3, si4) -> si5
```

```mlir
%3 = hwarith.sub %16, %17 : (si4, ui6) -> si8
```

--------------------------------

### Example: FIRRTL Register with Preset Value

Source: https://github.com/llvm/circt/blob/main/docs/Dialects/Seq/RationaleSeq.md

Demonstrates a FIRRTL register that uses a constant preset value instead of a reset signal.

```mlir
%reg_preset = seq.firreg %next clock %clock preset 123 : i32
```