From f03d7a0bd857f877f60fbdc1fde42aab17187b3c Mon Sep 17 00:00:00 2001 From: Mike Urbach Date: Thu, 8 Feb 2024 15:46:19 -0800 Subject: [PATCH 1/4] [minor] Add Property primitive operations, starting with integer addition. This adds prose to the Expressions section introducing the concept of primitive Property operations, adds a new section defining the primitive Property operations, and adds primitive Property operations to the grammar. As a concrete example, integer addition is included. --- revision-history.yaml | 1 + spec.md | 47 ++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/revision-history.yaml b/revision-history.yaml index 232a2a08..7013f594 100644 --- a/revision-history.yaml +++ b/revision-history.yaml @@ -16,6 +16,7 @@ revisionHistory: - Define "Storable Type". - Change the minimum width of the result of "Shift Right" on UInt to 0-bit. - Allow assert and assume statements to have a format string + - Add Property primitive operations, starting with integer addition abi: - Add ABI for public modules and filelist output. - Changed ABI for group and ref generated files. diff --git a/spec.md b/spec.md index 26a6dd09..9539ede5 100644 --- a/spec.md +++ b/spec.md @@ -2450,6 +2450,26 @@ asClock(x) [@sec:primitive-operations] will describe the format and semantics of each primitive operation. +## Primitive Property Operations {#sec:expressions:primitive-property-operations} + +All fundamental operations on property types are expressed as a FIRRTL primitive operation. +In general, each operation takes some number of property type expressions as arguments. + +The general form of a primitive property operation is expressed as follows: + +```firrtl +op(arg0, arg1, ..., argn) +``` + +The following examples of primitive property operations demonstrate adding two property expressions, `a`{.firrtl} and `b`{.firrtl}, and adding an integer property literal to expression `a`{.firrtl}. + +```firrtl +integer_add(a, b) +integer_add(a, Integer(2)) +``` + +[@sec:primitive-property-operations] will describe the format and semantics of each primitive property operation. + ## Reading Probe References Probes are read using the `read`{.firrtl} operation. @@ -3070,6 +3090,24 @@ n must be non-negative and less than or equal to the bit width of e. The tail operation truncates the n most significant bits from e. n must be non-negative and less than or equal to the bit width of e. +# Primitive Property Operations {#primitive-property-operations} + +The arguments of all primitive property operations must be expressions with property types. +Each specific operation can place additional restrictions on the number and types of their arguments. +In general, primitive property operations are named with a prefix indicating the property type on which they operate. + +## Integer Arthmetic + +Integer arithmetic operations take `Integer`{.firrtl} property type expressions as arguments and return an `Integer`{.firrtl} property type result. + +### Integer Add Operation + +| Name | Arguments | Arg Types | Result Type | +|--------------|-----------|-------------------|-------------| +| integer_add | (e1,e2) | (Integer,Integer) | Integer | + +The add operation result is the arbitrary precision signed integer arithmetic sum of e1 and e2. + # Notes on Syntax FIRRTL's syntax is designed to be human-readable but easily algorithmically parsed. @@ -3411,7 +3449,8 @@ expr_probe = | reference_static ; property_literal_expr = "Integer", "(", int, ")" ; -property_expr = reference_static | property_literal_expr ; +property_expr = reference_static | property_literal_expr | property_expr_primop ; +property_expr_primop = property_primop_2expr ; expr_primop = primop_2expr | primop_1expr | primop_1expr1int | primop_1expr2int ; (* Types *) @@ -3459,6 +3498,9 @@ primop_1expr = primop_1expr_keyword , "(" , expr , ")" ; primop_1expr1int = primop_1expr1int_keyword , "(", expr , "," , int , ")" ; primop_1expr2int = primop_1expr2int_keyword , "(" , expr , "," , int , "," , int , ")" ; +(* Primitive Property Operations *) +property_primop_2expr = property_primop_2expr_keyword , "(" , property_expr , "," , property_expr ")" ; + (* Tokens: Annotations *) annotations = "%" , "[" , json_array , "]" ; @@ -3525,6 +3567,9 @@ primop_1expr1int_keyword = "pad" | "shl" | "shr" | "head" | "tail" ; primop_1expr2int_keyword = "bits" ; + +property_primop_2expr_keyword = + "integer_add" ; ``` # Versioning Scheme of this Document From 9fa389fb55928288aeea50d3486959e305af7d74 Mon Sep 17 00:00:00 2001 From: Mike Urbach Date: Thu, 8 Feb 2024 17:20:14 -0700 Subject: [PATCH 2/4] Reflow property_primop_2expr. --- spec.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 9539ede5..c01544f0 100644 --- a/spec.md +++ b/spec.md @@ -3499,7 +3499,8 @@ primop_1expr1int = primop_1expr1int_keyword , "(", expr , "," , int , ")" ; primop_1expr2int = primop_1expr2int_keyword , "(" , expr , "," , int , "," , int , ")" ; (* Primitive Property Operations *) -property_primop_2expr = property_primop_2expr_keyword , "(" , property_expr , "," , property_expr ")" ; +property_primop_2expr = property_primop_2expr_keyword , + "(" , property_expr , "," , property_expr ")" ; (* Tokens: Annotations *) annotations = "%" , "[" , json_array , "]" ; From e7aef34a8ee6777bf778a6fdd0aa58ec7c8c7aa0 Mon Sep 17 00:00:00 2001 From: Mike Urbach Date: Thu, 8 Feb 2024 17:23:58 -0700 Subject: [PATCH 3/4] Updates from review feedback. --- spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec.md b/spec.md index c01544f0..a7f6368a 100644 --- a/spec.md +++ b/spec.md @@ -2457,13 +2457,13 @@ In general, each operation takes some number of property type expressions as arg The general form of a primitive property operation is expressed as follows: -```firrtl +``` firrtl op(arg0, arg1, ..., argn) ``` -The following examples of primitive property operations demonstrate adding two property expressions, `a`{.firrtl} and `b`{.firrtl}, and adding an integer property literal to expression `a`{.firrtl}. +The following examples of primitive property operations demonstrate adding two property expressions, `a` and `b`, and adding an integer property literal to expression `a`. -```firrtl +``` firrtl integer_add(a, b) integer_add(a, Integer(2)) ``` From 470eb596b85cd6a72c322db0317138d41e932989 Mon Sep 17 00:00:00 2001 From: Mike Urbach Date: Thu, 8 Feb 2024 17:27:22 -0700 Subject: [PATCH 4/4] Run make format to adjust table format. --- spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec.md b/spec.md index a7f6368a..14cb7eda 100644 --- a/spec.md +++ b/spec.md @@ -3102,9 +3102,9 @@ Integer arithmetic operations take `Integer`{.firrtl} property type expressions ### Integer Add Operation -| Name | Arguments | Arg Types | Result Type | -|--------------|-----------|-------------------|-------------| -| integer_add | (e1,e2) | (Integer,Integer) | Integer | + Name Arguments Arg Types Result Type + ------------- ----------- ------------------- ------------- + integer_add (e1,e2) (Integer,Integer) Integer The add operation result is the arbitrary precision signed integer arithmetic sum of e1 and e2.