Skip to main content

Deep Dive into Connection Operators

Chisel contains two connection operators, := and <>. This document provides a deeper explanation of the differences of the two and when to use one or the other. The differences are demonstrated with experiments using Scastie examples which use DecoupledIO.

Experiment Setup​

// Imports used by the following examples
import chisel3._
import chisel3.util.DecoupledIO

The diagram for the experiment can be viewed here. Experiment Image

class Wrapper extends Module{
  val io = IO(new Bundle {
  val in = Flipped(DecoupledIO(UInt(8.W)))
  val out = DecoupledIO(UInt(8.W))
  })
  val p = Module(new PipelineStage)
  val c = Module(new PipelineStage)
  // connect Producer to IO
  p.io.a <> io.in
  // connect producer to consumer
  c.io.a <> p.io.b
  // connect consumer to IO
  io.out <> c.io.b
}
class PipelineStage extends Module{
  val io = IO(new Bundle{
    val a = Flipped(DecoupledIO(UInt(8.W)))
    val b = DecoupledIO(UInt(8.W))
  })
  io.b <> io.a
}

Below we can see the resulting Verilog for this example:

// Generated by CIRCT firtool-1.99.1
module PipelineStage(
  output       io_a_ready,
  input        io_a_valid,
  input  [7:0] io_a_bits,
  input        io_b_ready,
  output       io_b_valid,
  output [7:0] io_b_bits
);

  assign io_a_ready = io_b_ready;
  assign io_b_valid = io_a_valid;
  assign io_b_bits = io_a_bits;
endmodule

module Wrapper(
  input        clock,
               reset,
  output       io_in_ready,
  input        io_in_valid,
  input  [7:0] io_in_bits,
  input        io_out_ready,
  output       io_out_valid,
  output [7:0] io_out_bits
);

  wire       _c_io_a_ready;
  wire       _p_io_b_valid;
  wire [7:0] _p_io_b_bits;
  PipelineStage p (
    .io_a_ready (io_in_ready),
    .io_a_valid (io_in_valid),
    .io_a_bits  (io_in_bits),
    .io_b_ready (_c_io_a_ready),
    .io_b_valid (_p_io_b_valid),
    .io_b_bits  (_p_io_b_bits)
  );
  PipelineStage c (
    .io_a_ready (_c_io_a_ready),
    .io_a_valid (_p_io_b_valid),
    .io_a_bits  (_p_io_b_bits),
    .io_b_ready (io_out_ready),
    .io_b_valid (io_out_valid),
    .io_b_bits  (io_out_bits)
  );
endmodule

Concept 1: <> is Commutative​

This experiment is set up to test for the function of <> using the experiment above.

