Getting started guide

[matthew-humphrey]

We need a good "Getting Started" guide for the language.

Here are my initial thoughts on some things this should include:

High level overview - what is the language and why would you want to use it
Environment set-up - how to download and set up an environment to go through the code samples. Will initially restrict this to Linux / Windows+WSL, but eventually come back and add MacOS.
First code sample - simple class with a function Add that adds two integers. From there we will expand this to export a class, create a simple Verilog testbench to test it, and then run the whole thing in Verilator.
Expand upon the first sample to showcase the power of the language. One goal is to show how simple it is to add pipeline parallelism and spatial parallelism.
Showcase the power of the standard library by enhancing the (or creating a new) sample that leverages one or more library features.
Start to get into more "advanced" features of the language, starting with things people are almost certainly going to need (like atomic).
???
Somewhere in the above, the concept of callbacks and outbound interfaces needs to be introduced. I'd really like some feedback on this outline, as well as any ideas you might have for the samples in step 4 and 5.

Also in here, we need to cover the target device, and how one would use this with an actual FPGA.

@blakepelton @sapek @jptech

[blakepelton]

I like the outline. One possible theme for tutorials is a series of modules that accept a stream of integers as input, and produce a stream of integers as output.

The first one could do something simple like multiply each input by 3 and add 1. The tutorial docs should show how this one gets pipeline parallelism "for free" (no explicitly pipelining in the kanagawa code is necessary to get pipelined hardware output).

To show spatial parallelism, the interface could be changed to pass 2 numbers in/out per cycle, with a static for loop in the Kanagawa code.

To show nested pipelining, the static for could be changed to a pipelined_map. The docs could mention that this trades throughput for area.

To show atomics, the function could change to compute an aggregate like sum/min/max.

To show callbacks, the interface of the above module could be changed to return results via a callback only when the end flag is passed (via a callback).

To show the power of using larger library components, the interface could be changed to also pass a "key" along with each value. a hash_table could be used to compute separate aggregates for each unique key.

[matthew-humphrey]

I'm going to put it on the Wiki so we can have pages instead of a giant single document. Howevr, this does mean we lose the ability to run chkdoc to validate the internal code snippets. It would be nice to find a way to have that for selected Wiki pages.