Merge pull request #307 from SpinalHDL/improve-service-plugin-doc

Improve service plugin doc

Author: mrcmry

source/SpinalHDL/Libraries/Misc/service_plugin.rst

@@ -8,14 +8,21 @@ Introduction
 ------------
 
 For some design, instead of implementing your Component's hardware directly in it, 
-you may instead want to compose its hardware by using some sorts of Plugins. This can provide a few key features : 
-
-- You can extend the features of your component by adding new plugins in its parameters. For instance adding Floating point support in a CPU.
-- You can swap various implementations of the same functionality just by using another set of plugins. For instance one implementation of a CPU multiplier may fit well on some FPGA, while others may fit well on ASIC.
-- It avoid the very very very large hand written toplevel syndrome where everything has to be connected manually. Instead plugins can discover their neighborhood by looking/using the software interface of other plugins.
-
-VexRiscv and NaxRiscv projects are an example of this. Their are CPUs which have a mostly empty toplevel, 
-and their hardware parts are injected using plugins. For instance : 
+you may instead want to compose its hardware by using some sorts of Plugins. 
+This can provide a few key features : 
+
+- You can extend the features of your component by adding new plugins in its 
+  parameters. For instance adding Floating point support in a CPU.
+- You can swap various implementations of the same functionality just by using 
+  another set of plugins. For instance one implementation of a CPU multiplier 
+  may fit well on some FPGA, while others may fit well on ASIC.
+- It avoid the very very very large hand written toplevel syndrome where everything
+  has to be connected manually. Instead plugins can discover their neighborhood
+  by looking/using the software interface of other plugins.
+
+VexRiscv and NaxRiscv are projects that use their own implementation of this concept.
+Their are CPUs which have a mostly empty toplevel, and their hardware parts
+are injected using plugins. For instance : 
 
 - PcPlugin
 - FetchPlugin
@@ -24,18 +31,24 @@ and their hardware parts are injected using plugins. For instance :
 - IntAluPlugin
 - ...
 
-And those plugins will then negotiate/propagate/interconnect to each others via their pool of services.
+And those plugins will then negotiate/propagate/interconnect to each others via
+their pool of services.
 
-While VexRiscv use a strict synchronous 2 phase system (setup/build callback), NaxRiscv uses a more flexible approach which uses the spinal.core.fiber API to fork elaboration threads which can interlock each others in order to ensure a workable elaboration ordering.
+While VexRiscv use a strict synchronous 2 phase system (setup/build callback),
+NaxRiscv uses a more flexible approach which uses the :ref:`spinal.core.fiber API <fiber>`
+to fork elaboration threads which can interlock each others in order to ensure
+a workable elaboration ordering.
 
-The Plugin API provide a NaxRiscv like system to define composable components using plugins.
+The ``spinal.lib.misc.plugin`` API provide a NaxRiscv like system to define 
+composable components using plugins. It is used for example in VexiiRiscv.
 
 Execution order
 ---------------
 
 The main idea is that you have multiple 2 executions phases : 
 
-- Setup phase, in which plugins can lock/retain each others. The idea is not to start negotiation / elaboration yet.
+- Setup phase, in which plugins can lock/retain each others. The idea is not
+  to start negotiation / elaboration yet.
 - Build phase, in which plugins can negotiation / elaboration hardware.
 
 The build phase will not start before all ``FiberPlugin`` are done with their setup phase.
@@ -60,7 +73,7 @@ The build phase will not start before all ``FiberPlugin`` are done with their se
 Simple example
 --------------
 
-Here is a simple dummy example with a SubComponent which will be composed using 2 plugins :
+Here is a simple dummy example with a ``SubComponent`` which will be composed using 2 plugins :
 
 .. code-block:: scala
 
@@ -247,3 +260,6 @@ Clearly, those examples are overkilled for what they do, the idea in general is
 - Negotiate / create interfaces between plugins (ex jump / flush ports)
 - Schedule the elaboration (ex decode / dispatch specification)
 - Provide a distributed framework which can scale up (minimal hardcoding)
+
+More information can be found `in the documentation of VexiiRiscv 
+<https://spinalhdl.github.io/VexiiRiscv-RTD/master/VexiiRiscv/Framework/index.html#plugin-fiber-retainer>`_.

source/SpinalHDL/Sequential logic/memory.rst

@@ -379,7 +379,7 @@ There are currently 4 kinds of technologies possible:
 * ``distributedLut``
 * ``registerFile``
 
-Blackboxing can insert HDL attributes if ``SpinalConfig#setDevice(Device)``
+Blackboxing can insert HDL attributes if ``SpinalConfig#device``
 has been configured for your device-vendor.
 
 The resulting HDL attributes might look like: