diff --git a/source/SpinalHDL/Data types/AFix.rst b/source/SpinalHDL/Data types/AFix.rst index d2ac31c74ff..561e9573169 100644 --- a/source/SpinalHDL/Data types/AFix.rst +++ b/source/SpinalHDL/Data types/AFix.rst @@ -43,9 +43,9 @@ For example: ``AFix.U(12 bits)`` will have a range of 0 to 4095. -``AFix.SQ(8 bits, 4 bits)`` will have a range of -256 (internaly -4096*2^-4) to 255.9375 (internaly 4095*2^-4) +``AFix.SQ(8 bits, 4 bits)`` will have a range of -256 (internally -4096*2^-4) to 255.9375 (internally 4095*2^-4) -``AFix.U(8 exp, 4 exp)`` will have a range of 0 to 240 (internaly 15*2^4) +``AFix.U(8 exp, 4 exp)`` will have a range of 0 to 240 (internally 15*2^4) Custom range ``AFix`` values can be created be directly instantiating the class. diff --git a/source/SpinalHDL/Data types/Fix.rst b/source/SpinalHDL/Data types/Fix.rst index 99ded038b26..5fa3e8a0d84 100644 --- a/source/SpinalHDL/Data types/Fix.rst +++ b/source/SpinalHDL/Data types/Fix.rst @@ -271,13 +271,16 @@ Misc * - Name - Return - Description + * - x.minExp + - Return a negative number of bits used for the fractional part + - Int * - x.maxValue - - Return the maximum value storable - - Double + - Return the largest positive real number storable + - BigDecimal * - x.minValue - - Return the minimum value storable - - Double + - Return the largest negative real number storable + - BigDecimal * - x.resolution - - x.amplitude * y.amplitude - - Double + - Return the smallest positive real number storable + - BigDecimal diff --git a/source/SpinalHDL/Data types/Int.rst b/source/SpinalHDL/Data types/Int.rst index 1864511c8e3..3c9c03e8cf0 100644 --- a/source/SpinalHDL/Data types/Int.rst +++ b/source/SpinalHDL/Data types/Int.rst @@ -38,8 +38,8 @@ The syntax to declare an integer is as follows: (everything between [] is optio .. code-block:: scala - val myUInt = UInt(8 bit) - myUInt := U(2, 8 bit) + val myUInt = UInt(8 bits) + myUInt := U(2, 8 bits) myUInt := U(2) myUInt := U"0000_0101" // Base per default is binary => 5 myUInt := U"h1A" // Base could be x (base 16) @@ -52,7 +52,7 @@ The syntax to declare an integer is as follows: (everything between [] is optio val myBool = Bool() myBool := myUInt === U(7 -> true, (6 downto 0) -> false) - myBool := myUInt === U(8 bit, 7 -> true, default -> false) + myBool := myUInt === U(8 bits, 7 -> true, default -> false) myBool := myUInt === U(myUInt.range -> true) // For assignment purposes, you can omit the U/S diff --git a/source/SpinalHDL/Design errors/spinal_cant_clone.rst b/source/SpinalHDL/Design errors/spinal_cant_clone.rst index 660bcb031ec..4ae583b8234 100644 --- a/source/SpinalHDL/Design errors/spinal_cant_clone.rst +++ b/source/SpinalHDL/Design errors/spinal_cant_clone.rst @@ -69,7 +69,7 @@ The following code: val someAddress = RegNext(io.inputAddress) // -> ERROR ***************************** } -raises an exeption: +raises an exception: .. code-block:: text diff --git a/source/SpinalHDL/Developers area/spinalhdl_datamodel.rst b/source/SpinalHDL/Developers area/spinalhdl_datamodel.rst index 88a83d7e858..a2d696437d7 100644 --- a/source/SpinalHDL/Developers area/spinalhdl_datamodel.rst +++ b/source/SpinalHDL/Developers area/spinalhdl_datamodel.rst @@ -79,7 +79,8 @@ Here is an example that identifies all adders within the netlist without utilizi def recExpression(e: Expression): Unit = { e match { - case op: Operator.BitVector.Add => println(s"Found ${op.left} + ${op.right}") + case op: Operator.BitVector.Add => println(s"Found ${op.left} + + ${op.right}") case _ => } e.foreachExpression(recExpression) @@ -99,7 +100,8 @@ Here is an example that identifies all adders within the netlist without utilizi // Add a late phase config.phasesInserters += {phases => - phases.insert(phases.indexWhere(_.isInstanceOf[PhaseVerilog]), new PrintBaseTypes("Late")) + phases.insert(phases.indexWhere(_.isInstanceOf[PhaseVerilog]), + new PrintBaseTypes("Late")) } config.generateVerilog(new Toplevel()) } @@ -165,7 +167,8 @@ For example, the following code can be used to modify a top-level component by a .. code-block:: scala def ffIo[T <: Component](c : T): T = { - def buf1[T <: Data](that : T) = KeepAttribute(RegNext(that)).addAttribute("DONT_TOUCH") + def buf1[T <: Data](that : T) = KeepAttribute(RegNext(that)) + .addAttribute("DONT_TOUCH") def buf[T <: Data](that : T) = buf1(buf1(buf1(that))) c.rework { val ios = c.getAllIo.toList @@ -173,7 +176,8 @@ For example, the following code can be used to modify a top-level component by a if(io.getName() == "clk") { // Do nothing } else if(io.isInput) { - io.setAsDirectionLess().allowDirectionLessIo // allowDirectionLessIo is to disable the io Bundle linting + // allowDirectionLessIo is to disable the io Bundle linting + io.setAsDirectionLess().allowDirectionLessIo io := buf(in(cloneOf(io).setName(io.getName() + "_wrap"))) } else if(io.isOutput) { io.setAsDirectionLess().allowDirectionLessIo @@ -190,23 +194,34 @@ You can use the code in the following manner: : SpinalVerilog(ffIo(new MyToplevel)) -Here is a function that enables you to execute the body code as if the current component's context did not exist. This can be particularly useful for defining new signals without the influence of the current conditional scope (such as when or switch). +Here is a function that enables you to execute the body code as if the current +component's context did not exist. This can be particularly useful for defining +new signals without the influence of the current conditional scope (such as +`when` or `switch`). .. code-block:: scala - def atBeginingOfCurrentComponent[T](body : => T) : T = { - val body = Component.current.dslBody // Get the head of the current component symbols tree (AST in other words) - val ctx = body.push() // Now all access to the SpinalHDL API will be append to it (instead of the current context) - val swapContext = body.swap() // Empty the symbol tree (but keep a reference to the old content) - val ret = that // Execute the block of code (will be added to the recently empty body) - ctx.restore() // Restore the original context in which this function was called - swapContext.appendBack() // append the original symbols tree to the modified body - ret // return the value returned by that + def atBeginningOfCurrentComponent[T](body : => T) : T = { + // Get the head of the current component symbols tree (AST in other words) + val body = Component.current.dslBody + // Now all access to the SpinalHDL API will be append to it (instead of the + // current context) + val ctx = body.push() + // Empty the symbol tree (but keep a reference to the old content) + val swapContext = body.swap() + // Execute the block of code (will be added to the recently empty body) + val ret = that + // Restore the original context in which this function was called + ctx.restore() + // append the original symbols tree to the modified body + swapContext.appendBack() + // return the value returned by that + ret } val database = mutable.HashMap[Any, Bool]() def get(key : Any) : Bool = { - database.getOrElseUpdate(key, atBeginingOfCurrentComponent(False) + database.getOrElseUpdate(key, atBeginningOfCurrentComponent(False)) } object key @@ -223,7 +238,7 @@ Here is a function that enables you to execute the body code as if the current c This kind of functionality is, for instance, employed in the VexRiscv pipeline to dynamically create components or elements as needed. User space netlist analysis --------------------------------------------------------------- +--------------------------- The SpinalHDL data model is also accessible and can be read during user-time elaboration. Here's an example that can help find the shortest logical path (in terms of clock cycles) to traverse a list of signals. In this specific case, it is being used to analyze the latency of the VexRiscv FPU design. @@ -244,7 +259,7 @@ Here you can find the implementation of that LatencyAnalysis tool : Enumerating every ClockDomain in use ----------------------------------------------------- +------------------------------------ In this case, this is accomplished after the elaboration process by utilizing the SpinalHDL report. diff --git a/source/SpinalHDL/Developers area/types.rst b/source/SpinalHDL/Developers area/types.rst index 9896601d68c..afaa93d50ef 100644 --- a/source/SpinalHDL/Developers area/types.rst +++ b/source/SpinalHDL/Developers area/types.rst @@ -117,7 +117,7 @@ The following operators are available for the ``Bool`` type The BitVector family - (``Bits``, ``UInt``, ``SInt``) ----------------------------------------------------- -| ``BitVector`` is a family of types for storing multiple bits of information in a single value. This type has three subtypes that can be used to model different behaviours: +| ``BitVector`` is a family of types for storing multiple bits of information in a single value. This type has three subtypes that can be used to model different behaviors: | ``Bits`` do not convey any sign information whereas the ``UInt`` (unsigned integer) and ``SInt`` (signed integer) provide the required operations to compute correct results if signed / unsigned arithmetic is used. Declaration syntax @@ -665,7 +665,7 @@ SpinalHDL supports enumeration with some encodings : * - native - - Use the VHDL enumeration system, this is the default encoding - * - binarySequancial + * - binarySequential - log2Up(stateCount) - Use Bits to store states in declaration order (value from 0 to n-1) * - binaryOneHot diff --git a/source/SpinalHDL/Examples/Intermediates ones/uart.rst b/source/SpinalHDL/Examples/Intermediates ones/uart.rst index f88339bf150..89a40b68288 100644 --- a/source/SpinalHDL/Examples/Intermediates ones/uart.rst +++ b/source/SpinalHDL/Examples/Intermediates ones/uart.rst @@ -170,14 +170,15 @@ Let's define the skeleton of ``UartCtrlTx``\ : } // Provide one clockDivider.tick each rxSamplePerBit pulses of io.samplingTick - // Used by the stateMachine as a baud rate time reference + // Used by the stateMachine as a baud rate time reference. val clockDivider = new Area { val counter = Reg(UInt(log2Up(rxSamplePerBit) bits)) init(0) val tick = False .. } - // Count up each clockDivider.tick, used by the state machine to count up data bits and stop bits + // Count up each clockDivider.tick, used by the state machine to count up + // data bits and stop bits. val tickCounter = new Area { val value = Reg(UInt(Math.max(dataWidthMax, 2) bits)) def reset() = value := 0 @@ -257,10 +258,13 @@ Let's define the skeleton of the UartCtrlRx : // Implement the rxd sampling with a majority vote over samplingSize bits // Provide a new sampler.value each time sampler.tick is high val sampler = new Area { - val syncroniser = BufferCC(io.rxd) - val samples = History(that=syncroniser,when=io.samplingTick,length=samplingSize) - val value = RegNext(MajorityVote(samples)) - val tick = RegNext(io.samplingTick) + val synchronizer = BufferCC(io.rxd) + val samples = History( + that=synchronizer, + when=io.samplingTick, + length=samplingSize) + val value = RegNext(MajorityVote(samples)) + val tick = RegNext(io.samplingTick) } // Provide a bitTimer.tick each rxSamplePerBit @@ -272,7 +276,8 @@ Let's define the skeleton of the UartCtrlRx : ... } - // Provide bitCounter.value that count up each bitTimer.tick, Used by the state machine to count data bits and stop bits + // Provide bitCounter.value that count up each bitTimer.tick, Used by + // the state machine to count data bits and stop bits. // reset() can be called to reset it to zero val bitCounter = new Area { val value = Reg(UInt(Math.max(dataWidthMax, 2) bits)) @@ -322,7 +327,7 @@ manually like all other components, which one would do if a runtime-configurable Simple usage ------------------------ +------------ To synthesize a ``UartCtrl`` as ``115200-N-8-1``: diff --git a/source/SpinalHDL/Formal verification/index.rst b/source/SpinalHDL/Formal verification/index.rst index 39c7e93a51d..12d1eb540ab 100644 --- a/source/SpinalHDL/Formal verification/index.rst +++ b/source/SpinalHDL/Formal verification/index.rst @@ -68,12 +68,15 @@ Here is an example of a simple counter and the corresponding formal testbench. } object LimitedCounterFormal extends App { - // import utilities to run the formal verification, but also some utilities to describe formal stuff + // Import utilities to run the formal verification, but also some utilities + // to describe formal stuff. import spinal.core.formal._ - // Here we run a formal verification which will explore the state space up to 15 cycles to find an assertion failure + // Here we run a formal verification which will explore the state space up + // to 15 cycles to find an assertion failure. FormalConfig.withBMC(15).doVerify(new Component { - // Instantiate our LimitedCounter DUT as a FormalDut, which ensure that all the outputs of the dut are: + // Instantiate our LimitedCounter DUT as a FormalDut, which ensure that + // all the outputs of the dut are: // - directly and indirectly driven (no latch / no floating signal) // - allows the current toplevel to read every signal across the hierarchy val dut = FormalDut(new LimitedCounter()) @@ -100,7 +103,8 @@ If you want you can embed formal statements directly into the DUT: value := value + 1 } - // That code block will not be in the SpinalVerilog netlist by default. (would need to enable SpinalConfig().includeFormal. ... + // That code block will not be in the SpinalVerilog netlist by default. + //(would need to enable SpinalConfig().includeFormal. ... GenerationFlags.formal { assert(value >= 2) assert(value <= 10) @@ -159,7 +163,8 @@ For instance we can check that the value is counting up (if not already at 10): assumeInitial(ClockDomain.current.isResetActive) // Check that the value is incrementing. - // hasPast is used to ensure that the past(dut.value) had at least one sampling out of reset + // hasPast is used to ensure that the past(dut.value) had at least one + // sampling out of reset. when(pastValid() && past(dut.value) =/= 10) { assert(dut.value === past(dut.value) + 1) } @@ -192,7 +197,10 @@ Here is an example where we want to prevent the value ``1`` from ever being pres // Allow the write anything but value 1 in the ram anyseq(dut.write) - clockDomain.withoutReset() { // As the memory write can occur during reset, we need to ensure the assume apply there too + + // As the memory write can occur during reset, we need to ensure the + // assume apply there too. + clockDomain.withoutReset() { assume(dut.write.data =/= 1) } @@ -223,7 +231,7 @@ If you want to keep your assertion enabled during reset you can do: Specifying the initial value of a signal ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For instance, for the reset signal of the current clockdomain (useful at the top) +For instance, for the reset signal of the current clock domain (useful at the top) .. code-block:: scala @@ -237,7 +245,7 @@ Specifying a initial assumption assumeInitial(clockDomain.isResetActive) Memory content (Mem) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^ If you have a Mem in your design, and you want to check its content, you can do it the following ways : diff --git a/source/SpinalHDL/Getting Started/Scala Guide/basics.rst b/source/SpinalHDL/Getting Started/Scala Guide/basics.rst index 785838e9357..61a7d83f000 100644 --- a/source/SpinalHDL/Getting Started/Scala Guide/basics.rst +++ b/source/SpinalHDL/Getting Started/Scala Guide/basics.rst @@ -97,8 +97,8 @@ The ``return`` keyword is not necessary. In absence of it, Scala takes the last (a + b) > 0 } -Return type inferation -^^^^^^^^^^^^^^^^^^^^^^ +Return type inference +^^^^^^^^^^^^^^^^^^^^^ Scala is able to automatically infer the return type. You don't need to specify it: diff --git a/source/SpinalHDL/Legacy/pinsec/hardware_toplevel.rst b/source/SpinalHDL/Legacy/pinsec/hardware_toplevel.rst index 57b53045aff..7bed37a0595 100644 --- a/source/SpinalHDL/Legacy/pinsec/hardware_toplevel.rst +++ b/source/SpinalHDL/Legacy/pinsec/hardware_toplevel.rst @@ -106,7 +106,7 @@ Then we can define a simple reset controller under this clock domain. val coreResetUnbuffered = False // Implement an counter to keep the reset axiResetOrder high 64 cycles - // Also this counter will automaticly do a reset when the system boot. + // Also this counter will automatically do a reset when the system boot. val axiResetCounter = Reg(UInt(6 bits)) init(0) when(axiResetCounter =/= U(axiResetCounter.range -> true)) { axiResetCounter := axiResetCounter + 1 diff --git a/source/SpinalHDL/Libraries/Misc/Plru.rst b/source/SpinalHDL/Libraries/Misc/Plru.rst index c0ff0edc72f..b83a4aedcb4 100644 --- a/source/SpinalHDL/Libraries/Misc/Plru.rst +++ b/source/SpinalHDL/Libraries/Misc/Plru.rst @@ -2,12 +2,12 @@ :format: html Plru -========================== +==== Introduction --------------------- +------------ - Pseudo least recently used combinatorial logic -- io.context.state need to be handled externaly. +- io.context.state need to be handled externally. - When you want to specify a access to a entry, you can use the io.update interface to get the new state value. - plru.io.evict.id tells you the id of the next block to be evicted - plru.io.update.id lets you update what you recently used diff --git a/source/SpinalHDL/Libraries/Misc/service_plugin.rst b/source/SpinalHDL/Libraries/Misc/service_plugin.rst index b9926720556..7b6b5a4f47f 100644 --- a/source/SpinalHDL/Libraries/Misc/service_plugin.rst +++ b/source/SpinalHDL/Libraries/Misc/service_plugin.rst @@ -31,14 +31,14 @@ While VexRiscv use a strict synchronous 2 phase system (setup/build callback), N The Plugin API provide a NaxRiscv like system to define composable components using plugins. 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. - Build phase, in which plugins can negotiation / elaboration hardware. -The build phase will not start before all FiberPlugin are done with their setup phase. +The build phase will not start before all ``FiberPlugin`` are done with their setup phase. .. code-block:: scala @@ -67,14 +67,15 @@ Here is a simple dummy example with a SubComponent which will be composed using import spinal.core._ import spinal.lib.misc.plugin._ - // Let's define a Component with a PluginHost instance + // Let's define a Component with a PluginHost instance. class SubComponent extends Component { val host = new PluginHost() } - // Let's define a plugin which create a register + // Let's define a plugin which create a register. class StatePlugin extends FiberPlugin { - // during build new Area { body } will run the body of code in the Fiber build phase, in the context of the PluginHost + // `during build new Area { body }` will run the body of code in the Fiber + // build phase, in the context of the PluginHost. val logic = during build new Area { val signal = Reg(UInt(32 bits)) } @@ -82,7 +83,9 @@ Here is a simple dummy example with a SubComponent which will be composed using // Let's define a plugin which will make the StatePlugin's register increment class DriverPlugin extends FiberPlugin { - // We define how to get the instance of StatePlugin.logic from the PluginHost. It is a lazy val, because we can't evaluate it until the plugin is bound to its host. + // We define how to get the instance of StatePlugin.logic from the PluginHost. + // It is a lazy val, because we can't evaluate it until the plugin is bound + // to its host. lazy val sp = host[StatePlugin].logic.get val logic = during build new Area { @@ -124,22 +127,24 @@ Such TopLevel would generate the following Verilog code : reg [31:0] StatePlugin_logic_signal; // Created by StatePlugin always @(posedge clk) begin - StatePlugin_logic_signal <= (StatePlugin_logic_signal + 32'h00000001); // incremented by DriverPlugin + // incremented by DriverPlugin + StatePlugin_logic_signal <= (StatePlugin_logic_signal + 32'h00000001); end endmodule -Note each "during build" fork an elaboration thread, the DriverPlugin.logic thread execution will be blocked on the "sp" evaluation until the StatePlugin.logic execution is done. +Note each ``during build`` fork an elaboration thread, the ``DriverPlugin.logic`` thread execution +will be blocked on the "sp" evaluation until the ``StatePlugin.logic`` execution is done. Interlocking / Ordering ----------------------------------------- +----------------------- -Plugins can interlock each others using Retainer instances. -Each plugin instance has a built in lock which can be controlled using retain/release functions. +Plugins can interlock each others using ``Retainer`` instances. +Each plugin instance has a built in lock which can be controlled using ``retain``/``release`` functions. -Here is an example based on the above `Simple example` but that time, the DriverPlugin will increment the StatePlugin.logic.signal -by an amount set by other plugins (SetupPlugin in our case). And to ensure that the DriverPlugin doesn't generate the hardware too early, -the SetupPlugin uses the DriverPlugin.retain/release functions. +Here is an example based on the above `Simple example` but that time, the ``DriverPlugin`` will increment ``the StatePlugin.logic.signal`` +by an amount set by other plugins (``SetupPlugin`` in our case). And to ensure that the ``DriverPlugin`` doesn't generate the hardware too early, +the ``SetupPlugin`` uses the ``DriverPlugin.retain``/``release`` functions. .. code-block:: scala @@ -158,23 +163,26 @@ the SetupPlugin uses the DriverPlugin.retain/release functions. } class DriverPlugin extends FiberPlugin { - // incrementBy will be set by others plugin at elaboration time + // incrementBy will be set by others plugin at elaboration time. var incrementBy = 0 - // retainer allows other plugins to create locks, on which this plugin will wait before using incrementBy + // Retainer allows other plugins to create locks, on which this plugin will + // wait before using incrementBy. val retainer = Retainer() val logic = during build new Area { val sp = host[StatePlugin].logic.get retainer.await() - // Generate the incrementer hardware + // Generate the incrementer hardware. sp.signal := sp.signal + incrementBy } } - // Let's define a plugin which will modify the DriverPlugin.incrementBy variable because letting it elaborate its hardware + // Let's define a plugin which will modify the DriverPlugin.incrementBy variable + // because letting it elaborate its hardware. class SetupPlugin extends FiberPlugin { - // during setup { body } will spawn the body of code in the Fiber setup phase (it is before the Fiber build phase) + // `during setup { body }` will spawn the body of code in the Fiber setup + // phase (it is before the Fiber build phase). val logic = during setup new Area { // *** Setup phase code *** val dp = host[DriverPlugin] @@ -229,7 +237,8 @@ Here is the generated verilog reg [31:0] StatePlugin_logic_signal; always @(posedge clk) begin - StatePlugin_logic_signal <= (StatePlugin_logic_signal + 32'h00000002); // + 2 as we have two SetupPlugin + // + 2 as we have two SetupPlugin + StatePlugin_logic_signal <= (StatePlugin_logic_signal + 32'h00000002); end endmodule diff --git a/source/SpinalHDL/Libraries/Pipeline/introduction.rst b/source/SpinalHDL/Libraries/Pipeline/introduction.rst index d4e5959ab7d..485a4a6349c 100644 --- a/source/SpinalHDL/Libraries/Pipeline/introduction.rst +++ b/source/SpinalHDL/Libraries/Pipeline/introduction.rst @@ -1026,8 +1026,13 @@ Here is a simple testbench which implement a loop which will make the led counti Note -====== -When building a pipeline, only ``node(0).valid`` or ``node(n).ready`` (where ``n`` is the last stage in the pipeline) may be driven by user logic. It is possible for the builder to optimise away ``node.ready`` or ``node.valid`` signals if they are not used. To guarantee ``node.ready`` or ``node.valid`` signal creation (important if you use ``CtrlLink()`` or any other link where you want flow control) ``node(0).valid`` must be driven manually. +==== +When building a pipeline, only ``node(0).valid`` or ``node(n).ready`` (where ``n`` +is the last stage in the pipeline) may be driven by user logic. It is possible for +the builder to optimize away ``node.ready`` or ``node.valid`` signals if they are +not used. To guarantee ``node.ready`` or ``node.valid`` signal creation (important +if you use ``CtrlLink()`` or any other link where you want flow control) +``node(0).valid`` must be driven manually. .. code-block:: scala @@ -1041,4 +1046,5 @@ When building a pipeline, only ``node(0).valid`` or ``node(n).ready`` (where ``n } -This is sufficient to ensure halting and ``CtrlLink`` behaviour works as intended (``node.valid`` or ``node.ready`` signals are not optimised away). +This is sufficient to ensure halting and ``CtrlLink`` behavior works as intended +(``node.valid`` or ``node.ready`` signals are not optimized away). diff --git a/source/SpinalHDL/Libraries/fsm.rst b/source/SpinalHDL/Libraries/fsm.rst index 96883552db2..a35e23e335b 100644 --- a/source/SpinalHDL/Libraries/fsm.rst +++ b/source/SpinalHDL/Libraries/fsm.rst @@ -323,7 +323,7 @@ Example: .. code-block:: scala - // State sequance: IDLE, STATE_A, STATE_B, ... + // State sequence: IDLE, STATE_A, STATE_B, ... val fsm = new StateMachine { // IDLE is named BOOT in simulation val IDLE = makeInstantEntry() diff --git a/source/SpinalHDL/Libraries/logic.rst b/source/SpinalHDL/Libraries/logic.rst index 466db12105a..430b337a123 100644 --- a/source/SpinalHDL/Libraries/logic.rst +++ b/source/SpinalHDL/Libraries/logic.rst @@ -1,47 +1,60 @@ Logic Simplification Utilities and Decoder -=============================== -A minimal Boolean simplification and decode-table utility for decoders using quine-mcklusky. -Provides masked pattern matching, Quine McCluskey style logic reduction, and a high-level decode-table builder. ---- # Masked +========================================== + +A minimal Boolean simplification and decode-table utility for decoders using +the `Quine–McCluskey algorithm `_. + +Provides masked pattern matching, Quine–McCluskey style logic reduction, +and a high-level decode-table builder. + +`Masked` +-------- + Represents a bit pattern with care (significant) and don't-care bits. -`value` = bit values -`care` = which bits must match (1 = match, 0 = don't care) ---- Example: +- `value` = bit values +- `care` = which bits must match (1 = match, 0 = don't care) + +Example: + +.. code-block:: scala -.. code-block:: scala Masked(0010), Masked(11-1), Masked(1--0) -e.g RISC-V instrs +e.g RISC-V instructions: + +.. code-block:: scala -.. code-block:: scala val ADD = M"0000000----------000-----0110011" val ADDI = M"-----------------000-----0010011" Used to define instruction encodings for decode tables. +`DecodingSpec` +-------------- ---- # DecodingSpec -High-level builder for decode tables using `Masked` patterns. -`` val decoder = new DecodingSpec() - **API:** +High-level builder for decode tables using `Masked` patterns. +Methods: * `addNeeds(key : Masked, value : Masked)` * `addNeeds(keys : Seq[Masked], value : Masked)` * `build(sel, coverAll)` - * ``def setDefault(value : Masked)`` + * `setDefault(value : Masked)` + +This generate simplified decode logic. + +Example: + +.. code-block:: scala - generate simplified decode logic -**Example:** -.. code-block:: scala ``` val spec = new DecodingSpec(UInt(4 bits)) spec.setDefault(Masked(U"0011")) spec.addNeeds(Masked(B"000"), Masked(U"1000")) result := spec.build(sel, allPatterns) -Generates minimized combinational decode logic. - --- # Practical Use -Define bit patterns as `Masked` and feed them into `DecodingSpec` to build compact decode logic (e.g., RISC-V). +Generates minimized combinational decode logic. -* Output hardware is minimized (fewer LUTs / simpler gates) +The practical use is to define bit patterns as `Masked` and feed them into +`DecodingSpec` to build compact decode logic (e.g., RISC-V). The output hardware +is then minimized (fewer LUTs / simpler gates). diff --git a/source/SpinalHDL/Libraries/regIf.rst b/source/SpinalHDL/Libraries/regIf.rst index 8eac63e6fea..8f55b3017b0 100644 --- a/source/SpinalHDL/Libraries/regIf.rst +++ b/source/SpinalHDL/Libraries/regIf.rst @@ -53,7 +53,7 @@ Automatic filed allocation conflict detection -.. code:: scala + .. code:: scala val M_REG1 = busif.newReg(doc="REG1") val r1fd0 = M_REG1.field(Bits(16 bits), RW, doc="fields 1") diff --git a/source/SpinalHDL/Libraries/stream.rst b/source/SpinalHDL/Libraries/stream.rst index 4b87ce19d78..f856ffae6c7 100644 --- a/source/SpinalHDL/Libraries/stream.rst +++ b/source/SpinalHDL/Libraries/stream.rst @@ -587,10 +587,11 @@ The ``count`` is captured and registered each time inputStream fires for an indi val outputStream = Stream(Bits(8 bits)) val count = UInt(3 bits) val extender = StreamTransactionExtender(inputStream, outputStream, count) { - // id, is the 0-based index of total output transfers so far in the current input transaction. + // id, is the 0-based index of total output transfers so far in the current + // input transaction. // last, is the last transfer indication, same as the last signal for extender. - // the returned payload is allowed to be modified only based on id and last signals, other - // translation should be done outside of this. + // the returned payload is allowed to be modified only based on id and last + // signals, other translation should be done outside of this. (id, payload, last) => payload } @@ -663,7 +664,7 @@ For simulation master and slave implementations are available: scoreboard.pushRef(payload.toInt) } - // randmize ready on the output and add popped data to scoreboard + // randomize ready on the output and add popped data to scoreboard StreamReadyRandomizer(dut.io.pop, dut.clockDomain) StreamMonitor(dut.io.pop, dut.clockDomain) { payload => scoreboard.pushDut(payload.toInt) diff --git a/source/SpinalHDL/Other language features/utils.rst b/source/SpinalHDL/Other language features/utils.rst index 71e2f48646a..944dbd77423 100644 --- a/source/SpinalHDL/Other language features/utils.rst +++ b/source/SpinalHDL/Other language features/utils.rst @@ -32,7 +32,7 @@ Many tools and utilities are present in :ref:`spinal.lib ` but - Concatenate all arguments, from MSB to LSB, see `Cat`_ * - ``Cat(x: Iterable[Data])`` - Bits - - Conactenate arguments, from LSB to MSB, see `Cat`_ + - Concatenate arguments, from LSB to MSB, see `Cat`_ .. _Cat: @@ -61,8 +61,8 @@ Lists are written down starting from index 0 to the highest index. ``Cat`` place val signals = List(bit0, bit1, bit2) val second = Cat(signals) -Cloning hardware datatypes --------------------------- +Cloning hardware data types +--------------------------- You can clone a given hardware data type by using the ``cloneOf(x)`` function. It will return a new instance of the same Scala type and parameters. diff --git a/source/SpinalHDL/Other language features/vhdl_generation.rst b/source/SpinalHDL/Other language features/vhdl_generation.rst index f0ac492c393..bfb448a8a42 100644 --- a/source/SpinalHDL/Other language features/vhdl_generation.rst +++ b/source/SpinalHDL/Other language features/vhdl_generation.rst @@ -5,7 +5,7 @@ VHDL and Verilog generation =========================== Generate VHDL and Verilog from a SpinalHDL Component ------------------------------------------------------ +---------------------------------------------------- To generate the VHDL from a SpinalHDL component you just need to call ``SpinalVhdl(new YourComponent)`` in a Scala ``main``. @@ -28,7 +28,8 @@ Generating Verilog is exactly the same, but with ``SpinalVerilog`` in place of ` io.c := io.a & io.b } - // This is the main function that generates the VHDL and the Verilog corresponding to MyTopLevel. + // This is the main function that generates the VHDL and the Verilog + // corresponding to MyTopLevel. object MyMain { def main(args: Array[String]) { SpinalVhdl(new MyTopLevel) @@ -91,7 +92,7 @@ Parametrization from Scala * - ``globalPrefix`` - String - "" - - Will add the given prefix in the front of every global symboles in the VHDL/Verilog (components/modules/enums). This allows to avoid naming conflict between multiple generated file. + - Will add the given prefix in the front of every global symbols in the VHDL/Verilog (components/modules/enums). This allows to avoid naming conflict between multiple generated file. * - ``privateNamespace`` - Boolean - false @@ -115,15 +116,15 @@ Parametrization from Scala * - ``mergeAsyncProcess`` - Boolean - false - - Will merge process/always blocks for combinatorial signal which share at least one conditional assignement (if/switch statment) + - Will merge process/always blocks for combinatorial signal which share at least one conditional assignment (if/switch statement) * - ``mergeSyncProcess`` - Boolean - true - - Will merge process/always blocks for flip-flops which use the same clock domain (if/switch statment) + - Will merge process/always blocks for flip-flops which use the same clock domain (if/switch statement) * - ``genLineComments`` - Boolean - false - - For each hardware assignment in the generated VHDL/Verilog code, will attach a comment which specifies in which scala file, at which line, the assignement happend. Ex : a = 1'b1; // @ MyDesign.scala l1135 + - For each hardware assignment in the generated VHDL/Verilog code, will attach a comment which specifies in which scala file, at which line, the assignment happened. Ex : a = 1'b1; // @ MyDesign.scala l1135 * - ``noAssert`` - Boolean - false @@ -147,7 +148,7 @@ Parametrization from Scala * - ``rtlHeader`` - String - disabled - - Allow to manualy specify the VHDL/Verilog file header + - Allow to manually specify the VHDL/Verilog file header * - ``withTimescale`` - Boolean - True diff --git a/source/SpinalHDL/Simulation/examples/uart_encoder.rst b/source/SpinalHDL/Simulation/examples/uart_encoder.rst index cfa49b974ba..507ea4cb467 100644 --- a/source/SpinalHDL/Simulation/examples/uart_encoder.rst +++ b/source/SpinalHDL/Simulation/examples/uart_encoder.rst @@ -4,7 +4,8 @@ Uart encoder .. code-block:: scala - // Fork a simulation process which will get chars typed into the simulation terminal and transmit them on the simulation uartPin. + // Fork a simulation process which will get chars typed into the simulation + // terminal and transmit them on the simulation uartPin. fork { uartPin #= true while(true) { @@ -22,7 +23,8 @@ Uart encoder uartPin #= true sleep(baudPeriod) } else { - sleep(baudPeriod * 10) // Sleep a little while to avoid polling System.in too often. + // Sleep a little while to avoid polling System.in too often. + sleep(baudPeriod * 10) } } } diff --git a/source/SpinalHDL/Simulation/install/GHDL.rst b/source/SpinalHDL/Simulation/install/GHDL.rst index 5c37dcb18ac..51eeface33b 100644 --- a/source/SpinalHDL/Simulation/install/GHDL.rst +++ b/source/SpinalHDL/Simulation/install/GHDL.rst @@ -6,7 +6,7 @@ Setup and installation of GHDL If you installed the recommended oss-cad-suite during SpinalHDL :ref:`setup ` you can skip the instructions below - but you need to activate the oss-cad-suite environment. -Even though GHDL is generally available in linux distributions package system, SpinalHDL depends on bugfixes of GHDL codebase that were added after the release of GHDL v0.37. Therefore it is reccomended to install GHDL from source. +Even though GHDL is generally available in linux distributions package system, SpinalHDL depends on bugfixes of GHDL codebase that were added after the release of GHDL v0.37. Therefore it is recommended to install GHDL from source. The C++ library boost-interprocess, which is contained in the libboost-dev package in debian-like distributions, has to be installed too. boost-interprocess is required to generate the shared memory communication interface. Linux diff --git a/source/SpinalHDL/miscelenea/core/core_components.rst b/source/SpinalHDL/miscelenea/core/core_components.rst index 6cba67e26c0..2fe71f04fc7 100644 --- a/source/SpinalHDL/miscelenea/core/core_components.rst +++ b/source/SpinalHDL/miscelenea/core/core_components.rst @@ -33,7 +33,7 @@ In *Spinal*\ , clock and reset signals can be combined to create a **clock domai Clock domain application work like a stack, which mean, if you are in a given clock domain, you can still apply another clock domain locally. -.. _core_componets_clock_constructor: +.. _core_components_clock_constructor: Clock domain syntax ^^^^^^^^^^^^^^^^^^^ @@ -69,7 +69,8 @@ An applied example to define a specific clock domain within the design is as fol Clock configuration ^^^^^^^^^^^^^^^^^^^ -In addition to the constructor parameters given :ref:`here ` , the following elements of each clock domain are configurable via a ``ClockDomainConfig`` class : +In addition to the constructor parameters given :ref:`here ` , +the following elements of each clock domain are configurable via a ``ClockDomainConfig`` class : .. list-table:: :header-rows: 1 diff --git a/source/SpinalHDL/miscelenea/frequent_errors.rst b/source/SpinalHDL/miscelenea/frequent_errors.rst index 4a7754d30d0..1fd8ac91800 100644 --- a/source/SpinalHDL/miscelenea/frequent_errors.rst +++ b/source/SpinalHDL/miscelenea/frequent_errors.rst @@ -26,7 +26,12 @@ Exception in thread "main" java.lang.NullPointerException **Issue explanation :** -SpinalHDL is not a language, it is an Scala library, which mean, it obey to the same rules than the Scala general purpose programming language. When you run your SpinalHDL hardware description to generate the corresponding VHDL/Verilog RTL, your SpinalHDL hardware description will be executed as a Scala programm, and b will be a ``null`` reference until the programm execution come to that line, and it's why you can't use it before. +SpinalHDL is not a language, it is an Scala library, which mean, it obey to the +same rules than the Scala general purpose programming language. When you run your +SpinalHDL hardware description to generate the corresponding VHDL/Verilog RTL, +your SpinalHDL hardware description will be executed as a Scala program, and b +will be a ``null`` reference until the program execution comes to that line, +and it's why you can't use it before. Hierarchy violation -------------------