Add fast datapath high level overview

[awh]

Document fast datapath.

[awh]

I shall address David's comments from #1510 in this PR.

[awh]

@dpw thanks for comments!

This sounds definitional, but it seems like a "for instance" to me ... I'd urge not to try to enumerate the keys and actions in created flows according to the context. It's fiddly

I agree that it's fiddly to maintain, but it's also essential for those who are trying to understand how it actually works now - in fact it's the main thing that I wanted to record after discovering it myself, so I'd prefer to leave it as is.

Unknown for the bridge implementation. Not unknown in terms of MacCache.

Is that an important distinction to draw in this doc?

[dpw]

This sounds definitional, but it seems like a "for instance" to me ... I'd urge not to try to enumerate the keys and actions in created flows according to the context. It's fiddly

I agree that it's fiddly to maintain, but it's also essential for those who are trying to understand how it actually works now - in fact it's the main thing that I wanted to record after discovering it myself, so I'd prefer to leave it as is.

I disagree that it is essential. Rather the opposite: it is significant that the full keys are left implicit, and generated as a side effect of handling packets, is one of the most important design elements. That design freed me from having to think about what the full rules looked like, and I'd encourage everyone else to understand the code in the same terms (particularly when it comes to extending it in the future).

Giving an example of what the generated rules look like seems ok, as context. Beyond that encourages misunderstanding.

Unknown for the bridge implementation. Not unknown in terms of MacCache.

Is that an important distinction to draw in this doc?

Would it take more than a few additional words to avoid the risk of confusion?

[awh]

I disagree that it is essential ... I'd encourage everyone else to understand the code in the same terms (particularly when it comes to extending it in the future).

I think the disagreement comes from the fact that I am trying to capture the way in which fastdp configures the datapath, not just how it does it. The document is as much of interest to people who want to treat the router as a black box but understand what effects it has on the network configuration of the machine its running on, as much as it is to a future maintainer of the code itself IMO... does it make sense in that context? Would you prefer to split that out into a separate document?

Would it take more than a few additional words to avoid the risk of confusion?

No, assuming the reader already knows the difference between the bridge MAC table and the router cache...

[rade]

Why is this in 1.4/master? Surely it should be on latest_release_doc_updates.

[awh]

Why is this in 1.4/master? Surely it should be on latest_release_doc_updates.

It's developer documentation in weave/docs, and is not linked from site.

[rade]

not linked from site

oh, I thought this was going to be an extension of "How it works", for folks interested in that kind of stuff.

[awh]

oh, I thought this was going to be an extension of "How it works", for folks interested in that kind of stuff.

The plan was for it to evolve into that, but even trying to get these minimal internal docs merged is proving an uphill battle 😄