spinalhdl/spinaldoc-rtd

The sources of the online SpinalHDL doc

About SpinalHDL

SpinalHDL is:

• A language to describe digital hardware
• Compatible with EDA tools, as it generates VHDL/Verilog files
• Much more powerful than VHDL, Verilog, and SystemVerilog in its syntax and features
• Much less verbose than VHDL, Verilog, and SystemVerilog
• Not an HLS, nor based on the event-driven paradigm
• Only generates what you asked it in a one-to-one way (no black-magic, no black box)
• Not introducing area/performance overheads in your design (versus a hand-written VHDL/Verilog design)
• Based on the RTL description paradigm, but can go much further
• Allowing you to use Object-Oriented Programming and Functional Programming to elaborate your hardware and verify it
• Free and can be used in the industry without any license

Links

• Documentation
  https://spinalhdl.github.io/SpinalDoc-RTD/
• Chinese documentation
  https://spinalhdl.github.io/SpinalDoc-RTD/zh_CN/
• Chinese documentation (v1.7.2 from thuCGRA)
  https://thucgra.github.io/SpinalHDL_Chinese_Doc/
• API reference
  https://spinalhdl.github.io/SpinalHDL/dev/spinal/index.html
• Presentation of the language
  https://spinalhdl.github.io/SpinalDoc-RTD/master/SpinalHDL/Getting%20Started/presentation.html
• SBT base project
  https://github.com/SpinalHDL/SpinalTemplateSbt
• Gradle base project
  https://github.com/SpinalHDL/SpinalTemplateGradle
• Jupyter bootcamp
  https://github.com/SpinalHDL/Spinal-bootcamp
• Workshop
  https://github.com/SpinalHDL/SpinalWorkshop
• Google group
  https://groups.google.com/forum/#!forum/spinalhdl-hardware-description-language
• Donation channel
  https://opencollective.com/spinalhdl

English: 中文:

Get it

SpinalHDL is simply a set of Scala libraries. Include them into your project and you're good to go! If you're unsure about what to do, simply clone one of our example projects (see links above).

SBT (Scala build tool)

scalaVersion := "2.11.12"

libraryDependencies ++= Seq(
  "com.github.spinalhdl" % "spinalhdl-core_2.11" % "latest.release",
  "com.github.spinalhdl" % "spinalhdl-lib_2.11" % "latest.release",
  compilerPlugin("com.github.spinalhdl" % "spinalhdl-idsl-plugin_2.11" % "latest.release")
)

You can force SBT to pick a specific SpinalHDL version by replacing latest.release with a specific version. See the SpinalHDL SBT Template project's build.sbt file for a full SBT example.

Gradle

repositories {
	mavenCentral()
}

dependencies {
	compile group: 'com.github.spinalhdl', name: 'spinalhdl-core_2.11', version: '1.6.4'
	compile group: 'com.github.spinalhdl', name: 'spinalhdl-lib_2.11', version: '1.6.4'
}

Mill(Build Tool)

import mill._
import mill.scalalib._

object MySpinalModule extends ScalaModule {
  def scalaVersion = "2.11.12"

  def ivyDeps = Agg(
    ivy"com.github.spinalhdl::spinalhdl-core:1.6.4",
    ivy"com.github.spinalhdl::spinalhdl-lib:1.6.4",
  )

  def scalacPluginIvyDeps = Agg(ivy"com.github.spinalhdl::spinalhdl-idsl-plugin:1.6.4")
}

JAR

https://oss.sonatype.org/content/groups/public/com/github/spinalhdl/spinalhdl-core_2.11/
https://oss.sonatype.org/content/groups/public/com/github/spinalhdl/spinalhdl-lib_2.11/

The files are available on Maven as well.

Change logs

https://github.com/SpinalHDL/SpinalHDL/tags

License

The SpinalHDL core is using the LGPL3 license while SpinalHDL lib and others are using the MIT license. That's for the formalities. But there are some practical statements implied by those licenses:

Your freedoms are:

• You can use SpinalHDL core and lib in your closed/commercial projects.
• The generated RTL is yours (.vhd/.v files)
• Your hardware description is yours (.scala files)

Your obligations (and my wish) are:

• If you modify the SpinalHDL core (the compiler itself), please, share your improvements.

Also, SpinalHDL is provided "as is", without warranty of any kind.

spinaldoc-rtd's Issues

Document #* operator

Update Windows installation procedure for Verilator

A clean msys2 installation contains a reference to verilator 4.200 which is not compatible with SpinalTemplateSbt project:

...
[Progress] Verilator compilation started
In file included from C:/msys64/mingw64/share/verilator/include/verilated_vcd_c.cpp:21:
C:/msys64/mingw64/share/verilator/include/verilated_vcd_c.cpp: In member function 'void VerilatedVcd::dumpHeader()':
C:/msys64/mingw64/share/verilator/include/verilatedos.h:496:37: error: 'localtime_r' was not declared in this scope; did you mean 'localtime_s'?
  496 | # define VL_LOCALTIME_R(timep, tmp) localtime_r((timep), (tmp))
      |                                     ^~~~~~~~~~~
C:/msys64/mingw64/share/verilator/include/verilated_vcd_c.cpp:355:9: note: in expansion of macro 'VL_LOCALTIME_R'
  355 |         VL_LOCALTIME_R(&tick, &ticktm);
      |         ^~~~~~~~~~~~~~
make: *** [/mingw64/share/verilator/include/verilated.mk:241: verilated_vcd_c.o] Error 1
make: *** Waiting for unfinished jobs....
Exception in thread "main" java.lang.AssertionError: assertion failed: Verilator C++ model compilation failed
	at scala.Predef$.assert(Predef.scala:170)
	at spinal.sim.VerilatorBackend.compileVerilator(VerilatorBackend.scala:480)
	at spinal.sim.VerilatorBackend.<init>(VerilatorBackend.scala:542)
	at spinal.core.sim.SpinalVerilatorBackend$.apply(SimBootstraps.scala:135)
	at spinal.core.sim.SpinalSimConfig.compile(SimBootstraps.scala:625)
	at spinal.core.sim.SpinalSimConfig.compile(SimBootstraps.scala:588)
	at spinal.core.sim.SpinalSimConfig.doSim(SimBootstraps.scala:565)
	at mylib.MyTopLevelSim$.main(MyTopLevelSim.scala:13)
	at mylib.MyTopLevelSim.main(MyTopLevelSim.scala)

Process finished with exit code 1

An elder version of verilator should be installed by pacman -U http://repo.msys2.org/mingw/x86_64/mingw-w64-x86_64-verilator-4.032-1-any.pkg.tar.xz.

So, this doc section should be updated:

Sequential logic/memory: matters arising from docs with annotations/blackbox/memory/device complexities

This started as a comment to Tranche 3 but requires more investigation to help clarify both the code/mechanisms and the documentation around it.

So to track I open this.

---

Objectives

• Explain the eject process, so 100% manual configuration can be achieved by the designed. So Mem is used but the designer wants to take complete control over attributes and output HDL to ensure their flow has the correct memory created.
• Check my understanding of their being a default device NONE and the impact.
• Ensure all code / Phases that make use of knowing the device or device-family, upon seeing that is it NONE, emit a log message pointing into documentation and details of automatic support. This provides awareness to the user 'this situation looks like one we have help with available here read the docs'
• Check my understanding of configuring to a Device() and the impact on attributes.
• Confirm if the auto insertion is disabled if one or more manually provided attributes is present. Consider log message:
  • Log message: INFO At MyCode.scala:123 the Mem[name] instance for device-family Xilinx device xgt123-1202g did not have automatic addAttribute("special-memory-mode, "foobar") applied due to one or more existing attributes present. See documentation at https://spinalhdl.github.io/path/to/page
• Consider an attribute type that means, this instance do not perform automatic insertion of attributes that.addAttribute(InhibitAutomaticAttributes)
• Try to document some known forms of memory with well-known vendors. This sounds like a new page, with section per vendor and memory types.
• This leads into blackboxing modes and any simulation/elaboration differences.

Idea: automatically test examples

Pre-scriptum: sorry for the long text

It is possible to add Rust code into documentation (equivalent of scaladoc). Not only it supports syntax highlighting, it also enable testing the examples, to make sure it is up to date with the documented API.

An idiomatic way to write an example in Rust is to call a function, then assert its result, so in the example there is the assertion into the which the user/reader sees the returned value. For things not returning a value (we have plenty of them to describe hardware), no assertions is done (there are already unit tests elsewhere in Rust, just like with Scalatest), and it still checks that it builds and does not panic (~ throw an exception).

For SpinalHDL, it could be possible to check if examples build and if it returns an error or not (for instance design errors). For full examples with hardware + test, check if the test is successful.

I think the main question is: how have a source translated to RTD and scala test files?

First, to check with current API I think it is possible to clone the SpinalHDL template for tests and add / replace files (GitHub actions or other mechanism would enable caching dependencies).

Then, how to have testable code? It does not seem possible to automatically translate all current examples and voilà the tests run and pass. I see several ways, all of them are opt-in and would not break current documentation (so the documentation would need refactoring of each test to make it testable). These are listed below (to be updated during discussion):

Tests in scala files

Sphinx can include files as code blocks, and these files can be used in a scala environment but it does not seem easy to deal with:

• Sphinx can take them as-is
• How to integrate them into tests?
• You may not want to show all the lines to not have heavy full examples everywhere in the docs. When showing code which goes into a component, adding a "component" start and end all the time may be noisy.
• Put all examples in the same directory and have paths like ../../examples/section/subsection/example.rst? Or put examples with the code and make them harder to find to execute tests?

Partial tests in scala files

Having Scala files with only shown part of a test and some metadata to help including it in a test. Still needs to be injected in some code.

Parsing rst files

Please don't do that.

Writing a Sphinx extension

I think it is the most flexible solution so I'm gonna write a little bit about what I think we could get.

This extension, written in Python, would bring tags like .. spinalComponent, followed some metadata, then by code (like current situation). It would generate an example like:

test("some test name from some metadata?") {
  class ComponentNameFromMetadata extends Component {
    the code of the example
  }
  SpinalConfig.generateVerilog(new ComponentNameFromMetadata)
  // I would like a "check" function to not generate a file ^^'
}

There would be several tags, for several contexts (Component, full test, maybe others?).

It would also make it possible to have more features:

• Hiding some lines (for instance declaring signals, but the example is often more clear if they appear on it) by prefixing them with a # (like Rustdoc)
• Checking that some code does not build (scalatest has a function for that) or has design errors (check that generation throws an error), and in this case print the example a different way.
• A "copy" button to copy example code wrapped into an App to play around with it, or a button to show this App.

The CI flow get stuck in these days.

It reports that "detected dubious ownership" while "Build multiversioned doc" stage.
I did not know in which stage the docs directory is created, as well as why its ownership changed.
@numero-744 do you have any idea?

Document SpinalSpec

Do not merge until SpinalHDL/SpinalHDL#968 has not been merged

• Mention late evaluation done not before the it compiles test (so assertions to build component are delayed)

No saturation/safe arithmetic for S/UInt in the doc

The following operators are missing in the Integer types page:

+^
-^
+|
-|

Document setWhen and clearWhen

Should be in: https://spinalhdl.github.io/SpinalDoc-RTD/master/SpinalHDL/Sequential%20logic/registers.html
(source: https://github.com/SpinalHDL/SpinalDoc-RTD/blob/master/source/SpinalHDL/Sequential%20logic/registers.rst)

Simplified example:

val inFrameLate = Reg(Bool) setWhen(!sclRead) clearWhen(!inFrame)

License change

Hi, sorry if i mention you in this issue, but we need you to approve the license change to from MIT to CC0 (for this fork).
If you're ok with this please reply, otherwise we can discuss this here.
@lambdaShade
@pmudry
@Snoopy87
@Dolu1990 (pro-forma)

Thank you for your time.
Luca Cristaldi(wifasoi)

make html failed

python : 3.7.13 (anaconda)

install the package by pip3 install -r requirements.txt

output:

Running Sphinx v1.8.6

Extension error:
Could not import extension sphinxcontrib.wavedrom (exception: No module named cairosvg)
Makefile:19: recipe for target 'html' failed
make: *** [html] Error 2

Document scala file path

See answer from SpinalHDL/SpinalTemplateSbt#9

But, as SpinalHDL is a DSL, maybe the general guidelines are suboptimal and we could suggest another structure which would fit more the hardware description needs? Would it be supported by scala toolchains? Do you have suggestions?

Also, if we support scalatest in the template (as suggested in SpinalHDL/SpinalTemplateSbt#21) maybe we should specify that the testbench should be in the tests?

Fix table value

https://spinalhdl.github.io/SpinalDoc-RTD/SpinalHDL/Semantic/assignements.html
in the table it should be \= and not =

Better introduce the pdf version

From #133

Document compile SpinalHDL by mill.

Do not merge until SpinalHDL/SpinalHDL#969 has not been merged.

Copy button for code

What do you think about it?

https://sphinx-copybutton.readthedocs.io/en/latest/

How did you draw all these schematics? What tools do you use?

They all look very decent.
I actually believe I have seen the answer before... But my apologies, I really can't remember where.

Formal support is missing in documentation

There is no mentioning in the documentation for the formal support.
It could include things like:

• How to include formal in the design

import spinal.core.GenerationFlags._
import spinal.core.Formal._

GenerationFlags.formal{
   assume(... )
   assert(... )
   cover(...)
   ...
}

• How to generate a design with formal included

val config = SpinalConfig()
        config.includeFormal.generateSystemVerilog(new MyTopLevel())

• list the limitation of the current system

update the bus_slave_factory

It seems that the bus salve factory doc has no update 3 years ago, but the spinal.lib.bus had implemented lots of new functions, such as:setOnSet,readAndSetOnSet, ect.

I have made a list about that:

createReadAndClearOnSet
readAndClearOnSet
clearOnSet
createReadAndSetOnSet
readAndSetOnSet
setOnSet
createReadMultiWord
createWriteMultiWord
createWriteAndReadMultiWord
multiCycleRead
readSyncMemWordAligned
readSyncMemMultiWord
writeMemMultiWord
writeMemWordAligned

It would be better to update the doc to make others use those functions clearly. :>

Investigate image conversion error

A commit introduce a error

WARNING: convert exited with error:
[stderr]
Unit… specificata non valida. (italian for Specified unit not valid)

this is between 2ba70f7 (bad, acutal dev HEAD) and d161f14 (good, master HEAD 1.3.0 tag)
Tote to self: run git bisect and find the commit responsible for this

ci: generate pdf

PDF generation is done in two phases: rst->tex & tex->pdf. I get an error in the first phase.

Expected: create latex files

Actual:

% make latex
Extension error:
convert exited with error:
[stderr]
b"convert-im6.q16: delegate failed `'rsvg-convert' -o '%o' '%i'' @ error/delegate.c/InvokeDelegate/1966.\nconvert-im6.q16: unable to open file `/tmp/magick-js2pMmJNdpHh0gLO_sYh6hvy9N2dsNJn': No such file or directory @ error/constitute.c/ReadImage/614.\nconvert-im6.q16: no images defined `/docs/docs/doctrees/images/process_rtl.png' @ error/convert.c/ConvertImageCommand/3229.\n"
[stdout]
b''
make: *** [Makefile:19: latex] Error 2

Document Latch

Do not merge before SpinalHDL/SpinalHDL#944

Should be added in v1.8? I think new features can get such an "added on vX.X" tag to make things explicit. Is there something for that in Sphinx?

Need info on TraversableOncePimped

I am preparing pushing a few doc updates, and I would like to add stuff on Vec helper functions accessible through the TraversableOncePimped class. I have a simple question: why are some function names prefixed by "s" and some aren't ?
E.g. sExist, sCount vs shuffle, read.

I am wondering if I am missing something before writing some doc on that.

Where to submit grammatical PRs while reading

Great job with this project.

As I read the docs, I'm encountering a lot of grammatical errors. My question is: is it worth it for me to correct these errors as I read and issue PRs? If so, on which branch? I'm noticing that there are many features in the code that are not present in the docs and I don't want to put the effort in if the Docs are going stale, so to speak. Unfortunately, I don't have the required expertise to bring the docs up to date with the code, yet, but figured English proof-reading might be useful.

Document PackedBundle

Implemented in SpinalHDL/SpinalHDL#889

Document mux limitation to 4096

• Is it still true?
• Suggested location: When/Switch/Mux — SpinalHDL documentation (source: Semantic/when_switch.rst)
• Document limitation and explain why
• Add workaround with example (indexing on Vec?)

Ancestor: SpinalHDL/SpinalHDL#230

BufferCC can not be used for general multi Bits sync

i found BufferCC is Recommend for cross clock domain, https://spinalhdl.github.io/SpinalDoc-RTD/SpinalHDL/Structuring/clock_domain.html?highlight=buffercc

BufferCC can be used for single bit or Bits with Gray-coded Sync.

Suggestion of structure for docs

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 #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 #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 (#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/

Link to the scaladoc page

We should use more linking to the scaladoc page (http://spinalhdl.github.io/SpinalHDL).
There should be a TOC entry somewhere to link it, and a hyperlink for each function/class in the documentation.

this from a discussion in #25

Spelling mistakes

In the (https://github.com/SpinalHDL/SpinalDoc-RTD/blob/master/source/SpinalHDL/Structuring/function.rst')
You need to use the case class to define the MyBus class, and you should use def when you override the AsMaster method.

For example

case class MyBus(payloadWidth: Int) extends Bundle with IMasterSlave {
    val valid   = Bool
    val ready   = Bool
    val payload = Bits(payloadWidth bits)

    // Define the direction of the data in a master mode
    override def asMaster(): Unit = {
        out(valid, payload)
        in(ready)
    }
 // Connect that to this
    def <<(that: MyBus): Unit = {
        this.valid   := that.valid
        that.ready   := this.ready
        this.payload := that.payload
    }

    // Connect this to the FIFO input, return the fifo output
    def queue(size: Int): MyBus = {
        val fifo = new MyBusFifo(payloadWidth, size)
        fifo.io.push << this
        return fifo.io.pop
    }
}

Document implicit Fragment -> payload conversion

https://github.com/SpinalHDL/SpinalDoc-RTD/blob/master/source/SpinalHDL/Libraries/fragment.rst

• How to use it with example
• Warning about getWidth
• Seek for other similar implicit conversions (Stream, Flow, etc.) and document them too if there are things

Document randomize() returning new value

See SpinalHDL/SpinalHDL#940

Have a TODO list

I think have a todo list of what is missing in the documentation is handy.

Here is the aggregated todo :

Additions to existing pages

• Add Vec[Reg[T]] example to the Vec page. This would illustrate that registered types can be stuffed into Vecs just as easily as their combinational variants. (This was non-obvious to me when I first started using Spinal, as there were no examples in the docs of it.)
• Add Vec[Type] function parameter examples on the Function page. This could make it easier for Scala newbies to get the type signatures correct on medium-complexity functions.
• Add a Component renaming example to the Component and hierarchy page. This is a useful feature especially when working in legacy RTL projects, where fixed naming schemes may be expected. Currently, this functionality is only documented on the Blackboxing (Instantiate VHDL and Verilog IP) page.
• Updates to the Users page. The "repos" section especially could use some love, and if we could get links to the websites of companies using Spinal, that'd be awesome too.

Global changes

• More consistent code-formatting in the API sections across the data-types pages. Currently, some pages have better code formatting around their API docs than others. Having these be more consistent would be nice. 😄

Proposed new pages

• MaskedLiteral / MaskedBoolean docs. These are mentioned in a footnote on the Data types page, but are not comprehensively covered anywhere else in the docs.
• An "Internals" or "Built-ins" page, documenting spinal.core built-ins, like exp / bits / bits / pos / slice, etc. This might live under the Developers Area section.
• A "Physical units" page, documenting the convenience units, like kHz/MHz, KiB/MiB, hr/min/sec, etc. that all live under spinal.core.

Proposed new code examples

• Examples of reduce / reduceBalancedTree. These are very useful (espec. for things like adder trees), and don't seem to be comprehensively shown off in examples, or documented thoroughly anywhere. (This could be worth doing in a "Functional Programming Idioms" section or something. 🤷‍♂️ )
• Pipelining examples. These examples would demonstrate how to implement pipelining for a simple ALU or other component, and might cover idiomatic usage for Reg / RegInit / RegNext when used in chains of registers.
• Data structure examples. These examples would demonstrate how to use Scala collections to make generating certain types of hardware much easier. (Example: specifying a sorting network as a list of swap indices.)
• More Memory -related examples! Memory types, especially RAMs, seem to have sparse documentation overall. Example ideas might include:
  • Loading a RAM's initial contents from a hex file, altering some values, and reading the updated values.
  • Putting a RAM in as a data source for an ALU or something.
  • Using a RAM/ROM inside an existing component. (IIRC, SpinalCrypto may have some examples of this with lookup tables, S-Boxes, etc.)

Document design error: Partially assigned register

Missing favicon

Is simple as defining the html_favicon variable in the conf.py.
Do the project have a favicon already used somewhere, or should I try to create one from the logo?

Investigate why the tag release did't trigger a new build

or maybe the git describe isn't working

typo `repalce` in document

In Structuring - Instantiate VHDL and Verilog IP, replace is spelled as repalce.

 // Function used to rename all signals of the blackbox
  private def renameIO(): Unit = {
    io.flatten.foreach(bt => {
      if(bt.getName().contains("portA")) bt.setName(bt.getName().repalce("portA_", "") + "_A")
      if(bt.getName().contains("portB")) bt.setName(bt.getName().repalce("portB_", "") + "_B")
    })
  }

Use Introduction page as example introduction

use this page as the intorduction of the section: https://spinalhdl.github.io/SpinalDoc-RTD/SpinalHDL/Examples/Simple%20ones/introduction.html

Add section for idioms

Spinal enables representing the code in a way which is not possible in RTL.

This section would show idioms which are useful in Spinal. For each idiom, it would explain it, how to use it, when and why it is good to use it, and maybe how it works.

Example of idiom:

val doSomethingFlag = False
def doSomething(): Unit = doSomethingFlag := True

I find it useful in fsm.State.whenActive to express the output logic.

  val fsm = new StateMachine {
    val IDLE, Rnd0, RndI, RndN, DONE = new State
    setEntry(IDLE)

    // Transition logic
    IDLE.whenIsActive { when(io.start) { goto(Rnd0) } }
    Rnd0.whenIsActive { goto(RndI) }
    RndI.whenIsActive { when(round.isLast) { goto(RndN) } }
    RndN.whenIsActive { goto(DONE) }
    DONE.whenIsActive { when(!io.start) { goto(IDLE) } }

    // Output logic, using only this idiom
    IDLE.whenIsActive { round.resetCount }
    Rnd0.whenIsActive { run; useInputs }
    RndI.whenIsActive { run }
    RndN.whenIsActive { run; withoutMixColumns }
    DONE.whenIsActive { enableOutput }
  }

Update regif documentation

Do not merge until SpinalHDL/SpinalHDL#976 has not been merged

Add FAQ for vpi errors on get_time_precision.

As SpinalHDL/SpinalHDL#1022 discussed, the VPI code would remain in simulation directory (such as simWorkspace) without updated while version bumped.

It's reasonable to add a guideline on how to dear with it.

However, it is neither "Design Errors" nor "FAQ"(some bigger question is answered there).
Where to put this is a problem, do you have any idea?

Document CombInit

LinkCheck: Libraries/Bus/avalon/avalonmm (broken HTTP/404)

(SpinalHDL/Libraries/Bus/avalon/avalonmm: line 18) broken https://www.intel.com/content/dam/www/programmable/us/en/pdfs/literature/manual/mnl_avalon_spec.pdf - 404 Client Error: Not Found for url: https://cdrdv2.intel.com/v1/dl/getContent/667068?fileName=mnl_avalon_spec-683091-667068.pdf

`there <https://www.intel.com/content/dam/www/programmable/us/en/pdfs/literature/manual/mnl_avalon_spec.pdf>`_

url: https://www.intel.com/content/dam/www/programmable/us/en/pdfs/literature/manual/mnl_avalon_spec.pdf
page: source/SpinalHDL/Libraries/Bus/avalon/avalonmm.rst
line: 18
code: https://github.com/SpinalHDL/SpinalDoc-RTD/blob/master/source/SpinalHDL/Libraries/Bus/avalon/avalonmm.rst

Have Slides/pdfs as a separate repo

Need to check if the CI/CD is happy about it

equivalent constructs at elaboration time/hardware/sim

possible typo in getting started

At this line, should this be a change directory to SpinalTemplateSbt instead of SpinalBaseProject?
https://github.com/SpinalHDL/SpinalDoc-RTD/blame/master/source/SpinalHDL/Getting%20Started/getting_started.rst#L62

Or perhaps the intent is to rename it? or perhaps change the clone to:

   git clone https://github.com/SpinalHDL/SpinalTemplateSbt.git SpinalBaseProject

Document switch(coverUnreachable = ...)

Source file to modify: source/SpinalHDL/Semantic/when_switch.rst

See SpinalHDL/SpinalHDL#946

Structuring/parametrization.rst ScopeProperty explanation

what it does ?
in what situations is it better ?
example on how to use ?

ScalaDoc hosting

I think having a ScalaDoc page hosted (maibe on SpinalHDL repo) can be handy. Should we add it to the CI/CD flow?

Faq: publishLocal must match project's scala version

I did sbt clean publishLocal so it published for 2.11 but my project is using 2.12 so it didn't work.

Document BU and BS string prefixes

Do not merge until SpinalHDL/SpinalHDL#981 has not been merged