Create wiki

[cutephoton]

trafficstars

This is the first RISCV core I've been able to get up and running without breaking my head. Much appreciation for the SpinalHDL team for the making this work with Qsys and Avalon. :) (Although SpinalHDL itself puzzling still.)

Where should notes and documentation go? (Is there a wiki?) There's a lot of little things I had to figure out. It would be nice to make it easy to post the notes. One example, for Quartus, is the memory initialization files. Quartus memory initialization files are interpreted with the wrong endianess. Another configuration option is required to support intel hex as well. (Or maybe there's a simpler approach to making programming files?)

Objcopy can produce compatible output using this...

$(RISCV_OBJCOPY) --strip-debug --remove-section=.comment --remove-section=.note --strip-unneeded -O ihex --reverse-bytes=4 $^ $@

I'm not sure where to put these nuggets of information.

[Dolu1990]

Hi,

Great :D The integration with the Qsys tcl stuff worked fine ?

Currently, the only documentation about VexRiscv is the root readme.md, that's not enough, i agree.

So, for the memory initialisation, i personnaly only used the memories generated out from SpinalHDL itself, that's why i never hit those issues, which would be usefull to document.

For additional documentation, maybe we can create a doc folder in the VexRiscv repo that we can then fill with some xxx.md (instead of keeping the readme.md bigger and bigger) ? would that be good enough ?

[cutephoton]

What about using the wiki feature on github? Should do as above for more formal documentation as content becomes more complete.

It works (although I disabled the caches). Interrupts work. The main problem is the limited support for avalon. Although the jtag interface works, it usually misbehaves -- the writes and reads are often corrupted. Writing 0xAAA5555 becomes 0x55559FFE. I'm going to try some other jtag adapters.

(gdb) info registers
ra             0x000000a3	163
sp             0x000000a3	163
gp             0x000000a3	163
tp             0x000000a3	163
t0             0x000000a3	163
t1             0x000000a3	163
...
t5             0x000000a3	163
t6             0x000000a3	163
pc             0x000000a3	163

But loading code using the "in system memory content editor" and manual resets work. Some simple tests were pretty satisfying.

[Dolu1990]

The issue that i have with the github wiki is that the wiki ressources aren't in the repository itself, but a related one (https://github.com/Dolu1990/VexRiscv.wiki.git) That's why i'm proposing using markdown (or rst) doc ^^

For the jtag, at which frequancy is the jtag running, and at which frequancy is your design running ?

What is the issue with the avalon support ?

Be carefull with the signal cross talk, the jtag clock can be sensitive :)

[tomverbeure]

I really prefer keeping the documentation in the main repo itself. The wiki is a different repo that doesn't allow standard pull requests.

Tom

[cutephoton]

The rationale for keeping the docs in the main repo is sound. The counter point is that that it creates a barrier to entry to contribute. With that said, creating a docs folder and creating a bit of structure is a good place to start.

I'll create a separate issue for my jtag issues since this is probably the wrong place to debug.

[Dolu1990]

So, i have to say i'm one of the worst for the documentation, as i'm in the SpinalHDL/VexRiscv stuff since too long. How would be a good structure from you point of view :) ?

[wifasoi]

(self proclaimed) Doc guy to the rescue! We can use sphinx for fun and profit! (and let the tedious work of compiling/checking/pushing to gh-pages to travis) We can link it (if necessary, or if we like) to the main SpinalDoc-RTD repo with Inter-Sphinx. You only need to learn is how to write in ReStructuredText (Sphinx supporst markdown.. but i prefer rst).

I think the barrier to entry can be lowered by trowing documentation at it :) [META doc is the best doc] So the only thing left is to generate the content, all the rest will be taken care by (me) and the CI.

What do you think?

[Dolu1990]

Let's move for the Sphynx doc, with the sources directly into the VexRiscv repo ?

[wifasoi]

yes, and if in the future we want to move it to a separate repo we can use the power of git filter-branch :P I can create a preliminary PR with the necessary CI/CD setup tomorrow.

[eine]

The issue that i have with the github wiki is that the wiki resources aren't in the repository itself, but a related one (Dolu1990/VexRiscv.wiki.git) That's why i'm proposing using markdown (or rst) doc ^^

What about adding VexRiscv.wiki as a submodule of VexRiscv (say, in subdir doc)? GitHub Wiki sources are a bunch of markdown files in the end. Hence, the same sources can be used to generate a gh-pages site with a tool such as Hugo.

However, if you want to use Sphinx, as proposed in SpinalHDL/VexRiscv#50, integrating the wiki can be painful. It is possible, because Sphinx accepts both rst and md sources, but less features are supported in md.

[wifasoi]

I prefer to not use the wiki, and only gh-pages with sphinx html export. I feel support both (sphinx/static site generation and the wiki) is more a hack than a solution. I like to keep the doc generation as simple as possible and limit the CI/CD fanciness to a minimum, so anyone can pick up my work easily. There is the case that "You can not break something that is not there": so is better to have sphinx or wiki and be solid like a tank, than both ways and (possibly) flaky. This is just my opinion, I'm open to other ideas. Disclaimer: I'm the author of #50