[WIP] Documentation to diplomacy(Nodes part) #2316

sequencer · 2020-03-03T08:29:50Z

Related issue:
#2311

Type of change: other enhancement

Impact: no functional change

Development Phase: proposal

Release Notes

This PR is split from #2311, for the documentation to Nodes.scala

It's still a draft version, since I'm not fully understand resolveStar function.
I'm trying to reavl out this function, may luck be with me.

mwachs5 · 2020-03-12T00:01:25Z

@sequencer , how would you feel if I copied @richardxia 's documentation to this same PR and use this as the PR going forward? I think you both have complementary information and it may be easier to review at once vs trying to do them separately? If you are OK with this plan can you add the "allow edits from admins" box again?

sequencer · 2020-03-12T01:20:44Z

I have added "allow edits from admins", please feel free to edit my PR:)
Sorry, I got some work on physical design these days, and I will work on this this weekend.

mwachs5 · 2020-03-12T04:34:16Z

I havae merged the changes and some minor edits from #2311 here. I suggest we close #2311 and work together on this PR.

mwachs5 · 2020-03-16T23:52:00Z

@ryoungsun here is another diplomacy doc PR

mwachs5

Ok, this took a while but I did a pass for english language and to better merge @sequencer and @richardxia's work.

I think we should get rid of the "master slave" information, because everything in this file can be described in terms of "upwards/downwards" and "input/output". Frankly i dont think I did a good job of doing that yet. Need to save the work though.

mwachs5 · 2020-06-22T23:48:40Z

src/main/scala/diplomacy/Nodes.scala

+  * Since all blocks(CPUs, caches, peripheries) are connected to bus,
+  * It has a very complex data flow illustrated graph below:
+  *                                                  ┌────────────────────────────────────────────────────────────────────────────┐
+  *                                                  ↓                                                                            │


I'll be honest, this diagram doesn't help me much and it's kinda scary as the first thing to run into in this file...
how would you feel about removing it / moving it down / adding it back in a follow-up PR?

I think I should move it down to MixedNode, I think it’s really useful to understand behaviour of diplomacy negotiation in a detail sequence. Maybe I need to make it more detail.

src/main/scala/diplomacy/Nodes.scala

mwachs5 · 2020-06-22T23:55:44Z

src/main/scala/diplomacy/Nodes.scala

+  *
+  * Is an "edge" and a binding the same thing?
+  *
+  *


Todo: ASCII art for "anatomy of a Node"?

It think my scary ascii art be a "anatomy of a Node"

mwachs5 · 2020-06-22T23:57:08Z

src/main/scala/diplomacy/Nodes.scala

+  * - Inward refers to edges that point into a node.
+  * - Outward refers to edges that point out of a node.
+  *
+  * A useful mnemonic for distinguishing between inward and outward is to always


This mnemonic doesn't help me. It is like this:

|------------------| "upstream" node A ---inward edge---> | | "upstream" node B ---inward edge---> | Intermediate Node| <----- inward edge --> "downstream" node X "upstream" node C <---outward edge-- | | ------- outward edge -> "downstream" node Y |------------------|

Or is the point that the above is illegal, given that you can't go "upstream" with an inward edge?

Yeah, sorry, I was having difficulty eloquently describing what finally "clicked" for me.

Your diagram is mostly what I was trying to convey, where I specifically was trying to draw attention to the fact that the "inward" and "outward" labels on those edges are only true from the perfective of that Intermediate Node. However, the edge coming out of Node A is an "outward" edge from the perspective of A.

Maybe embedding this actual ASCII diagram into the comments and specifically remarking on the inward/outward directions and different perspectives would be helpful?

To elaborate on why I found this notable enough to write documentation for, it was originally I was thinking of "inward" and "outward" of describing some more global inward and outward directions. To make a crappy, false mnemonic, if you think of the surface of the planet Earth as being "outward" and the core of the planet as being "inward", then "inward" and "outward" are global directions regardless of where you are. They are "global" in the sense that all of your neighbors will agree on those general directions.

This is exactly not the case with Diplomacy, and inward and outward are always from the perspective of you.

right, i think this is really important and I feel like I still haven't fully grasped why it's important to distinguish inward/outward from Up and Down.

