Skip to content

Commit 72b39ac

Browse files
christiaanbchristiaanb
committed
deploy: 13c556f 
1 parent 562d651 commit 72b39ac

File tree

8 files changed

+482
-8
lines changed

8 files changed

+482
-8
lines changed

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

Lines changed: 346 additions & 0 deletions
Large diffs are not rendered by default.

‎pr-10/compiler-user-guide/developing-hardware/flags.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -364,7 +364,7 @@ <h1 id="clash-compiler-flags"><a class="header" href="#clash-compiler-flags">Cla
364364
<i class="fa fa-angle-left"></i>
365365
</a>
366366

367-
<a rel="next prefetch" href="../developing-hardware/primitives.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
367+
<a rel="next prefetch" href="../developing-hardware/annotations.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
368368
<i class="fa fa-angle-right"></i>
369369
</a>
370370

@@ -378,7 +378,7 @@ <h1 id="clash-compiler-flags"><a class="header" href="#clash-compiler-flags">Cla
378378
<i class="fa fa-angle-left"></i>
379379
</a>
380380

381-
<a rel="next prefetch" href="../developing-hardware/primitives.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
381+
<a rel="next prefetch" href="../developing-hardware/annotations.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
382382
<i class="fa fa-angle-right"></i>
383383
</a>
384384
</nav>

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -541,7 +541,7 @@ <h2 id="systemverilog-examples"><a class="header" href="#systemverilog-examples"
541541

542542
<nav class="nav-wrapper" aria-label="Page navigation">
543543
<!-- Mobile navigation buttons -->
544-
<a rel="prev" href="../developing-hardware/flags.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
544+
<a rel="prev" href="../developing-hardware/annotations.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
545545
<i class="fa fa-angle-left"></i>
546546
</a>
547547

@@ -555,7 +555,7 @@ <h2 id="systemverilog-examples"><a class="header" href="#systemverilog-examples"
555555
</div>
556556

557557
<nav class="nav-wide-wrapper" aria-label="Page navigation">
558-
<a rel="prev" href="../developing-hardware/flags.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
558+
<a rel="prev" href="../developing-hardware/annotations.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
559559
<i class="fa fa-angle-left"></i>
560560
</a>
561561

‎pr-10/compiler-user-guide/highlight.js‎

Lines changed: 3 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -786,6 +786,132 @@ <h2 id="undefined-values"><a class="header" href="#undefined-values">Undefined V
786786
Sets the second part of Verilog's <code>timescale 100fs/100fs</code>.
787787
E.g., setting this flag to <code>1fs</code> would make Clash generate Verilog files with <code>timescale 100fs/1fs</code> as their header.</p>
788788
<p><strong>Default:</strong> <code>100fs</code></p>
789+
<div style="break-before: page; page-break-before: always;"></div><h1 id="synthesize-annotations-controlling-vhdlsystemverilog-generation"><a class="header" href="#synthesize-annotations-controlling-vhdlsystemverilog-generation">Synthesize annotations: controlling VHDL/(System)Verilog generation.</a></h1>
790+
<p><code>Synthesize</code> annotations allow us to control hierarchy and naming aspects of the Clash compiler, specifically, they allow us to:</p>
791+
<ul>
792+
<li>Assign names to entities (VHDL) / modules ((System)Verilog), and their ports.</li>
793+
<li>Put generated HDL files of a logical (sub)entity in their own directory.</li>
794+
<li>Use cached versions of generated HDL, i.e., prevent recompilation of (sub)entities that have not changed since the last run.
795+
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>
796+
</ul>
797+
<p>Functions with a 'Synthesize' annotation must adhere to the following restrictions:</p>
798+
<ul>
799+
<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>
800+
<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>
801+
</ul>
802+
<p>Also take the following into account when using <code>Synthesize</code> annotations.</p>
803+
<ul>
804+
<li>The Clash compiler is based on the GHC Haskell compiler, and the GHC machinery does not understand <code>Synthesize</code> annotations and it might subsequently decide to inline those functions.
805+
You should therefor also add a <code>{-# OPAQUE f #-}</code> pragma to the functions which you give a <code>Synthesize</code> functions.</li>
806+
<li>Functions with a <code>Synthesize</code> annotation will not be specialized on constants.</li>
807+
</ul>
808+
<p>Finally, the root module, the module which you pass as an argument to the Clash compiler must either have:</p>
809+
<ul>
810+
<li>A function with a <code>Synthesize</code> annotation.</li>
811+
<li>A function called <em>topEntity</em>.</li>
812+
</ul>
813+
<p>You apply <code>Synthesize</code> annotations to functions using an <code>ANN</code> pragma:</p>
814+
<pre><code class="language-haskell">{-# OPAQUE topEntity #-}
815+
{-# ANN topEntity (Synthesize {t_name = ..., ... }) #-}
816+
topEntity x = ...
817+
</code></pre>
818+
<p>For example, given the following specification:</p>
819+
<pre><code class="language-haskell">module Blinker where
820+
821+
import Clash.Signal
822+
import Clash.Prelude
823+
import Clash.Intel.ClockGen
824+
825+
createDomain vSystem{vName="DomInput", vPeriod=20000, vResetPolarity=ActiveLow}
826+
createDomain vSystem{vName="Dom100", vPeriod=10000}
827+
828+
topEntity
829+
:: Clock DomInput
830+
-&gt; Reset DomInput
831+
-&gt; Signal Dom100 Bit
832+
-&gt; Signal Dom100 (BitVector 8)
833+
topEntity clk rst =
834+
exposeClockResetEnable (mealy blinkerT (1,False,0) . isRising 1) pllOut pllRst enableGen
835+
where
836+
(pllOut,pllRst) = altpllSync clk rst
837+
838+
blinkerT (leds,mode,cntr) key1R = ((ledsN,modeN,cntrN),leds)
839+
where
840+
-- clock frequency = 100e6 (100 MHz)
841+
-- led update rate = 333e-3 (every 333ms)
842+
cnt_max = maxBound :: Index 33300000 -- 100e6 * 333e-3
843+
844+
cntrN | cntr == cnt_max = 0
845+
| otherwise = cntr + 1
846+
847+
modeN | key1R = not mode
848+
| otherwise = mode
849+
850+
ledsN | cntr == 0 = if mode then complement leds
851+
else rotateL leds 1
852+
| otherwise = leds
853+
</code></pre>
854+
<p>The Clash compiler will normally generate the following <code>topentity.vhdl</code> file:</p>
855+
<pre><code class="language-vhdl">-- Automatically generated VHDL-93
856+
library IEEE;
857+
use IEEE.STD_LOGIC_1164.ALL;
858+
use IEEE.NUMERIC_STD.ALL;
859+
use IEEE.MATH_REAL.ALL;
860+
use std.textio.all;
861+
use work.all;
862+
use work.Blinker_topEntity_types.all;
863+
864+
entity topEntity is
865+
port(-- clock
866+
clk : in Blinker_topEntity_types.clk_DomInput;
867+
-- reset
868+
rst : in Blinker_topEntity_types.rst_DomInput;
869+
eta : in std_logic;
870+
result : out std_logic_vector(7 downto 0));
871+
end;
872+
873+
architecture structural of topEntity is
874+
...
875+
end;
876+
</code></pre>
877+
<p>However, if we add the following <code>Synthesize</code> annotation in the file:</p>
878+
<pre><code class="language-haskell">{-# OPAQUE topEntity #-}
879+
{-# ANN topEntity
880+
(Synthesize
881+
{ t_name = "blinker"
882+
, t_inputs = [PortName "CLOCK_50", PortName "KEY0", PortName "KEY1"]
883+
, t_output = PortName "LED"
884+
}) #-}
885+
</code></pre>
886+
<p>The Clash compiler will generate the following <code>blinker.vhdl</code> file instead:</p>
887+
<pre><code class="language-vhdl">-- Automatically generated VHDL-93
888+
library IEEE;
889+
use IEEE.STD_LOGIC_1164.ALL;
890+
use IEEE.NUMERIC_STD.ALL;
891+
use IEEE.MATH_REAL.ALL;
892+
use std.textio.all;
893+
use work.all;
894+
use work.blinker_types.all;
895+
896+
entity blinker is
897+
port(-- clock
898+
CLOCK_50 : in blinker_types.clk_DomInput;
899+
-- reset
900+
KEY0 : in blinker_types.rst_DomInput;
901+
KEY1 : in std_logic;
902+
LED : out std_logic_vector(7 downto 0));
903+
end;
904+
905+
architecture structural of blinker is
906+
...
907+
end;
908+
</code></pre>
909+
<p>Where we now have:</p>
910+
<ul>
911+
<li>A top-level component that is called <code>blinker</code>.</li>
912+
<li>Inputs and outputs that have a <em>user</em>-chosen name: <code>CLOCK_50</code>, <code>KEY0</code>, <code>KEY1</code>, <code>LED</code>, etc.</li>
913+
</ul>
914+
<p>See the documentation of <code>Synthesize</code> for the meaning of all its fields.</p>
789915
<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>
790916
<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.
791917
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.

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

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pr-10/compiler-user-guide/toc.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,6 @@
2727
<!-- Custom theme stylesheets -->
2828
</head>
2929
<body class="sidebar-iframe-inner">
30-
<ol class="chapter"><li class="chapter-item expanded affix "><a href="index.html" target="_parent">Clash User Guide</a></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.</strong> Getting Started</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="getting-started/installing.html" target="_parent"><strong aria-hidden="true">1.1.</strong> Installing</a></li></ol></li><li class="chapter-item expanded "><a href="general/index.html" target="_parent"><strong aria-hidden="true">2.</strong> General</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="general/relnotes.html" target="_parent"><strong aria-hidden="true">2.1.</strong> Release Notes</a></li><li class="chapter-item expanded "><a href="general/faqs.html" target="_parent"><strong aria-hidden="true">2.2.</strong> FAQs</a></li><li class="chapter-item expanded "><a href="general/license.html" target="_parent"><strong aria-hidden="true">2.3.</strong> License</a></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.</strong> Developing Hardware</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="developing-hardware/language.html" target="_parent"><strong aria-hidden="true">3.1.</strong> Language</a></li><li class="chapter-item expanded "><a href="developing-hardware/prelude.html" target="_parent"><strong aria-hidden="true">3.2.</strong> Prelude</a></li><li class="chapter-item expanded "><a href="developing-hardware/flags.html" target="_parent"><strong aria-hidden="true">3.3.</strong> Flags</a></li><li class="chapter-item expanded "><a href="developing-hardware/primitives.html" target="_parent"><strong aria-hidden="true">3.4.</strong> User-defined primitives</a></li><li class="chapter-item expanded "><a href="developing-hardware/limitations.html" target="_parent"><strong aria-hidden="true">3.5.</strong> Limitations of the compiler</a></li></ol></li><li class="chapter-item expanded "><a href="hacking-on-clash/index.html" target="_parent"><strong aria-hidden="true">4.</strong> Hacking on Clash</a></li></ol>
30+
<ol class="chapter"><li class="chapter-item expanded affix "><a href="index.html" target="_parent">Clash User Guide</a></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.</strong> Getting Started</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="getting-started/installing.html" target="_parent"><strong aria-hidden="true">1.1.</strong> Installing</a></li></ol></li><li class="chapter-item expanded "><a href="general/index.html" target="_parent"><strong aria-hidden="true">2.</strong> General</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="general/relnotes.html" target="_parent"><strong aria-hidden="true">2.1.</strong> Release Notes</a></li><li class="chapter-item expanded "><a href="general/faqs.html" target="_parent"><strong aria-hidden="true">2.2.</strong> FAQs</a></li><li class="chapter-item expanded "><a href="general/license.html" target="_parent"><strong aria-hidden="true">2.3.</strong> License</a></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.</strong> Developing Hardware</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="developing-hardware/language.html" target="_parent"><strong aria-hidden="true">3.1.</strong> Language</a></li><li class="chapter-item expanded "><a href="developing-hardware/prelude.html" target="_parent"><strong aria-hidden="true">3.2.</strong> Prelude</a></li><li class="chapter-item expanded "><a href="developing-hardware/flags.html" target="_parent"><strong aria-hidden="true">3.3.</strong> Flags</a></li><li class="chapter-item expanded "><a href="developing-hardware/annotations.html" target="_parent"><strong aria-hidden="true">3.4.</strong> Controlling HDL generation</a></li><li class="chapter-item expanded "><a href="developing-hardware/primitives.html" target="_parent"><strong aria-hidden="true">3.5.</strong> User-defined primitives</a></li><li class="chapter-item expanded "><a href="developing-hardware/limitations.html" target="_parent"><strong aria-hidden="true">3.6.</strong> Limitations of the compiler</a></li></ol></li><li class="chapter-item expanded "><a href="hacking-on-clash/index.html" target="_parent"><strong aria-hidden="true">4.</strong> Hacking on Clash</a></li></ol>
3131
</body>
3232
</html>

‎pr-10/compiler-user-guide/toc.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ class MDBookSidebarScrollbox extends HTMLElement {
88
super();
99
}
1010
connectedCallback() {
11-
this.innerHTML = '<ol class="chapter"><li class="chapter-item expanded affix "><a href="index.html">Clash User Guide</a></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.</strong> Getting Started</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="getting-started/installing.html"><strong aria-hidden="true">1.1.</strong> Installing</a></li></ol></li><li class="chapter-item expanded "><a href="general/index.html"><strong aria-hidden="true">2.</strong> General</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="general/relnotes.html"><strong aria-hidden="true">2.1.</strong> Release Notes</a></li><li class="chapter-item expanded "><a href="general/faqs.html"><strong aria-hidden="true">2.2.</strong> FAQs</a></li><li class="chapter-item expanded "><a href="general/license.html"><strong aria-hidden="true">2.3.</strong> License</a></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.</strong> Developing Hardware</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="developing-hardware/language.html"><strong aria-hidden="true">3.1.</strong> Language</a></li><li class="chapter-item expanded "><a href="developing-hardware/prelude.html"><strong aria-hidden="true">3.2.</strong> Prelude</a></li><li class="chapter-item expanded "><a href="developing-hardware/flags.html"><strong aria-hidden="true">3.3.</strong> Flags</a></li><li class="chapter-item expanded "><a href="developing-hardware/primitives.html"><strong aria-hidden="true">3.4.</strong> User-defined primitives</a></li><li class="chapter-item expanded "><a href="developing-hardware/limitations.html"><strong aria-hidden="true">3.5.</strong> Limitations of the compiler</a></li></ol></li><li class="chapter-item expanded "><a href="hacking-on-clash/index.html"><strong aria-hidden="true">4.</strong> Hacking on Clash</a></li></ol>';
11+
this.innerHTML = '<ol class="chapter"><li class="chapter-item expanded affix "><a href="index.html">Clash User Guide</a></li><li class="chapter-item expanded "><div><strong aria-hidden="true">1.</strong> Getting Started</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="getting-started/installing.html"><strong aria-hidden="true">1.1.</strong> Installing</a></li></ol></li><li class="chapter-item expanded "><a href="general/index.html"><strong aria-hidden="true">2.</strong> General</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="general/relnotes.html"><strong aria-hidden="true">2.1.</strong> Release Notes</a></li><li class="chapter-item expanded "><a href="general/faqs.html"><strong aria-hidden="true">2.2.</strong> FAQs</a></li><li class="chapter-item expanded "><a href="general/license.html"><strong aria-hidden="true">2.3.</strong> License</a></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.</strong> Developing Hardware</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="developing-hardware/language.html"><strong aria-hidden="true">3.1.</strong> Language</a></li><li class="chapter-item expanded "><a href="developing-hardware/prelude.html"><strong aria-hidden="true">3.2.</strong> Prelude</a></li><li class="chapter-item expanded "><a href="developing-hardware/flags.html"><strong aria-hidden="true">3.3.</strong> Flags</a></li><li class="chapter-item expanded "><a href="developing-hardware/annotations.html"><strong aria-hidden="true">3.4.</strong> Controlling HDL generation</a></li><li class="chapter-item expanded "><a href="developing-hardware/primitives.html"><strong aria-hidden="true">3.5.</strong> User-defined primitives</a></li><li class="chapter-item expanded "><a href="developing-hardware/limitations.html"><strong aria-hidden="true">3.6.</strong> Limitations of the compiler</a></li></ol></li><li class="chapter-item expanded "><a href="hacking-on-clash/index.html"><strong aria-hidden="true">4.</strong> Hacking on Clash</a></li></ol>';
1212
// Set the current, active page, and reveal it if it's hidden
1313
let current_page = document.location.href.toString().split("#")[0].split("?")[0];
1414
if (current_page.endsWith("/")) {

0 commit comments

Comments
 (0)