From 51a68cff32350372b9697347bea9586cd06f668d Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Mon, 11 Jul 2022 17:12:10 -0700 Subject: [PATCH 01/12] Add subword assignment to spec (bit-index expression) --- spec.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/spec.md b/spec.md index 7aeb1212..7958ad84 100644 --- a/spec.md +++ b/spec.md @@ -1840,6 +1840,26 @@ module MyModule : out[4] <= in ``` +## Bit-indices + +The bit-index expression statically refers, by index, to a particular bit of an +expression with an integer type (`UInt` or `SInt`). The index must be a +non-negative integer and cannot be equal to or exceed the width of the integer +it indexes. The bit-index must be connected to a value of type `UInt<1>` and +can only be used as a sink. In order to get a particular bit of an integer +expression as a source, use the `bits` primitive operation (see +[@sec:bit-extraction-operation]). + +The following example connects the `in`{.firrtl} port to the fifth bit +of the `out`{.firrtl} port. + +``` firrtl +module MyModule : + input in: UInt<1> + output out: UInt<10> + out[4] <= in +``` + ## Sub-accesses The sub-access expression dynamically refers to a sub-element of a vector-typed @@ -2382,6 +2402,8 @@ wire or register is duplex. The flow of a sub-index or sub-access expression is the flow of the vector-typed expression it indexes or accesses. +The flow of a bit-index is sink. + The flow of a sub-field expression depends upon the orientation of the field. If the field is not flipped, its flow is the same flow as the bundle-typed expression it selects its field from. If the field is flipped, then its flow is @@ -2646,6 +2668,8 @@ following restrictions: - The partial connect statement is not used. +- The bit-index expression is not used + The first three restrictions follow from the fact that any LoFIRRTL circuit is also a legal MidFIRRTL circuit. The additional restrictions give LoFIRRTL a direct correspondence to a circuit netlist. From 86bcca22c14b3395e8855fea5ed7f4e44ea07a9f Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Mon, 11 Jul 2022 19:26:20 -0700 Subject: [PATCH 02/12] Highlight inline code --- spec.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 7958ad84..0feac2f2 100644 --- a/spec.md +++ b/spec.md @@ -1843,12 +1843,12 @@ module MyModule : ## Bit-indices The bit-index expression statically refers, by index, to a particular bit of an -expression with an integer type (`UInt` or `SInt`). The index must be a -non-negative integer and cannot be equal to or exceed the width of the integer -it indexes. The bit-index must be connected to a value of type `UInt<1>` and -can only be used as a sink. In order to get a particular bit of an integer -expression as a source, use the `bits` primitive operation (see -[@sec:bit-extraction-operation]). +expression with an integer type (`UInt`{.firrtl} or `SInt`{.firrtl}). The index +must be a non-negative integer and cannot be equal to or exceed the width of +the integer it indexes. The bit-index must be connected to a value of type +`UInt<1>`{.firrtl} and can only be used as a sink. In order to get a particular +bit of an integer expression as a source, use the `bits`{.firrtl} primitive +operation (see [@sec:bit-extraction-operation]). The following example connects the `in`{.firrtl} port to the fifth bit of the `out`{.firrtl} port. From b2dff2e927b9b9a3fe51ace6fe26ec533a07ff2f Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Tue, 12 Jul 2022 11:56:34 -0700 Subject: [PATCH 03/12] Update wording on connection semantics --- spec.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/spec.md b/spec.md index 0feac2f2..1c60bebe 100644 --- a/spec.md +++ b/spec.md @@ -1845,10 +1845,11 @@ module MyModule : The bit-index expression statically refers, by index, to a particular bit of an expression with an integer type (`UInt`{.firrtl} or `SInt`{.firrtl}). The index must be a non-negative integer and cannot be equal to or exceed the width of -the integer it indexes. The bit-index must be connected to a value of type -`UInt<1>`{.firrtl} and can only be used as a sink. In order to get a particular -bit of an integer expression as a source, use the `bits`{.firrtl} primitive -operation (see [@sec:bit-extraction-operation]). +the integer it indexes. The type of a bit-index expression is +`UInt<1>`.{firrtl} (even if the indexed variable is an `SInt`) and it can only +be used as a sink. In order to get a particular bit of an integer expression as +a source, use the `bits`{.firrtl} primitive operation (see +[@sec:bit-extraction-operation]). The following example connects the `in`{.firrtl} port to the fifth bit of the `out`{.firrtl} port. From 30c6c305cb5d1325c12073f2ecfcd3fd8f7cfef1 Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Fri, 22 Jul 2022 16:39:48 -0700 Subject: [PATCH 04/12] Update spec to include bit slicing --- spec.md | 35 ++++++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/spec.md b/spec.md index 1c60bebe..aac57dca 100644 --- a/spec.md +++ b/spec.md @@ -1842,14 +1842,30 @@ module MyModule : ## Bit-indices -The bit-index expression statically refers, by index, to a particular bit of an -expression with an integer type (`UInt`{.firrtl} or `SInt`{.firrtl}). The index -must be a non-negative integer and cannot be equal to or exceed the width of -the integer it indexes. The type of a bit-index expression is -`UInt<1>`.{firrtl} (even if the indexed variable is an `SInt`) and it can only -be used as a sink. In order to get a particular bit of an integer expression as -a source, use the `bits`{.firrtl} primitive operation (see -[@sec:bit-extraction-operation]). +The bit-index expression statically refers, by index, to a particular bit, or +slice of bits, of an expression with an integer type (`UInt`{.firrtl} or +`SInt`{.firrtl}). The indices must be non-negative integers and cannot be equal +to or exceed the width of the integer they index. The bit-index `x[hi:lo]` +selects bits `hi` (most significant) through `lo` (least significant) of `x`. +The bit-index `x[i]` selects the single bit `i`. + +The type of the bit-index expression `x[hi:lo]`.{firrtl} is `UInt`.{firrtl} (even if `x` is an `SInt`) and the type of `x[i]`.{firrtl} is +`UInt<1>`.{firrtl}. + +The bit-index can be used as a sink or source. When used as a source, +`x[hi:lo]` is equivalent to `bits(x, hi, lo)` and `x[i]` is equivalent to +`bits(x, i, i)`. See the `bits`{.firrtl} primitive operation +([@sec:bit-extraction-operation]). When used as a sink, the bit-index assigns +to only the sliced bits of the integer. If a value has multiple bit-index +assignments, the assignments are accumulated in order according to last-connect +semantics, in the same way as the behavior of last-connect semantics for +aggregate types (see [@sec:last-connect-semantics]). + +Bit-indexing does not participate in width inference (see +[@sec:width-inference]), and if a bit-index is applied to a value with an +unspecified width, that value must have another use that allows its width to be +inferred. Otherwise this causes an error. The following example connects the `in`{.firrtl} port to the fifth bit of the `out`{.firrtl} port. @@ -2403,7 +2419,7 @@ wire or register is duplex. The flow of a sub-index or sub-access expression is the flow of the vector-typed expression it indexes or accesses. -The flow of a bit-index is sink. +The flow of a bit-index is the flow of the integer-typed expression it indexes. The flow of a sub-field expression depends upon the orientation of the field. If the field is not flipped, its flow is the same flow as the bundle-typed @@ -2921,6 +2937,7 @@ expr = reference = id | reference , "." , id | reference , "[" , int , "]" + | reference , "[" , int , ":" , int , "]" | reference , "[" , expr , "]" ; (* Memory *) From c6e26cd2491f9485c7e7d1f52ec511ccb4b38ea1 Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Mon, 25 Jul 2022 13:06:51 -0700 Subject: [PATCH 05/12] Note on memory ports --- spec.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec.md b/spec.md index aac57dca..0678bcd5 100644 --- a/spec.md +++ b/spec.md @@ -1877,6 +1877,8 @@ module MyModule : out[4] <= in ``` +Bit-indexing is not supported on memory ports. + ## Sub-accesses The sub-access expression dynamically refers to a sub-element of a vector-typed From 2e26a19421115e7a7bae478ba9d1ef88b4a6cdd9 Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Mon, 25 Jul 2022 13:10:41 -0700 Subject: [PATCH 06/12] Add ref in width section --- spec.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec.md b/spec.md index 0678bcd5..b409ba1b 100644 --- a/spec.md +++ b/spec.md @@ -2454,6 +2454,8 @@ expression. The width of each primitive operation is detailed in [@sec:primitive-operations]. +The width of a bit-index is detailed in [@sec:bit-indices]. + The width of the integer literal expressions is detailed in their respective sections. From 65ebef383e0abb69df95ff74aeed9e199a9f7714 Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Tue, 26 Jul 2022 13:27:28 -0700 Subject: [PATCH 07/12] Note on initialization --- spec.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index b409ba1b..a998f9a0 100644 --- a/spec.md +++ b/spec.md @@ -1862,6 +1862,11 @@ assignments, the assignments are accumulated in order according to last-connect semantics, in the same way as the behavior of last-connect semantics for aggregate types (see [@sec:last-connect-semantics]). +A value that is bit-indexed must be fully initialized at the bit-level. There +must be a valid assignment accounting for every bit in the value regardless +of paths through whens. Registers are implicitly initialized with their current +contents. + Bit-indexing does not participate in width inference (see [@sec:width-inference]), and if a bit-index is applied to a value with an unspecified width, that value must have another use that allows its width to be @@ -1877,8 +1882,6 @@ module MyModule : out[4] <= in ``` -Bit-indexing is not supported on memory ports. - ## Sub-accesses The sub-access expression dynamically refers to a sub-element of a vector-typed From 267e1df993b7ac80e47d23d3679dec5ad1dfa9b8 Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Wed, 3 Aug 2022 13:17:11 -0700 Subject: [PATCH 08/12] Minor update to wording --- spec.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/spec.md b/spec.md index a998f9a0..6f380b46 100644 --- a/spec.md +++ b/spec.md @@ -1863,9 +1863,8 @@ semantics, in the same way as the behavior of last-connect semantics for aggregate types (see [@sec:last-connect-semantics]). A value that is bit-indexed must be fully initialized at the bit-level. There -must be a valid assignment accounting for every bit in the value regardless -of paths through whens. Registers are implicitly initialized with their current -contents. +must be a valid assignment accounting for every bit in the value. Registers are +implicitly initialized with their current contents. Bit-indexing does not participate in width inference (see [@sec:width-inference]), and if a bit-index is applied to a value with an @@ -2672,6 +2671,8 @@ following restrictions: - The dynamic sub-access expression is not used. +- The bit-index expression is not used as a sink. + - All components are connected to exactly once. - All uninferred `Reset`{.firrtl} types have been inferred to `UInt<1>`{.firrtl} @@ -2692,8 +2693,6 @@ following restrictions: - The partial connect statement is not used. -- The bit-index expression is not used - The first three restrictions follow from the fact that any LoFIRRTL circuit is also a legal MidFIRRTL circuit. The additional restrictions give LoFIRRTL a direct correspondence to a circuit netlist. From 2872b62e1c1f1d32299b264a477448e83d7c1cc2 Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Wed, 24 Aug 2022 10:44:19 -0700 Subject: [PATCH 09/12] Mention bit-index in invalidate section --- spec.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/spec.md b/spec.md index 6f380b46..b02ab98d 100644 --- a/spec.md +++ b/spec.md @@ -990,6 +990,9 @@ sub-element in the vector. Invalidating a component with a bundle type recursively invalidates each sub-element in the bundle. +Invalidating a particular subset of bits in an integer is possible by +performing a bit-index with `is invalid`{.firrtl} (see [@sec:bit-indices]). + ## Attaches The `attach`{.firrtl} statement is used to attach two or more analog signals, From eb591221cff8f668fa1c55e714d773fbd352a7e7 Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Wed, 31 Aug 2022 13:03:03 -0700 Subject: [PATCH 10/12] Add additional clarification about UInt vs SInt --- spec.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index b02ab98d..42bddbb6 100644 --- a/spec.md +++ b/spec.md @@ -1854,7 +1854,9 @@ The bit-index `x[i]` selects the single bit `i`. The type of the bit-index expression `x[hi:lo]`.{firrtl} is `UInt`.{firrtl} (even if `x` is an `SInt`) and the type of `x[i]`.{firrtl} is -`UInt<1>`.{firrtl}. +`UInt<1>`.{firrtl}. This means that when connecting to a bit-indexed value, the +right-hand-side of the connection must be a `UInt`.{firrtl}, even if the value +being indexed is an `SInt`.{firrtl}. The bit-index can be used as a sink or source. When used as a source, `x[hi:lo]` is equivalent to `bits(x, hi, lo)` and `x[i]` is equivalent to From c72b34da07b552f43d73af2ce2a605886a3e9ab7 Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Thu, 1 Sep 2022 10:55:28 -0700 Subject: [PATCH 11/12] Update revision history --- revision-history.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/revision-history.yaml b/revision-history.yaml index 50623198..133dcc05 100644 --- a/revision-history.yaml +++ b/revision-history.yaml @@ -4,7 +4,8 @@ revisionHistory: # populated using the "version" that the Makefile grabs from git. Notable # additions to the specification should append entries here. thisVersion: - - Specify behavior of zero bit width integers, add zero-width literals + - Specify behavior of zero bit width integers, add zero-width literals, add + bit-index assignment and syntax # Information about the old versions. This should be static. oldVersions: - version: 1.1.0 From 8e077c7e473156d5f22d68f4519a83c1c928ef16 Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Tue, 13 Sep 2022 13:21:57 -0700 Subject: [PATCH 12/12] Separate bullet point --- revision-history.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/revision-history.yaml b/revision-history.yaml index 133dcc05..be8c5965 100644 --- a/revision-history.yaml +++ b/revision-history.yaml @@ -4,8 +4,8 @@ revisionHistory: # populated using the "version" that the Makefile grabs from git. Notable # additions to the specification should append entries here. thisVersion: - - Specify behavior of zero bit width integers, add zero-width literals, add - bit-index assignment and syntax + - Specify behavior of zero bit width integers, add zero-width literals + - Add bit-index assignment and syntax # Information about the old versions. This should be static. oldVersions: - version: 1.1.0