deploy: 3f0d19b

Author: christiaanb

pr-10/compiler-user-guide/developing-hardware/annotations.html

@@ -174,7 +174,7 @@ <h1 id="synthesize-annotations-controlling-vhdlsystemverilog-generation"><a clas
 <li>Use cached versions of generated HDL, i.e., prevent recompilation of (sub)entities that have not changed since the last run.
 Caching is based on a <code>.manifest</code> which is generated alongside the HDL; deleting this file means deleting the cache; changing this file will result in <em>undefined</em> behavior.</li>
 </ul>
-<p>Functions with a 'Synthesize' annotation must adhere to the following restrictions:</p>
+<p>Functions with a <code>Synthesize</code> annotation must adhere to the following restrictions:</p>
 <ul>
 <li>Although functions with a <code>Synthesize</code> annotation can of course depend on functions with another <code>Synthesize</code> annotation, they must not be mutually recursive.</li>
 <li>Functions with a <code>Synthesize</code> annotation must be completely <em>monomorphic</em> and <em>first-order</em>, and cannot have any <em>non-representable</em> arguments or result.</li>

pr-10/compiler-user-guide/developing-hardware/limitations.html

@@ -305,17 +305,17 @@ <h1 id="limitations-of-the-compiler"><a class="header" href="#limitations-of-the
 <p><code>Int</code> and <code>Word</code> are represented by the same number of bits as is native for the architecture of the computer on which the Clash compiler is executed.
 This means that if you are working on a 64-bit machine, <code>Int</code> and <code>Word</code> will be 64-bit.
 This might be problematic when you are working in a team, and one designer has a 32-bit machine, and the other has a 64-bit machine.
-In general, you should be avoiding 'Int' in such cases, but as a band-aid solution, you can force the Clash compiler to use a specific bit-width for <code>Int</code> and <code>Word</code> using the <code>-fclash-intwidth=N</code> flag, where <em>N</em> must either be <em>32</em> or <em>64</em>.</p>
+In general, you should be avoiding <code>Int</code> in such cases, but as a band-aid solution, you can force the Clash compiler to use a specific bit-width for <code>Int</code> and <code>Word</code> using the <code>-fclash-intwidth=N</code> flag, where <em>N</em> must either be <em>32</em> or <em>64</em>.</p>
 </li>
 <li>
-<p>When you use the <code>-fclash-intwidth=32</code> flag on a <em>64-bit</em> machine, the 'Word64' and 'Int64' types <em>cannot</em> be translated. This restriction does <em>not</em> apply to the other three combinations of <code>-fclash-intwidth</code> flag and machine type.</p>
+<p>When you use the <code>-fclash-intwidth=32</code> flag on a <em>64-bit</em> machine, the <code>Word64</code> and <code>Int64</code> types <em>cannot</em> be translated. This restriction does <em>not</em> apply to the other three combinations of <code>-fclash-intwidth</code> flag and machine type.</p>
 </li>
 <li>
-<p>The translation of 'Integer' is not meaning-preserving.
-'Integer' in Haskell is an arbitrary precision integer, something that cannot be represented in a statically known number of bits.
-In the Clash compiler, we chose to represent 'Integer' by the same number of bits as we do for <code>Int</code> and <code>Word</code>.
+<p>The translation of <code>Integer</code> is not meaning-preserving.
+<code>Integer</code> in Haskell is an arbitrary precision integer, something that cannot be represented in a statically known number of bits.
+In the Clash compiler, we chose to represent <code>Integer</code> by the same number of bits as we do for <code>Int</code> and <code>Word</code>.
 As you have read in a previous bullet point, this number of bits is either 32 or 64, depending on the architecture of the machine the Clash compiler is running on, or the setting of the <code>-fclash-intwidth</code> flag.</p>
-<p>Consequently, you should use <code>Integer</code> with due diligence; be especially careful when using <code>fromIntegral</code> as it does a conversion via 'Integer'.
+<p>Consequently, you should use <code>Integer</code> with due diligence; be especially careful when using <code>fromIntegral</code> as it does a conversion via <code>Integer</code>.
 For example:</p>
 <pre><code class="language-haskell">signedToUnsigned :: Signed 128 -&gt; Unsigned 128
 signedToUnsigned = fromIntegral

pr-10/compiler-user-guide/developing-hardware/primitives.html

@@ -168,7 +168,8 @@ <h1 class="menu-title">Clash Compiler User Guide</h1>
                     <main>
                         <h1 id="user-defined-primitives"><a class="header" href="#user-defined-primitives">User-defined primitives</a></h1>
 <p>There are times when you already have an existing piece of IP, or there are times where you need the HDL to have a specific shape so that the HDL synthesis tool can infer a specific component.
-In these specific cases you can resort to defining your own HDL primitives. Actually, most of the primitives in Clash are specified in the same way as you will read about in this section.
+In these specific cases you can resort to defining your own HDL primitives.
+Actually, most of the primitives in Clash are specified in the same way as you will read about in this section.
 There are perhaps 10 (at most) functions which are truly hard-coded into the Clash compiler.
 You can take a look at the files in <a href="https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/vhdl">https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/vhdl</a> (or <a href="https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/verilog">https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/verilog</a> for the Verilog primitives or <a href="https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/systemverilog">https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/systemverilog</a> for the SystemVerilog primitives) if you want to know which functions are defined as "regular" primitives.
 The compiler looks for primitives in four locations:</p>

pr-10/compiler-user-guide/developing-hardware/troubleshooting.html

@@ -172,7 +172,8 @@ <h1 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooti
 <li>
 <p><strong>Type error: Couldn't match expected type <code>Signal dom (a,b)</code> with actual type <code>(Signal dom a, Signal dom b)</code></strong>:</p>
 <p>Signals of product types and product types of signals are <strong>isomorphic</strong> due to synchronisity principle, but are not (structurally) equal.
-Tuples are a product type. Use the <code>bundle</code> function to convert from a product type to the signal type.
+Tuples are a product type.
+Use the <code>bundle</code> function to convert from a product type to the signal type.
 So if your code which gives the error looks like:</p>
 <pre><code class="language-haskell">... = f a b (c,d)
 </code></pre>
@@ -188,7 +189,8 @@ <h1 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooti
 <li>
 <p><strong>Type error: Couldn't match expected type <code>(Signal dom a, Signal dom b)</code> with actual type <code>Signal dom (a,b)</code></strong>:</p>
 <p>Product types of signals and signals of product types are <strong>isomorphic</strong> due to synchronicity principle, but are not (structurally) equal.
-Tuples are a product type. Use the <code>unbundle</code> function to convert from a signal type to the product type.
+Tuples are a product type.
+Use the <code>unbundle</code> function to convert from a signal type to the product type.
 So if your code which gives the error looks like:</p>
 <pre><code class="language-haskell">(c,d) = f a b
 </code></pre>
@@ -253,7 +255,8 @@ <h1 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooti
 </li>
 <li>
 <p><strong>&lt;*** Exception: &lt;&lt;loop&gt;&gt; or "blinking cursor"</strong></p>
-<p>You are using value-recursion, but one of the <code>Vec</code>tor functions that you are using is too <em>strict</em> in one of the recursive arguments. For example:</p>
+<p>You are using value-recursion, but one of the <code>Vec</code>tor functions that you are using is too <em>strict</em> in one of the recursive arguments.
+For example:</p>
 <pre><code class="language-haskell">-- Bubble sort for 1 iteration
 sortV xs = map fst sorted :&lt; (snd (last sorted))
  where

pr-10/compiler-user-guide/print.html

