docs: split User Guide #53
Conversation
|
Thank you very much - so were so active! 👍 I still like the idea of having everything in one place - but maybe this is a situation (again), where things make perfect sense to me, but everybody else would struggle... So I am open about this 😉
No worries. I would take care of that. That is the least I can do. |
❤️
I do understand that, and I also understand why some users would want to have "the NEORV32 documentation book". Yet, at the same time, I see why newcomers would like to read a User Guide without being overwhelmed by the length of "the book". This allows them to interpret the resources as "this is what we expect you to read and these other docs are for you to understand when you are slightly more experienced". Being more specific, I would like to print one copy of the User Guide for each "student" in a workshop/course, and provide it to them along with an Arty and/or a Fomu. We already use Arty at university, and I hope I can talk with @mithro for organising some workshop in some meeting in Europe when that's a thing again. I've never been to CCC or FOSDEM, so those would be nice places to let people tinker with the renewed learning resources (the addition of VHDL and RTL related content, such as the verilog UART-through-USB). Nonetheless, we can provide both document type solutions. Generating a book is just a matter of adding an additional top-level By the way, I renamed "Let’s Get It Started!" to "User Guide" because it made it easier to name the subdirs and URLs. I kept that sentence at the beginning for cheering up the readers. Feel free to suggest another name (say "Getting Started").
👍🏼 ❤️ |
|
Another option is to generate the website as in this PR (a subdir for the user guide), but don't generate mutiple PDF (not 2, not 3, just one). |
Ok, sounds reasonable 😉 👍
That would be awesome! I really love the Lattice ice40 UltraPlus FPGAs - now even more since there is an open-source implementation flow available for this project 😉
Please also add an badge to the documentation linking to the HTML-based user guide.
I'm fine with that.
Good question. The book thing sounds nice, but that is not really relevant right now. If you can download a PDF for the documentation and another one for the user guide it's fine. |
You might want to have a look at some board with an ECP5 device. Those have 25k-85k LUTs. See hdl.github.io/awesome/boards. Those are supported by Yosys and nextpnr, similarly to ICE40.
See https://carlosedp.medium.com/xilinx-open-source-fpga-toolchain-on-docker-containers-93202650a615.
It's in place. However, if I push other branches, it's updated/removed. See the following captures:
Then, I believe this is ready to merge. Be careful when merging. I recommend that you do it before pushing new commits to master. Otherwise, please let me know and I will rebase before merging. For building locally, you can use |
I have never worked with those FPGAs so far. But it seems like they provide distributed RAM - a very handy feature I am missing in the ice40s.
This is just awesome! 🤩
Looks great!
Got it. 😉 |
Yeah. It's a completely different scale. ICE40 devices are really small and low-power. They are not meant to contain complete SoCs with CPU + accelerators + external QSPI mem streaming. It's actually impressive what we are being able to squeeze into the Fomu, UPDuino, Icebreaker, etc. Those boards should not be able to run the awesome demos that people are showing 😆 On ECP5 devices, people have described Linux capable soft cores. That's a different beast! While you might not get the same performance/size as on Xilinx's 7 series devices (I'm thinking about the features of BRAM, DSP and other hard IP), for most of hobbyist, hacker and academic projects, ECP5 are more than good enough. From a design complexity perspective, you can already do all you can imagine on an ECP5. See, for instance, the OrangeCrab board. That's an ECP5 with DDR memory on a "Feather" form-factor. The ButterStick is very interesting too (by the same designer). However, ECP5 boards are more expensive than ICE40 boards, for obvious reasons. There is a very relevant exception: Colorlight boards. Those include ECP5 devices and the price is 15-30€. They were built as LED controller boards, but people are repurposing them as FPGA dev boards.
It is ❤️. I'm looking forward to having time for integrating it into hdl/containers (or for any contributor to help with that). I saw that you already fixed the internal cross-references. Thank you so much! As commented in bd54389#r51728253, I think you can use relative references in the README. By the same token, in the adoc sources it should be possible to have some helper, for avoiding hardcoding the full URLs in each cross-reference. Sphinx has the concept of extlinks and intersphinx_mapping. Unfortunately, I didn't find an equivalent feature in asciidoctor. I use two workarounds:
|
I am really shocked when I see what can be fit into this tiny FPGA. 😆 "Shocked" because the ice40 architecture is so(!) damn(!) simple(!) when compared with mainstream Intel and Xilinx FPGAs: no distributed RAM, no fancy multiplexers behind the LUT for effective LUT-widening, no dedicated carry-chains between LUT and FF.... Everything is implemented using LUT4!!! But still, you can put a whole SoC into that. I bet someday there will be someone playing Doom on an ice40 🤣
I did not intend to say these FPGAs are less good than the Xilinx or Intel ones.
I have seen that on Tindie. And I always wanted to have one! But they are still pretty expensive...
🤩 Do you have a link?
I think it is ok for now. But thanks for the information! One more for the ToDo-stack 😉 |
Amen 👏🏼
Too late mate! There are a bunch of demos already! Go check @sylefeb's Silice and his examples (sylefeb/Silice: projects/doomchip). You... will... ❤️ them!
He and @BrunoLevy (BrunoLevy/learn-fpga) have strong mathematical and computer graphics background, and they are doing some really impressive stuff! Recently, there were some experiments about dynamic reconfiguration: https://github.com/sylefeb/Silice/blob/draft/projects/ice40-warmboot/README.md.
There are several models with different prices:
I'm no expert in all the different models... Recently, the developer of IceSugar did some slightly different designs, which might be more interesting as an FPGA development board. It's an standard SODIMM connector and a baseboard:
There is also the IceSugar-Pro, compatible with the same base board: https://github.com/wuxx/icesugar-pro. The main difference is that the icesugar-pro has the USB and the programmer on-board, so it can be used without the baseboard. These are the prices in MuseLab-Tech (https://muselab-tech.aliexpress.com/store/5940159), but the Colorlight boards are available from multiple shops. I believe the IceSugar-Pro is only available here:
For completeness, two other popular ECP5 boards which I didn't mention:
The smallest models of these are ~100€, which is very acceptable compared to Arty boards. |
This is really incredible! 🥳
It is so cool that ice40 provides this feature! I am experimenting with a NEORV32 setup that uses the WARMBOOT primitive in order to get rid of the FPGA programmer: just send the bitstream to the NEORV32 bootloader via UART. The bootloader puts that in external flash and reconfigures the FPGA. After reset (FPGA "reset", actually) the golden image with the NEORV32 is back and you can start again. 😎
Arty boars are available here for ~50 bucks via educational programs. But still, 100€ seems ok for these boards. When looking through all your board recommendations I stumbled across the Icebreaker bitsy. I provides lots of external RAM (pseudo SRAM)!! Finally!!! I was looking for something like that build around an ice40 UP!!! 👍 |
As a matter of fact, that is how Fomu's bootloader works, which is based on TinyFPGA's bootloader. Both of them have a reset image which acts as a passthrough for writing the "user design" in memory. By default, ICE40 devices can only manage 4 images + reset, but you'll see that we found how to handle any number of images.
Yeah. I got my PYNQ-Z1 at $65 back when they were promoting it in 2017. However, I don't think that is fair. The company is losing money (or not earning it) so that you can get dependent on their technology, and only the targets of such strategy can get the discounted price. Nowadays, the price of that same board is $200 regular, and $150 academic: https://reference.digilentinc.com/_media/sales-resources/academic_prices.pdf. So, a 25% discount instead of 70%.
A few days ago, the developers/sellers of icebreaker-bitsy offered to send you one if you wanted to add NEORVR32 support (i.e. test that NEORV32 works). Did you miss that message? With regard to pseudo SRAM, note that's a trick/hack you can apply to any FPGA board with a QSPI flash, which has the 4 data lanes routed to the FPGA. See icebreaker-fpga/icebreaker#19:
|
I have not further investigated the FOMU bootloader yet. Is it "pure" hardware or does it use the SERV CPU as "middle ware"?
No, I didn't. But I feel uncomfortable when being treated special 😳
Well, that's a nice Frankenstein setup! 😄 |
My understanding is that's a RISCV middleware. Not a SERV, tho. It's a VexRiscv, written in spinalhdl (scala) and exported to Verilog. See https://github.com/im-tomu/foboot and https://github.com/im-tomu/foboot/tree/master/hw/rtl.
Let me put it differently 😉. Compared to open source software, doing hardware is more dependent on having specific devices at hand. Unfortunately, not all of us have access to the same resources, which generates an imbalance with regard to how much we can do, or how far we can advance. Fortunately, tho, there are some people who have enough resources and they are kind enough to donate material for the community. It's not about someone being special, but about trying no one to be limited (another kind of undesirable special) while others can help within their capability. Hence, if you feel uncomfortable taking it as a present, you might consider yourself to be the temporary custodian of some piece of hardware that belongs to the community. You were offered it because you need it, in the sense that you want to do something specific with it, but you don't have it physically. Take it, use it while you have something to do/build with it; then, give it away to some other people of the community, the same way it was given to you. There will always be people who know more and less than you, and who have more or less access to resources. Some will be close to you, others very far away. Some hardware will be lost, other will be donated. It doesn't matter, as long as each transaction serves for helping at least one person and for enhancing one open source project. One little step at a time.
Agree. However, this trip with Fomu is just starting 🚀 Having it supported and running the PWM is just the very first step. Lots of enhancements and demos can be done afterwards:
I won't be able to implement/test all those features myself, so it would be helpful if other NEORV32 + Fomu users could join. I agree that most of these features might be implemented on other boards with the same device. However, Fomu is the one where it is most necessary, due to the limited I/O and size.
It is! Note that Icebreaker and Icebreaker-bitsy use one extra pin for selecting either the "regular" flash or the pseudo-ram. Furthermore, the performance you can get is limited by the design! Therefore, in order to gain advantage from the psudo-ram, some minimal DMA needs to be implemented. I think the ~20MHz of the NEORV32 are not enough for making a difference. |
|
Hi - great discussion! Hoping to resume on warmboot soon (my early tests for keeping SPRAM content did not work, but clearly I missed something! looking forward to explore this further). Great work on neorv32, looks very complete, efficient and well documented! |
That is absolutely true - even though I never thought about that.
This is a very kind view and I am thankful for that. But I am fine. As long as I have a FPGA board with an ice40up and a soldering iron on my desk I think I could at least try to "emulate" the boards I do not actually have 😉
It is really fun to test that and to see what synthesis comes up with. Sometimes even plain old Vivado suprises me.
This was I am trying right now. Put an executable to external SPI flash via the FPGA programming interface and fetch that via the bootloader to execute it. I would love to have a setup where you only need to program "one file" to the flash (bitstream(s) + executable(s)) to tinker around with the board.
I was not aware of this but this is a feature I really need to test! 😄
It is really difficult to handle a whole USB stack in such a small FPGA - so I am even more impressed by the FOMU!
I think the primary point is to have more storage than just the internal 128kB. Maybe it is possible to build a small SPI engine plus cache that uses QSPI and runs at ~48MHz. Then you could use the external RAM without much penalty as general purpose storage for any setup similar to using BRAM. Thank you very much! |
Note that several boards do have an FTDI along with the FPGA (icebreaker, icestick...) or an ARM for the same purpose (blackice, icesugar...). Therefore, I don't see much value on adding that to a board which does not provide those. In the Fomu, for instance, the SPI mem can be flashed externally. The challenge is how you get to connect to those tiny pins in the board. That is, it's a mechanical problem, not electronical/digital. It's something you would only do out of need if it went grilled. Otherwise, icebreaker or icesugar provide a much better learning/developer experience. Nevertheless, @juanmard used an Arduino connected to the iCESugar for doing the screen captures you saw in recent issues, instead of passing through the ARM.
I've seen the concept of pseudo-RAM mostly used for streaming to video output, so mostly a performance motivation. I believe there are non pseudo-RAMs with similar or larger size which should be cheaper.
Exactly that's how it's used. I've seen it run at 2-3 times that speed. The one in the Fomu is rated at 133 MHz (see https://github.com/im-tomu/fomu-hardware/tree/master/archive/pvt). So, compared to NEORV32 running at, say 22 MHz, that is at least 6 times faster than the CPU itself can handle. In "videogame" engines, a CPU is used for driving the logic, but drawing in the screen is actually done by streaming content from the external flash to the VGA/DVI output, without intervention of the CPU. |
Maybe you could use the FOMU's "buttons" to solder a JTAG interface to it 🤔
The ARM is just gateware for host access, right? So configuring and passing UART data?!
Right. But even if the SPI flash is accessed in quad mode you have some overhead plus you need to send commands and addresses to the flash. In summary, a 128 Mhz SPI interface might be directly integrated to a 16Mhz SoC without any CPU wait states. |
You can. Actually, @sylefeb soldered an SPI screen to those... https://twitter.com/sylefeb/status/1391898528285351948
The ARM on the iCESugar is multipurpose. It is used for programming the flash or the FPGA. It is shown as drive on Windows and you can drag & drop the bitstream for having it automatically uploaded. Other than that, it has UART connection (optional). There are some other optional connections between them I think. Hence, you can use the ARM for nothing or from some rather complex co-execution setup.
My understanding is that the extra speed is used for dealing with the command/page overhead. However, such details are off my knowledge. I take your word 😉 |
This is incredible! 🤩 |
As commented in #42 (comment), this PR splits the User Guide from the Datasheet.
Subdirs
docs/datasheetanddocs/userguidewere created the sources fromdocs/src_adocwere moved. Theindex.adocwas copied.neorv32.adocwas renamed tomain.adocand it was copied too.The artifacts (PDFs and HTML) are now generated in
docs/public.The Makefile, CI workflow 'Documentation' and gitignore were updated accordingly. Shields/badges were added to the README and to both HTML pages. Figures and icons are shared by both HTML pages.
Section 'Legal' was included in both the Datasheet and the User Guide.
Still, internal (now external) references and references from the README to the site need to be checked/updated.
See: