Skip to content

Commit

Permalink
[docs] Minor updates to FIRRTL intrinsics docs
Browse files Browse the repository at this point in the history 
Remove mention of `intmodule` since FIRRTL intrinsics are now primarily
handled through the generic intrinsic expression and statement in
FIRRTL.

Add a table of contents.

Split the ports tables into arguments and results to more closely
reflect how the generic intrinsics work. Also remove empty parameter
tables.

Also add a table of contents to the FIRRTL rationale.
  • Loading branch information
@fabianschuiki
fabianschuiki committed Feb 5, 2025
1 parent a91040b commit 3ef66cf
Show file tree
Hide file tree
Showing 2 changed files with 94 additions and 90 deletions.
182 changes: 92 additions & 90 deletions docs/Dialects/FIRRTL/FIRRTLIntrinsics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -14,33 +14,32 @@ 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

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

Expand All @@ -50,42 +49,42 @@ 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

Enables and disables a clock safely, without glitches, based on a boolean enable value. If the enable input is 1, the output clock produced by the clock gate is identical to the input clock. If the enable input is 0, the output clock is a constant zero.

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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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 |
Expand All @@ -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.
2 changes: 2 additions & 0 deletions docs/Dialects/FIRRTL/RationaleFIRRTL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 3ef66cf

Please sign in to comment.