Add examples

[umarcor]

As discussed in #56, in this PR:

• Subdir boards/osflow was created, in order to share sources between configurations using the open source tools.
  • UPduino_v3_ghdl-yosys-nextpnr was moved to boards/osflow/UPduino_v3.
  • filesets.mk, PnR_Bit.mk, synthesis.mk and tools.mk were created/split from the UPduino_v3 Makefiles.
  • Subdir boards/osflow/devices/ice40 was created.
• rtl/top_templates was renamed to rtl/templates and subdirs processor and system were created.
  • Existing templates were moved to one of those subdirs and renamed accordingly (both filename and entity name).
  • The existing UPduino_v3 'top' was split into a BoardTop and a ProcessorTop. The latter, named Small, was added to rtl/templates/processor.
• An examples directory was created.
  • The BoardTop corresponding to the UPduino Small Processor example was added.
  • A Makefile was added, which allows building any design for any board, as long as the corresponding BoardTop file exists, and the corresponding board support subdir is available in boards/osflow.
• A new 'Minimal' ProcessorTop was added to rtl/templates/processor, and the corresponding BoardTop for UPduino_v3 was added to examples.

I'm not sure about how to handle documentation. See the last commit in this PR.

• The README from the UPduino_v3_ghdl-yosys-nextpnr subdir was moved to boards/osflow.
• The README in rtl/templates was updated.
• A README was added to examples.

I moved part of the content from the first README to the other two. I think we want to have the "How To Run" section in examples, because that's the entrypoint (where the users need to execute make in order to get a bitstream). However, the details about the device (the platform-specific IMEM and DMEM used in ICE40 designs) might not belong in the examples. Overall, maybe it's worth having most of this content in the User Guide?

• The generics exposed in the Minimal and Small processor templates might be too few. Hiding the generics corresponding to the disabled peripherals is ok, but maybe the CPU extensions and others should always be available.
• The neorv32_UPduino_v3_SmallProcessor.bit bitstream should be equivalent to the previous demo contributed by @tmeissner. I did not change any feature (on purpose). I'd be glad if someone with an UPduino v3 could try it. Bitstreams are generated in CI (see below).
• I guess that the neorv32_UPduino_v3_MinimalProcessor.bit does not work. As per the discussion in Fomu #56, it might be too minimal. Note that I would like it to support one GPIO and 3 PWM by default, so that it can be used for blinky tests on boards with either a single LED or an RGB LED. neorv32_UPduino_v3_MinimalProcessor.bit should also work.
• The docs and READMEs need to be updated, according to all these enhancements.

[stnolting]

First of all: great work! 👍

rtl/top_templates was renamed to rtl/templates and subdirs processor and system were created.

I am still looking through your changes... So maybe this question will resolve. Anyway, where is the actual difference between system and processor?

The existing UPduino_v3 'top' was split into a BoardTop and a ProcessorTop. The latter, named Small, was added to rtl/templates/processor.

I struggle with descriptions like "small configuration" because they are very relative in terms of the actual use case. In contrast, i think the description "minimal configuration" is fine because you know what you'll get 😉

An examples directory was created.

Maybe we should remove boards and examples as root directories and put everything into a new folder implementation?
examples could be misleading and I think files related to an actual FPGA board setup should be somewhere together 🤔

I'm not sure about how to handle documentation. See the last commit in this PR.

Don' worry too much about that 😄 You already did a great job. 👍

By the way... Isn't it possible to include "all VHDL files" from rtl/core at once instead of including each single file in boards/osflow/filesets.mk?

[umarcor]

I am still looking through your changes... So maybe this question will resolve. Anyway, where is the actual difference between system and processor?

processor is just an instance of neorv32_top plus some routing/type conversion, without any other logic. Conversely, system is neorv32_top plus some other logic, such as the Wishbone to AXI-Lite bridge.

I struggle with descriptions like "small configuration" because they are very relative in terms of the actual use case. In contrast, i think the description "minimal configuration" is fine because you know what you'll get 😉

Agree. First, I named them FancyName and AnotherFancyName. Then, I changed to Minimal and Small, respectively. I also thought about using "Torsten" or "Meissner" instead of "Small", since he created that "setup". As you see, I'm awful at naming things 😭. Can you please decide better names? I believe they can be absolutely personal/made-up names. It is very difficult to describe all the details in a name, apart from "Minimal" and "Full".

Maybe we should remove boards and examples as root directories and put everything into a new folder implementation?
examples could be misleading and I think files related to an actual FPGA board setup should be somewhere together 🤔

I'm not sure about implementation being the best name, but I agree with putting boards and examples in the same subdir, and I cannot think about any better name. Hence, I'll move them into implementation.