Are these words correct: Edges always "go" from up to down, But edge parameters flow along those directed edges BOTH up and down. As a node, an inward edge is always coming from the "up" direction, and an outward edge is always going in the "down" direction. But again you can both send and receive edge parameters in either direction on both inward and outward edges.

i think a good analogy for inward/outward could be "producer/consumer", "sender-receiver".
If you draw an edge from producer->consumer, then the producer sees that as an "outward" edge and the consumer sees it as an "inward" edge. It's the same edge. The parameters will flow downwards along that edge from the producer->consumer, but consumer gets to send upwards parameters along the edge as well.

Are these words correct: Edges always "go" from up to down, But edge parameters flow along those directed edges BOTH up and down. As a node, an inward edge is always coming from the "up" direction, and an outward edge is always going in the "down" direction. But again you can both send and receive edge parameters in either direction on both inward and outward edges.

I think this is correct. I guess another way of looking at this is that the Up and Down always flow in the direction of the underlying Bundle type, whereas In and Out always flow in the direction of the parameter negotiation.

i think a good analogy for inward/outward could be "producer/consumer", "sender-receiver".

The only problem with these specific analogies is that they are tied to the underlying DAG being modeled. In TileLink, is the "producer" the node "producing requests", or is the "producer" the node producing "responses"? At some level, inward and outward are arbitrary, as you could just flip all the edges of a TileLink network and just define the edges as pointing from receiver to sender.

Right. the protocol gets to further decide its own naming "Master/Slave", "Producer/Consumer", "Source/Sink", "First/Second" based on the types of messages it is sending and the way it has decided to map that to the "Upwards/Downwards" direction.

Updating my ASCII art:

|------------------| "upstream" node A --- edge a ---> | | "upstream" node B --- edge b ---> | Current Node | ----- edge x --> "downstream" node X "upstream" node C ----edge c ---> | | ------ edge y --> "downstream" node Y |------------------| From "Current Node"'s perspective, edge `a` is an inward edge. Edge `x` is an outward edge. But node A sees edge a as an outward edge and node X sees edge `x` as an inward edge. HOWEVER, parameters can flow both "up" and "down" along any edge. From Current Node's perspective, The type of the parameters that flow "up" on edge a are "UI". The ones that flow down are of type "DI". The type of the paramters that flow "down" on edge x are "DO". The ones that flow up are "UO". Terms like "master/slave", "consumer/producer", "source/sink" are generally NOT part of diplomacy itself, but of the concrete protocols that are built on top of Diplomacy (by extending `NodeImp`). After negotiation, the UI+DI+DO+UO parameters on a given edge have all been resolved such that from a node's perspective, its input edges just have one parameter of type EI, and its output edge just have one parameter of type EO. Then during hardware construction, those EI parameters get turned into a hardware (parameterized) bundle of type BI, and the EO parameters get turned into a hardware (parameterized) bundle of type BO.

I'll suggest a change to the words here that capture this.

Wait, is your updated diagram correct? I might just not actually understand whether your previous diagram was correct or whether your new diagram is correct.

Could you change some of the "upstream" and "downstream" nodes to be flipped in order to demonstrate that nodes can be downstream yet still inward?

Actually, now I'm kind of confused about whether edges can be said to be "inward" or "outward", and whether a single edge can be both "inward" and "outward" at the same time from the perspective of a single node. From Current Node's perspective, couldn't "edge a" be inward for parameters that flow from A to Current but simultaneously outward for parameters that flow from Current to A?

"Could you change some of the "upstream" and "downstream" nodes to be flipped in order to demonstrate that nodes can be downstream yet still inward?"

I don't believe that is true. I dont think my previous diagram was right.

Inward/Outward refers to the ultimately physical direction. I don't believe that a single edge can be both inward and outward at the same time from the perspective of a single node.

From Current Node's perspective, couldn't "edge a" be inward for parameters that flow from A to Current but simultaneously outward for parameters that flow from Current to A?

No. Edge a comes in to Current Node. The parameters along that edge a flow both "Upwards" and "Downwards" on that edge. Since it's an inward edge, then from Current Node's perspective, the parameters that flow DOWN on edge a are "DI" parameters. The parameters that flow UP on edge a are "UI" parameters. Nothing about edge a is "out" from Current Node's perspective.

@mwachs5 @aswaterman
I have already read the diplomacy code, and lots of other stuff, But I still feel very confused about what problem the diplomacy framework can solve specificly.
Suppose we have two nodes, a source node and a sink node, they comply with TL-UL, the source node initiates an GET operation on channel A, and the sink node responded with AccessAckData on channel D. According to the diplomacy, we have to define two lazymodule. Inside each lazymodule, we define source node for the Master lazymodule, and sinknode for the slave lazymodule. also we have to implement nodeImp to conduct the specific negotiating logic. And inside the nodeImp, we have to decide the EO and EI according to the DO and UO for the source node (DI and UI for the sinknode). I know the general idea of diplomacy, but my confusion is what can we negotiate in real life? Take the source node as an example, is the DO params something related to the channel A? and the UO is some thing related to the channel D of the tile link protocol? I think the word negotiation is bilateral bargaining on something they both claim, the channel A and channel D are actually something seperated.

src/main/scala/diplomacy/Nodes.scala

src/main/scala/diplomacy/package.scala

src/main/scala/diplomacy/Nodes.scala

richardxia · 2020-07-02T05:41:09Z

src/main/scala/diplomacy/Nodes.scala

+  * - Inward refers to edges that point into a node.
+  * - Outward refers to edges that point out of a node.
+  *
+  * A useful mnemonic for distinguishing between inward and outward is to always


Yeah, sorry, I was having difficulty eloquently describing what finally "clicked" for me.

Your diagram is mostly what I was trying to convey, where I specifically was trying to draw attention to the fact that the "inward" and "outward" labels on those edges are only true from the perfective of that Intermediate Node. However, the edge coming out of Node A is an "outward" edge from the perspective of A.

Maybe embedding this actual ASCII diagram into the comments and specifically remarking on the inward/outward directions and different perspectives would be helpful?

To elaborate on why I found this notable enough to write documentation for, it was originally I was thinking of "inward" and "outward" of describing some more global inward and outward directions. To make a crappy, false mnemonic, if you think of the surface of the planet Earth as being "outward" and the core of the planet as being "inward", then "inward" and "outward" are global directions regardless of where you are. They are "global" in the sense that all of your neighbors will agree on those general directions.

This is exactly not the case with Diplomacy, and inward and outward are always from the perspective of you.

src/main/scala/diplomacy/Nodes.scala

src/main/scala/diplomacy/package.scala

mwachs5 · 2020-07-02T20:36:33Z

src/main/scala/diplomacy/Nodes.scala

+    * @param pd the downward-flowing parameters into the node
+    * @param pu the upward-flowing parameters going out of the node
+    * @param p the [[Parameters]] which can be accessed by this node as needed
+    * @param sourceInfo [[SourceInfo]] of this edge
+    * @return an inward edge of this node


Suggested change

* @param pd the downward-flowing parameters into the node

* @param pu the upward-flowing parameters going out of the node

* @param p the [[Parameters]] which can be accessed by this node as needed

* @param sourceInfo [[SourceInfo]] of this edge

* @return an inward edge of this node

* @param pd the downward-flowing parameters into the node along the edge

* @param pu the upward-flowing parameters going out of the node along the edge

* @param p the [[Parameters]] which can be accessed by this node as needed

* @param sourceInfo [[SourceInfo]] of this edge

* @return an inward edge of this node

mwachs5 · 2020-07-02T20:39:18Z

src/main/scala/diplomacy/Nodes.scala

+   * 
+   * The default behavior is to just return [[pu]].
+   * 
+   * @param pu parameters flowing upwards


Suggested change

* @param pu parameters flowing upwards

* @param pu parameters flowing upwards to "mix in"

mwachs5 · 2020-07-02T20:39:46Z

src/main/scala/diplomacy/Nodes.scala

+   * The default behavior is to just return [[pu]].
+   * 
+   * @param pu parameters flowing upwards
+   * @param node node to "mix" the parameters with


Suggested change

* @param node node to "mix" the parameters with

* @param node [[InwardNode]] to "mix" the parameters with

src/main/scala/diplomacy/Nodes.scala

