diff --git a/spec.md b/spec.md index b0d98c39..17df7fef 100644 --- a/spec.md +++ b/spec.md @@ -729,6 +729,63 @@ module Example: input intProp : Integer ; an input port of Integer property type ``` +### String Type + +The `String` type represents a human-readable ASCII (TODO Unicode?) string. + +TODO Add an example: + +``` firrtl +module Example: + input intProp : Integer ; TODO +``` + +### Double Type + +The `Double` type represents a IEEE 754 double-precision floating point number. + +TODO Add an example: + +``` firrtl +module Example: + input intProp : Integer ; TODO +``` + +### Boolean Type + +The `Boolean` type represents a boolean value. + +TODO Add an example: + +``` firrtl +module Example: + input intProp : Integer ; TODO +``` + +### Reference to objects + +TODO Fix this section +The `Ref` type represents a reference to a TODO. + +TODO Add an example: + +``` firrtl +module Example: + input intProp : Integer ; TODO +``` + +### List Type + +The `List` type represents a list of properties. +The type `T` must be a property type. + +TODO Add an example: + +``` firrtl +module Example: + input intProp : Integer ; TODO +``` + ## Connectable Types A **connectable type** is one which may be the type of expressions which may participate in the `connect`{.firrtl} statement. @@ -1198,45 +1255,6 @@ attach(x, y) ; binary attach attach(z, y, x) ; attach all three signals ``` -# Property Assignments - -Connections between property typed expressions (see [@sec:property-types]) are not supported in the `connect`{.firrtl} statement (see [@sec:connections]). - -Instead, property typed expressions are assigned with the `propassign`{.firrtl} statement. - -Property typed expressions have the normal rules for flow (see [@sec:flow]), but otherwise use a stricter, simpler algorithm than `connect`{.firrtl}. In order for a property assignment to be legal, the following conditions must hold: - -1. The left-hand and right-hand side expressions must be of property types. - -2. The types of the left-hand and right-hand side expressions must be the same. - -3. The flow of the left-hand side expression must be sink. - -4. The flow of the right-hand side expression must be source. - -5. The left-hand side expression may be used as the left-hand side in at most one property assignment. - -6. The property assignment must not occur within a conditional scope. - -Note that property types are not legal for any expressions with duplex flow. - -The following example demonstrates a property assignment from a module's input property type port to its output property type port. - -``` firrtl -module Example: - input propIn : Integer - output propOut : Integer - propassign propOut, propIn -``` - -The following example demonstrates a property assignment from a property literal expression to a module's output property type port. - -``` firrtl -module Example: - output propOut : Integer - propassign propOut, Integer(42) -``` - # Empty Statement The empty statement does nothing and is used simply as a placeholder where a statement is expected. @@ -2527,6 +2545,88 @@ The probed expression must be a static reference. See [@sec:probe-types; @sec:probe] for more details on probe references and their use. +# Properties + +TODO + +TODO See https://www.chisel-lang.org/docs/explanations/properties + +Properties allow us to describe the hardware in a way which is suitable for consumption by tooling after the FIRRTL-level RTL has been produced. +They cannot affect the behavior of hardware. + +For the types see [@sec:property-types] + + +## Object Graphs + +TODO + +## Classes + +TODO + +A class is a bit like a module where all of the ports are property type. +The only statements allowed in a class are property-level statements (or somethign like that), etc and propassign statements. +They are used to represent arbitrary object graphs. + +When you instantiate a module, it takes some property inputs, it instantiates a class into a module, then takes a referene to that object and passes it out. +We want to be able to tie the object graphs to the RTL instance graph. + +Eg, if you want to describe the properties of a cache, we want to allow the graph to "overlay" the RTL for that cache. + +They are a little different than the plain structs that you see in Rust or C++. +Because they are closer to a module in that they separate their outputs from their inputs. +You can have a class that is like a simple struct where you plug in the inputs and you can read from the outputs as if they were fields. +They are more like a class in Java with the class constructor arguments, you need to supply those to instantiate, and then you can read out the values you instantiated. + +## Objects + +TODO + +## Property Ports + +TODO + +## Property Assignments + +Connections between property typed expressions (see [@sec:property-types]) are not supported in the `connect`{.firrtl} statement (see [@sec:connections]). + +Instead, property typed expressions are assigned with the `propassign`{.firrtl} statement. + +Property typed expressions have the normal rules for flow (see [@sec:flow]), but otherwise use a stricter, simpler algorithm than `connect`{.firrtl}. In order for a property assignment to be legal, the following conditions must hold: + +1. The left-hand and right-hand side expressions must be of property types. + +2. The types of the left-hand and right-hand side expressions must be the same. + +3. The flow of the left-hand side expression must be sink. + +4. The flow of the right-hand side expression must be source. + +5. The left-hand side expression may be used as the left-hand side in at most one property assignment. + +6. The property assignment must not occur within a conditional scope. + +Note that property types are not legal for any expressions with duplex flow. + +The following example demonstrates a property assignment from a module's input property type port to its output property type port. + +``` firrtl +module Example: + input propIn : Integer + output propOut : Integer + propassign propOut, propIn +``` + +The following example demonstrates a property assignment from a property literal expression to a module's output property type port. + +``` firrtl +module Example: + output propOut : Integer + propassign propOut, Integer(42) +``` + + # Namespaces All modules in a circuit exist in the same module namespace, and thus must all have a unique name.