By the way... Isn't it possible to include "all VHDL files" from rtl/core at once instead of including each single file in boards/osflow/filesets.mk?

It should. I did not try. I used ghdl -i and ghdl -m for simulation but not for synthesis. So, I tried to not do too many changes/experiments in here. That is an enhancement that we can "easily" try after we've done the most of these changes. At now, I'm concerned with "loading" the bitstreams. The current make BOARD=boardname designame works for generating the bitstream, but then I need to call dfu-util manually. I need to fix that (enhance examples/Makefile).

BTW, I can confirm that the Small example works on the Fomu by connecting gpio_o(0) to one of the RGB drivers. That is, the bootloader works. Now I need to adapt Minimal so that I get the same result. Then, I will update this PR.

[stnolting]

processor is just an instance of neorv32_top plus some routing/type conversion, without any other logic. Conversely, system is neorv32_top plus some other logic, such as the Wishbone to AXI-Lite bridge.

Tanks for clearing that. I like that approach 👍

Agree. First, I named them FancyName and AnotherFancyName. Then, I changed to Minimal and Small, respectively. I also thought about using "Torsten" or "Meissner" instead of "Small", since he created that "setup". As you see, I'm awful at naming things 😭. Can you please decide better names? I believe they can be absolutely personal/made-up names. It is very difficult to describe all the details in a name, apart from "Minimal" and "Full".

I feel you. I'm even worse giving things a name... Since we had this talk about "application-specific" setup (#42 (reply in thread)) I thought about creating some exemplary templates (now that would be in rtl/processor for application-specific configurations: a tiny one for low-area, a full-scale one and several configs in between and giving them some made-up names (I had Janeway, Sisco, and Riker 😆 ). But I dropped that.
Anyway, the actual is not really important as long as it does not "imply something". So go for it and just take any. 😉

I'm not sure about implementation being the best name, but I agree with putting boards and examples in the same subdir, and I cannot think about any better name. Hence, I'll move them into implementation.

How about example_setups or just setups? 🤔

It should. I did not try. I used ghdl -i and ghdl -m for simulation but not for synthesis. So, I tried to not do too many changes/experiments in here. That is an enhancement that we can "easily" try after we've done the most of these changes.

It's not urgent at all. Your are right, let's focus on the important things.

BTW, I can confirm that the Small example works on the Fomu by connecting gpio_o(0) to one of the RGB drivers. That is, the bootloader works. Now I need to adapt Minimal so that I get the same result. Then, I will update this PR.

Good to hear! 🚀
I'm looking forward to this. 👍

[umarcor]

I think this might be good to merge now.

• Created subdir setups and I moved boards and examples there.
• Renamed ProcessorTop Minimal to MinimalBoot, and Small to UP5KDemo.
• Exposed the generics and ports in MinimalBoot and UP5KDemo corresponding to the CPU or to the features/peripherals enabled by default.
• It's now possible to either build the bitstream only, or also program the board: make BOARD=boardname TASK=load UP5KDemo. A load target is required in the corresponding setups/boards/osflow/boardname/Makefile. That's not the case with UPduino_v3. @stnolting, @tmeissner, how do you program that board?

I tried this workflow with Fomu (#56) and I can confirm that the following do work:

make BOARD=Fomu MinimalBoot UP5KDemo
make BOARD=Fomu TASK=load MinimalBoot
make BOARD=Fomu TASK=load UP5KDemo
make BOARD=Fomu TASK='clean load' MinimalBoot
make BOARD=Fomu TASK='clean load' UP5KDemo

Note that README's/docs should be updated accordingly. @stnolting, will you take care of that?

I thought about creating some exemplary templates (now that would be in rtl/processor for application-specific configurations: a tiny one for low-area, a full-scale one and several configs in between and giving them some made-up names (I had Janeway, Sisco, and Riker 😆 ). But I dropped that.

I think Janeway, Sisco, and Riker, or any other is perfectly acceptable 😉

BTW, I can confirm that the Small example works on the Fomu by connecting gpio_o(0) to one of the RGB drivers. That is, the bootloader works. Now I need to adapt Minimal so that I get the same result. Then, I will update this PR.

Good to hear! 🚀
I'm looking forward to this. 👍

Since the Fomu has an external 48MHz clock, I still want to enhance those BoardTop files (#56). However, I think that this PR (related to UPduino_v3 examples only) is ready to merge. That will allow us to work on enhacements separatedly:

• Docs.
• Adding a load target to UPduino_v3.
• Running demo_pwm on Fomu, without a bootloader.

[stnolting]

I think this might be good to merge now.
[...]
I tried this workflow with Fomu (#56) and I can confirm that the following do work:

Awesome!! 🚀

Note that README's/docs should be updated accordingly. @stnolting, will you take care of that?

Yes of course.