Suggestion of structure for docs

[numero-744]

The goal is to both:

• Make it easier for all people discovering SpinalHDL (knowing VHDL and Verilog might help but it is not a requirement)
• Make it easier for people to find information

---

Root:

• short description
• short motivation
• where to find docs

1. Introduction
   1. About SpinalHDL
      1. What is SpinalHDL?
      2. The Spinal flow
      3. Advantages of using SpinalHDL over VHDL and Verilog
   2. A simple example (from the template)
      1. Component
      2. Ports
      3. Internal logic
   3. Projects using SpinalHDL
   4. Getting in touch
   5. License
   6. Contributing
   7. FAQ
   8. More learning materials (add cheatsheets)
      1. Help for people coming from VHDL
2. Getting Started
   1. Install and setup
   2. Using spinal from *
   3. A simple guided exercise
      1. Writing the logic step by step
      2. Writing the test step by step (with only assignments sleep, also mention requirements and how to generate code if no compatible simulator)
      3. Running the test and open the waves in Gtkwave
      4. Congratulations! page
3. Common hardware description concepts
   1. Notion of comb and seq logic (mention a few design errors)
   2. Data types & basic operators, literals
   3. Rules / conditions / muxing (+ setWhen/clearWhen + a few design errors)
   4. Component (+ interface, directions, how to instantiate)
   5. Comments (Huh, fast part)
   6. Areas (preview of clockdomains)
4. Compound types (Bundle and Vec)
5. Enumerated types (& encoding)
6. Configuring generation (SpinalConfig)
7. Blackboxing
8. Managing growing projects (with package and import)
9. More simulation facilities
   1. Simulation time vs hardware (types, syntax equivalent constructs at elaboration time/hardware/sim #145 + read & write into hardware)
   2. Interacting with a clockdomain
   3. Random tests
   4. Control flow and functions (like before but focusing on simulation)
10. Common hardware generation concepts
    1. Elaboration-time vs hardware (types, syntax equivalent constructs at elaboration time/hardware/sim #145)
    2. Component parameters
    3. Creating a configuration
    4. Elaboration-time control flow (if, for, also mention null and mutability)
    5. Functions (+ when an Area should be created)
    6. Pre-conditions (require)
11. The standard library
    1. Interconnections
       1. Flow
       2. Stream
       3. Fragment
    2. Buses
    3. Logic
       1. State machine
    4. Peripheral
       5. UART
    5. TODO other things
12. Writing better code
    1. Style guidelines
    2. Idioms (Add section for idioms #131)
13. At least one harder / less guided project for exercise (TODO)
14. Helper scripts
    1. HTML test report generation (easy, just sbt config) + XML parser to match test list with spec if I have time (spoiler: I won't, unless my manager tells me to, and he is quite interested)
    2. Ubuntu full-flow installer (for teaching)
    3. Use one GTKWave config with several wave files
    4. GTKWave user configuration example
15. More advanced stuff
    1. Clock domains
    2. Assertions
    3. Report
    4. RAM/ROM
    5. Analog and inout
    6. Details about simulation
    7. Formal verification
    8. Scope property
    9. Interaction with Scala
16. Examples
17. Appendix
    1. All other, more formal, contents
    2. Design errors

---

I would like "developers area" (about internals I guess) to be apart, because when searching things sometimes it appears first…
An idea could be to manage master and dev in parallel: dev has this and master doesn't.
Pushing/merging into master automatically opens a PR from master to dev, and contributions to this section are PR'd to dev.
Or maybe even two separate branches with completely different contents.

For reference, structure is inspired from: https://doc.rust-lang.org/stable/book/

[numero-744]

I think that "More simulation facilities" would go before "Common hardware generation concepts" because it will not be a full course about verification, and these simulation facilities will be really useful to simulate things, including the stuff of "hardware generation concept". So I would swap those two parts.

[Readon]

Do you think it's better to describe things as sections below:

Working flow

...

Elaborate Stage

• if else
• for
• SpinalConfig
• ...

Hardware Description

• Comb Logic
• when
• switch
• design errors

Verify Stage

• Simulation
• Formal Verification

Standard Library

Interconnection

• Flow
• Stream

Bus

• Axi4
• Wishbone

Peripheral

• UART

Although, this would make a deep tree, or we can use this definition constantly.

[numero-744]

IMO this structure is clear for us as we already know Scala, Spinal and how they relate to each other. This theory-first approach is okay too for students. But it wouldn't be really helpful for hardware designers discovering SpinalHDL, who know VHDL and/or Verilog, a little bit of C just to write tests to run in a CPU in simulation and copy-pasting tcl and tcsh commands around to run simulations and have an idea of the number of gates used by their IP in synthesis, without knowing any other programming language. For them it is not really practical and fun to learn, not enough practice-first. I think putting Elaborate stage before Hardware description is really Scala/software-oriented so not practical for people wanting to learn describing hardware using SpinalHDL and not knowing Scala and programming languages in general. It is putting more advanced things (how to generate) before simple things (structuring, inputs, outputs, comb logic, seq logic); how to make your component generic before leaning how to create a simple component. Putting Simulation at the end is not practical and fun because they won't be able to practice things, to see how what they write behaves as they write it. For design errors I think it is good to put them in hardware description as they will likely encounter them there ^^' What about introducing them as long as they can encounter them with the notions they learn (eg: mention latch in when section) and keeping the full descriptions and workarounds/tags as we currently have them in a later section? I like this more fine-grained way to split things in the library, I'll update the issue description; thanks! Le 21 novembre 2022 02:31:12 UTC, Readon ***@***.***> a écrit :

…

Do you think it's better to describe things as sections below: ### Working flow ... #### Elaborate Stage - if else - for - SpinalConfig - ... #### Hardware Description - Comb Logic - when - switch - design errors #### Verify Stage - Simulation - Formal Verification ### Standard Library #### Interconnection - Flow - Stream #### Bus - Axi4 - Wishbone #### Peripheral - UART Although, this would make a deep tree, or we can use this definition constantly. -- Reply to this email directly or view it on GitHub: #151 (comment) You are receiving this because you were assigned. Message ID: ***@***.***>

[Dolu1990]

Fondamentaly, we can have both, both aproache fit different situations.

[numero-744]

Having two parallel tables of contents?

[wifasoi]

As long there is not a table of table of contents

[numero-744]

Unless arguments against the suggested (updated) structure or example cases where it does not fit are provided, and unless it is shown that no modifications can be provided to have one structure matching all cases, I don't think it is a good thing to duplicate docs.

[Dolu1990]

I would not count it as duplication, as they are different perspective, as poeple which know well VHDL / Verilog will have very different expectation than people discovering hardware design.
But fondamentaly, the way you propose (numero-744) should be the default one i think.

[numero-744]

So I suggest to first go for this structure, and with the result see if something else should be added for other cases

[Dolu1990]

fine to me ^^

[numero-744]

TODO: move developer area to branch dev-area, keep empty section to point to it and add link into CONTRIBUTING.md to it. Default branch becomes dev and master points to the most recent tag.