mwachs5 · 2020-07-09T15:41:01Z

I think @sequencer plans to:

Make a PR that separates this file (in its current form on master) into (a) the NodeImp/binding stuff and (b) the different abstract node types (SourceNode, etc).
Make this PR focus on the documentation for (a)
Make another PR to focus on the documentation for (b)

This would help both 2 and 3 get through faster, I think.

sequencer · 2020-07-09T17:42:36Z

Thanks @mwachs5 for the explanation,
Rewrite the parameter propagation flow takes me too much time, sorry for that.
I almost finish general Nodes.scala documentations.
Remain questions are:

flexibleArityDirection/edgeArityDirection/edgeAritySelect
iForward/oForward/iTrace/oTrace

sequencer · 2020-07-09T17:50:28Z

src/main/scala/diplomacy/Nodes.scala

  def outputs: Seq[(BaseNode, RenderedEdge)]

+  /** @todo
+    * [[MixedAdapterNode]] will be true, otherwise will be false
+    */
  protected[diplomacy] def flexibleArityDirection: Boolean = false


I still don't understand what arity direction means?
I can only see it is overwritten in MixedAdapterNode

"Arity" is a word that essentially means "number of" in a few different areas of mathematics and computer science.

When talking about functions, it means the number of arguments to the function. When talking about graphs, it's usually about the number if edges coming out (or going in) to a node. I'm not specifically familiar with this code, so I don't know the specific meaning, but you should be able to figure it out from reading where it is used.

sequencer · 2020-07-09T17:52:24Z

src/main/scala/diplomacy/Nodes.scala

  protected[diplomacy] val oPortMapping: Seq[(Int, Int)]
+
+  /** @todo */
  protected[diplomacy] def oForward(x: Int): Option[(Int, OutwardNode[DO, UO, BO])] = None


AFAIK, oForward and iForward are only used in EphemeralNode

sequencer · 2020-07-09T17:52:52Z

src/main/scala/diplomacy/Nodes.scala

      val iSum = iBindings.map { case (_, n, b, _, _) => b match {
        case BIND_ONCE  => 1
        case BIND_FLEX  => edgeAritySelect(n, n.oStar, iStar)
        case BIND_QUERY => n.oStar
        case BIND_STAR  => iStar }}.scanLeft(0)(_+_)
+      /** @todo [[oTotal]] and [[iTotal]] is not used. */


these two codes are not used.

src/main/scala/diplomacy/Nodes.scala

Co-Authored-By: Jack Koenig <koenig@sifive.com> Co-authored-by: Megan Wachs <megan@sifive.com> Co-authored-by: Richard Xia <richardxia@richardxia.com>

debs-sifive · 2020-08-12T23:35:31Z

src/main/scala/diplomacy/Nodes.scala

+  * - Upward refers to a flow of parameters in the outward direction.
+  * - Downward refers to a flow of parameters in the inward direction.


The use of inward/outward here is kind of confusing, since we want to distinguish between up/down versus in/out.

sequencer · 2020-08-23T13:46:13Z

#2604

baltazarortiz mentioned this pull request Apr 27, 2020

Expanded error messages / examples for Diplomacy Nodes? #2438

Open

sequencer closed this Jun 28, 2020

sequencer force-pushed the diplomacy_node_doc branch from 3288c6f to a023a83 Compare June 28, 2020 05:56

sequencer reopened this Jun 28, 2020

sequencer force-pushed the diplomacy_node_doc branch from 3288c6f to b48b3ed Compare June 28, 2020 06:02

mwachs5 requested changes Jun 29, 2020

View reviewed changes

richardxia reviewed Jul 2, 2020

View reviewed changes

mwachs5 reviewed Jul 2, 2020

View reviewed changes

mwachs5 reviewed Jul 5, 2020

View reviewed changes

src/main/scala/diplomacy/Nodes.scala Show resolved Hide resolved

sequencer force-pushed the diplomacy_node_doc branch 2 times, most recently from 3cde7d8 to 1b67268 Compare July 8, 2020 07:01

sequencer force-pushed the diplomacy_node_doc branch from 7678c35 to fe6caa3 Compare July 9, 2020 17:37

sequencer commented Jul 9, 2020

View reviewed changes

