diff --git a/docs/Dialects/FIRRTL/FIRRTLIntrinsics.md b/docs/Dialects/FIRRTL/FIRRTLIntrinsics.md index 3c64e533dbf4..fe07dce59d0c 100644 --- a/docs/Dialects/FIRRTL/FIRRTLIntrinsics.md +++ b/docs/Dialects/FIRRTL/FIRRTLIntrinsics.md @@ -3,7 +3,7 @@ Intrinsics provide an implementation-specific way to extend the FIRRTL language with new operations. -Intrinsics are currently implemented as `intmodule`'s. +[TOC] ## Motivation @@ -14,19 +14,18 @@ and type checking. ## Supported Intrinsics - ### circt_sizeof Returns the size of a type. The input port is not read from and may be any type, including uninferred types. -| Parameter | Type | Description | -| ---------- | ------ | ------------- | +| Argument | Type | Description | +| -------- | ---- | ------------------------------------------ | +| i | Any | value whose type's size is to be returned | -| Port | Direction | Type | Description | -| ---------- | --------- | -------- | ----------------------------------- | -| i | input | Any | value whose type is to be returned | -| size | output | UInt<32> | Size of type of i | +| Result | Type | Description | +| ------ | -------- | ----------------- | +| size | UInt<32> | Size of type of i | ### circt_isX @@ -34,13 +33,13 @@ Tests if the value is a literal `x`. FIRRTL doesn't have a notion of 'x per-se, but x can come in to the system from external modules and from SV constructs. Verification constructs need to explicitly test for 'x. -| Parameter | Type | Description | -| ---------- | ------ | ------------- | +| Argument | Type | Description | +| -------- | ---- | ------------- | +| i | Any | value to test | -| Port | Direction | Type | Description | -| ---------- | --------- | -------- | ----------------------------------- | -| i | input | Any | value test | -| found | output | UInt<1> | i is `x` | +| Result | Type | Description | +| ------ | ------- | ----------- | +| found | UInt<1> | i is `x` | ### circt_plusargs_value @@ -50,27 +49,27 @@ Tests and extracts a value from simulator command line options with SystemVerilo We do not currently check that the format string substitution flag matches the type of the result. -| Parameter | Type | Description | -| ---------- | ------ | ------------- | -| FORMAT | string | Format string per SV 21.6 | +| Parameter | Type | Description | +| --------- | ------ | ------------- | +| FORMAT | string | Format string per SV 21.6 | -| Port | Direction | Type | Description | -| ---------- | --------- | -------- | ----------------------------------- | -| found | output | UInt<1> | found in args | -| result | output | AnyType | found in args | +| Result | Type | Description | +| ------- | ------- | --------------------- | +| found | UInt<1> | found in args | +| result | AnyType | value of the argument | ### circt_plusargs_test Tests simulator command line options with SystemVerilog `$test$plusargs`. This is described in SystemVerilog 2012 section 21.6. -| Parameter | Type | Description | -| ---------- | ------ | ------------- | -| FORMAT | string | Format string per SV 21.6 | +| Parameter | Type | Description | +| --------- | ------ | ------------------------- | +| FORMAT | string | Format string per SV 21.6 | -| Port | Direction | Type | Description | -| ---------- | --------- | -------- | ----------------------------------- | -| found | output | UInt<1> | found in args | +| Result | Type | Description | +| ------ | ------- | ------------- | +| found | UInt<1> | found in args | ### circt_clock_gate @@ -78,14 +77,14 @@ Enables and disables a clock safely, without glitches, based on a boolean enable The enable input is sampled at the rising edge of the input clock; any changes on the enable before or after that edge are ignored and do not affect the output clock. -| Parameter | Type | Description | -| --------- | ---- | ----------- | +| Argument | Type | Description | +| -------- | ------- | --------------------------- | +| in | Clock | input clock | +| en | UInt<1> | enable for the output clock | -| Port | Direction | Type | Description | -| ---- | --------- | -------- | --------------------------- | -| in | input | Clock | input clock | -| en | input | UInt<1> | enable for the output clock | -| out | output | Clock | gated output clock | +| Result | Type | Description | +| ------ | ----- | ------------------ | +| out | Clock | gated output clock | ### circt_chisel_assert @@ -97,12 +96,12 @@ Generate a clocked SV assert statement, with optional formatted error message. | label | string | Label for assert/assume. Optional. | | guards | string | Semicolon-delimited list of pre-processor tokens to use as ifdef guards. Optional. | -| Port | Direction | Type | Description | -| --------- | --------- | -------- | -------------------------- | -| clock | input | Clock | input clock | -| predicate | input | UInt<1> | predicate to assert/assume | -| enable | input | UInt<1> | enable signal | -| ... | input | Signals | arguments to format string | +| Argument | Type | Description | +| --------- | ------- | -------------------------- | +| clock | Clock | input clock | +| predicate | UInt<1> | predicate to assert/assume | +| enable | UInt<1> | enable signal | +| ... | Signals | arguments to format string | Example output: ```systemverilog @@ -123,12 +122,12 @@ Has legacy special behavior and should not be used by new code. This intrinsic also accepts the `label` and `guard` parameters which are recorded but not used in the normal emission. -| Port | Direction | Type | Description | -| --------- | --------- | -------- | --------------------------- | -| clock | input | Clock | input clock | -| predicate | input | UInt<1> | predicate to check | -| enable | input | UInt<1> | enable signal | -| ... | input | Signals | arguments to format string | +| Argument | Type | Description | +| --------- | ------- | -------------------------- | +| clock | Clock | input clock | +| predicate | UInt<1> | predicate to check | +| enable | UInt<1> | enable signal | +| ... | Signals | arguments to format string | Example SV output: ```systemverilog @@ -155,12 +154,12 @@ Generate a clocked SV assume statement, with optional formatted error message. | label | string | Label for assume statement. Optional. | | guards | string | Semicolon-delimited list of pre-processor tokens to use as ifdef guards. Optional. | -| Port | Direction | Type | Description | -| --------- | --------- | -------- | -------------------------- | -| clock | input | Clock | input clock | -| predicate | input | UInt<1> | predicate to assume | -| enable | input | UInt<1> | enable signal | -| ... | input | Signals | arguments to format string | +| Argument | Type | Description | +| --------- | ------- | -------------------------- | +| clock | Clock | input clock | +| predicate | UInt<1> | predicate to assume | +| enable | UInt<1> | enable signal | +| ... | Signals | arguments to format string | Example SV output: ```systemverilog @@ -176,11 +175,11 @@ Generate a clocked SV cover statement. | label | string | Label for cover statement. Optional. | | guards | string | Semicolon-delimited list of pre-processor tokens to use as ifdef guards. Optional. | -| Port | Direction | Type | Description | -| --------- | --------- | -------- | ------------------ | -| clock | input | Clock | input clock | -| predicate | input | UInt<1> | predicate to cover | -| enable | input | UInt<1> | enable signal | +| Argument | Type | Description | +| --------- | ------- | ------------------ | +| clock | Clock | input clock | +| predicate | UInt<1> | predicate to cover | +| enable | UInt<1> | enable signal | Example SV output: ```systemverilog @@ -191,18 +190,17 @@ cover__label: cover property (@(posedge clock) enable & cond); Generate a SV assume statement whose predicate is used in a sensitivity list of the enclosing always block. - | Parameter | Type | Description | | --------- | ------ | ----------------------------------------------------------------------------------- | | format | string | Format string per SV 20.10, 21.2.1. Optional. | | label | string | Label for assume statement. Optional. | | guards | string | Semicolon-delimited list of pre-processor tokens to use as ifdef guards. Optional. | -| Port | Direction | Type | Description | -| --------- | --------- | -------- | -------------------------- | -| predicate | input | UInt<1> | predicate to assume | -| enable | input | UInt<1> | enable signal | -| ... | input | Signals | arguments to format string | +| Argument | Type | Description | +| --------- | ------- | -------------------------- | +| predicate | UInt<1> | predicate to assume | +| enable | UInt<1> | enable signal | +| ... | Signals | arguments to format string | Example SV output: ```systemverilog @@ -238,14 +236,18 @@ not called. Hence their values will not be modify in that clock. | outputName | string | Output name. Optional. | -| Port | Direction | Type | Description | -| ----------------- | --------- | -------- | ------------------------------- | -| clock (optional) | input | Clock | Optional clock operand | -| enable | input | UInt<1> | Enable signal | -| ... | input | Signals | Arguments to DPI function call | -| result (optional) | output | Signal | Optional result of the dpi call | +| Argument | Type | Description | +| ---------------- | ------- | ------------------------------ | +| clock (optional) | Clock | Optional clock operand | +| enable | UInt<1> | Enable signal | +| ... | Signals | Arguments to DPI function call | + +| Result | Type | Description | +| ----------------- | ------ | ------------------------------- | +| result (optional) | Signal | Optional result of the dpi call | + +#### DPI Intrinsic ABI -##### DPI Intrinsic ABI Function Declaration: * Imported DPI function must be a void function that has input arguments which correspond to operand types, and an output argument which correspond to a result type. * Output argument must be a last argument. @@ -296,14 +298,14 @@ This will become a SystemVerilog Interface that is driven by its arguments. This is _not_ a true SystemVerilog Interface, it is only lowered to one. -| Parameter | Type | Description | -| ------------- | ------ | --------------------------------------------------- | -| name | string | Instance name of the view. | -| info | string | JSON encoding the view structure. | +| Parameter | Type | Description | +| --------- | ------ | --------------------------------- | +| name | string | Instance name of the view. | +| info | string | JSON encoding the view structure. | -| Port | Direction | Type | Description | -| ---------- | --------- | -------- | ----------------------------------- | -| ... | input | Ground | Leaf ground values for the view | +| Argument | Type | Description | +| -------- | ------ | ------------------------------- | +| ... | Ground | Leaf ground values for the view | The structure of the view is encoded using JSON, with the top-level object required to be an `AugmentedBundleType`. @@ -353,9 +355,9 @@ endinterface #### AugmentedGroundType -| Property | Type | Description | -| ---------- | ------ | ------------- | -| class | string | `sifive.enterprise.grandcentral.AugmentedGroundType` | +| Property | Type | Description | +| -------- | ------ | ---------------------------------------------------- | +| class | string | `sifive.enterprise.grandcentral.AugmentedGroundType` | Creates a SystemVerilog logic type. @@ -370,10 +372,10 @@ Example: #### AugmentedVectorType -| Property | Type | Description | -| ---------- | ------ | ------------- | -| class | string | `sifive.enterprise.grandcentral.AugmentedVectorType` | -| elements | array | List of augmented types. | +| Property | Type | Description | +| -------- | ------ | ---------------------------------------------------- | +| class | string | `sifive.enterprise.grandcentral.AugmentedVectorType` | +| elements | array | List of augmented types. | Creates a SystemVerilog unpacked array. @@ -395,7 +397,7 @@ Example: #### AugmentedField | Property | Type | Description | -| ---------- | ------ | ------------- | +| ----------- | ------ | ---------------------------------- | | name | string | Name of the field | | description | string | A textual description of this type | | tpe | string | A nested augmented type | @@ -405,10 +407,10 @@ what the field in the bundle is. #### AugmentedBundleType -| Property | Type | Description | -| ---------- | ------ | ------------- | -| class | string | sifive.enterprise.grandcentral.AugmentedBundleType | -| defName | string | The name of the SystemVerilog interface. May be renamed. | -| elements | array | List of AugmentedFields | +| Property | Type | Description | +| -------- | ------ | --------------------------------------------------------- | +| class | string | sifive.enterprise.grandcentral.AugmentedBundleType | +| defName | string | The name of the SystemVerilog interface. May be renamed. | +| elements | array | List of AugmentedFields | Creates a SystemVerilog interface for each bundle type. diff --git a/docs/Dialects/FIRRTL/RationaleFIRRTL.md b/docs/Dialects/FIRRTL/RationaleFIRRTL.md index 1efaa14394d8..0a61ec9e2f64 100644 --- a/docs/Dialects/FIRRTL/RationaleFIRRTL.md +++ b/docs/Dialects/FIRRTL/RationaleFIRRTL.md @@ -4,6 +4,8 @@ This document describes various design points of the FIRRTL dialect, why it is the way it is, and current status and progress. This follows in the spirit of other [MLIR Rationale docs](https://mlir.llvm.org/docs/Rationale/). +[TOC] + ## Introduction [The FIRRTL project](https://github.com/chipsalliance/firrtl) is an existing