The C± language¶
C± (read “C plus-minus”) is the language YANC was built for: C cut down to what turns into hardware of a size known at compile time, plus a complex number type and a notation for vectors. If you know C you can read C± straight away; what needs learning is mostly what is missing, and why.
Every variable has a fixed address in the data memory: there is no heap, no
pointer, no recursion. That is what lets each variable show up by name in
the simulation waveform (one written and never read is left out, unless
#WAVE keeps it), and what lets the compiler build only the hardware
the program uses: a program that never divides gets a processor with no
divider.
A first program¶
#NUIOIN 1
#NUIOOU 1
int twice(int x)
{
return 2 * x;
}
void main()
{
while (1)
{
int a = in(0); // read input port 0
out(0, twice(a)); // write output port 0
}
}
yanc twice.cmm turns this file into the processor twice (the file’s
name), in the folder twice/. The file’s name becomes the name of a Verilog
module, so it has to be one: letters, digits and _, not starting with a
digit, and not a Verilog keyword (begin.cmm or my-prog.cmm are refused;
rename the file). The lines starting with # configure the
processor: here, one input port and one output port. The other settings have
defaults; see Directives.
Types¶
type |
what it is |
|---|---|
|
signed integer, |
|
the SAPHO floating point: |
|
a complex number: two floats, the real part and the imaginary part |
|
only as the return type of a function |
There is no char, double, unsigned, bool, struct, string or
pointer. int and float convert into each other on their own wherever
one is used for the other (an assignment, a function argument, a return, an
output), and the compiler prints a warning at each place; there is no cast.
Variables and arrays¶
int a, b;
int n = 0, k, m = n + 1; // any name of a list can be initialised
float gain = 0.5;
int v[128]; // an array
float M[4][4]; // two dimensions at most
float table[64] "table.txt"; // initialised from a file
A variable can be declared at the top of the file (global) or anywhere inside a function (local to it). Any name of a declaration list can have an initialiser, and a later name can read an earlier one, as in C. A local initialiser runs each time the function is called. A global initialiser runs once, before
main, wherever the file declares the global, between functions too, and it may call a function defined above it.The size of an array is a number (or a
#definename for one), at least 1; a matrix has fewer than 2^31 elements.An array is initialised between braces, as in C, or from a file:
int v[5] = {3, -2, 7}; // v[3] and v[4] are 0 float g[3] = {1.5, -0.25, 4}; comp z[2] = {1.5-2i, 3}; int m[2][3] = {{1, 2}, {4, 5, 6}}; // or the six values without inner braces int t[256] "tabela.txt"; // one value per line, beside the source
Between braces go constants (a minus sign in front is fine): only integers in an
intarray, integers and floats in afloatone, any of the three in acompone. Positions left out are zero; more values than positions is an error. In a 2D array, inner braces mark the rows: every row in braces or none. The file holds one value per line (int,float, orre+imiforcomp, as1.5-2i); fewer lines than the size is an error, more lines are ignored with a warning.Either way the values go straight into the data memory: no instruction stores them, so they cost nothing at run time. They are loaded once, with the memory, when the FPGA is configured: a local array keeps, from one call of its function to the next, what the function wrote into it (like a C
static; the compiler warns), and a reset does not bring the values back.v[k]reads or writes an element;M[r][c]an element of a matrix. A constant index past the end is an error (each index of a matrix on its own); a computed one is not checked, as in C.v[k)(a closing parenthesis) reads or writes the element at the bit-reversed index, the addressing an FFT needs (its width set by#FFTSIZ).An array cannot be a function parameter; share it as a global.
Operators¶
family |
operators |
notes |
|---|---|---|
arithmetic |
|
|
comparison |
|
1 or 0; with a |
logical |
|
1 or 0; on ints and floats (not |
bitwise |
|
ints |
shifts |
|
|
increment |
|
also inside an expression |
The precedence is C’s. There is no --, no compound assignment (+=,
-=, …), no ?:, no sizeof. A shift costs almost nothing in hardware,
a division a divider and five clock cycles (four for a float division):
x >> 2 instead of x / 4 when x is not negative.
A float or comp divided by a literal is multiplied by the literal’s
reciprocal instead, one instruction and no divider, when the result is the
same: the literal is a power of two (x / 4.0 is x * 0.25). Any other
literal (x / 3.0) is multiplied by its rounded reciprocal only when nothing
else in the program divides floats, so that the float divider stays out of
the processor; the result can then differ from the division in the last bit
(2.5 / 1.25 gives 1.9999999, which an fout truncates to 1). When the
program divides floats elsewhere, the divider is there anyway, and every
division by a literal stays a division.
Control flow¶
if / else, while, do … while, for, switch / case /
default, break, continue, return, as in C. There is no goto.
for (init; condition; step):initis an assignment or a declaration with a value (int k = 0),stepan assignment ork++; either can be empty. One clause each, no commas.casetakes a constant number. Acasewithoutbreakfalls through to the next, as in C. As in C, a value appears in onecaseof aswitchonly, and aswitchhas onedefaultat most.breakleaves the innermost loop orswitch;continuegoes to the next turn of the innermost loop.The empty statement
;and the empty block{ }emit nothing, so a waiting loop is written as in C:while (in(1)) ;.A condition (
if,while,for,do, and the operands of!,&&,||) is true when its value is not zero, as in C, also for a float:if (0.5)is true andif (0.0)false. The compiler tests the float’s mantissa (AND 2^NBMANT - 1, one instruction), with no conversion to int. Acompcondition is true when its real or its imaginary part is not zero (C99). Aswitchindex, by contrast, is converted to int, truncating.
Functions¶
float mean(float a, float b)
{
return (a + b) * 0.5;
}
main()is required; the program starts there.return;inmainends the program: the processor stays at the end ofmain, where the testbench stops. In a program with a#PRACAit stays where thereturn;is, waiting foritr(Directives).A function is defined above its first call: there are no prototypes, and the whole program is one
.cmmfile.Parameters, as many as needed, are passed by value; they can be
int,floatorcomp, never an array. The return type isint,float,comporvoid.A function that is not
voidreturns on every path: the compiler stops when a path can reach the end of the body, which would run on into the next function. A path ends in a return when its last statement is areturn, anif/elsewhose two sides end in one, awhile (1)left only by areturn, or aswitchwith adefaultand nobreakwhose last statement does.No recursion. The locals of a function have fixed addresses, so a call to itself would overwrite them; the compiler stops with an error. C++ (see The C++ YANC accepts) allows recursion.
Input and output¶
The processor talks to the outside through numbered ports, as many as
#NUIOIN (inputs) and #NUIOOU (outputs) say. The port number is a
literal, not a variable.
int a = in(0); // read port 0 as an int
float g = fin(1); // read port 1 and convert it to float
out(0, a + 1); // write an int to port 0
fout(1, g * 2.0); // convert a float to int and write it to port 1
A port always carries an integer word. fin converts the word it reads to
float; fout converts a float to an integer (truncating) before writing.
out with a float, or fout with an int, still works, with a warning.
In simulation, input port N reads its values from input_N.txt beside the
source, one per line, and output port N writes output_N.txt in the output
folder.
Complex numbers¶
comp z = 3 + 4i;
comp w = complex(1.0, -2.0);
comp p = z * w;
float r = real(p);
float m = abs(z); // |z| = 5
+ - * / work on comp. == and != too, as in C: two complex numbers
are equal when their real parts are equal and their imaginary parts are
equal, and a real is the comp with a zero imaginary part (3+0i == 3).
They have no order: <, >, <= and >= with a comp are an error;
compare abs(z), mod2(z), real(z) or imag(z). real(z), imag(z), conj(z), abs(z),
mod2(z) (|z|²) and fase(z) (the angle) take one apart, and sqrt,
exp, log, sin, cos, tan, atan accept a comp. A comp does not
go to an output port as such: write real(z) and imag(z).
Library¶
The functions that cost little map almost one to one onto instructions:
abs(x), pset(x) (0 if negative), sign(x, y) (y with the sign of
x), norm(x) (x divided by #NUGAIN, a power of two, without a
divider) and copy(x, y) (copies the bits of x into the variable y
with no conversion). The mathematical ones become routines of many
instructions: sqrt, exp, log, pow, sin, cos, tan, atan,
sinh, cosh, tanh, floor, ceil, round. See
The library.
Several processors¶
toma(k, x) hands x to the processor at the other end of link k;
cade(k) and fcade(k) take a word from it. See
Several processors.
The preprocessor¶
#define NAME text replaces the name by the text from there on:
#define N 64; with no text, the name is replaced by nothing. It takes
no arguments, and a program may have any number of them. There is no
#include and no #if.
What does not exist¶
Pointers, struct, strings and characters ('a' is an error),
recursion, dynamic memory, #include, several
source files, arrays of more than two dimensions, arrays as parameters,
goto, --, compound assignment, ?:, casts. Most of them are in the C++
YANC accepts, at a cost in instructions; C± keeps the processor small.
Comments, names and literals¶
Comments:
// to the end of the lineand/* across lines */.Names: letters, digits and
_, not starting with a digit, at most 1000 characters. The limit leaves room for the names the compiler builds from yours, about twice as long, in the Verilog and the waveform (GitHub issue #66). Names starting with__belong to the compiler. A name may not be spelt like an instruction of the processor once the compiler has prefixed it (a localxof the functionfbecomesf_xin the assembly): the compiler says so, and which two names collide.iis reserved for the imaginary unit:int i;is an error. Usek,n,idx.Integer literals, in every form C writes them:
42,0x2A,052(octal: a leading 0 makes it octal, as in C, so010is 8),0b101010, and theu,U,l,Lsuffixes (they change nothing: there is one int). A negative number is the unary minus applied to it:-42. A decimal literal must fit the#NUBITSword: at 8 bits the largest is 127, and200is an error (arithmetic past the word wraps, as the hardware does:100 + 100is -56). The one exception is the most negative int:-128at 8 bits (-2147483648at 32) is accepted, so 128 may follow a unary minus, buta - 128is still an error. An array size, a port and a directive are no values of the word and take any literal:int v[200];at 8 bits compiles, with a warning that an int index reaches only 127. A hexadecimal, octal or binary literal is a bit pattern of the#NUBITSword, as in C: with the sign bit set it is negative, so0xFFFFFFFFis -1 and0x80000000the most negative int at 32 bits (0xFFand0x80at 8). Such a literal is accepted in expressions and in lists between braces; an array size, a port or acasetakes a positive one.Float literals, in every form C writes them:
3.14,0.5,.5,2.,1e-5,2.5E+3,007.5, and with a suffix1.5f(f,F,l,L; the suffix changes nothing, there is one float). Each one is encoded exactly to the nearest value of the format, ties to even.Imaginary literals: a number followed by
i,2i,0.5i,1e-8i. A complex number is a sum, as in C99:3 + 4i,-1.5 - 2i,1e-8 + 2e-8i,2i, and with the precedence of any sum, soy*3 + 2iis(y*3) + 2i. A real literal and an imaginary one make one constant, and a real expression and an imaginary literal arecomplex(x, b): no instruction adds the zero real part. From two variables, usecomplex(re, im).