# The C++ YANC accepts `cppcomp`, YANC's C++ compiler, takes a large part of C and C++: classes, inheritance and virtual functions, templates, references, `new` and `delete`, recursion, function pointers, a few standard headers. It is for code written elsewhere (a filter, an estimator, a control loop) that should run on a SAPHO with few changes. What it costs is size and speed: the same algorithm written in C± (see [The C± language](language-cmm.md)) usually takes fewer instructions and cycles. ```cpp #pragma yanc nuioin 1 #pragma yanc nuioou 1 int fact(int n) { return n <= 1 ? 1 : n * fact(n - 1); } void main(void) { int n = in(0); out(0, fact(n)); } ``` `yanc fact.cpp` makes the processor `fact` (the file's name, which has to be a valid Verilog module name: see [The C± language](language-cmm.md)). The program is one source file, which can `#include` others. ## The program - `main` is required. `void main(void)` and `int main()` both work; the value `main` returns is discarded. - One source file per processor. Other files come in with `#include`, searched in the including file's folder, then in the folders given with `yanc -I `, then in the headers that come with YANC. - The processor is configured with `#pragma yanc` lines, the C++ form of the C± directives (see [Configuration](#configuration)). ## Input and output | call | does | |---|---| | `in(p)` | reads input port `p` (an integer literal) as an `int` | | `out(p, v)` | writes the integer `v` to output port `p` | | `toma(k, x)`, `cade(k)`, `fcade(k)` | pass a word over link `k` to another processor (see [Several processors](multiprocessor.md)), with the `_sync` forms for a partner on the same clock | A port carries an integer word. There is no `fin`/`fout` in C++: to read a float, read an int and scale it; to write one, cast it, `out(0, (int)x)`. `out` with a `float` writes the float's raw bits, not its value, and the compiler warns. With a keyboard and a screen beside the processor (`myKeyPS2` and `myVGAText`, see [Peripherals](peripherals.md)), a program reads and writes text as on a PC: ```cpp #include using namespace std; int main() { char nome[20]; int a, b; cout << "Nome? "; cin.getline(nome, 20); cout << "Oi, " << nome << '!' << endl; cout << "a b? "; cin >> a >> b; cout << a << " + " << b << " = " << a + b << endl; return 0; } ``` See [Text on the keyboard and the screen](#text-on-the-keyboard-and-the-screen). ## Types | type | in YANC | |---|---| | `int`, `short`, `long`, `char`, `signed`, `unsigned` | one word, 32 bits; `unsigned` compares and divides as unsigned | | `int8_t`, `uint8_t`, `int16_t`, `uint16_t` | stored in a word, wrapping at their width as on a PC | | `long long`, `int64_t`, `uint64_t` | one 32-bit word: the compiler warns that the 64 bits are ignored | | `bool` | a word holding 0 or 1 | | `float` | the SAPHO float, 23 mantissa and 8 exponent bits by default: the sizes of IEEE 754 single, **not** its encoding, no infinity, no NaN (see [Floating point](floating-point.md)) | | `double`, `long double` | the same 32-bit float, with a warning | | pointers, references | one word; a pointer counts in words, and `p + n` steps `n` elements of the type it points to | | arrays | up to 8 dimensions; `int t[N] "file.txt";` initialises one from a file, as in C± | | `enum`, `enum class` | the values are integer literals (`enum E { A = 1 }`); `= -1`, `= A + 1` and an underlying type (`enum class E : int`) are not accepted | | `struct`, `class`, `union`, bitfields | as in C++ | | `auto` | for a local with an initializer, and in a range-for | **Constant data in the data memory.** A string literal, and a global `const` array whose initializer is made of constants (`const int t[4] = {1, 2, 3};`, `const float k[] = {0.5f, -1.0f};`, `const char msg[] = "Oi";`), go straight into the data memory: no instruction stores them at the start of the program. Write a table that never changes as `const`: without it, a global array with an initializer is stored by code when `main` starts (3 instructions a word), because the data memory is loaded once, when the FPGA is configured, and a value the program changed would stay changed after a reset. An array of classes or of pointers is always stored by code. `sizeof` counts words, not bytes: `sizeof(int) == sizeof(char) == 1`. `const` objects cannot be assigned; `constexpr` is read as `const`, and a `const int` with a constant value can size an array or be a template argument. Every float operation rounds to the nearest (`#FROUND 2`): C++ always compiles at that level. ## Statements and expressions Everything C has: `if`, `switch` (with fall-through), `while`, `do`, `for`, `break`, `continue`, `goto`, `return`; compound assignment (`+=`, `<<=`, ...), `++`/`--`, `?:`, the comma, casts (C casts and `static_cast`, `reinterpret_cast`, `const_cast`, `dynamic_cast`, the last with no runtime check), `sizeof`, `static_assert`, designated initializers, compound literals. A range-for (`for (auto x : c)`) walks an array, or an object with `size()` and `operator[]` such as `std::vector` and `std::array`. A number starting with `0` is octal. A float used as a condition (`if (x)`, `!x`, `x && y`, `x ? a : b`) is true when it is not zero, as in C: the compiler tests its mantissa, because SAPHO's zero float is not an all-zero word. ## Functions - Overloading by the number and type of the parameters, and default arguments, for functions and methods. The overload is chosen as C++ ranks it: the same type first, then a promotion (`char` or `bool` to `int`), then a conversion (between integer types, integer and float, one pointer type to another). `char`, `bool`, `unsigned` and `int` are told apart (`f('A')` calls `f(char)`), `'A'` is a `char`, `true` a `bool`, and a reference parameter (`int&`) matches by the type it refers to. - **Recursion works**: a function that can reach itself gets a stack frame on a 1024-word call stack, built only when the program has one. Inside a recursive function a local cannot be an array or a struct; the compiler says so. Functions that do not recurse keep their locals at fixed addresses, as in C±. - Function pointers, including arrays of them, as parameters and as struct fields. - No variadic functions (`f(int n, ...)`). ## Classes - Data members, methods (inline or defined outside the class), access labels, static data members and static methods. - Constructors, overloaded, with member-init lists and default member initializers; copy constructors; destructors, run at the end of the scope and on `return`, `break` and `continue`. Every object is constructed: globals, locals, array elements, members, `new` and `new[]`. - **Single** inheritance (one base class), virtual functions, pure virtual functions, virtual destructors. - Operator overloading, as member functions only, of `+ - * / == != < > <= >= << >> = [] += -= *= /=` and unary `-` and `+`. Not `%`, `<<=`, `>>=`, the bitwise operators, `!`, `++`, `--`, `->`, `()`, conversion operators, and not as free functions. An operator that returns a reference to its object chains: `s << a << b` calls `operator<<` on what the first returned. - Templates of functions and of classes, with type parameters (`typename`/`class`) and `int` parameters, explicit `f(...)`. No specialization and no default template argument. - Namespaces, nested; a qualified name and `using namespace` work. No anonymous `namespace {`. A namespace only groups names: every name in it is also global, so `std::cout` and `cout` are one object, and a program that includes `` cannot name its own variable `hex` or `dec`. - A lambda only as an immediately-invoked global initializer with no captures and no parameters (`int k = []() { ... }();`). ## Dynamic memory `new`, `new[]`, `delete`, `delete[]`, and `malloc(nwords)` / `free(p)` (sizes in words). They share a heap of 2048 words, which the processor gets only when the program allocates; when it is full, the allocation returns 0. The heap's size is fixed. ## The standard headers | header | gives | |---|---| | `` | `fabs`, `sqrt`, `isfinite`, `isnan`, `isinf` (the last two always 0: there is no infinity or NaN) | | `` | `std::vector`: `size()`, `data()`, `operator[]`, `reserve`, `resize`, `push_back`; its storage is never freed, and there is no `erase`, `insert`, `clear` or iterator | | `` | `std::array`: `operator[]`, `data()`, `size()` | | `` | `strlen`, `strcmp`, `strncmp`, `strcpy`, `strncpy`, `strcat`, `strncat`, `strchr`, `strrchr`, `strstr`, as C's (a char is a word, a string ends with a 0); `memcpy`, `memmove`, `memset`, `memcmp`, `memchr`, `n` in words | | `` | `std::cout`, `std::cin` on the screen and the keyboard: [below](#text-on-the-keyboard-and-the-screen) | | `` | `putchar`, `puts`, `fputs`, `fputc`, `putc`, `getchar`, `fgetc`, `getc`, `fgets`, with `stdin`, `stdout`, `stderr`: [below](#text-on-the-keyboard-and-the-screen) | | ``, `` | the integer types, `size_t`, `ptrdiff_t` | | `` | `std::numeric_limits`, with `infinity()` = 1e30 | | `` | `std::bit_cast` | There is no ``, ``, `` or ``. A header the program includes but does not use costs nothing: the code nobody calls leaves the processor. ## Text on the keyboard and the screen `` and `` read the keyboard block `myKeyPS2` and write the screen block `myVGAText` ([Peripherals](peripherals.md)), over two links. By default the keyboard is on link 0 and the screen on link 1, both blocks on the processor's clock. A program changes that with `#define` before its first `#include`: | define | default | means | |---|---|---| | `YANC_STDIN_LINK` | 0 | the keyboard's link | | `YANC_STDOUT_LINK` | 1 | the screen's link | | `YANC_LINK_SYNC` | 1 | 1: the blocks on the processor's clock (`cade_sync`/`toma_sync`; the blocks may take `.LINK_SYNC(1)`); 0: on another clock (`cade`/`toma`; the blocks at their default, `LINK_SYNC` 0) | | `YANC_ECHO` | 1 | 1: what is typed shows on the screen | | `YANC_LINE_MAX` | 80 | the longest line read | **Writing.** `cout <<` takes `const char*`, `char`, `bool` (written as 1 or 0, as C++ does), `int`, `unsigned` and `float`, and `std::endl`, `std::flush`, `std::hex`, `std::dec`, `std::oct`. A float is written as C++ writes it by default, with 6 significant digits: `7.5`, `3.14159`, `1e+10`, `0.00015`. The SAPHO float carries about 7 decimal digits, so the sixth can be off by one. `cout.put(c)` and `cout.write(s, n)` also work. In C: `putchar(c)`, `puts(s)` (adds the new line), `fputs(s, stdout)`. **Reading.** As on a PC, nothing reaches the program before Enter: the characters typed show on the screen and Backspace takes the last one back. On a PC the terminal does that; here `std::cin` and `getchar` do. Then: | call | reads | |---|---| | `cin >> x` | `int`, `unsigned`, `float` (`2.5`, `-1e3`), `char` (the next one that is not blank) or `char*` (a word); blanks and new lines before it are skipped | | `cin.getline(s, n)` | the rest of the line, up to `n - 1` characters; the new line is taken and not stored | | `cin.get()`, `cin.peek()` | the next character, taken or left | | `cin.ignore(n, c)` | drops up to `n` characters, stopping after `c` | | `getchar()`, `fgets(s, n, stdin)` | as C's (`fgets` keeps the new line) | A number that is not there (a letter where `cin >> n` wants digits) sets `cin.fail()`, gives 0 and takes nothing; `cin.clear()` resets it. As on a PC, `cin >> n` leaves the Enter in the line, so a `getline` right after it reads an empty line: `cin.ignore(100, '\n')` between them. **What it costs.** Only what the program calls: a program that writes but never reads gets no keyboard link. Printing a number divides nothing (the processor gets no divider for it); printing or reading a float uses the float adder and multiplier. The line typed takes `YANC_LINE_MAX + 2` words of data memory. **Not yet** (GitHub issue #5): `printf` and `scanf` (they need variadic functions), `std::string` and `std::getline(cin, s)`, `setw`, `setprecision`, and `if (cin >> x)` or `!cin` (use `cin.fail()`). ## The preprocessor `#include "..."` and `<...>`, `#define` with or without arguments (variadic macros, `#` and `##`), `#undef`, `#if`/`#elif`/`#else`/`#endif` with `defined`, `#ifdef`/`#ifndef`, `#pragma once`, `#error` (stops) and `#warning`. A line cannot continue onto the next with a backslash, and there are no predefined macros (`__FILE__`, `__cplusplus`). `yanc -S` keeps the assembly; `cppcomp -E file.cpp` prints the preprocessed source. ## Configuration `#pragma yanc ` sets what the C± directives set (see [Directives](directives.md)): | setting | sets | default | |---|---|---| | `nubits` | the word width | 32 | | `nbmant`, `nbexpo` | the float's mantissa and exponent bits | 23 and 8 at 32 bits | | `nuioin`, `nuioou` | the number of input and output ports | 1 and 1 | | `nugain` | C±'s `norm()` divisor; C++ has no `norm()`, so it changes nothing | 128 | | `ndstac`, `sdepth` | the data and call stack depths | worked out from the program | An unknown setting gives a warning. `#pragma yanc prname` (the name is the file's), `fftsiz` and `itradd` (bit-reversed addressing and interrupts exist in C± only) are errors. ## What does not exist Exceptions (`try`, `catch`, `throw`), `typeid` and RTTI, `friend`, `decltype`, multiple inheritance, variadic functions, lambdas inside a function or with captures, template specialization and default template arguments, `std::string`, file streams, `printf`, `enum` values that are not plain literals, and more than one source file (use `#include`). Most of these stop the compiler with "syntax error" at the line. GitHub issue #43 keeps the list of the forms not accepted yet, and issue #31 the functions of C±'s library that C++ lacks (`fin`, `fout`, `sin` and the rest).