Reorganise the documentation

[umarcor]

#26 (comment)

I am also thinking about cutting down the main README of the repo. From my point of view, the current version provides way too much in-detail information. Having just a short summary with links to the GH pages (for the interested reader to continue)
might be a better approach.

#26 (comment)

I believe that the purpose of the README is to catch the attention, both from users (brief description and relevant links) and from maintainers (CI and broken stuff). Any additional information you put in the README is likely to be duplicated in the documentation, so the maintenace burden is increased.

#26 (comment)

I think that some sections of the README should be standalone documents. That is the case of Contribute/Feedback/Questions. Getting Started would also deserve a more visible location. That content is then extended in chapter 6 of the datasheet, named Let’s Get It Started!. From a project level point of view, the "User Guide" or "Getting Started Guide" is not part of the datasheet, but a sibling document. See https://documentation.divio.com/ for very interesting knowledge about how to organise technical documentation.

If we take this to the limit, each of the chapters in the datasheet might be a different document (a separated PDF and a subdir in the HTML site):

• NEORV32: Project [Understanding]
• NEORV32: CPU [Information]
• NEORV32: System on Chip [Information]
• NEORV32: Software Framework [Information]
• NEORV32: Debugging [Problem]
• NEORV32: User Guide [Learning]
• NEORV32: Contributing (maybe markdown/HTML only, or included in 'Project')

From a user point of view, if I printed the datasheet, I would not bind it all together, because I will want to read multiple of the documents at the same time. E.g., I want to have the CPU and SoC chapters at hand while reading the User Guide or how to Debug a design.

#26 (comment)

Right now I am cleaning up the main README - but I am not really happy with the current version. I can't decide on what to keep there. What is important? What should be there as "immediate advertising"? The problem is that I do not want to overwhelm FPGA/RISC-V/VHDL/whatever beginners but on the other side I don't want to offend the pros... You know what I mean? 😄

#26 (comment)

Apart from that, I think that some sections of the README should be standalone documents.

I also thought about this. But actually, I like having everything in one place. But maybe this has already gotten way too confusing as more and more stuff is added to the documentation.

[umarcor]

GitHub provides an autogenerated table of contents for the README. That is only visible in GitHub and not in any editor which users might use for viewing the cloned repo. However, I believe it's not worth maintaining the toc manually. In fact, it's currently "outdated", since Acknowledgements is not shown, and some titles don't match.

[stnolting]

I have cleaned up the README and also the TOC.
Acknowledgements and Legal is not "relevant" for the normal user at the very first visit of the page so I have not included that into the TOC.

[umarcor]

Should 'Legal' be ## instead of ###?

[umarcor]

Also the URL is now https://github.com/stnolting/neorv32#copyright-legal (note the copyright, because of the icon).

[stnolting]

Oh, "Legal" should not be in the TOC at all 😄 I will remove that.
I think it is not so important on "first encounter".

[umarcor]

I don't think that Acknowledgements or Legal need to be in the README. They are way too far at the bottom, and the size of the logos in the Acknowledgements section is not proportionated. Instead, I would suggest adding the Acknowledgements section to chapter 1 of the datasheet/site. By the same token, the Legal info is already included in chapter 1 of the datasheet/site. Moreover, the license is identified by GitHub and it is shown in the right sidebar. There is also a shield/badge at the top of the README, pointing to the license file. It might be interesting to make it point to the Legal section of the datasheet/site. The Citing info/comment is currently shown in the README only. I would keep it there, but I would add it to the datasheet/site too.

[stnolting]

I don't think that Acknowledgements or Legal need to be in the README.

I think you are right. Maybe it is better to put that only into the documentation and add something like an "imprint" with a link into the README.

The Citing info/comment is currently shown in the README only. I would keep it there, but I would add it to the datasheet/site too.

Good point. I was not aware this is not in the documentation.

[umarcor]

I like the new Legal chapter in the docs. All together, tidy and easy to find. Good job!

With regard to the citation, you might want to provide a code/verbatim block with the BibTeX entry. As a researcher, it is very annoying when some reference does not provide that, because sometimes you need to spend time finding the details and making sure you are not messing something. Unfortunately, academia, and tooling used in academia, are way behind 2021. They are at least a decade behind. Hence, there is no standard format for referencing repositories:

• https://academia.stackexchange.com/questions/14010/how-do-you-cite-a-github-repository
• https://github.com/AASJournals/Tutorials/blob/master/Repositories/CitingRepositories.md
• https://gitlab.inria.fr/gt-sw-citation/bibtex-sw-entry

Yet, something such as the following might work:

