FixChisel3: Add some commentary to scaladoc

[mwachs5]

Related issue:

Type of change: other enhancement

Impact: no functional change

Development Phase: implementation

Release Notes

Added some scaladoc commentary to the "FixChisel3" operators :<>, :<=, :=> to explain what they do and the rationale for their creation.

[leikou01]

As a new user, I found that the below comments are useful for me. That tells me that these operators can be used to connect Wires to IO.

implicit class EnhancedChisel3Assign(val x: Data) extends AnyVal {
// Assign all output fields of x from y; note that the actual direction of x is irrelevant
def :<= (y: Data): Unit = FixChisel3.assignL(x, y)
// Assign all input fields of y from x; note that the actual direction of y is irrelevant
def :=> (y: Data): Unit = FixChisel3.assignR(x, y)

Also, it might be helpful to replace "a" with "c" (as Consumer) and "b" with "p" (as Producer), I think.

[terpstra]

LGTM. There is a bit of additional functionality now, in that my operators allow you to customize their behaviour on your Bundles. In particular, for BundleMaps, this means that when you bulk connect two BundleMaps with different fields, mismatched fields get the field-defined default value. This is particularly relevant for user/echo-bits in the updated TileLink bundles.

[leikou01]

this one actually means
* c :=> p // means drive all flipped fields of 'p' from 'c' (e.g.: ready) , e.g.: p.ready := c.ready ?

[mwachs5]

so should this say p :=> c for a more consistent example?

[leikou01]

My understanding is "no".

Rule #1 for this set of operator is "consumer always on LHS". (It is sort of directional operator from the producer-consumer's viewpoint. not sure of the best way to express this).

p:=> c means that the consumer's ready (input) is driven by the producer's ready (output), which is wrong.

[terpstra]

You are correct. Consumer is always on the left-hand-side. The comment should have been:

c :=> p // means drive all flipped fields of 'p' from 'c' (e.g.: p.ready := c.ready)

[jackkoenig]

Gender has been replaced by Flow. Also if this results in flow errors in FIRRTL, I think it would be better to just catch them here instead.

[terpstra]

You propose to try and introspect the actual direction? And if it cannot be determined (ie: is a wire), just trust the user? That is fine by me.

[DecodeTheEncoded]

@jackkoenig do you have any plan of supporting these operators in chisel?

[terpstra]

This is wrong.
c := p is equivalent to 'c :<= p' + 'p :=> c'.

'c :<> p' is not related to 'c := p' at all.

[terpstra]

In other words, 'c := p' says drive ALL fields of 'c' from 'p' regardless of their direction.

(which is pretty much only useful when you want to put a VIP monitor down that watches the wires of an existing producer-consumer pair)

[terpstra]

Please fix the comment about ':=', but otherwise, I approve.