Achieving this involves flipping the RHS and LHS of the <> operator and seeing how <> will react. ( Scastie link for the experiment:https://scastie.scala-lang.org/Shorla/LVhlbkFQQnq7X3trHfgZZQ )

import chisel3._
import chisel3.util.DecoupledIO

class Wrapper extends Module{
  val io = IO(new Bundle {
  val in = Flipped(DecoupledIO(UInt(8.W)))
  val out = DecoupledIO(UInt(8.W))
  })
  val p = Module(new PipelineStage)
  val c = Module(new PipelineStage)
  // connect producer to I/O
  io.in <> p.io.a
  // connect producer  to consumer
  p.io.b <> c.io.a
  // connect consumer to I/O
  c.io.b <> io.out
}
class PipelineStage extends Module{
  val io = IO(new Bundle{
    val a = Flipped(DecoupledIO(UInt(8.W)))
    val b = DecoupledIO(UInt(8.W))
  })
  io.a <> io.b
}

Below we can see the resulting Verilog for this example:

// Generated by CIRCT firtool-1.99.1
module PipelineStage(
  output       io_a_ready,
  input        io_a_valid,
  input  [7:0] io_a_bits,
  input        io_b_ready,
  output       io_b_valid,
  output [7:0] io_b_bits
);

  assign io_a_ready = io_b_ready;
  assign io_b_valid = io_a_valid;
  assign io_b_bits = io_a_bits;
endmodule

module Wrapper(
  input        clock,
               reset,
  output       io_in_ready,
  input        io_in_valid,
  input  [7:0] io_in_bits,
  input        io_out_ready,
  output       io_out_valid,
  output [7:0] io_out_bits
);

  wire       _c_io_a_ready;
  wire       _p_io_b_valid;
  wire [7:0] _p_io_b_bits;
  PipelineStage p (
    .io_a_ready (io_in_ready),
    .io_a_valid (io_in_valid),
    .io_a_bits  (io_in_bits),
    .io_b_ready (_c_io_a_ready),
    .io_b_valid (_p_io_b_valid),
    .io_b_bits  (_p_io_b_bits)
  );
  PipelineStage c (
    .io_a_ready (_c_io_a_ready),
    .io_a_valid (_p_io_b_valid),
    .io_a_bits  (_p_io_b_bits),
    .io_b_ready (io_out_ready),
    .io_b_valid (io_out_valid),
    .io_b_bits  (io_out_bits)
  );
endmodule

Conclusion:​

The Verilog remained the same without incurring errors, showing that the <> operator is commutative.

Concept 2: := means assign ALL LHS signals from the RHS, regardless of the direction on the LHS.​

Using the same experiment code as above, we set to test for the function of := We replace all instances of <> with := in the sample code above. (Scastie link to the experiment: https://scastie.scala-lang.org/Shorla/o1ShdaY3RWKf0IIFwwQ1UQ/1)

import chisel3._
import chisel3.util.DecoupledIO

class Wrapper extends Module{
  val io = IO(new Bundle {
  val in = Flipped(DecoupledIO(UInt(8.W)))
  val out = DecoupledIO(UInt(8.W))
  })
  val p = Module(new PipelineStage)
  val c = Module(new PipelineStage)
  // connect producer to I/O
  p.io.a := io.in
  // connect producer  to consumer
  c.io.a := p.io.b
  // connect consumer to I/O
  io.out := c.io.b
}
class PipelineStage extends Module{
  val io = IO(new Bundle{
    val a = Flipped(DecoupledIO(UInt(8.W)))
    val b = DecoupledIO(UInt(8.W))
  })
  io.a := io.b
}

Below we can see the resulting error message for this example:

circt.stage.ChiselStage.emitSystemVerilog(new Wrapper)
// chisel3.package$ChiselException: Connection between sink (PipelineStage.io.a: IO[DecoupledIO]) and source (PipelineStage.io.b: IO[DecoupledIO]) failed @: .bitsio.a.bits in PipelineStage cannot be written from module PipelineStage.
// 	at ... ()
// 	at repl.MdocSession$MdocApp3$PipelineStage.<init>(connection-operators.md:124)
// 	at repl.MdocSession$MdocApp3$Wrapper$$anonfun$30$$anonfun$apply$20.apply(connection-operators.md:108)
// 	at repl.MdocSession$MdocApp3$Wrapper$$anonfun$30$$anonfun$apply$20.apply(connection-operators.md:108)
// 	at chisel3.ObjectModuleImpl.evaluate(ModuleImpl.scala:97)
// 	at chisel3.ObjectModuleImpl.evaluate$(ModuleImpl.scala:63)
// 	at chisel3.Module$.evaluate(Module.scala:10)
// 	at chisel3.ObjectModuleImpl._applyImpl(ModuleImpl.scala:36)
// 	at chisel3.ObjectModuleImpl._applyImpl$(ModuleImpl.scala:34)
// 	at chisel3.Module$._applyImpl(Module.scala:10)
// 	at chisel3.Module$.do_apply(Module.scala:22)
// 	at repl.MdocSession$MdocApp3$Wrapper$$anonfun$30.apply(connection-operators.md:108)
// 	at repl.MdocSession$MdocApp3$Wrapper$$anonfun$30.apply(connection-operators.md:108)
// 	at chisel3.internal.plugin.package$.autoNameRecursively(package.scala:33)
// 	at repl.MdocSession$MdocApp3$Wrapper.<init>(connection-operators.md:108)
// 	at repl.MdocSession$MdocApp3$$anonfun$39$$anonfun$apply$25.apply(connection-operators.md:132)
// 	at repl.MdocSession$MdocApp3$$anonfun$39$$anonfun$apply$25.apply(connection-operators.md:132)
// 	at chisel3.ObjectModuleImpl.evaluate(ModuleImpl.scala:97)
// 	at chisel3.ObjectModuleImpl.evaluate$(ModuleImpl.scala:63)
// 	at chisel3.Module$.evaluate(Module.scala:10)
// 	at chisel3.ObjectModuleImpl._applyImpl(ModuleImpl.scala:36)
// 	at chisel3.ObjectModuleImpl._applyImpl$(ModuleImpl.scala:34)
// 	at chisel3.Module$._applyImpl(Module.scala:10)
// 	at chisel3.Module$.do_apply(Module.scala:22)
// 	at chisel3.stage.phases.Elaborate.$anonfun$transform$2(Elaborate.scala:58)
// 	at chisel3.internal.Builder$.$anonfun$buildImpl$1(Builder.scala:1090)
// 	at scala.util.DynamicVariable.withValue(DynamicVariable.scala:59)
// 	at chisel3.internal.Builder$.buildImpl(Builder.scala:1080)
// 	at chisel3.internal.Builder$.$anonfun$build$1(Builder.scala:1072)
// 	at logger.Logger$.$anonfun$makeScope$4(Logger.scala:148)
// 	at scala.util.DynamicVariable.withValue(DynamicVariable.scala:59)
// 	at logger.Logger$.makeScope(Logger.scala:146)
// 	at logger.Logger$.makeScope(Logger.scala:133)
// 	at ... ()
// 	at ... (Stack trace trimmed to user code only. Rerun with --full-stacktrace to see the full stack trace)

Conclusion:​

The := operator goes field-by-field on the LHS and attempts to connect it to the same-named signal from the RHS. If something on the LHS is actually an Input, or the corresponding signal on the RHS is an Output, you will get an error as shown above.

Concept 3: Always Use := to assign DontCare to Wires​

When assigning DontCare to something that is not directioned, should you use := or <>? We will find out using the sample codes below: ( Scastie link for the experiment:https://scastie.scala-lang.org/Shorla/ZIGsWcylRqKJhZCkKWlSIA/1)

import chisel3._
import chisel3.util.DecoupledIO

class Wrapper extends Module{
  val io = IO(new Bundle {
  val in = Flipped(DecoupledIO(UInt(8.W)))
  val out = DecoupledIO(UInt(8.W))
  })
  val p = Module(new PipelineStage)
  val c = Module(new PipelineStage)
  //connect Producer to IO
  io.in := DontCare
  p.io.a <> DontCare
  val tmp = Wire(Flipped(DecoupledIO(UInt(8.W))))
  tmp := DontCare
  p.io.a <> io.in
  // connect producer to consumer
  c.io.a <> p.io.b
  //connect consumer to IO
  io.out <> c.io.b
}
class PipelineStage extends Module{
  val io = IO(new Bundle{
    val a = Flipped(DecoupledIO(UInt(8.W)))
    val b = DecoupledIO(UInt(8.W))
  })
  io.b <> io.a
}

Below we can see the resulting Verilog for this example:

// Generated by CIRCT firtool-1.99.1
module PipelineStage(
  output       io_a_ready,
  input        io_a_valid,
  input  [7:0] io_a_bits,
  input        io_b_ready,
  output       io_b_valid,
  output [7:0] io_b_bits
);

  assign io_a_ready = io_b_ready;
  assign io_b_valid = io_a_valid;
  assign io_b_bits = io_a_bits;
endmodule

module Wrapper(
  input        clock,
               reset,
  output       io_in_ready,
  input        io_in_valid,
  input  [7:0] io_in_bits,
  input        io_out_ready,
  output       io_out_valid,
  output [7:0] io_out_bits
);

  wire       _c_io_a_ready;
  wire       _p_io_b_valid;
  wire [7:0] _p_io_b_bits;
  PipelineStage p (
    .io_a_ready (io_in_ready),
    .io_a_valid (io_in_valid),
    .io_a_bits  (io_in_bits),
    .io_b_ready (_c_io_a_ready),
    .io_b_valid (_p_io_b_valid),
    .io_b_bits  (_p_io_b_bits)
  );
  PipelineStage c (
    .io_a_ready (_c_io_a_ready),
    .io_a_valid (_p_io_b_valid),
    .io_a_bits  (_p_io_b_bits),
    .io_b_ready (io_out_ready),
    .io_b_valid (io_out_valid),
    .io_b_bits  (io_out_bits)
  );
endmodule

Conclusion:​

If <> were used to assign the unidrectioned wire tmp to DontCare, we would get an error. But in the example above, we used := and no errors occurred. But when := was used to assign the wire to DontCare, no errors will occur.

Thus, when assigning DontCare to a Wire, always use :=.

Concept 4: You can use <> or := to assign DontCare to directioned things (IOs)​

When assigning DontCare to something that is directioned, should you use := or <>? We will find out using the sample codes below: ( Scastie link for the experiment:https://scastie.scala-lang.org/Shorla/ZIGsWcylRqKJhZCkKWlSIA/1)

import chisel3._
import chisel3.util.DecoupledIO

class Wrapper extends Module{
  val io = IO(new Bundle {
  val in = Flipped(DecoupledIO(UInt(8.W)))
  val out = DecoupledIO(UInt(8.W))
  })
  val p = Module(new PipelineStage)
  val c = Module(new PipelineStage)
  //connect Producer to IO
  io.in := DontCare
  p.io.a <> DontCare
  val tmp = Wire(Flipped(DecoupledIO(UInt(8.W))))
  tmp := DontCare
  p.io.a <> io.in
  // connect producer to consumer
  c.io.a <> p.io.b
  //connect consumer to IO
  io.out <> c.io.b
}
class PipelineStage extends Module{
  val io = IO(new Bundle{
    val a = Flipped(DecoupledIO(UInt(8.W)))
    val b = DecoupledIO(UInt(8.W))
  })
  io.b <> io.a
}

Below we can see the resulting Verilog for this example:

// Generated by CIRCT firtool-1.99.1
module PipelineStage(
  output       io_a_ready,
  input        io_a_valid,
  input  [7:0] io_a_bits,
  input        io_b_ready,
  output       io_b_valid,
  output [7:0] io_b_bits
);

  assign io_a_ready = io_b_ready;
  assign io_b_valid = io_a_valid;
  assign io_b_bits = io_a_bits;
endmodule

module Wrapper(
  input        clock,
               reset,
  output       io_in_ready,
  input        io_in_valid,
  input  [7:0] io_in_bits,
  input        io_out_ready,
  output       io_out_valid,
  output [7:0] io_out_bits
);

  wire       _c_io_a_ready;
  wire       _p_io_b_valid;
  wire [7:0] _p_io_b_bits;
  PipelineStage p (
    .io_a_ready (io_in_ready),
    .io_a_valid (io_in_valid),
    .io_a_bits  (io_in_bits),
    .io_b_ready (_c_io_a_ready),
    .io_b_valid (_p_io_b_valid),
    .io_b_bits  (_p_io_b_bits)
  );
  PipelineStage c (
    .io_a_ready (_c_io_a_ready),
    .io_a_valid (_p_io_b_valid),
    .io_a_bits  (_p_io_b_bits),
    .io_b_ready (io_out_ready),
    .io_b_valid (io_out_valid),
    .io_b_bits  (io_out_bits)
  );
endmodule

Conclusion:​

Both <> and := can be used to assign directioned things (IOs) to DontCare as shown in io.in and p.io.a respectively. This is basically equivalent because in this case both <> and := will determine the direction from the LHS.

Concept 5: <> works between things with at least one known flow (An IO or child's IO).​

If there is at least one known flow what will <> do? This will be shown using the experiment code below: ( Scastie link for the experiment:https://scastie.scala-lang.org/Shorla/gKx9ReLVTTqDTk9vmw5ozg)

import chisel3._
import chisel3.util.DecoupledIO

class Wrapper extends Module{
  val io = IO(new Bundle {
  val in = Flipped(DecoupledIO(UInt(8.W)))
  val out = DecoupledIO(UInt(8.W))
  })
  val p = Module(new PipelineStage)
  val c = Module(new PipelineStage)
  //connect Producer to IO
    // For this experiment, we add a temporary wire and see if it works...
  //p.io.a <> io.in
  val tmp = Wire(DecoupledIO(UInt(8.W)))
  // connect intermediate wire
  tmp <> io.in
  p.io.a <> tmp
  // connect producer to consumer
  c.io.a <> p.io.b
  //connect consumer to IO
  io.out <> c.io.b
}
class PipelineStage extends Module{
  val io = IO(new Bundle{
    val a = Flipped(DecoupledIO(UInt(8.W)))
    val b = DecoupledIO(UInt(8.W))
  })
  io.b <> io.a
}

Below we can see the resulting Verilog for this example:

chisel3.docs.emitSystemVerilog(new Wrapper)
// res9: String = """// Generated by CIRCT firtool-1.99.1
// module PipelineStage(
//   output       io_a_ready,
//   input        io_a_valid,
//   input  [7:0] io_a_bits,
//   input        io_b_ready,
//   output       io_b_valid,
//   output [7:0] io_b_bits
// );
// 
//   assign io_a_ready = io_b_ready;
//   assign io_b_valid = io_a_valid;
//   assign io_b_bits = io_a_bits;
// endmodule
// 
// module Wrapper(
//   input        clock,
//                reset,
//   output       io_in_ready,
//   input        io_in_valid,
//   input  [7:0] io_in_bits,
//   input        io_out_ready,
//   output       io_out_valid,
//   output [7:0] io_out_bits
// );
// 
//   wire       _c_io_a_ready;
//   wire       _p_io_b_valid;
//   wire [7:0] _p_io_b_bits;
//   PipelineStage p (
//     .io_a_ready (io_in_ready),
//     .io_a_valid (io_in_valid),
//     .io_a_bits  (io_in_bits),
//     .io_b_ready (_c_io_a_ready),
//     .io_b_valid (_p_io_b_valid),
//     .io_b_bits  (_p_io_b_bits)
//   );
//   PipelineStage c (
//     .io_a_ready (_c_io_a_ready),
//     .io_a_valid (_p_io_b_valid),
//     .io_a_bits  (_p_io_b_bits),
//     .io_b_ready (io_out_ready),
//     .io_b_valid (io_out_valid),
//     .io_b_bits  (io_out_bits)
//   );
// endmodule
// 
// """

Conclusion:​

The connection above went smoothly with no errors, this goes to show <> will work as long as there is at least one directioned thing (IO or submodule's IO) to "fix" the direction.

Concept 6: <> and := connect signals by field name.​

This experiment creates a MockDecoupledIO which has the same fields by name as a DecoupledIO. Chisel lets us connect it and produces the same verilog, even though MockDecoupledIO and DecoupledIO are different types. ( Scastie link for the experiment:https://scastie.scala-lang.org/Uf4tQquvQYigZAW705NFIQ)

import chisel3._
import chisel3.util.DecoupledIO

class MockDecoupledIO extends Bundle {
  val valid = Output(Bool())
  val ready = Input(Bool())
  val bits = Output(UInt(8.W))
}
class Wrapper extends Module{
  val io = IO(new Bundle {
  val in = Flipped(new MockDecoupledIO())
  val out = new MockDecoupledIO()
  })
  val p = Module(new PipelineStage)
  val c = Module(new PipelineStage)
  // connect producer to I/O
  p.io.a <> io.in
  // connect producer  to consumer
  c.io.a <> p.io.b
  // connect consumer to I/O
  io.out <> c.io.b
}
class PipelineStage extends Module{
  val io = IO(new Bundle{
    val a = Flipped(DecoupledIO(UInt(8.W)))
    val b = DecoupledIO(UInt(8.W))
  })
  io.a <> io.b
}

Below we can see the resulting Verilog for this example:

// Generated by CIRCT firtool-1.99.1
module PipelineStage(
  output       io_a_ready,
  input        io_a_valid,
  input  [7:0] io_a_bits,
  input        io_b_ready,
  output       io_b_valid,
  output [7:0] io_b_bits
);

  assign io_a_ready = io_b_ready;
  assign io_b_valid = io_a_valid;
  assign io_b_bits = io_a_bits;
endmodule

module Wrapper(
  input        clock,
               reset,
               io_in_valid,
  output       io_in_ready,
  input  [7:0] io_in_bits,
  output       io_out_valid,
  input        io_out_ready,
  output [7:0] io_out_bits
);

  wire       _c_io_a_ready;
  wire       _p_io_b_valid;
  wire [7:0] _p_io_b_bits;
  PipelineStage p (
    .io_a_ready (io_in_ready),
    .io_a_valid (io_in_valid),
    .io_a_bits  (io_in_bits),
    .io_b_ready (_c_io_a_ready),
    .io_b_valid (_p_io_b_valid),
    .io_b_bits  (_p_io_b_bits)
  );
  PipelineStage c (
    .io_a_ready (_c_io_a_ready),
    .io_a_valid (_p_io_b_valid),
    .io_a_bits  (_p_io_b_bits),
    .io_b_ready (io_out_ready),
    .io_b_valid (io_out_valid),
    .io_b_bits  (io_out_bits)
  );
endmodule

And here is another experiment, where we remove one of the fields of MockDecoupledIO: ( Scastie link for the experiment:https://scastie.scala-lang.org/ChtkhKCpS9CvJkjjqpdeIA)

import chisel3._
import chisel3.util.DecoupledIO

class MockDecoupledIO extends Bundle {
  val valid = Output(Bool())
  val ready = Input(Bool())
  //val bits = Output(UInt(8.W))
}
class Wrapper extends Module{
  val io = IO(new Bundle {
  val in = Flipped(new MockDecoupledIO())
  val out = new MockDecoupledIO()
  })
  val p = Module(new PipelineStage)
  val c = Module(new PipelineStage)
  // connect producer to I/O
  p.io.a <> io.in
  // connect producer  to consumer
  c.io.a <> p.io.b
  // connect consumer to I/O
  io.out <> c.io.b
}
class PipelineStage extends Module{
  val io = IO(new Bundle{
    val a = Flipped(DecoupledIO(UInt(8.W)))
    val b = DecoupledIO(UInt(8.W))
  })
  io.a <> io.b
}

Below we can see the resulting error for this example:

circt.stage.ChiselStage.emitSystemVerilog(new Wrapper)
// chisel3.package$ChiselException: Connection between left (PipelineStage.io.a: IO[DecoupledIO]) and source (Wrapper.io.in: IO[MockDecoupledIO]) failed @.bits: Right Record missing field (bits).
// 	at ... ()
// 	at repl.MdocSession$MdocApp12$Wrapper.<init>(connection-operators.md:357)
// 	at repl.MdocSession$MdocApp12$$anonfun$119$$anonfun$apply$79.apply(connection-operators.md:378)
// 	at repl.MdocSession$MdocApp12$$anonfun$119$$anonfun$apply$79.apply(connection-operators.md:378)
// 	at chisel3.ObjectModuleImpl.evaluate(ModuleImpl.scala:97)
// 	at chisel3.ObjectModuleImpl.evaluate$(ModuleImpl.scala:63)
// 	at chisel3.Module$.evaluate(Module.scala:10)
// 	at chisel3.ObjectModuleImpl._applyImpl(ModuleImpl.scala:36)
// 	at chisel3.ObjectModuleImpl._applyImpl$(ModuleImpl.scala:34)
// 	at chisel3.Module$._applyImpl(Module.scala:10)
// 	at chisel3.Module$.do_apply(Module.scala:22)
// 	at chisel3.stage.phases.Elaborate.$anonfun$transform$2(Elaborate.scala:58)
// 	at chisel3.internal.Builder$.$anonfun$buildImpl$1(Builder.scala:1090)
// 	at scala.util.DynamicVariable.withValue(DynamicVariable.scala:59)
// 	at chisel3.internal.Builder$.buildImpl(Builder.scala:1080)
// 	at chisel3.internal.Builder$.$anonfun$build$1(Builder.scala:1072)
// 	at logger.Logger$.$anonfun$makeScope$4(Logger.scala:148)
// 	at scala.util.DynamicVariable.withValue(DynamicVariable.scala:59)
// 	at logger.Logger$.makeScope(Logger.scala:146)
// 	at logger.Logger$.makeScope(Logger.scala:133)
// 	at ... ()
// 	at ... (Stack trace trimmed to user code only. Rerun with --full-stacktrace to see the full stack trace)

This one fails because there is a field bits missing.

Conclusion:​

For :=, the Scala types do not need to match but all the signals on the LHS must be provided by the RHS or you will get a Chisel elaboration error. There may be additional signals on the RHS, these will be ignored. For <>, the Scala types do not need to match, but all signals must match exactly between LHS and RHS. In both cases, the order of the fields does not matter.