@misc{nolting20,
  author = {Notling, S.},
  title = {The NEORV32 RISC-V Processor},
  year = {2020},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/stnolting/neorv32}}
}

Moreover, you might want to have some "more formal" reference identifier. That is, a DOI. As mentioned in some of the references above, there are a couple of solutions for achieving that:

• https://guides.github.com/activities/citable-code/
• Publish a "dummy" article. For instance, the articles in joss.theoj.or are basically placeholders, since the main purpose is to provide a developer friendly mechanism without charges/fees. The submission procedure is handled through GitHub: openjournals/joss. See, for example, joss.theoj.org/papers/10.21105/joss.01349, which corresponds to mviereck/x11docker. Note that articles are not "alive". Once published, they are not modified, even though the software might evolve.

[stnolting]

I like the new Legal chapter in the docs. All together, tidy and easy to find. Good job!

Haha thanks 😉

With regard to the citation, you might want to provide a code/verbatim block with the BibTeX entry.

Good point! I will update the legal section with that (nice!) BibTeX entry.

Moreover, you might want to have some "more formal" reference identifier. That is, a DOI. As mentioned in some of the references above, there are a couple of solutions for achieving that:

I was not aware of this https://guides.github.com/activities/citable-code/
I have authorized Zenodo and I will try getting a DOI with the next release. 👍

[umarcor]

If Implementation and/or Performance results/tables are potentailly going to be updated dynamically from CI results, I believe it's better to keep them in the datasheet/site only. Currently, there is more info in the readme than in the datasheet, which is not intuitive. One or multiple shields/badges might be added to the readme, pointing to the corresponding section(s) in the site.

[stnolting]

A minimal description of the processor's performance and logic requirements is an important metric for comparison with other RISC-V SoCs (in combination with the ISA extensions and SoC features).

