You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<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.
171
171
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.
172
172
There are perhaps 10 (at most) functions which are truly hard-coded into the Clash compiler.
173
-
You can take a look at the files in <ahref="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 <ahref="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 <ahref="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
174
-
as "regular" primitives.
173
+
You can take a look at the files in <ahref="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 <ahref="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 <ahref="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.
175
174
The compiler looks for primitives in four locations:</p>
<p>The <code>name</code> of the primitive is the <em>fully qualified</em> name of the function you are creating the primitive for.
214
213
Because we are creating an <em>expression</em> primitive the kind must be set to <code>Expression</code>.
215
-
As the name suggest, it is a VHDL /template/, meaning that the compiler must fill in the holes heralded by the tilde (~).
214
+
As the name suggest, it is a VHDL <em>template</em>, meaning that the compiler must fill in the holes heralded by the tilde (~).
216
215
Here:</p>
217
216
<ul>
218
-
<li><code>~ARG[1]</code> denotes the second argument given to the <code>(*#)</code> function, which corresponds to the LHS of the (<code>*</code>) operator.</li>
219
-
<li><code>~ARG[2]</code> denotes the third argument given to the <code>(*#)</code> function, which corresponds to the RHS of the (<code>*</code>) operator.</li>
220
-
<li><code>~LIT[0]</code> denotes the first argument given to the <code>(*#)</code> function, withthe extra condition that it must be a <code>LIT</code>eral.
217
+
<li><code>~ARG[1]</code> denotes the second argument given to the <code>(*#)</code> function, which corresponds to the LHS of the (<code>*</code>) operator.</li>
218
+
<li><code>~ARG[2]</code> denotes the third argument given to the <code>(*#)</code> function, which corresponds to the RHS of the (<code>*</code>) operator.</li>
219
+
<li><code>~LIT[0]</code> denotes the first argument given to the <code>(*#)</code> function, with the extra condition that it must be a <code>LIT</code>eral.
221
220
If for some reason this first argument does not turn out to be a literal then the compiler will raise an error.
222
221
This first arguments corresponds to the <code>KnownNat n</code> class constraint.</li>
Because we are creating a <em>declaration</em> primitive the <em>kind</em> must be set to <code>Declaration</code>.
348
347
Instead of discussing what the individual template holes mean in the above context, we will instead just give a general listing of the available template holes:</p>
349
348
<ul>
350
-
<li><code>~RESULT</code>: Signal to which the result of a primitive must be assigned
351
-
to. NB: Only used in a <em>declaration</em> primitive.</li>
349
+
<li><code>~RESULT</code>: Signal to which the result of a primitive must be assigned to.
350
+
NB: Only used in a <em>declaration</em> primitive.</li>
352
351
<li><code>~ARG[N]</code>: <code>(N+1)</code>'th argument to the function.</li>
353
-
<li><code>~CONST[N]</code>: <code>(N+1)</code>'th argument to the function. Like <code>~ARG</code>, but Clash will try to reduce this to a literal, even if it would otherwise consider it too expensive.
352
+
<li><code>~CONST[N]</code>: <code>(N+1)</code>'th argument to the function.
353
+
Like <code>~ARG</code>, but Clash will try to reduce this to a literal, even if it would otherwise consider it too expensive.
354
354
And if Clash fails to reduce this argument to a literal it will produce an error.</li>
355
-
<li><code>~LIT[N]</code>: <code>(N+1)</code>'th argument to the function. Like <code>~CONST~</code> but values are rendered as a bare literals, without any size or type annotations.
355
+
<li><code>~LIT[N]</code>: <code>(N+1)</code>'th argument to the function.
356
+
Like <code>~CONST</code> but values are rendered as a bare literals, without any size or type annotations.
356
357
This only works for numeric types, and not for BitVector.</li>
357
358
<li><code>~TYP[N]</code>: VHDL type of the <code>(N+1)</code>'th argument.</li>
358
359
<li><code>~TYPO</code>: VHDL type of the result.</li>
359
-
<li><code>~TYPM[N]</code>: VHDL type_name_ of the <code>(N+1)</code>'th argument; used in <em>type qualification</em>.</li>
360
-
<li><code>~TYPMO</code>: VHDL type_name_ of the result; used in <em>type qualification</em>.</li>
360
+
<li><code>~TYPM[N]</code>: VHDL type<em>name</em> of the <code>(N+1)</code>'th argument; used in <em>type qualification</em>.</li>
361
+
<li><code>~TYPMO</code>: VHDL type<em>name</em> of the result; used in <em>type qualification</em>.</li>
361
362
<li><code>~ERROR[N]</code>: Error value for the VHDL type of the <code>(N+1)</code>'th argument.</li>
362
363
<li><code>~ERRORO</code>: Error value for the VHDL type of the result.</li>
363
-
<li><code>~GENSYM[<NAME>][N]</code>: Create a unique name, trying to stay as close to
364
-
the given <code><NAME></code> as possible. This unique symbol can be referred to in
365
-
other places using <code>~SYM[N]</code>.</li>
364
+
<li><code>~GENSYM[<NAME>][N]</code>: Create a unique name, trying to stay as close to the given <code><NAME></code> as possible.
365
+
This unique symbol can be referred to in other places using <code>~SYM[N]</code>.</li>
366
366
<li><code>~SYM[N]</code>: a reference to the unique symbol created by <code>~GENSYM[<NAME>][N]</code>.</li>
367
-
<li><code>~SIGD[<HOLE>][N]</code>: Create a signal declaration, using <code><HOLE></code> as the name
368
-
of the signal, and the type of the <code>(N+1)</code>'th argument.</li>
369
-
<li><code>~SIGDO[<HOLE>]</code>: Create a signal declaration, using <code><HOLE></code> as the name
370
-
of the signal, and the type of the result.</li>
367
+
<li><code>~SIGD[<HOLE>][N]</code>: Create a signal declaration, using <code><HOLE></code> as the name of the signal, and the type of the <code>(N+1)</code>'th argument.</li>
368
+
<li><code>~SIGDO[<HOLE>]</code>: Create a signal declaration, using <code><HOLE></code> as the name of the signal, and the type of the result.</li>
371
369
<li><code>~TYPEL[<HOLE>]</code>: The element type of the vector type represented by <code><HOLE></code>.
372
370
The content of <code><HOLE></code> must either be: <code>~TYP[N]</code>, <code>~TYPO</code>, or <code>~TYPEL[<HOLE>]</code>.</li>
373
371
<li><code>~COMPNAME</code>: The name of the component in which the primitive is instantiated.</li>
The content of <code><HOLE></code> must either be: <code>~TYP[N]</code>, <code>~TYPO</code>, or <code>~TYPEL[<HOLE>]</code>.</li>
377
375
<li><code>~SIZE[<HOLE>]</code>: The number of bits needed to encode the type represented by <code><HOLE></code>.
378
376
The content of <code><HOLE></code> must either be: <code>~TYP[N]</code>, <code>~TYPO</code>, or <code>~TYPEL[<HOLE>]</code>.</li>
379
-
<li><code>~IF <CONDITION> ~THEN <THEN> ~ELSE <ELSE> ~FI</code>: renders the <code><ELSE></code>
380
-
part when <code><CONDITION></code> evaluates to <em>0</em>, and renders the <code><THEN></code> in all
381
-
other cases.
377
+
<li><code>~IF <CONDITION> ~THEN <THEN> ~ELSE <ELSE> ~FI</code>: renders the <code><ELSE></code> part when <code><CONDITION></code> evaluates to <em>0</em>, and renders the <code><THEN></code> in all other cases.
382
378
Valid <code><CONDITION></code>s are <code>~LENGTH[<HOLE>]</code>, <code>~SIZE[<HOLE>]</code>, <code>~CMPLE[<HOLE1>][<HOLE2>]</code>, <code>~DEPTH[<HOLE>]</code>, <code>~VIVADO</code>, <code>~IW64</code>, <code>~ISLIT[N]</code>, <code>~ISVAR[N]</code>, <code>~ISACTIVEENABLE[N]</code>, <code>~ISSYNC[N]</code>, and <code>~AND[<HOLE1>,<HOLE2>,..]</code>.</li>
383
-
<li><code>~VIVADO</code>: <em>1</em> when Clash compiler is invoked with the <code>-fclash-xilinx</code> or
384
-
<code>-fclash-vivado</code> flag.
379
+
<li><code>~VIVADO</code>: <em>1</em> when Clash compiler is invoked with the <code>-fclash-hdlsyn Vivado</code> (or <code>Xilinx</code> or <code>ISE</code>) flag.
385
380
To be used with in an <code>~IF .. ~THEN .. ~ELSE .. ~FI</code> statement.</li>
386
381
<li><code>~CMPLE[<HOLE1>][<HOLE2>]</code>: <em>1</em> when <code><HOLE1> <= <HOLE2></code>, otherwise <em>0</em></li>
387
382
<li><code>~IW64</code>: <em>1</em> when <code>Int</code>/<code>Word</code>/<code>Integer</code> types are represented with 64 bits in HDL.
In (System)Verilog only <code>Bit</code> and <code>Bool</code> are considered scalar.
402
397
In VHDL, in addition to those two, enumeration types and integers are considered scalar.</li>
403
398
<li><code>~TAG[N]</code>: Name of given domain.
404
-
Errors when called on an argument which is not a 'KnownDomain', 'Reset', or 'Clock'.</li>
399
+
Errors when called on an argument which is not a <code>KnownDomain</code>, <code>Reset</code>, or <code>Clock</code>.</li>
405
400
<li><code>~PERIOD[N]</code>: Clock period of given domain.
406
-
Errors when called on an argument which is not a 'Clock', 'Reset', 'KnownDomain' or 'KnownConf'.</li>
407
-
<li><code>~ISACTIVEENABLE[N]</code>: Is the <code>(N+1)</code>'th argument a an Enable line <strong>not</strong> set to a constant True.
408
-
Can be used instead of deprecated (and removed) template tag</li>
401
+
Errors when called on an argument which is not a <code>Clock</code>, <code>Reset</code>, <code>KnownDomain</code> or <code>KnownConf</code>.</li>
402
+
<li><code>~ISACTIVEENABLE[N]</code>: Is the <code>(N+1)</code>'th argument an Enable line <strong>not</strong> set to a constant True.</li>
409
403
<li><code>~ISSYNC[N]</code>: Does synthesis domain at the <code>(N+1)</code>'th argument have synchronous resets.
410
-
Errors when called on an argument which is not a 'Reset', 'Clock', 'Enable', 'KnownDomain' or 'KnownConf'.</li>
404
+
Errors when called on an argument which is not a <code>Reset</code>, <code>Clock</code>, <code>Enable</code>, <code>KnownDomain</code> or <code>KnownConf</code>.</li>
411
405
<li><code>~ISINITDEFINED[N]</code>: Does synthesis domain at the <code>(N+1)</code>'th argument have defined initial values.
412
-
Errors when called on an argument which is not a 'Clock', 'Reset', 'Enable', 'KnownDomain' or 'KnownConf'.</li>
413
-
<li><code>~ACTIVEEDGE[edge][N]</code>: Does synthesis domain at the <code>(N+1)</code>'th argument respond to
414
-
<em>edge</em>.
415
-
<em>edge</em> must be one of 'Falling' or 'Rising'.
416
-
Errors when called on an argument which is not a 'Clock', 'Reset', 'Enable', 'KnownDomain' or 'KnownConf'.</li>
406
+
Errors when called on an argument which is not a <code>Clock</code>, <code>Reset</code>, <code>Enable</code>, <code>KnownDomain</code> or <code>KnownConf</code>.</li>
407
+
<li><code>~ACTIVEEDGE[edge][N]</code>: Does synthesis domain at the <code>(N+1)</code>'th argument respond to <em>edge</em>.
408
+
<em>edge</em> must be one of <code>Falling</code> or <code>Rising</code>.
409
+
Errors when called on an argument which is not a <code>Clock</code>, <code>Reset</code>, <code>Enable</code>, <code>KnownDomain</code> or <code>KnownConf</code>.</li>
417
410
<li><code>~AND[<HOLE1>,<HOLE2>,..]</code>: Logically <em>and</em> the conditions in the <code><HOLE></code>'s</li>
418
411
<li><code>~VAR[<NAME>][N]</code>: Like <code>~ARG[N]</code> but binds the argument to a variable named NAME.
419
412
The <code><NAME></code> can be left blank, then Clash will come up with a (unique) name.</li>
0 commit comments