mwachs5 reviewed Jul 9, 2020

View reviewed changes

src/main/scala/diplomacy/Nodes.scala Show resolved Hide resolved

mwachs5 reviewed Jul 9, 2020

View reviewed changes

src/main/scala/diplomacy/Nodes.scala Outdated Show resolved Hide resolved

sequencer and others added 5 commits July 16, 2020 08:27

split Nodes.scala from original PR.

df1d285

add documentation to package

cd5551d

WIP adding scaladoc comments for Diplomacy.

6d6e000

Apply suggestions from code review

11d0caf

Co-Authored-By: Jack Koenig <koenig@sifive.com> Co-authored-by: Megan Wachs <megan@sifive.com> Co-authored-by: Richard Xia <richardxia@richardxia.com>

wip documentation

b09daeb

sequencer and others added 3 commits July 16, 2020 08:27

update for review, rework on the ascii art of parameter propagation.

50bcd24

Update by reviewer.

7010433

add documentation to iForward and oForward.

cb06c23

sequencer force-pushed the diplomacy_node_doc branch from 47178e8 to cb06c23 Compare July 16, 2020 08:29

sequencer marked this pull request as draft July 17, 2020 23:11

debs-sifive reviewed Aug 12, 2020

View reviewed changes

sequencer closed this Aug 23, 2020

sequencer deleted the diplomacy_node_doc branch November 18, 2020 03:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Documentation to diplomacy(Nodes part) #2316

[WIP] Documentation to diplomacy(Nodes part) #2316

sequencer commented Mar 3, 2020

mwachs5 commented Mar 12, 2020

sequencer commented Mar 12, 2020

mwachs5 commented Mar 12, 2020

mwachs5 commented Mar 16, 2020

mwachs5 left a comment

mwachs5 Jun 22, 2020

sequencer Jun 29, 2020

mwachs5 Jun 22, 2020

sequencer Jul 9, 2020

mwachs5 Jun 22, 2020

richardxia Jul 2, 2020

mwachs5 Jul 2, 2020

mwachs5 Jul 2, 2020

richardxia Jul 2, 2020

mwachs5 Jul 2, 2020 •

edited

Loading

mwachs5 Jul 2, 2020 •

edited

Loading

richardxia Jul 2, 2020

mwachs5 Jul 2, 2020 •

edited

Loading

DecodeTheEncoded Nov 18, 2020

richardxia Jul 2, 2020

mwachs5 Jul 2, 2020 •

edited

Loading

mwachs5 Jul 2, 2020

mwachs5 Jul 2, 2020

mwachs5 commented Jul 9, 2020

sequencer commented Jul 9, 2020 •

edited

Loading

sequencer Jul 9, 2020

richardxia Jul 9, 2020

sequencer Jul 9, 2020

sequencer Jul 9, 2020

debs-sifive Aug 12, 2020

sequencer commented Aug 23, 2020

	* @param pu parameters flowing upwards
	* @param pu parameters flowing upwards to "mix in"

	* @param node node to "mix" the parameters with
	* @param node [[InwardNode]] to "mix" the parameters with

		* - Upward refers to a flow of parameters in the outward direction.
		* - Downward refers to a flow of parameters in the inward direction.

[WIP] Documentation to diplomacy(Nodes part) #2316

[WIP] Documentation to diplomacy(Nodes part) #2316

Conversation

sequencer commented Mar 3, 2020

mwachs5 commented Mar 12, 2020

sequencer commented Mar 12, 2020

mwachs5 commented Mar 12, 2020

mwachs5 commented Mar 16, 2020

mwachs5 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mwachs5 Jul 2, 2020 • edited Loading

Choose a reason for hiding this comment

mwachs5 Jul 2, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mwachs5 Jul 2, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mwachs5 Jul 2, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mwachs5 commented Jul 9, 2020

sequencer commented Jul 9, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sequencer commented Aug 23, 2020

mwachs5 Jul 2, 2020 •

edited

Loading

mwachs5 Jul 2, 2020 •

edited

Loading

mwachs5 Jul 2, 2020 •

edited

Loading

mwachs5 Jul 2, 2020 •

edited

Loading

sequencer commented Jul 9, 2020 •

edited

Loading