For the READMe is might be better to put everything into a single sentence ("CPU coremark performance between x.x and y.y" ... "requiring between x and y LUTs) and place a link to the documentation's implementation results section.

[umarcor]

Agree. I don't mean there should be no info about it in the README, but that the tables with the details should be better located in the docs. It's ok to have a paragraph (no need to be a sentence only) in the README summarising the smallest and largest achievable configurations.

With regard to comparison with other solutions, VexRiscv uses a code block in the README (https://github.com/SpinalHDL/VexRiscv#area-usage-and-maximal-frequency), which I (coherently) dislike. However, SiFive's Core Designer has a more interesting visualisation: scs.sifive.com/core-designer/. You can see which ARM models they compare to roughtly. Then, in the details of each configuration, you get a comparison table. For instance, sifive.com/cores/e20. Note also the different block diagrams for each configuration.

Overall, I think the documentation in this repo should head towards the SiFive approach. Not so complex/fancy, but preserving the idea of "an entrypoint for users who are going to use the configuration as a pre-built black-box". So, "exemplary setups" would be not just a list of one implementation for each board; but the section for each exemplary configuration, and then the results for the implementation of that configuration using a different board. Currently, setups are "as much as we can fit in this board". However, in practice, engineers are application driven. Therefore, configurations should appeal to the target audience. See the descriptions of SiFive series:

E20

(...) microcontroller applications such as IoT, Analog Mixed Signal, and Programmable Finite State Machines.

E21

(...) microcontroller applications such as Sensor Fusion, Smart IoT, Wearables, Connected Toys, and more.

E24

(...) a high-performance microcontroller with hardware support for single-precision floating-point capabilities, implementing the RISC-V ISA’s F standard extension.

E31

(...) the E31 takes maximum advantage of the RISC-V ISA, resulting in a power-efficient core that delivers the high performance needed for tomorrow’s smart IoT, storage, and industrial applications.

Naturally, the solutions in this repo do not need to be so granular and detailed. That is a company that sells IP, and they have people for doing that. This is a single-man open source project. Yet, it makes sense to "advertise" some configurations for "niche" (or not so niche) applications. For example, a 4-in-1 Electronic Speed Controller (ESC), which requires 4 x 3 x 2 = 24 PWM (actually, can be 4-12 if additional ad-hoc hardware is supported).

By the way, how do you generate the block diagrams and figures? Do you create them manually?

Note that ARM does also have a Cortex-M System Design Kit: https://developer.arm.com/ip-products/subsystem/corstone/corstone-101. However, I don't understand ARM's website... 😕.

[stnolting]

VexRiscv uses a code block in the README (https://github.com/SpinalHDL/VexRiscv#area-usage-and-maximal-frequency), which I (coherently) dislike

I also do not like that at all. Furthermore, I also struggle with architecture descriptions like "small and productive". They are far too vague on the one hand, but on the other hand they might be good for some kind of "categorization". 🤔

However, SiFive's Core Designer has a more interesting visualisation: scs.sifive.com/core-designer/.

Are you talking about the individual core diagrams on that page? I don't understand them at all 😅

Currently, setups are "as much as we can fit in this board". However, in practice, engineers are application driven. Therefore, configurations should appeal to the target audience.

True, unfortunately :D
I think it is a good idea to show a more application-driven overview of required hardware resource and maybe even performance.
So maybe the VexRISC approach with "small and productive" is not that bad at all. I will put that on my to-do list!

By the way, how do you generate the block diagrams and figures? Do you create them manually?

Yes I do. I am using PowerPoint for that.. And yes... I know... this might not be en vogue, but it doesn't matter - I like the style 😎

[umarcor]

Are you talking about the individual core diagrams on that page? I don't understand them at all

Neither the naming nor the diagrams make any sense to me. I believe that is something the whole industry learnt from ARM and Microchip 😆. However, I meant the general idea of listing (briefly) configurations of different complexity/performance with some (arguably) nice/descriptive icon and then having an specific page for each of them, where the implementation/result figures are shown along with a "marketing" descriptions appealing to the expected application.

So maybe the VexRISC approach with "small and productive" is not that bad at all. I will put that on my to-do list!

Yes! That's the common idea between VexRiscv and SiFive, but they implemented it completely differently. VexRiscv is a single man which provides all the raw data. SiFive is a company with several layers until you get to the details.

I must say I'm awful at marketing. Therefore, I am not very usable in this area 😢.

Yes I do. I am using PowerPoint for that.. And yes... I know... this might not be en vogue, but it doesn't matter - I like the style 😎

Oh, I rely on Tikz/pgfplots, so I cannot really criticize you for demodè tooling 😆.

It was a genuinely curious question. I've been long looking for a tool/language that allows drawing diagrams programmatically, and having them saved in text. That is, what I get from Tikz, but which allows to generate SVGs, PNGs, etc. and not just LaTeX figures with LaTeX style. Unfortunately, I didn't found a solution yet. Lately, I'm using draw.io, which is more modern than PowerPoint, it's open source, and the source is "text". However, from the usage point of view, it's not significantly different from PowerPoint. In case you are curious about this topic:

• hdl.github.io/containers: Graph generation/parsing
• RTL Schematic View f4pga/ideas#41 (general discussion about RTL diagrams)
• Generate a schematic starting from dump produced by GHDL (XML or others) ghdl/ghdl#1519 (about using GHDL for generating the diagrams)
• SymbiFlow/sphinxcontrib-hdl-diagrams (it'd be nice to have an equivalent plugin for asciidoctor-diagram)

[umarcor]

I believe that the summary of project features, CPU features and SoC features all belong to the README. Therefore, I wouldn't modify that part of the README.

[umarcor]

In "NEORV32 CPU Features":

• You can write the 5 items in "General" as a paragraph, instead of a list.
• Don't need to specify what each extension means in the README. You can list A, B, C...DB and link to the datasheet for the users that need/want to check the meaning. Most experienced users already know what they mean. Less experienced user don't understand what they mean, even if you define them.
• Similarly, no need to list all the supported traps and define them. You can say "interrups (MTI, MEI, MSI, FIRQ and NMI) and exceptions (intruction, load/store, breakpoint, environment call) are supported".

---

I would move the main diagram to section "NEORV32 Processor Features", since that allows to avoid listing and defining all the modules in the README. WDT, UART, SPI, TWI, GPIO, WISHBONE, PWM, TRNG, CFS, NCO, NEOLED, JTAG/OpenOCD are shown in the diagram already. You can say that "more than 16 commonly used peripherals in uC devices can be optionally built-in". You might want to list some of them explicitly, but I don't think it's worth providing details about UART, SPI, PWM, GPIO, etc. Those are all "expected" features in a uC.

The order of introducing the SoC and the CPU feels strange. You define the project as "a SoC based on a CPU" and the main diagram is showing the SoC. However, then you explain the CPU features first, before explaining the SoC. In the section about implementation results, the CPU figures are shown and the SoC then. Last, performance is about the CPU. So it's a diagram(top)-bottom-top-bottom-top-bottom explanation for someone reading the whole README in order. I would suggest some more linear approach (either top-down or bottom-up). Just a possible solution:

• Moving the diagram to the section about the SoC (as suggested above) is a partial solution: bottom-diagram(top)-top-bottom-top-bottom.
• Moreover, you might want to move the performance together with CPU results: bottom-diagram(top)-top-bottom-bottom-top.
• I would present the SoC first and the CPU afterwards. That is coherent with: "It is recommended to use the processor setup even if you want to use the CPU in stand-alone mode". So the result would be: diagram(top)-top-bottom-bottom-bottom-top.
• Last, you might want to provide SoC implementation results as a subsection of the SoC info: diagram(top)-top-top-bottom-bottom-bottom.

---

I would extend the "NEORV32 Software Framework" to "NEORV32 Software Framework and Tooling". That section should contain, the most relevant features/complements that users need to know after understanding they are working with the RTL code of a RISC-V based SoC. What to do with the RTL? How (with which tools) to implement it? How (with which tools) to program it? What (which software libraries) to program?

Hence, I would list the support for OpenOCD and DBG here. Those tools are most useful when there is some software to debug. Furthermote, I would list both the following:

• Implementation with open source tooling (GHDL, Yosys and nextpnr; in the future Verilog-to-Routing) is supported. So, both software and hardware can be developed and debugged with open source tooling.
• Continuous Integration is available for:
  • Allowing users to see the expected execution/output of the tools.
  • Ensuring specification compliance.
  • Catching regressions.
  • Providing ready-to-use and up-to-date bitstreams and documentation.

Naturally, no need to list all of that. Those are just some ideas. The point is that CI is an important quality asset of the project (and it's going to be more important as better testing and more target configurations/setups are added). Currently, a single implementation job is setup. However, I'd like to contribute jobs based on MSYS2 (see CI of GHDL, VUnit, umarcor/SIEAV...). My colleagues and students use Windows 10 mostly. Hence, even though containers are faster in CI than setting up MSYS2, I believe it is worth having both examples. That allows users to see runs that match their local setup.

[stnolting]

You can write the 5 items in "General" as a paragraph, instead of a list.

Do you mean as real text?

Don't need to specify what each extension means in the README. You can list A, B, C...DB and link to the datasheet for the users that need/want to check the meaning. Most experienced users already know what they mean. Less experienced user don't understand what they mean, even if you define them.

So maybe something like this?

CPU: RV32[I/E][M][...]

(ISA extensions in capital letter to make them clickable)

Similarly, no need to list all the supported traps and define them. You can say "interrups (MTI, MEI, MSI, FIRQ and NMI) and exceptions (intruction, load/store, breakpoint, environment call) are supported".

👍

I would move the main diagram to section "NEORV32 Processor Features", since that allows to avoid listing and defining all the modules in the README. [...]

Yea, you are right regarding the listing of all modules. However, I thought having the diagram right at the beginning might be a good eye catcher 🤔

The order of introducing the SoC and the CPU feels strange.

Good point. It is nice to have some feedback here, since "in my head" everything makes sense all the time 😅
How about this order?

• overview
• key features (really required?)
• SoC
  • diagram
  • features
  • implementation results (whole SoC)
• CPU
  • features
  • implementation results (CPU only)
  • performance

I would extend the "NEORV32 Software Framework" to "NEORV32 Software Framework and Tooling".

Sounds good.
I also need to emphasize the part regarding open-source tools. And yes, CI is a quality metric that should be emphasized, too.

Currently, a single implementation job is setup. However, I'd like to contribute jobs based on MSYS2 (see CI of GHDL, VUnit, umarcor/SIEAV...).

Another point I have not thought about.
That would be really great (as I am also a Windows fan boy 😄)!

[umarcor]

You can write the 5 items in "General" as a paragraph, instead of a list.

Do you mean as real text?

Yeah. For instance:

NEORV32 is an official (see architecture ID) little-endian two-stage RISC-V CPU with independent instruction/data bus interfaces, and multiple supported operating modes / privilege levels: machine and optional user and debug_mode.

---

So maybe something like this?

CPU: RV32[I/E][M][...]

(ISA extensions in capital letter to make them clickable)

Yes. However, you can use spaces! We won't charge you for those characters 😝. For instance, appending it to the previous paragraph:

NEORV32 is an official (see architecture ID) little-endian two-stage RISC-V CPU with independent instruction/data bus interfaces, and multiple supported operating modes / privilege levels: machine and optional user and debug_mode.
Currently, the following RISC-V compatible ISA extensions are supported:

• Always enabled: [I] [...]
• Optional: [E] [M] [...]

You can put that as the first paragraph in that section, instead of being the last.

---

Yea, you are right regarding the listing of all modules. However, I thought having the diagram right at the beginning might be a good eye catcher 🤔

It is. But it's also overkill. At some point, it's too much for being an eye-catcher and too little for being representative of the "whole" SoC capabilites. For the purpose you pursupe, I would propose something such as the following:

It shows the CPU, the SoC, that it has "many" optional modules, debugging features... Furthermore you could add some representation of the supported toolchains.
That's some quick draft. Proportions are not correct, and it's maybe an oversimplification. I would probably add the architecture ID (19). Yet, I hope you understand the idea.
Then, below, in the SoC section, you can place the current or a more detailed diagram. There, you might remove all the blocks inside the yellow CPU subsystem, in order to make place for SoC related blocks.

Good point. It is nice to have some feedback here, since "in my head" everything makes sense all the time 😅

I feel that. It's almost impossible to do this properly alone. Some external view is required, which is not aware of the details and can therefore make the most basic questions, which are not obvious for the developer anymore 😆.

How about this order?

Looks nice!

• key features (really required?)

I think it's nice. However, I'd put it at the beginning, right below the first paragraph and before the list of "icon items". So:

The NEORV32 Processor is....

• CPU plus...
• completly....
• ...

📚 Find further information in the CPU and SoC sections below, and take a look at...

...

---

• SoC
• CPU

👍🏼

I also need to emphasize the part regarding open-source tools. And yes, CI is a quality metric that should be emphasized, too.

👍🏼

That would be really great (as I am also a Windows fan boy 😄)!

Well, I'm not exactly a Windows fan boy 😆. I use MSYS2 and containers for everything 😄. I do like the window snapping features in Windows, tho. I use 3 monitors, so the 3 x 2x2 grid is really useful. I couldn't find a similar solution using an open source desktop...

[stnolting]

NEORV32 is an official (see architecture ID) little-endian two-stage RISC-V CPU with independent instruction/data bus interfaces, and multiple supported operating modes / privilege levels: machine and optional user and debug_mode.

👍 I will plagiarize that! 😄

Yes. However, you can use spaces! We won't charge you for those characters 😝. For instance, appending it to the previous paragraph:

I will play around with some formattings.

It is. But it's also overkill. At some point, it's too much for being an eye-catcher and too little for being representative of the "whole" SoC capabilites. For the purpose you pursupe, I would propose something such as the following:

Don't you think this is too simple? I think about all these AVR, PIC or MSP430 data sheets where you have a full floor plan right at the beginning so you know what is going on. 🤔

I would probably add the architecture ID (19).

Good idea. I will try to squeeze that into the CPU block.

Well, I'm not exactly a Windows fan boy 😆. I use MSYS2 and containers for everything 😄.

I like (and can recommend) the Windows Subsystem for Linux and Ubuntu on Windows 👍

[umarcor]

Don't you think this is too simple? I think about all these AVR, PIC or MSP430 data sheets where you have a full floor plan right at the beginning so you know what is going on. 🤔

Yes, that might be too simple. However, this is the README, not the datasheet 😉. The datasheet is the website/PDF. See, for instance, the "landing" of the following AVR/PIC products:

• https://www.microchip.com/wwwproducts/en/ATTINY3224
• https://www.microchip.com/en-us/products/microcontrollers-and-microprocessors/32-bit-mcus

So, I think it's good to have all the optional modules with/without the ring symbol, because that provides more info than "15+ optional modules". However, all the arrows and most of the info outside of the SoC block are probably too much to be shown before any other sentence in the readme. The datasheet is different. When people go there, they expect to scroll a lot, because all CPU datasheets are veeeery long.

I like (and can recommend) the Windows Subsystem for Linux and Ubuntu on Windows 👍

I've had bad experienced with it... Too many opaque layers to make things look easier than they should. I understand why some people do not want to handle the difference between Linux/Windows binaries/filesystems. However, I'm good with having to know when a shell is inside a Linux environment and when I'm on Windows, even though I use bash in both cases.
Nonetheless, it seems that WSL2 is much better now. Last time I updated Docker, I was tempted to change the engine from HyperV to WSL2. I don't remember why I did not. I think it was because of limiting the resources.

[umarcor]

With regard to splitting the documentation into multiple pages/PDFs, if asciidoctor supported generating multiple HTML pages, I wouldn't recommend taking care of it yet. However, since that seems not to be straightforward, I would suggest to start with splitting just the User Guide. So, keep all chapters in the datasheet, except the last one. On the site, the User Guide might be located in https://stnolting.github.io/neorv32/ug, consistently with the sw subdir used for doxygen sources.

The complexity of doing so is that "internal" references between the datasheet and the user guide will not work. Those will need to be handled as external sites. Then, each of them will be built independently, and put together by creating a subdir for the user guide.
Coherently, it might makes sense to create separated subdirs for the adoc sources in docs/src/datasheet and docs/src/userguide.

[umarcor]

See #53.