core
An abstract class for data types that solely consist of (are an aggregate of) other Data objects.
Data type for representing bidirectional bitvectors of a given width
Data type for representing bidirectional bitvectors of a given width
Analog support is limited to allowing wiring up of Verilog BlackBoxes with bidirectional (inout) pins. There is currently no support for reading or writing of Analog types within Chisel code.
Given that Analog is bidirectional, it is illegal to assign a direction to any Analog type. It is legal to "flip" the direction (since Analog can be a member of aggregate types) which has no effect.
Analog types are generally connected using the bidirectional attach mechanism, but also
support limited bulkconnect <>. Analog types are only allowed to be bulk connected *once* in a
given module. This is to prevent any surprising consequences of last connect semantics.
This API is experimental and subject to change
Abstract base class for Modules, an instantiable organizational unit for RTL.
Format bits as Binary
A Binder is a function from UnboundBinding to some Binding.
A Binder is a function from UnboundBinding to some Binding.
These are used exclusively by Binding.bind and sealed in order to keep all of them in one place. There are two flavors of Binders: Non-terminal (returns another UnboundBinding): These are used to reformat an UnboundBinding (like setting direction) before it is terminally bound. Terminal (returns any other Binding): Due to the nature of Bindings, once a Data is bound to anything but an UnboundBinding, it is forever locked to being that type (as it now represents something in the hardware graph).
Note that some Binders require extra arguments to be constructed, like the enclosing Module.
A data type for values represented by a single bitvector.
A data type for values represented by a single bitvector. Provides basic bitwise operations.
Defines a black box, which is a module that can be referenced from within Chisel, but is not defined in the emitted Verilog.
Defines a black box, which is a module that can be referenced from within Chisel, but is not defined in the emitted Verilog. Useful for connecting to RTL modules defined outside Chisel.
Some design require a differential input clock to clock the all design. With the xilinx FPGA for example, a Verilog template named IBUFDS must be integrated to use differential input:
IBUFDS #(.DIFF_TERM("TRUE"), .IOSTANDARD("DEFAULT")) ibufds ( .IB(ibufds_IB), .I(ibufds_I), .O(ibufds_O) );
To instantiate it, a BlackBox can be used like following:
import chisel3._ import chisel3.experimental._ // Example with Xilinx differential buffer IBUFDS class IBUFDS extends BlackBox(Map("DIFF_TERM" -> "TRUE", // Verilog parameters "IOSTANDARD" -> "DEFAULT" )) { val io = IO(new Bundle { val O = Output(Clock()) // IO names will be the same val I = Input(Clock()) // (without 'io_' in prefix) val IB = Input(Clock()) // }) }
The parameters API is experimental and may change
A data type for booleans, defined as a single bit indicating true or false.
Base class for data types defined as a bundle of other data types.
Base class for data types defined as a bundle of other data types.
Usage: extend this class (either as an anonymous or named class) and define members variables of Data subtypes to be elements in the Bundle.
Example of an anonymous IO bundle
class MyModule extends Module { val io = IO(new Bundle { val in = Input(UInt(64.W)) val out = Output(SInt(128.W)) }) }
Or as a named class
class Packet extends Bundle { val header = UInt(16.W) val addr = UInt(16.W) val data = UInt(32.W) } class MyModule extends Module { val io = IO(new Bundle { val inPacket = Input(new Packet) val outPacket = Output(new Packet) }) val reg = Reg(new Packet) reg <> inPacket outPacket <> reg }
Format bits as Character
This is a stand-in for the firrtl.Annotations.Annotation because at the time this annotation is created the component cannot be resolved, into a targetString.
This is a stand-in for the firrtl.Annotations.Annotation because at the time this annotation is created the component cannot be resolved, into a targetString. Resolution can only happen after the circuit is elaborated
A chisel thingy to be annotated, could be module, wire, reg, etc.
A fully-qualified class name of the transformation pass
A string value to be used by the transformation pass
This forms the root of the type system for wire data types.
This forms the root of the type system for wire data types. The data value must be representable as some number (need not be known at Chisel compile time) of bits, and must have methods to pack / unpack structured data to / from bits.
Format bits as Decimal
Element is a leaf data type: it cannot contain other Data objects.
Element is a leaf data type: it cannot contain other Data objects. Example uses are for representing primitive data types, like integers and bits.
Defines a black box, which is a module that can be referenced from within Chisel, but is not defined in the emitted Verilog.
Defines a black box, which is a module that can be referenced from within Chisel, but is not defined in the emitted Verilog. Useful for connecting to RTL modules defined outside Chisel.
A variant of BlackBox, this has a more consistent naming scheme in allowing multiple top-level IO and does not drop the top prefix.
Some design require a differential input clock to clock the all design. With the xilinx FPGA for example, a Verilog template named IBUFDS must be integrated to use differential input:
IBUFDS #(.DIFF_TERM("TRUE"), .IOSTANDARD("DEFAULT")) ibufds ( .IB(ibufds_IB), .I(ibufds_I), .O(ibufds_O) );
To instantiate it, a BlackBox can be used like following:
import chisel3._ import chisel3.experimental._ // Example with Xilinx differential buffer IBUFDS class IBUFDS extends ExtModule(Map("DIFF_TERM" -> "TRUE", // Verilog parameters "IOSTANDARD" -> "DEFAULT" )) { val O = IO(Output(Clock())) val I = IO(Input(Clock())) val IB = IO(Input(Clock())) }
The parameters API is experimental and may change
Superclass for Firrtl format specifiers for Bits
A sealed class representing a fixed point number that has a bit width and a binary point The width and binary point may be inferred.
A sealed class representing a fixed point number that has a bit width and a binary point The width and binary point may be inferred.
IMPORTANT: The API provided here is experimental and may change in the future.
Put full name within parent namespace (eg.
Put full name within parent namespace (eg. bundleName.field)
Format bits as Hexidecimal
Abstract base class for Modules, which behave much like Verilog modules.
Abstract base class for Modules, which behave much like Verilog modules. These may contain both logic and state which are written in the Module body (constructor).
Module instantiations must be wrapped in a Module() call.
Legacy Module class that restricts IOs to just io, clock, and reset, and provides a constructor for threading through explicit clock and reset.
Legacy Module class that restricts IOs to just io, clock, and reset, and provides a constructor for threading through explicit clock and reset.
While this class isn't planned to be removed anytime soon (there are benefits to restricting IO), the clock and reset constructors will be phased out. Recommendation is to wrap the module in a withClock/withReset/withClockAndReset block, or directly hook up clock or reset IO pins.
A combinational/asynchronous-read, sequential/synchronous-write memory.
A combinational/asynchronous-read, sequential/synchronous-write memory.
Writes take effect on the rising clock edge after the request. Reads are combinational (requests will return data on the same cycle). Read-after-write hazards are not an issue.
when multiple conflicting writes are performed on a Mem element, the result is undefined (unlike Vec, where the last assignment wins)
Put innermost name (eg.
Put innermost name (eg. field of bundle)
Abstract trait defining operations available on numeric-like wire data types.
Wrapper for printing Scala Strings
Parameters for BlackBoxes
Superclass of things that can be printed in the resulting circuit
Superclass of things that can be printed in the resulting circuit
Usually created using the custom string interpolator p"..." TODO Add support for names of Modules Currently impossible because unpack is called before the name is selected Could be implemented by adding a new format specifier to Firrtl (eg. %m) TODO Should we provide more functions like map and mkPrintable?
Use PrivateObject to force users to specify width and binaryPoint by name
Unquoted String
Base class for Aggregates based on key values pairs of String and Data
Base class for Aggregates based on key values pairs of String and Data
Record should only be extended by libraries and fairly sophisticated generators. RTL writers should use Bundle. See Record#elements for an example.
A sequential/synchronous-read, sequential/synchronous-write memory.
A sequential/synchronous-read, sequential/synchronous-write memory.
Writes take effect on the rising clock edge after the request. Reads return data on the rising edge after the request. Read-after-write behavior (when a read and write to the same address are requested on the same cycle) is undefined.
when multiple conflicting writes are performed on a Mem element, the result is undefined (unlike Vec, where the last assignment wins)
A data type for unsigned integers, represented as a binary bitvector.
A data type for unsigned integers, represented as a binary bitvector. Defines arithmetic operations between other integer types.
Abstract base class for Modules that contain Chisel RTL.
A vector (array) of Data elements.
A vector (array) of Data elements. Provides hardware versions of various collection transformation functions found in software array implementations.
Careful consideration should be given over the use of Vec vs Seq or some other scala collection. In general Vec only needs to be used when there is a need to express the hardware collection in a Reg or IO Bundle or when access to elements of the array is indexed via a hardware signal.
Example of indexing into a Vec using a hardware address and where the Vec is defined in an IO Bundle
val io = IO(new Bundle { val in = Input(Vec(20, UInt(16.W))) val addr = UInt(5.W) val out = Output(UInt(16.W)) }) io.out := io.in(io.addr)
type of elements
A trait for Vecs containing common hardware generators for collection operations.
Internal mechanism for generating a when.
Internal mechanism for generating a when. Because of the way FIRRTL commands are emitted, generating a FIRRTL elsewhen or nested whens inside elses would be difficult. Instead, this keeps track of the negative of the previous conditions, so when an elsewhen or otherwise is used, it checks that both the condition is true and all the previous conditions have been false.
These implicit classes allow one to convert scala.Int|scala.BigInt to Chisel.UInt|Chisel.SInt by calling .asUInt|.asSInt on them, respectively.
These implicit classes allow one to convert scala.Int|scala.BigInt to Chisel.UInt|Chisel.SInt by calling .asUInt|.asSInt on them, respectively. The versions .asUInt(width)|.asSInt(width) are also available to explicitly mark a width for the new literal.
Also provides .asBool to scala.Boolean and .asUInt to String
Note that, for stylistic reasons, one should avoid extracting immediately after this call using apply, ie. 0.asUInt(1)(0) due to potential for confusion (the 1 is a bit length and the 0 is a bit extraction position). Prefer storing the result and then extracting from it.
Implementation note: the empty parameter list (like U()) is necessary to prevent
interpreting calls that have a non-Width parameter as a chained apply, otherwise things like
0.asUInt(16) (instead of 16.W) compile without error and produce undesired results.
Object that provides factory methods for Analog objects
Object that provides factory methods for Analog objects
This API is experimental and subject to change
BiConnect.connect executes a bidirectional connection element-wise.
BiConnect.connect executes a bidirectional connection element-wise.
Note that the arguments are left and right (not source and sink) so the intent is for the operation to be commutative.
The connect operation will recurse down the left Data (with the right Data). An exception will be thrown if a movement through the left cannot be matched in the right (or if the right side has extra fields).
See elemConnect for details on how the root connections are issued.
The purpose of a Binding is to indicate what type of hardware 'entity' a specific Data's leaf Elements is actually bound to.
The purpose of a Binding is to indicate what type of hardware 'entity' a specific Data's leaf Elements is actually bound to. All Data starts as being Unbound (and the whole point of cloneType is to return an unbound version). Then, specific API calls take a Data, and return a bound version (either by binding the original model or cloneType then binding the clone). For example, Reg[T<:Data](...) returns a T bound to RegBinding.
It is considered invariant that all Elements of a single Data are bound to the same concrete type of Binding.
These bindings can be checked (e.g. checkSynthesizable) to make sure certain operations are valid. For example, arithemetic operations or connections can only be executed between synthesizable nodes. These checks are to avoid undefined reference errors.
Bindings can carry information about the particular element in the graph it represents like: - For ports (and unbound), the 'direction' - For (relevant) synthesizable nodes, the enclosing Module
TODO(twigg): Enrich the bindings to carry more information like the hosting module (when applicable), direction (when applicable), literal info (when applicable). Can ensure applicable data only stored on relevant nodes. e.g. literal info on LitBinding, direction info on UnboundBinding and PortBinding, etc.
TODO(twigg): Currently, bindings only apply at the Element level and an Aggregate is considered bound via its elements. May be appropriate to allow Aggregates to be bound along with the Elements. However, certain literal and port direction information doesn't quite make sense in aggregates. This would elegantly handle the empty Vec or Record problem though.
TODO(twigg): Binding is currently done via allElements. It may be more elegant if this was instead done as a more explicit tree walk as that allows for better errors.
Factory and convenience methods for the FixedPoint class IMPORTANT: The API provided here is experimental and may change in the future.
Input, Output, and Flipped are used to define the directions of Module IOs.
Input, Output, and Flipped are used to define the directions of Module IOs.
Note that they currently clone their source argument, including its bindings.
Thus, an error will be thrown if these are used on bound Data
MonoConnect.connect executes a mono-directional connection element-wise.
MonoConnect.connect executes a mono-directional connection element-wise.
Note that this isn't commutative. There is an explicit source and sink already determined before this function is called.
The connect operation will recurse down the left Data (with the right Data). An exception will be thrown if a movement through the left cannot be matched in the right. The right side is allowed to have extra Record fields. Vecs must still be exactly the same size.
See elemConnect for details on how the root connections are issued.
Note that a valid sink must be writable so, one of these must hold: - Is an internal writable node (Reg or Wire) - Is an output of the current module - Is an input of a submodule of the current module
Note that a valid source must be readable so, one of these must hold: - Is an internal readable node (Reg, Wire, Op) - Is a literal - Is a port of the current module or submodule of the current module
Represents escaped percents
(Since version chisel3) debug doesn't do anything in Chisel3 as no pruning happens in the frontend