@@ -794,7 +794,7 @@ <h2 id="undefined-values"><a class="header" href="#undefined-values">Undefined V
 <li>Use cached versions of generated HDL, i.e., prevent recompilation of (sub)entities that have not changed since the last run.
 Caching is based on a <code>.manifest</code> which is generated alongside the HDL; deleting this file means deleting the cache; changing this file will result in <em>undefined</em> behavior.</li>
 </ul>
-<p>Functions with a 'Synthesize' annotation must adhere to the following restrictions:</p>
+<p>Functions with a <code>Synthesize</code> annotation must adhere to the following restrictions:</p>
 <ul>
 <li>Although functions with a <code>Synthesize</code> annotation can of course depend on functions with another <code>Synthesize</code> annotation, they must not be mutually recursive.</li>
 <li>Functions with a <code>Synthesize</code> annotation must be completely <em>monomorphic</em> and <em>first-order</em>, and cannot have any <em>non-representable</em> arguments or result.</li>
@@ -914,7 +914,8 @@ <h2 id="undefined-values"><a class="header" href="#undefined-values">Undefined V
 <p>See the documentation of <code>Synthesize</code> for the meaning of all its fields.</p>
 <div style="break-before: page; page-break-before: always;"></div><h1 id="user-defined-primitives"><a class="header" href="#user-defined-primitives">User-defined primitives</a></h1>
 <p>There are times when you already have an existing piece of IP, or there are times where you need the HDL to have a specific shape so that the HDL synthesis tool can infer a specific component.
-In these specific cases you can resort to defining your own HDL primitives. Actually, most of the primitives in Clash are specified in the same way as you will read about in this section.
+In these specific cases you can resort to defining your own HDL primitives.
+Actually, most of the primitives in Clash are specified in the same way as you will read about in this section.
 There are perhaps 10 (at most) functions which are truly hard-coded into the Clash compiler.
 You can take a look at the files in <a href="https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/vhdl">https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/vhdl</a> (or <a href="https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/verilog">https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/verilog</a> for the Verilog primitives or <a href="https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/systemverilog">https://github.com/clash-lang/clash-compiler/tree/master/clash-lib/prims/systemverilog</a> for the SystemVerilog primitives) if you want to know which functions are defined as "regular" primitives.
 The compiler looks for primitives in four locations:</p>
@@ -1288,7 +1289,8 @@ <h2 id="systemverilog-examples"><a class="header" href="#systemverilog-examples"
 <li>
 <p><strong>Type error: Couldn't match expected type <code>Signal dom (a,b)</code> with actual type <code>(Signal dom a, Signal dom b)</code></strong>:</p>
 <p>Signals of product types and product types of signals are <strong>isomorphic</strong> due to synchronisity principle, but are not (structurally) equal.
-Tuples are a product type. Use the <code>bundle</code> function to convert from a product type to the signal type.
+Tuples are a product type.
+Use the <code>bundle</code> function to convert from a product type to the signal type.
 So if your code which gives the error looks like:</p>
 <pre><code class="language-haskell">... = f a b (c,d)
 </code></pre>
@@ -1304,7 +1306,8 @@ <h2 id="systemverilog-examples"><a class="header" href="#systemverilog-examples"
 <li>
 <p><strong>Type error: Couldn't match expected type <code>(Signal dom a, Signal dom b)</code> with actual type <code>Signal dom (a,b)</code></strong>:</p>
 <p>Product types of signals and signals of product types are <strong>isomorphic</strong> due to synchronicity principle, but are not (structurally) equal.
-Tuples are a product type. Use the <code>unbundle</code> function to convert from a signal type to the product type.
+Tuples are a product type.
+Use the <code>unbundle</code> function to convert from a signal type to the product type.
 So if your code which gives the error looks like:</p>
 <pre><code class="language-haskell">(c,d) = f a b
 </code></pre>
@@ -1369,7 +1372,8 @@ <h2 id="systemverilog-examples"><a class="header" href="#systemverilog-examples"
 </li>
 <li>
 <p><strong>&lt;*** Exception: &lt;&lt;loop&gt;&gt; or "blinking cursor"</strong></p>
-<p>You are using value-recursion, but one of the <code>Vec</code>tor functions that you are using is too <em>strict</em> in one of the recursive arguments. For example:</p>
+<p>You are using value-recursion, but one of the <code>Vec</code>tor functions that you are using is too <em>strict</em> in one of the recursive arguments.
+For example:</p>
 <pre><code class="language-haskell">-- Bubble sort for 1 iteration
 sortV xs = map fst sorted :&lt; (snd (last sorted))
  where
@@ -1533,17 +1537,17 @@ <h2 id="systemverilog-examples"><a class="header" href="#systemverilog-examples"
 <p><code>Int</code> and <code>Word</code> are represented by the same number of bits as is native for the architecture of the computer on which the Clash compiler is executed.
 This means that if you are working on a 64-bit machine, <code>Int</code> and <code>Word</code> will be 64-bit.
 This might be problematic when you are working in a team, and one designer has a 32-bit machine, and the other has a 64-bit machine.
-In general, you should be avoiding 'Int' in such cases, but as a band-aid solution, you can force the Clash compiler to use a specific bit-width for <code>Int</code> and <code>Word</code> using the <code>-fclash-intwidth=N</code> flag, where <em>N</em> must either be <em>32</em> or <em>64</em>.</p>
+In general, you should be avoiding <code>Int</code> in such cases, but as a band-aid solution, you can force the Clash compiler to use a specific bit-width for <code>Int</code> and <code>Word</code> using the <code>-fclash-intwidth=N</code> flag, where <em>N</em> must either be <em>32</em> or <em>64</em>.</p>
 </li>
 <li>
-<p>When you use the <code>-fclash-intwidth=32</code> flag on a <em>64-bit</em> machine, the 'Word64' and 'Int64' types <em>cannot</em> be translated. This restriction does <em>not</em> apply to the other three combinations of <code>-fclash-intwidth</code> flag and machine type.</p>
+<p>When you use the <code>-fclash-intwidth=32</code> flag on a <em>64-bit</em> machine, the <code>Word64</code> and <code>Int64</code> types <em>cannot</em> be translated. This restriction does <em>not</em> apply to the other three combinations of <code>-fclash-intwidth</code> flag and machine type.</p>
 </li>
 <li>
-<p>The translation of 'Integer' is not meaning-preserving.
-'Integer' in Haskell is an arbitrary precision integer, something that cannot be represented in a statically known number of bits.
-In the Clash compiler, we chose to represent 'Integer' by the same number of bits as we do for <code>Int</code> and <code>Word</code>.
+<p>The translation of <code>Integer</code> is not meaning-preserving.
+<code>Integer</code> in Haskell is an arbitrary precision integer, something that cannot be represented in a statically known number of bits.
+In the Clash compiler, we chose to represent <code>Integer</code> by the same number of bits as we do for <code>Int</code> and <code>Word</code>.
 As you have read in a previous bullet point, this number of bits is either 32 or 64, depending on the architecture of the machine the Clash compiler is running on, or the setting of the <code>-fclash-intwidth</code> flag.</p>
-<p>Consequently, you should use <code>Integer</code> with due diligence; be especially careful when using <code>fromIntegral</code> as it does a conversion via 'Integer'.
+<p>Consequently, you should use <code>Integer</code> with due diligence; be especially careful when using <code>fromIntegral</code> as it does a conversion via <code>Integer</code>.
 For example:</p>
 <pre><code class="language-haskell">signedToUnsigned :: Signed 128 -&gt; Unsigned 128
 signedToUnsigned = fromIntegral

pr-10/compiler-user-guide/searchindex.js

@@ -0,0 +1 @@
+This file makes sure that Github Pages doesn't process mdBook's output.