cir2c translates C and C++ programs into verifier-friendly C. Formal verification tools that read only C can then examine C++ programs. They can also examine C programs that their own front ends do not process correctly.
C or C++ source --clang -emit-cir--> CIR --cir2c--> verifier-friendly C
CIR is the ClangIR dialect of MLIR. Clang makes the CIR from the source code.
Note: The entry that follows is a placeholder. We'll soon replace it when the publication is available.
@misc{cir2c,
author = {Bajczi, Levente and {\'A}d{\'a}m, Zs{\'o}fia},
title = {{cir2c}: A {ClangIR}-based Translator from {C}/{C++}
to Verifier-Friendly {C}},
year = {2026},
howpublished = {\url{https://github.com/ftsrg/cir2c}}
}Give also the version that you used. The cir2c --version command prints the
commit. Each release contains the llvm-version.txt file, which gives the LLVM
revision.
- Cite this work
- 1. Description
- 2. Get the binaries
- 3. Requirements
- 4. Build
- 5. Operation
- 6. The LLVM toolchain
- 7. Design
- 8. Limits
- 9. Tests
- 10. Contribute
- 11. License
cir2c uses CIR as its input. CIR keeps the structure that a verification tool must have. It keeps loops, records, scopes, exception regions and virtual dispatch. At the same time, Clang removes the C++ constructions that a C tool cannot read. Clang removes templates, overloads, constructors, destructors, RAII and name mangling.
LLVM IR is not sufficient for this task. LLVM IR removes too much. Loops become branches, and records become byte offsets.
WARNING: The output is a model of the input program. The output is not an equivalent program. Some parts of C++ have no equivalent in C. In these parts, cir2c makes an approximation. Read 8. Limits before you accept a result from a verification tool.
The output is C code with a small set of verifier intrinsics. cir2c declares all of these intrinsics in the output file.
| Construction | Form in the output |
|---|---|
| Unknown value | __VERIFIER_nondet_<type>(), __VERIFIER_nondet_memory(p, n) |
| Virtual dispatch | __VERIFIER_virtual_call_<sig>(obj, slot, first, …) with a vtable |
throw, try, catch |
The __cir_exc_* global variables and a comparison of the RTTI tag |
| Static initialization | Calls to the global constructors at the start of main |
| C++ names | Demangled and made safe: ns::f(int) becomes ns__f_int |
cir2c writes a comment in the output file for each approximation that it makes.
Each push to the main branch makes a release. The release contains static
binaries: cir2c, clang, clang++ and cir-opt. The binaries need only
libc. You do not have to build or install LLVM.
gh release download --repo ftsrg/cir2c --pattern 'cir2c-*.zip'
unzip cir2c-*.zip # Makes the cir2c-<commit>/ directory
cd cir2c-*/Each archive unpacks into a directory with the name of the release. Thus you can keep more than one release at the same time.
The archive contains these items:
| Item | Contents |
|---|---|
cir2c, clang, clang++, cir-opt |
The static binaries |
include/ |
The Clang resource headers |
libcxx/ |
The libc++ headers and the static libraries |
llvm-version.txt |
The LLVM revision of the build |
LICENSE, LICENSE.LLVM |
The licenses |
To translate a C++ program with these binaries, do the steps that follow:
./clang++ -std=c++23 -stdlib=libc++ -nostdinc++ -isystem ./libcxx/include/c++/v1 \
-S -emit-cir hello.cpp -o hello.mlir
./cir2c hello.mlir hello.cIf you have a source checkout, use the run-cir2c.sh script. The script does
all the steps and sets these flags for you. Refer to
5. Operation.
To build cir2c, you must have these items:
| Item | Version |
|---|---|
| CMake | 3.20 or later |
| A C++ compiler | C++17 or later |
| Ninja or Make | Any |
| Git | Any |
| An LLVM with ClangIR | 24.0 or later |
CAUTION: A standard LLVM package is not sufficient. The LLVM build must
have the -DCLANG_ENABLE_CIR=ON option. Without this option, there is no
clang -emit-cir command, no cir-opt command and no CIR dialect.
To build the LLVM toolchain, you must also have these items:
cmake,ninjaandgitclangandlld(a GCC host compiler operates, but it is slower)- A static zlib: the
libz.afile and thezlib.hfile (on Debian and Ubuntu, install thezlib1g-devpackage) - 50 GB of free disk space and 16 GB of memory
To run the tests, you must also have bash, GNU parallel and python3.
There are three methods. Select a method from the table.
| Method | Time | Select this method when |
|---|---|---|
| A. Use the toolchain image | Minutes | You have Docker |
| B. Build the toolchain | 1 to 4 hours | You do not have Docker |
| C. Use your own LLVM | Minutes | You have a ClangIR build |
The ghcr.io/ftsrg/cir2c-llvm image contains the pinned LLVM. The image
installs LLVM in the /opt/cir directory. The image also contains libc++,
libc++abi and libunwind.
docker run --rm -it -v "$PWD:/src" -w /src ghcr.io/ftsrg/cir2c-llvm:latest bash
# In the container. CMake finds /opt/cir automatically.
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failureIf you did not use this registry before, first do the docker login ghcr.io
command.
The docker/build-llvm.sh script builds LLVM, Clang and MLIR with ClangIR. The
script then builds libc++, libc++abi and libunwind. The script makes static
libraries and installs all of them in one prefix.
./docker/build-llvm.sh --prefix ./llvm-install
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build buildCMake finds the ./llvm-install directory automatically.
| Option | Function |
|---|---|
--prefix DIR |
The install prefix. The default is /opt/cir. |
--src DIR |
The llvm-project checkout. The default is ./llvm-project. The script clones it if it is not there. |
--ref REF |
The revision to build. The default is the contents of llvm-version.txt. |
--jobs N |
The number of parallel jobs. The default is nproc. |
--clean |
Delete the large build directories at the end. |
Note: The script also builds libc++. Clang compiles C++ input with libc++
and not with libstdc++. libstdc++ keeps some container functions in compiled
.cc files. ClangIR sees only a declaration for these functions. libc++ keeps
list, map, set and deque fully in the headers. Refer to
8.2 The standard library.
Give CMake the prefix of your LLVM installation:
cmake -B build -DCIR2C_LLVM_PREFIX=/path/to/llvm-installIf the directory layout is different, give CMake the two package directories:
cmake -B build \
-DLLVM_DIR=/path/to/lib/cmake/llvm \
-DMLIR_DIR=/path/to/lib/cmake/mlirThe scripts read the same prefix from the environment:
export CIR2C_LLVM_PREFIX=/path/to/llvm-install
./run-cir2c.sh input.cpp output.cIf you set no variable, CMake examines these locations in this sequence:
./llvm-install, then /opt/cir, then the system search path.
| Option | Default | Function |
|---|---|---|
CIR2C_LLVM_PREFIX |
Found automatically | The prefix of the ClangIR toolchain |
LLVM_DIR, MLIR_DIR |
Made from the prefix | The CMake package directories |
CMAKE_BUILD_TYPE |
Empty | Use Release for all work except debug work |
CMake writes the binary to build/cir2c. The cmake --install build command
copies the binary to <prefix>/bin.
build/cir2c --version # Prints the Git commit of the build
ctest --test-dir build --output-on-failurectest runs the integration tests. Refer to 9. Tests.
./scripts/build-static-binaries.sh # Writes to the ./output directoryThe script compiles cir2c on the toolchain image and exports the binaries. The script does not build LLVM again. Thus the script is quick.
If your user account is not in the docker group, set DOCKER='sudo docker'.
| Message | Cause and correction |
|---|---|
Could NOT find MLIR or Could NOT find LLVM |
CMake found no toolchain. Give the -DCIR2C_LLVM_PREFIX=… option, or use method B. |
This LLVM install has no ClangIR headers |
The LLVM build did not have the -DCLANG_ENABLE_CIR=ON option. |
cir2c needs LLVM >= 24.0 |
The LLVM is too old. Refer to 6. The LLVM toolchain. |
libMLIRCIR not found |
The prefix has the headers but not the library. Without the library, all cir.* operations fail to parse. Make sure that the LLVM build completed and installed. |
no ClangIR-enabled clang found |
The scripts do their own search. Set CIR2C_LLVM_PREFIX. Set also CIR2C_BIN or CIR2C_BUILD_DIR if the binary is not at build/cir2c. |
Note: A shared-library LLVM is not tested. cir2c links the CIR dialect by
absolute path. For a static build, cir2c gives the full library directory to the
linker in one --start-group list. The pinned toolchain is fully static.
The run-cir2c.sh script is the recommended interface. The script does all three
steps: clang -emit-cir, then preprocessing, then cir2c.
./run-cir2c.sh input.c output.c # A C program
./run-cir2c.sh input.cpp output.c # A C++ programThe script makes the output directory if it is not there.
The script gives these options to clang, in addition to the options of the
table below. Each option changes the CIR, so record them with a result.
| Option | Input | Function |
|---|---|---|
-fmacro-prefix-map=<dir>/= |
C and C++ | Removes the directory from __FILE__. The script gives one option for the directory of the input file, one for models/, and one for the libc++ headers. Thus the message of an assertion contains main.cpp, not /home/user/tasks/main.cpp, and the output does not change with the directory of the translation. |
-stdlib=libc++ -nostdinc++ -isystem <libc++> |
C++ | Uses the libc++ headers of the toolchain (see 8.2). |
-fno-threadsafe-statics |
C++ | A plain flag guards the initialization of a static local variable, for example static int v = f();. Without this option, clang calls __cxa_guard_acquire and __cxa_guard_release of the C++ runtime, which lock the variable against other threads. The output does not contain these functions. For a program with one thread, the two forms have the same behavior: the initializer runs once, and when it throws, the next call runs it again. |
-I, -include of the models |
C++, --no-externalize-std |
See 8.2. |
Programs with threads. The output of a C++ program has one thread. The
-fno-threadsafe-statics option and the exception state of
7.5 (plain global variables) are not
correct for more than one thread. Thus cir2c stops with an error when the output
of a C++ program calls pthread_create or thrd_create. std::thread and
std::async start their threads with pthread_create. With the
--no-externalize-std option, <thread> does not compile with the models (see
8.2). cir2c does not stop for a C program with
threads: C has no exceptions, and the script gives -fno-threadsafe-statics
only for C++.
run-cir2c.sh [OPTIONS] <input-file> <output.c>
run-cir2c.sh [OPTIONS] --merge c|cir <input1> <input2> [...] <output.c>
Give the options before the input files. With more than one input file, the script merges the translation units into one C program. See 5.6 Merge translation units.
| Option | Function |
|---|---|
--lang c|c++ |
Set the input language. The default comes from the file extension. The .cpp, .cxx, .cc and .C extensions are C++. |
--std STD |
Set the language standard. The default is c23 for C and c++23 for C++. |
--mlir FILE |
Write the intermediate CIR to FILE. Use this option to find problems. |
--include DIR |
Add the -I DIR option to the CIR step. You can give this option more than one time. |
--cflag FLAG |
Add FLAG to the CIR step, for example -DNAME=VALUE. You can give this option more than one time. The script adds no such flag itself. |
--no-call-conv-lowering |
Skip the ClangIR calling-convention lowering, for types that it cannot lower yet. CAUTION: this is not sound. An object with a move constructor is then passed as a bitwise copy, so the caller never sees it moved from and destroys it. Use it for all translation units of a program or for none. |
--merge c|cir |
Set how more than one input file is merged. c (the default) merges the C outputs. cir merges the CIR modules with cir-merge. Use cir: c can drop a definition or keep the wrong one of two different definitions, without an error (issue #20, see 5.6). |
--externalize-std |
Replace the std:: calls and the library calls with unknown values. This is the default. |
--tu-part |
The output is one translation unit of several, to be linked: internal symbols are static, symbols that each unit may define are weak, functions have their symbol names, and global constructors have __attribute__((constructor)). See 5.6. |
--no-externalize-std |
Keep the bodies of the std:: functions. For C++ input, the script also compiles the models of 8.2 with the program. CAUTION: Read 8.2 The standard library first. |
| Exit code | Meaning |
|---|---|
| 0 | The operation is successful. |
| 1 | The arguments are not correct, or the script cannot find the toolchain or a model. |
| 2 | clang failed. The source has an error, or ClangIR cannot process a construction. |
| 3 | cir-opt failed during the calling-convention lowering of --merge cir. |
| 4 | cir2c failed. Usually the CIR contains an unsupported operation. |
| 5 | cir-merge rejected the translation units (--merge cir only). Its messages give the symbol and the reason. |
Exit code 2 is important. It shows that Clang made no CIR. This is a limit of ClangIR and not a limit of cir2c.
By default, cir2c reads structured CIR. The cir.for, cir.while, cir.if,
cir.scope and cir.try operations are still regions. The output C code has
for, while and if statements and correct scopes. Use this default. A
verification tool examines structured control flow more efficiently. The output
is also easier to read.
The cir2c binary can also read flat CIR, in which cir-opt -cir-flatten-cfg
changed these operations into basic blocks and branches. run-cir2c.sh does not
offer this step: in the flat output, a caught exception ends in abort()
(issue #21). For a verification task, that is unsound: the program stops at a
point where the real program continues.
The scripts examine these locations for clang, clang++ and cir-opt, in
this sequence:
- The
$CIR2C_LLVM_PREFIXdirectory - The
<repository>/llvm-installdirectory - The
/opt/cirdirectory - The
PATHvariable
The scripts examine these locations for the cir2c binary:
- The
$CIR2C_BINfile - The
${CIR2C_BUILD_DIR:-<repository>/build}/cir2cfile
If the scripts find no tool, they print the locations that they examined.
If you have a CIR module, you can start the binary directly. You must then make the CIR and preprocess it yourself.
cir2c [--monitor-json <trace.json>] [--[no-]externalize-std] <input.mlir> <output.c>
cir2c --version
| Argument | Function |
|---|---|
<input.mlir> |
A CIR module from clang -S -emit-cir, with an optional cir-opt -cir-flatten-cfg step |
<output.c> |
The path of the output C file |
--version |
Print the Git commit of the build and stop |
--monitor-json FILE |
Write a JSON trace. The trace maps each CIR operation to the C lines that it made. |
--[no-]externalize-std |
The same function as in the script. The default is --externalize-std. |
| Exit code | Meaning |
|---|---|
| 0 | The operation is successful. |
| 2 | The arguments are not correct. |
| 3 | cir2c cannot open the input file. |
| 4 | The MLIR did not parse. |
| 5 | cir2c cannot open the output file. |
| 6 | The translation failed. |
The --monitor-json option records the operation text, the C code and the line
numbers on the two sides. Use this trace to build tools that show a source
construction and its translation together. Use it also to examine a result from
a verification tool. cir2c calculates the line map only when you give this
option, because the calculation is slow.
- Keep the intermediate CIR:
./run-cir2c.sh --mlir /tmp/case.mlir case.cpp /tmp/case.c
- If the exit code is 2, the problem is in Clang. Clang made no CIR for that source. Read the Clang messages.
- If the exit code is 4, the CIR is in
/tmp/case.mlir. cir2c prints the name of the operation that it cannot translate. Find that name in the.mlirfile. The handlers are in thesrc/handlers/directory. - If cir2c made C code but the code is not correct, start the binary again on
the
.mlirfile. This removes Clang andcir-optfrom the sequence and makes the work cycle quick.
A program can have more than one source file. run-cir2c.sh accepts more than
one input file and makes one C file. There are two merge strategies:
| Strategy | Sequence |
|---|---|
--merge c |
Not reliable (issue #20): scripts/merge-c.sh finds the definitions by text patterns and keeps the first definition of each name. It can drop a definition, or keep one of two different definitions for both files, without an error. Translate each file to C, then merge the C files with scripts/merge-c.sh. For C++ input, this is not possible with --no-externalize-std: the definition check of 8.2 needs the whole program, and each file alone uses the symbols of the other files. The script stops with exit code 1. |
--merge cir |
Compile each file to CIR without the calling-convention lowering, merge the CIR modules with cir-merge, lower the merged module once, then translate it. |
To keep the translation units apart, translate each file with --tu-part. Its
output keeps the C linkage of the symbols. Link the files with a C linker, or give
them all to a verifier that can link, such as Theta with a .yml file that lists
them as input_files.
cir-merge is a C++ program in tools/cir-merge/. The build makes it next to
the cir2c binary. It uses the MLIR parser, the MLIR verifier and the MLIR
printer of the same LLVM build as cir2c. It does not parse CIR text itself.
cir-merge --output merged.cir input-a.cir input-b.cir [...]
| Option | Function |
|---|---|
--output FILE, -o FILE |
Write the merged module to FILE. |
--dump-symbols |
Print the symbol inventory (input, kind, definition or declaration, linkage, name). |
--verbose |
Print the decision for each symbol. |
cir-merge is conservative. If an input is outside the supported subset,
cir-merge stops with an error. It does not make an approximate module. A
merged module is a module that passes these checks. It is not a proof that the
C++ program obeys the One Definition Rule.
The steps are:
- Parse and verify each input in a separate MLIR context. Record the definition of each record (struct, class, union).
- Give the anonymous records their names in the merged module, and compare the named record definitions of all inputs.
- Parse all inputs into one context.
- Rename the translation-unit-local symbols whose names collide (see below).
- Check the module attributes.
- Make the symbol inventory of all inputs.
- Make the merge plan for all symbols. The plan is complete before any change, so the result does not depend on the order of the inputs.
- Make the merged module. Verify it, check that each symbol reference resolves, print it, and parse the printed text again.
- Write the output to a temporary file, then rename it. A failed merge does not leave an output file.
Only cir.func and cir.global operations can be at the top level. Another
top-level operation is an error, because its meaning across translation units
is not known.
| Symbols with the same name | Result |
|---|---|
| The symbol is in one input only | Keep it |
| Compatible declarations only | Keep the first declaration with a complete type |
| Compatible declarations and one definition | Keep the definition |
Two or more equivalent definitions with linkonce_odr, weak_odr or available_externally linkage |
Keep one (see below) |
C tentative definitions with common linkage (-fcommon), and at most one regular definition |
Keep the regular definition, else one common definition |
| Two or more definitions with another linkage, or ODR definitions that differ | Error |
A declaration with a less complete type: extern T a[]; against T a[N], or a C declaration without a prototype (int f();) against a prototype with the same return type |
Adapt the declaration's uses (see below) |
| A function and a global | Error |
| Different function types, no-prototype flags or calling conventions | Error |
| Globals with different types, constness, TLS models or address spaces | Error |
| A symbol with internal or private linkage | Renamed before the merge (see below), so it does not collide |
A definition that is not external, common, linkonce_odr, weak_odr or available_externally, or a declaration that is not external |
Error |
A function is a definition when it has a body or is an alias (alias(@...)).
A global is a definition when it has an initial value, a constructor region, a
destructor region or an alias.
The attribute policy. When a symbol is in more than one input,
cir-merge keeps one operation and drops the others with their attributes.
Each attribute that a dropped operation can have is in one class. An attribute
that is in no class is an error.
| Class | Function attributes | Global attributes | Rule |
|---|---|---|---|
| Checked | sym_name, function_type, no_proto, calling_conv, linkage |
sym_name, sym_type, constant, tls_model, addr_space, linkage, initial_value |
Compared by the rules above |
| From the kept operation | sym_visibility, global_visibility, comdat, dso_local, arg_attrs, res_attrs, inline_kind, builtin, lambda, personality, side_effect, aliasee, cir.target-cpu, cir.target-features, cir.tune-cpu, nothrow, nobuiltin, noreturn, nocallback, allocsize |
sym_visibility, global_visibility, comdat, dso_local, ast, tls_refs, static_local_info, static_local_guard, aliasee, init_priority |
The value of the dropped operation is not necessary. These are properties of the definition, or hints for code generation that the call sites of the dropped declaration already contain. |
| Equal | func_info, coroutine, global_ctor_priority, global_dtor_priority, annotations |
annotations, strictfp |
Must have the same value on the kept operation |
| Alignment | alignment |
The kept symbol must be aligned at least as much as the dropped declaration says | |
| Section | section |
The kept symbol must be in the section that the dropped declaration gives |
The module attributes:
| Attribute | Rule |
|---|---|
cir.triple, dlti.dl_spec, cir.lang, cir.int_type_width, cir.size_type_width, cir.default_tls_model |
Must be equal in all inputs. Different targets, ABIs or languages are an error. |
cir.module_asm |
Must be empty. |
cir.record_layouts |
Merged. A record in more than one input must have the same layout. |
cir.global_ctors, cir.global_dtors |
Concatenated in input order. Each entry must name a function of the merged module. |
| Another attribute | Error |
The translation-unit-local symbols. A symbol with internal or private
linkage belongs to its translation unit: a static function or variable, a
string literal (.str, .str.1, ...), a C++ static initializer
(__cxx_global_var_init), a guard variable or a thread_local helper. If
another input uses the same name, cir-merge gives the local symbol the new
name NAME.tuN. N is the position of the input on the command line. If that
name is in use, cir-merge adds .1, .2, ... An input uses a name when it
defines or declares the symbol, or refers to it by a string (see below).
cir-merge then changes all references to the symbol in its input. MLIR
changes the symbol references (@name), also inside other attributes such as
#cir.global_view. CIR also refers to symbols with plain strings, which MLIR
does not see. cir-merge changes these too:
| String reference | Where |
|---|---|
#cir.global_ctor<"fn", priority>, #cir.global_dtor<...> |
The cir.global_ctors and cir.global_dtors module attributes |
static_local_guard<"guard"> |
A cir.global of a function-local static |
tls_refs = <"wrapper", "init"> |
A thread_local cir.global |
After the merge, cir-merge checks that each of these names a symbol of the
correct kind. Only the thread_local initializer can be absent: clang refers
to the initializer of an extern thread_local variable weakly. The CUDA
attributes also name kernels with strings. cir-merge does not change them,
so it rejects an input that has one.
The declarations with a less complete type. An input that declares
extern int a[]; or int f(); refers to the symbol only with
cir.get_global and with #cir.global_view initializers. cir-merge gives
each cir.get_global of the declaration the type of the kept symbol and adds a
bitcast to the type that the input expects. The C compiler and the linker do
the same. The #cir.global_view initializers do not change. Another use of
such a declaration is an error.
Two tentative definitions (int x; in two files) are an error without
-fcommon, as they are for the linker. With -fcommon, clang gives them
common linkage, and cir-merge merges them.
The ODR definitions. In C++, each translation unit that uses an inline
function, a template instance, a vtable or a typeinfo object emits its own
definition, with linkonce_odr linkage (weak_odr for an explicit
instantiation, available_externally for an extern template such as the
members of std::string). The One Definition Rule says that all of them are
the same, and the linker keeps one. cir-merge keeps one only if it can see
that they are the same:
- The definitions must be equal, operation by operation. The source locations,
the linkage, the COMDAT flag and the
dso_localflag do not count. - A reference to a translation-unit-local symbol matches a reference to a local
symbol of the other input if the two local symbols are equivalent in turn.
Thus an inline function that returns
"hello"matches in two translation units, also if the literal is.str.1in one unit and.strin the other. Mutually recursive local functions are compared coinductively. - If the definitions differ,
cir-mergestops with an error. The program breaks the ODR, or the translation units were compiled with different options.
cir-merge keeps a weak_odr definition if there is one, else a
linkonce_odr definition, else an available_externally definition.
The records. CIR identifies a named record by its name in an MLIR context.
If two inputs define the same name differently, the MLIR parser uses the first
definition for both inputs and gives no error. Thus cir-merge compares the
definitions before the inputs share a context. Two different definitions are
an error. A record that is incomplete in one input and complete in another
input is correct.
The anonymous records. Clang names a record without a name anon.N, with
a counter in each translation unit. Thus anon.0 of one input and anon.0 of
another input are not related. cir-merge identifies these records by their
structure: two anonymous records with the same structure get one name, two
different ones get different names. The first input keeps its names. An input
whose names change is rebuilt before it joins the shared context. A record
cannot change its name in an MLIR context, so the rebuild goes through
temporary names and a second context. When cir-merge compares two named
records, it compares their anonymous members by structure too.
These usual programs are errors at the moment:
- C programs that use the same struct name for different structs in two files.
- Declarations whose type is different from the definition, for example
extern int a[];andint a[10];.
libcxx-om/c++/v1 holds small replacements for the parts of libc++ that are heavy
or that live in its compiled library. Give it with --include libcxx-om/c++/v1 --no-externalize-std. All other headers stay libc++'s. See
OM_DESIGN.md for what each model does and what it does not preserve.
The llvm-version.txt file contains one revision:
945e3e825b3ee88a8c1fed0da2dc88d6b2114e37
The revision is immutable. It is a release tag, or a full 40-character commit SHA. It is never a branch name. A branch moves, and a moving toolchain changes the result of a build of unchanged sources.
All parts of the repository read this file. The docker/build-llvm.sh script
gets this revision. The toolchain image contains this revision and copies the
file to /opt/cir/llvm-version.txt. The static binaries include the file. The
toolchain image uses the revision as its tag. A weekly workflow compares the
file with the upstream releases.
To change the revision, change one line. Refer to 6.6 Change the pin.
CMakeLists.txt also sets a minimum version of LLVM 24.0. A build against a
different installation stops at the configuration step with a clear message.
Before, the build used a shallow clone of the default branch of llvm-project.
Each upstream commit that changed ClangIR or MLIR could break the build. The
break came with no warning. A person then had to build the toolchain image
again.
| Item | The main branch | A pinned revision |
|---|---|---|
| When a break occurs | At each upstream ClangIR change | Only when you change the pin |
| The toolchain image | Built again to correct a break | Built again when the pin changes |
| To repeat an old result | You must know the LLVM commit | The revision is in the repository |
| New ClangIR functions | Immediately | When you change the pin |
The last row is the cost. A CIR operation that upstream adds after the pinned revision is not available until a person moves the pin.
A release tag is better than a commit SHA. A tag is easier to read, and a release gets patch versions. Use a tag when you can.
This pin is a commit because a usable release does not exist yet:
| Candidate | Why it is not used |
|---|---|
llvmorg-23.1.0 |
It has no cir.fmuladd, and it has the removed special member accessor. |
llvmorg-24-init |
This tag is the start of the LLVM 24 cycle, not a release. It has the same limits as LLVM 23. |
| An LLVM 24 release | It does not exist. Upstream has not made one. |
The pinned commit is llvm-project main in the LLVM 24 cycle. It is still one
immutable revision, so it gives all the properties in the table of
6.2. Only the frequency of
the security patches and the quality of the release notes are different.
The Check for a newer LLVM release workflow knows this condition. While the pin is a commit, the workflow makes an issue only when a release becomes equal to or newer than the pinned LLVM version. Then a person can move the pin back to a tag.
Upstream adds ClangIR in steps. cir2c uses 150 different CIR operations. This table shows what each release does not have:
| LLVM release | What cir2c cannot get from it |
|---|---|
| 21.1.x | Almost all operations: arithmetic, exceptions, vtables, complex numbers, math |
| 22.1.x | 60 operations, and this includes all arithmetic operations |
| 23.1.0 | cir.fmuladd, cir.fma, and the current func_info attribute |
| 24 (the pin) | Nothing |
LLVM 22 and earlier releases use one cir.binop operation with a kind
attribute. LLVM 23 makes separate cir.add, cir.sub and cir.mul
operations. The cir2c handlers use the separate operations. Exception handling,
cir.cleanup_scope and cir.vtable.get_type_info are also new in LLVM 23.
LLVM 24 makes two changes that cir2c must obey:
- Clang emits one
cir.fmuladdoperation fora * b + cwhen the default-ffp-contract=onis active. Before, Clang emittedcir.fmulandcir.fadd. A mapper with no handler forcir.fmuladdstops with an error on usual floating-point code. - The special member slot of
cir.funcis now the more generalfunc_infoattribute, and MLIR made the symbol names inherent attributes. ThusgetCxxSpecialMember()andmlir::SymbolTable::getSymbolAttrName()do not exist. cir2c usesisCxxSpecialAssignment()withisCxxTrivialMemberFunction(), and a null-safesymbolNameAttr()helper.
All source files of cir2c compile against the ClangIR headers of the pinned revision. Thus the accessor names also agree.
The LLVM toolchain image workflow publishes the image with the pinned
revision as its tag, for example ghcr.io/ftsrg/cir2c-llvm:945e3e82.... The
CI workflow and the Release workflow pull that exact tag. They do not
pull latest.
This is necessary. A build of LLVM takes hours. In that time, latest continues
to point to the previous toolchain. A job that used latest after a pin change
would build the new sources against the old LLVM. Its result would be true for
neither.
Thus each LLVM-dependent job has a Toolchain image step before it:
| Condition | What occurs |
|---|---|
| The image for the pin exists | The jobs run against it. |
The image does not exist, on a push to main |
The jobs stop and wait. When the image build is successful, CI and Release start again for the same commit. |
| The image does not exist, in a pull request | The Toolchain image job fails and tells you to build the image. |
The checks that do not use LLVM (the license headers, the shell scripts and the commit messages) always run.
Only main moves the latest tag. Thus you can prepare a pin change on a
branch, and build its toolchain image, and not change what other persons pull.
Do these steps when you move to a newer LLVM:
- Change
llvm-version.txtto the new revision. Use a release tag if a usable release exists. If not, use a full commit SHA. Refer to 6.3. - Build the toolchain image again. Start the LLVM toolchain image workflow
from the Actions page. Start it on your branch, not on
main, while you prepare the change. As an alternative, do this command:docker build -f docker/llvm.Dockerfile -t ghcr.io/ftsrg/cir2c-llvm:latest .< 10BC8 /div>- Build cir2c against the new image and run the tests.
- Correct the errors. Changed accessor names cause compilation errors. Changed assembly syntax causes parse errors in the integration tests. A new operation that replaces an operation that cir2c maps needs a new handler.
- If the new revision removes a function that cir2c uses, increase
CIR2C_LLVM_MIN_VERSIONinCMakeLists.txtin the same commit.The Check for a newer LLVM release workflow operates each week. It makes an issue when a better pin becomes available.
input.cpp | clang -x c++ -std=c++23 -S -emit-cir (-stdlib=libc++) v CIR module (MLIR text) | preprocessing of the qualifiers v CIR module | cir2c v output.cEach step is a different process. Each intermediate result is text that you can read. This is intentional. When a translation is not correct, you can keep the CIR with the
--mliroption, change it, and give it tocir2cagain.cir2c does not build CIR. cir2c reads CIR. The
main.cppfile registers the CIR dialect with an MLIR context and parses the input module. All subsequent work is an examination ofmlir::Operationobjects.Component Function Mapper(Mapper.h,Mapper.cpp)The handler table, the map from SSA values to C expressions, the scope and loop stacks, the symbol names, and the set of necessary intrinsics ModuleEmitter.cppThe module output: the sequence of globals, function declarations, vtables and function bodies TypeMapperCIR types to C types. !cir.int<s, 32>becomesint.!cir.ptr<T>becomesT*. Records becomestructtypes.ConstantEmitterCIR constant attributes to C initializers, and this includes arrays and records TraceabilityThe map from operations to C lines for the --monitor-jsonoptionhandlers/One file for each group of CIR operations models/C++ headers for the parts of libc++ that libc++ keeps in its compiled library. They are not part of the cir2c binary. See 8.2. Each handler has the name of a CIR operation, for example
cir.alloca,cir.fororcir.throw. The handlers are in groups by subject:ArithmeticHandlers,ControlFlowHandlers,ExceptionHandlers,VTableHandlers,MemoryHandlers,RecordHandlers,CallHandlers,CastHandlers,ComplexHandlers,FloatMathHandlers,BuiltinHandlers,ConstantHandlers,GlobalHandlersandVariadicHandlers.Each group registers itself at start-up with the
REGISTER_HANDLER_MODULEmacro. To add a group, add a.cppfile toCMakeLists.txt. No other change is necessary.The handlers have types. The
Mapper::registerTypedHandler<cir::LoadOp>(...)function takes the operation name from the generated class. The handler receives an operation of the correct type. Thus the handler code usescir::LoadOpand not a rawOperation*.WARNING: An unknown operation is always an error. cir2c prints the name of the operation and stops with a non-zero exit code. cir2c does not ignore the operation. The output goes to a verification tool. A missing operation gives an incorrect result, and an incorrect result is worse than no result.
C needs a declaration before a use. The C++ constructions that cir2c models have circular references. A vtable refers to functions. Those functions use the record type. The methods of the record are in the vtable.
ModuleEmitteruses this fixed sequence:- First step. The
externdeclarations for the vtable symbols and the VTT symbols. - The globals. The global variables. A global whose initializer takes the address of a different symbol moves to step 4.
- The function declarations. A prototype for each function. Thus a body can call any function.
- The remaining globals. First the vtable arrays, then the VTTs. Their functions now have declarations.
- The function bodies. cir2c keeps the bodies in a buffer. Thus the
__VERIFIER_nondet_*declarations that it finds during this step can go to the top of the file.
The output does not contain an inline definition that nothing uses. Before the first step,
computeReachableDefsstarts atmainand at each function and global that does not have a linkonce or weak linkage. It follows the references from function bodies and from initializers. A linkonce, weak or available-externally function that it does not reach is not in the output. A linkonce or available-externally global that it does not reach is also not in the output. An example is the vtable of a class whose key function is inline, which clang emits also when nothing creates an object of the class.Virtual dispatch. cir2c writes the vtables as
void*arrays. A virtual call becomes a call to a wrapper function:/* The vtable pointer of obj is at offset 0. The function is vtable[slot]. */ int __VERIFIER_virtual_call_i_pv(void* __obj, int __slot, void* __first) { void* __fn = ((void**)*(void**)__obj)[__slot]; int (*__f)(void*) = (int (*)(void*))__fn; return __f(__first); }
There is one wrapper for each different signature. Each wrapper has one definition in each output file. A tool that models indirect calls exactly gets exact dispatch. A different tool sees a call through a pointer from a real array.
Each call through a function pointer goes through a variable of the function-pointer type, also at an indirect call of the program and at the destructor call of an exception (
void (*__dtor)(void*) = …; __dtor(…);). A verifier frontend can know the targets of a call only from a declared function pointer: Theta rejects a call whose callee is a cast expression.A method has a
struct T*receiver, but the wrapper calls through a pointer with avoid*receiver. In C, a call through a pointer of an incompatible type is undefined behavior. Thus a vtable slot does not hold the method itself. It holds a small function with avoid*receiver that calls the method:static int __cir2c_vt_Derived__f(void *p0) { return Derived__f((struct Derived*)p0); }
A pointer result of this function is
void*, and the wrapper converts it to the type of the call. Thus a covariant override agrees with the slot of its base. The destructor of a thrown object uses the same type of function.Virtual bases. The position of a virtual base subobject depends on the most-derived class, so the object finds it through its vtable. The entries before the address point are integers: the virtual-base offsets, the vcall offsets of the virtual thunks, and offset-to-top. cir2c writes them into the
void*array as integer constants (C11 6.6p9):void *_ZTV1D[] = { (void*)16UL, (void*)0, (void*)0, (void*)8UL, (void*)0xfffffffffffffff8UL /* -8 */, (void*)0 };
The CIR reads such an entry through casts and constant strides from the vtable pointer, as bytes or as 64-bit integers. cir2c writes no C for these steps, only the read of the
void*element, converted back to an integer (C11 6.3.2.3p5 and p6, implementation-defined):long vt12 = (long)(unsigned long)((void**)v10)[-3];
Any other use of a pointer into a vtable stops cir2c with an error. For a local or global variable of a class type, the object is complete, so its vtable pointer holds the primary address point of the vtable of its class. The entry is then a constant, and the output does not read the vtable pointer. The
_ZTT…array (the VTT) holds the address points that the complete-object constructor gives to the base constructors (&_ZTT1D[1]), also from the construction vtables_ZTC….Pointer arithmetic. C++ defines a null pointer plus 0, and a null pointer minus a null pointer. C does not, and libc++ does both with an empty container. Where the offset is not a constant and the pointer can be null, cir2c writes
(n == 0) ? p : &p[n]and(p == q) ? 0 : p - q.Exceptions. There is no
setjmp, nolongjmpand no unwinder. Four global variables hold the exception state:static void *__cir_exc_ptr; /* The exception object */ static const void *__cir_exc_type; /* The address of the RTTI tag */ static unsigned __cir_exc_type_id; /* The numeric tag */ static int __cir_exc_active; /* 1 while an exception is active */
A
throwstatement sets these variables and returns. Eachthrowstatement has a static variable of the thrown type, and the exception object is in that variable. Thus the object has its correct type and alignment, and it is available after the function returns. After each call that can throw, cir2c writes a test of__cir_exc_active. Eachcatchclause becomes a comparison with the RTTI tag. Eachtypeinfosymbol becomes astatic const char __cir_eh_type_<sym>[]array. Thus the address of the array is a unique tag.Static initialization. C has no
.init_arraysection. cir2c collects the global constructors and calls them at the start ofmainin the correct sequence. cir2c writes the destructor calls before eachreturninmain.Names. cir2c demangles the C++ symbols and makes safe C identifiers. The
ns::f(int)symbol becomesns__f_int. If two different symbols make the same name, cir2c adds a suffix that a person can read. Plain C names do not change. cir2c uses the demangler only for symbols with the_Zprefix.A C++ function can have the name of a C library function, for example
memcpy(void*, const void*, int). In C++, it is a different overload. In C, it would replace the library function, so cir2c adds the suffix to its name:memcpy_2.Clang names an unnamed class, for example a lambda, by its source location. cir2c keeps only the file name of that location, not the directory. Thus the output contains no path of the local machine:
lambda_at_list_1276_48.Two different records always get two different C names. A C++ name can give the C name of a different record, for example
ns::Xandns__X, or two lambdas at the same position of two files with the same name. Before the translation, cir2c finds such records and gives them different names. For source locations, it adds directories from the end of the path until the names differ:lambda_at_a_util_h_100_36andlambda_at_b_util_h_100_36. For other names, it adds a numeric suffix:ns__X_2. The names depend only on the set of records in the module. A name without such a conflict does not change. If two records still get one name, cir2c stops with an error. With--tu-part, cir2c stops with an error when a record needs a suffix or more directories: another unit, with other records, could give the same record another name, and C11 6.2.7 makes two struct types of different units compatible only with the same tag.operator newandoperator deletehave no body in CIR, because libc++ keeps them in its compiled library. With--no-externalize-std, the libcxx-out-of-line model defines them (8.2, issue #17), so a throwingnewthrowsstd::bad_allocwhenmallocfails. With--externalize-std, cir2c writes small functions that callmallocandfree. A throwingnewthere callsabort()whenmallocfails, so a program that catchesstd::bad_allocloses that path.Trivial assignment. CIR marks a trivial default copy operator or move operator with
func_info<#cir.cxx_assign<…, trivial true>>. The body is almost empty. The mark holds the "copy the object" behavior. cir2c finds the mark and writes*dst = *src. Without this rule, each such assignment does nothing.C++ copies only the data of the class, not its padding. Thus, when the record has a
padmember or an empty member, cir2c copies the data members one by one. Two cases need this rule:- An empty class, for example
std::less<int>, has no data. libc++ stores it with[[no_unique_address]], so it shares its address with another member, for example the size of astd::set. A copy of the whole C struct changes a byte of that member. - The tail padding of a base can hold a member of a derived class (see 8.7).
Calling convention. Clang applies the calling convention of the target already in the CIR. A trivially copyable record of 16 bytes or less travels in registers. The CIR then passes it as one or two integer, pointer or floating-point values, or as an anonymous struct of these values. To convert between the record and these values, the CIR stores one type into a local variable and reads the other type from the same address. In C, that read is undefined behavior (C11 6.5p7).
Usually, each value of the other type is exactly one scalar member of the record: the same offset, the same size and the same kind. Examples are an iterator
{ int *p; }that travels as one pointer, and a{ const char *p; unsigned long n; }that travels as a pointer and an integer. Then the variable keeps its type, and cir2c converts the values one by one. The CIR has only an untyped pointer, so a pointer member travels asvoid *:struct Iter coerce61; /* ... */ void* t62 = (void*)coerce61.p; /* the read as the other type */ int r63 = f(t62);
The kinds are an object pointer (converted through
void *, C11 6.3.2.3p1), an integer or abool(converted to the integer of the same size), andfloatanddouble(the same type). These conversions do not change the value. cir2c makes this check on the two CIR types of the variable. It does not use the signature of the function, which the CIR does not keep. A member that is an array, a union, a bit-field or a vector, and a type of another kind, for examplelong double, prevent the conversion.Otherwise, for example when one integer holds two members, cir2c declares such a variable as a union of all the types that the CIR reads it as. Each read as another type becomes a read of the member of that type. For a
struct P { char c; int i; }that a function returns:union { struct P v0; unsigned long v1; } coerce74; memset(&coerce74, 0, sizeof coerce74); coerce74.v0.c = t80.c; coerce74.v0.i = t80.i; unsigned long t81 = coerce74.v1; return t81;
C11 6.5.2.3 (note 95) defines the read of another member: the bytes get the new type. The union is zero at its declaration, and a record goes into and out of the union member by member. Two causes make this necessary:
- A copy of the whole record also copies its padding, which nothing wrote. The integer then contains uninitialized bytes.
- After a copy of the whole record, the TypeSanitizer of clang gives the copy the type of the source member, and it reports each later read of the copy. C permits these reads, but the reports would hide real ones.
cir2c does not make a union where C permits the access: through a character type, through the other signedness of an integer type, to the first member of a record, or through a record that is not larger and has the variable as its first member. A variable of an array type or a vector type does not become a union. The code of the union slots is in
src/Reinterpretation.cpp.- Make the failure again:
cir2c prints the name of the unknown operation.
./run-cir2c.sh --mlir /tmp/case.mlir case.cpp /tmp/case.c
- Find the definition of the operation in the
clang/include/clang/CIR/Dialect/IR/CIROps.tdfile of the pinned LLVM. Read the operands, the results, the attributes and the assembly format. - Add the handler to the correct group in
src/handlers/. Use theregisterTypedHandler<cir::TheOp>function. - Add a small test program to
test/integration/input/. Use the nametest_<subject>.cortest_<subject>.cpp. The test runner finds it automatically. - Run
ctest --test-dir build --output-on-failure.
If you cannot translate the operation correctly, this is an acceptable result. Add the operation to the
BLOCKLIST_OPSlist intest/run_tests.shwith a comment. Record it in 8. Limits.
The output is a model of the input program. This section gives all known approximations and their direction.
Two words have an exact meaning in this section:
- Conservative. The model permits behavior that the real program does not have. A proof on the model is also true for the program. A counterexample can be false.
- Unsound. The model can miss behavior that the real program has. A proof on the model is not true for the program.
For these constructions, cir2c stops with an error. cir2c does not write incorrect code. The corpus tests skip the programs with the CIR operations of the
BLOCKLIST_OPSlist intest/run_tests.sh. That list is only for the tests:run-cir2c.shitself stops with the error.Construction CIR operation Cause Inline assembly cir.asmThere is no C equivalent. SIMD vectors cir.vec.*,!cir.vector<…>There is no portable C model. A floating-point class test that tells a quiet NaN from a signaling NaN cir.is_fp_classwith only one of the two NaN flags (__builtin_issignaling,__builtin_isfpclass)The output tests the classes with comparisons ( x != xfor a NaN), and no comparison tells the two kinds apart. The other class tests (isnan,isinf,isfinite,isnormal,fpclassify) translate into comparisons with the smallest normal and the largest finite value offloat,doubleandlong double(the 80-bit format). A class test on another type, for example_Float16, stops cir2c.Integers wider than 64 bits cir.int<s,128>,cir.int<u,100>(__int128,_BitInt(100))C has no such type. Arithmetic on an integer of another width than 8, 16, 32 or 64 bits for example cir.addon!cir.int<u,24>(_BitInt(24))Such a value travels in the next wider type. That keeps its bits when the output only stores, loads or passes it, for example a record of 3 bytes that the calling convention coerces to !cir.int<u,24>. The arithmetic of the wider type would not wrap at the width.Other types without a C type for example a vector member outside the vector operations, or a half-precision MLIR float mapTypeToCwrites a marker for the type. cir2c stops when the finished output contains a marker, so a type in a function that the output does not contain does not stop it. A pointer to such a type becomes a pointer to an incomplete struct: the output can store and pass it, but not read through it.MSVC SEH cir.eh.setjmp,cir.eh.longjmpThis control flow has no model here. A handler that matches through a virtual base a catchof a virtual base class of the thrown classThe handler selection decides each pair during the translation (8.3), but the offset of a virtual base is in the vtable of the object, at run time. A vtable entry of a library object, with --externalize-stda read of a virtual-base offset or offset-to-top through the vtable pointer of a std::objectThe constructor of the object is unknown, so its vtable pointer is unknown. libc++ instantiates its streams in its compiled library, so their vtables are not in the module either. Computed goto cir.indirect_brThe GNU &&labelandgoto *pextensions have no ISO C equivalent. A sound translation must change the function into a switch statement on a label number. cir2c does not do this yet.Clang cannot make CIR for some other constructions. In this condition,
run-cir2c.shreturns exit code 2 and Clang gives the cause. Each LLVM release makes this set smaller.The
--externalize-stdoption and the--no-externalize-stdoption control the most important selection in the tool.The
--externalize-stdoption (the default) is conservative.cir2c replaces the
std::calls and the library calls with unknown values. For memory, cir2c writes__VERIFIER_nondet_memory(p, n). cir2c writes this comment in the output file:// Over-approximated (may be unsound): library/std:: calls replaced by // __VERIFIER_nondet_memory havoc (results are nondeterministic).
The model permits more behavior than the program. A proof is true for the program. A counterexample can be false, because it can use a library result that the real library does not give.
WARNING: The
--no-externalize-stdoption is UNSOUND for STL containers.Some libstdc++ functions have their bodies in compiled
.ccfiles and not in headers or templates. ClangIR sees only a declaration. Thus there is no body in the CIR, and the output C code has only anexterndeclaration. Examples are the_M_hook,_M_unhook,_M_transferand_M_reversefunctions ofstd::__detail::_List_node_base. Parts ofstd::stringand the locale code have the same condition.A verification tool that models an unknown call as an empty function removes their effects on memory. For
_M_hook, the list nodes have no connection. Thebegin()function returns the sentinel. Thefront()function and theback()function read the_M_sizefield of the sentinel as the element. The result is an incorrect counterexample.There is no correction in cir2c. The bodies are not in the CIR. A model of these functions needs specific knowledge of each libstdc++ function. This is not in the scope of the project. Do not verify STL container programs with the
--no-externalize-stdoption.For this cause, the sequence compiles C++ input with libc++. libc++ keeps
list,map,setanddequefully in the headers. Thus ClangIR sees the bodies. Therun-cir2c.shscript always gives the-stdlib=libc++option. There is no option to prevent this. The toolchain build installs libc++ with clang for this cause.The models. libc++ also keeps some parts in its compiled library and not in its headers. Examples are
std::cout, the output functions ofbasic_ostream<char>and the constructor ofstd::logic_error. ClangIR sees only a declaration of these parts. With the--no-externalize-stdoption, therun-cir2c.shscript compiles C++ input together with the models in themodels/directory. A model is C++ source code. Thus clang calculates the names, the layouts and the vtables, and cir2c translates the model like the program. The cir2c binary contains no model.A model directory has one or two of these parts:
include/: the script gives clang the-I models/<name>/includeoption. clang searches this directory before the libc++ headers. Thus a header in it replaces the libc++ header with the same name.prelude.h: the script gives clang the-include models/<name>/prelude.hoption. clang reads this file before the first line of the program.
The
MODELSlist inrun-cir2c.shselects the models. To use a different model, change the list. If two models have a header with the same name, the script stops.Model Function Relation to libc++ ostream-sinkstd::cout,std::cerrandstd::clogdiscard all output.An abstraction. The model uses only names from the C++ standard. istream-nondetstd::cingives an unknown value for each arithmetic extraction.An abstraction. The model uses only names from the C++ standard and the SV-COMP functions __VERIFIER_nondet_*.libcxx-out-of-lineThe members of six exception classes, std::nothrowand the replaceable allocation functions (operator new,operator delete), that libc++ keeps in its compiled library. The libc++ headers use them, for example invector::atandstd::stable_sort, and eachnewexpression calls an allocation function.The same behavior and the same what()texts as libc++. The model uses two private libc++ names.The ostream-sink model. The model replaces the
<ios>,<ostream>and<iostream>headers. The library's<iosfwd>declaresios_base,basic_iosandbasic_ostream. The model completes these declarations with qualified definitions, for exampleclass std::ios_base { ... };. Thus the model does not name the internal namespace of libc++.Part libc++ The model std::cout,std::cerr,std::clogThey write to stdoutandstderr.std::cerris tied tostd::coutand flushes after each output.They have no stream buffer and no tie. They are constant-initialized, so a program can use them at any time. <<for the arithmetic types,char,const char*,const void*,nullptr,std::stringandstd::string_viewFormats the value and writes it. Reads the characters of a char*up to'\0'.Returns the stream and does nothing else. std::endl,std::ends,std::flush,put(),flush()Write a character or flush the stream buffer. Do nothing. good(),eof(),fail(),bad(),rdstate(),operator bool,operator!,clear(),setstate()Read or change the state. clear()andsetstate()throwios_base::failurefor a state thatexceptions()selects. That mask is empty by default.The same, without the exception mask. The values of the state bits are those of libc++. The class structure basic_ostreamhas the virtual basebasic_iosand a virtual destructor.No virtual base and no virtual function. The class is final.The ostream-sink model has these limits:
- The output is lost. A verification tool cannot examine the text that the program writes.
- A write never fails. In libc++, a write to a closed
stdoutsetsbadbit. In the model, onlyclear()andsetstate()change the state. - The model does not read the data that it gets. libc++ reads the characters of
a
char*. If the pointer is not valid, that read is undefined behavior. A verification tool cannot find this undefined behavior in the model. The program evaluates the operands as usual:std::cout << f()callsf(). - The model does not include string streams, file streams, stream buffers,
locales or format manipulators. For each of
<sstream>,<fstream>,<streambuf>,<strstream>,<syncstream>,<iomanip>,<locale>and<print>, the model has a header that stops the compilation with an#errormessage. The input (<istream>andstd::cin) is in the istream-nondet model.<iostream>needs that model. - Some libc++ headers use the libc++ stream code internally.
<chrono>,<complex>,<filesystem>,<format>and<thread>do not compile with the model.
The istream-nondet model. The model replaces the
<istream>header and completes the declaration ofbasic_istreamfrom<iosfwd>, as the ostream-sink model does. The<iostream>header of the ostream-sink model definesstd::cin. The input of a verification task is unknown. Thus each extraction of an arithmetic value succeeds, and the variable gets the value of__VERIFIER_nondet_<type>(). The input never ends.Part libc++ The model >>forbool,short,int,long,long long, their unsigned forms,floatanddoubleReads and converts the text. At the end of the input or for text that is not a number, sets failbit.Gives the variable an unknown value. Never fails. std::ws,ignore()Skip input. Do nothing. The next values stay unknown. >>forchar,char*,std::string,long doubleandvoid*;get(),getline(),read(),peek()Read characters or a value. No definition. cir2c rejects the program. good(),eof(),fail(),bad(),rdstate(),operator bool,operator!of the input streamRead the state. No definition. cir2c rejects the program. The model rejects these parts on purpose:
- The input of characters and strings. A model of such input needs a bound on the length of the input.
- The state of the input stream. In the model, an extraction never fails. A
loop like
while (std::cin >> x)would never end, and the code after it would not be accessible. In the program, the loop ends at the end of the input. A proof for the model would not be true for the program. long doubleandvoid*. SV-COMP has no__VERIFIER_nondetfunction for them.
The libcxx-out-of-line model. The
prelude.hfile defines these members and objects as libc++ does. clang emits only the members and objects that the program uses.Member or object Behavior in libc++ and in the model std::nothrowAn empty object. new (std::nothrow) Tgives it tooperator new.~exception(),exception::what()Empty. what()returns"std::exception".The constructor, the destructor and what()ofbad_allocEmpty. what()returns"std::bad_alloc".The constructor, the destructor and what()ofbad_array_new_lengthEmpty. what()returns"bad_array_new_length".logic_error(const char*),~logic_error(),logic_error::what()The constructor copies the message, what()returns the copy, and the destructor releases it.~length_error(),~out_of_range()Empty. operator new,operator new[]mallocof the size, or of 1 byte for 0 bytes. Whenmallocgives a null pointer,throw std::bad_alloc().The std::nothrow_tforms ofnewThe result of malloc, also a null pointer.The std::align_val_tforms ofnewaligned_alloc, with the size rounded up to a multiple of the alignment (C11 7.22.3.1).All forms of operator deletefree.The libcxx-out-of-line model has these limits:
- libc++ keeps the message in the private member
__imp_, of the private type__libcpp_refstring. No standard name gives access to the message, so the model uses these two names. A different library needs a different model. - In libc++, the copies of an exception share the message through a reference
count. The model defines no copy constructor and no assignment for
logic_error. Thus each message has one owner. - When
mallocfails during the copy of a message, the model throwsstd::bad_alloc, as theoperator newof libc++ does. - libc++ calls the new handler of
std::set_new_handlerbefore it throwsbad_alloc. The model does not.set_new_handleris in the compiled library, so cir2c rejects a program that uses it (an undefined symbol). - The allocation functions of the model are
inline, so that each translation unit has one definition thatcir-mergecan merge, and the output contains only the forms that the program uses. C++ forbidsinlinereplacements ([replacement.functions]/3, no diagnostic required). clang accepts them with a warning, and the model turns the warning off. - A program that defines its own
operator newdoes not compile with the model: two definitions of one function. - Other members are not in the model, for example the constructors of
std::runtime_errorandlogic_error(const std::string&). cir2c rejects a program that uses one of them (see the next paragraph).
Undefined symbols. With the
--no-externalize-stdoption, cir2c stops with an error when the output of a C++ program uses a function or an object that has no definition. These symbols are permitted, because a verification tool knows them:- The functions of the C standard library, and
stdin,stdoutandstderr. - The
__VERIFIER_*functions,reach_error()and__assert_fail().
For any other undefined symbol, a verification tool chooses a behavior, and the result does not belong to the program. A destructor without a body is also undefined. Before this rule, cir2c gave it an empty body. cir2c lists the symbols and writes no output:
cir2c: error: with --no-externalize-std, the output must define each function and object that it uses, outside the C standard library (README 8.2). These have no definition: helper(int) [_Z6helperi] nondet_intThese conditions apply:
- The rule is for a C++ program, that is a module from C++ source with a
main()function. A module withoutmain()is a part of a program, and the other parts can define its symbols. A module that cir2c translates with--tu-partis also a part, also when it hasmain(). A C program has no models, and it can use POSIX functions, which the link of its output supplies. - A use counts only if it is in the output. A call in a function that the output does not contain does not count. A function attribute, for example the personality function of the exception handling, does not count.
To correct the error, add a model of the missing part, or use the
--externalize-stdoption.The selection of a handler. A handler of type
Hmatches an exception of typeEas in C++ ([except.handle]/3): whenEisH, whenHis an unambiguous public base class ofE, or whenHandEare pointers andEconverts toH(more qualifiers,void *, or a pointer to an unambiguous public base class). cir2c decides each pair during the translation, from the RTTI objects of the CIR, and writes one function for each handler type:static int __cir_eh_match__ZTI4Base(void) { if (__cir_exc_type == (const void*)__cir_eh_type__ZTI4Base) { __cir_exc_adj = __cir_exc_ptr; return 1; } if (__cir_exc_type == (const void*)__cir_eh_type__ZTI5Multi) { __cir_exc_adj = (void*)((char*)__cir_exc_ptr + 4); return 1; } return 0; }
The handler binds
__cir_exc_adj, the address of the base subobject. A pointer handler binds__cir_exc_pval, the converted pointer; a null pointer stays null.__cir_exc_ptrand__cir_exc_typekeep the exception object and its type, for a rethrow and for the destructor at the end of the handler.These limits apply:
- In a whole program, the candidates are the types that the module throws. A
module without
main(), or with--tu-part, can also get an exception from another part of the program. Then each class whose RTTI is in the module is also a candidate. An exception of a class that the module does not know matches only a handler of its own type, and a pointer that the module does not throw matches only a handler of its own pointer type. - The offset of a virtual base class is in the vtable of the object. cir2c stops with an error when a handler can match a thrown type through a virtual base class (see 8.1).
The global-variable model has these other effects:
- There is no unwinder. cir2c tests
__cir_exc_activeafter each call that can throw. If athrowstatement leaves a construction that cir2c does not model, the exception does not continue. - The
std::terminatefunction and the trap code becomeabort(). - An exception that leaves
main()or a static initializer callsabort(), asstd::terminatedoes. The destructors between thethrowandmain()operate before theabort(). C++ permits this: whether the stack unwinds beforestd::terminateis implementation-defined. - An exception that leaves a
noexceptfunction, for example a destructor, also callsabort(). The test is after the call: the destructors in thenoexceptfunction operate before theabort(). cir2c writes the test only after a call to a function that can throw, or after an indirect call. A destructor that operates during the unwinding of an exception starts with__cir_exc_activeset. Thus only a new exception from the call callsabort(), and a new exception during the unwinding continues as the first exception. - cir2c writes the global destructor calls before each
returninmain. They do not operate on theexit(),abort()or_exitpaths. These paths have no one text position.
A structure can end with an array that has no size:
struct one { int a; int values[]; } hobbit = {5, {1, 2, 3}};
CIR gives the member the length 0, but it keeps the correct initial values in the initializer. cir2c gives the member the length from the initializer. Thus the values stay correct.
The C compiler cannot initialize an array of length 0. If cir2c used the declared length, the compiler would discard the values, and the program would read the memory after the structure.
Note: The structure becomes larger. The member is always the last member, so no other member moves.
sizeofincreases. A calculation that usessizeofto find a size gives a larger result, never a smaller one.With the default
-ffp-contract=on, Clang gives onecir.fmuladdoperation fora * b + c. The operation permits two results: the target can use one fused multiply-add instruction, or a separate multiply and add.cir2c writes the unfused form:
double t = a * b + c;
This is one of the two results that the operation permits, and it keeps the output as usual arithmetic that a verification tool can examine. An opaque builtin call would hide the calculation.
Note: A verification tool examines the unfused form only. If the target machine fuses the operation, the two forms can be different by one rounding step. If your analysis must have the fused form, translate with
-ffp-contract=off. Then Clang gives separatecir.fmulandcir.faddoperations.cir.fma, which comes from__builtin_fma, is different. It makes sure of one rounding, thus cir2c keeps the call:fma(a, b, c).The default structured output keeps the
for,whileandifstatements and the scopes. Most verification tools examine this form more efficiently.run-cir2c.shmakes only the structured output. The flat output of the cir2c binary is not correct for exceptions (issue #21, see 5.2).Wide floating-point constants. clang writes a
long doubleconstant into the CIR as the shortest decimal for the 80-bit format, for example#cir.fp<1.000000e-01>for0.1L. The CIR parser reads a decimal as adouble, which loses the extra bits of the mantissa and each value outside the range ofdouble(LDBL_MAXbecomes an infinity,LDBL_TRUE_MINbecomes 0). Before the parse, cir2c replaces each such decimal (80-bit and 128-bit types) with its exact bit pattern, which the parser reads without loss (src/main.cpp).- The
long doubletype becomes the nearest C type on the host. Thex86_fp80,bf16andfp16types are in the output. But the bits are not always the same as in the source. - cir2c writes bit fields with explicit get and set operations and not with C bit-field syntax. Thus the layout is the layout of CIR and not the layout of the C compiler.
- A derived class can place its members in the tail padding of a base class
that is not POD (Itanium C++ ABI), for example the value of a
std::set<int>node. CIR then has two records for the base:Xfor a complete object andX.basefor a base subobject, without the tail padding. cir2c writesX.baseas its own struct,<tag of X>__base. A record that CIR marks as packed gets__attribute__((packed)), and a verification tool must honor it. - In C, a packed struct has the alignment 1, but its C++ objects have the
alignment of the class, for example 8. The address of a member, for example
&node->right, is aligned only when the object is aligned (C11 6.3.2.3p7). Thus a local or global variable gets the alignment of the CIR, for examplestruct Node node2 __attribute__((aligned(8)));, when it is larger than the alignment of its C type. An object frommallocis always aligned. clang still warns (-Waddress-of-packed-member), because it cannot see the object at the address operation. gcc-5 and clang-3.9 do not have this warning. - The output uses the target of the pinned toolchain. Do not give the output to a tool with a different data model, for example a 32-bit model or a different byte sequence.
- The output can access an object through a pointer cast to another type, which
C forbids (C11 6.5p7). cir2c removes these accesses for the calling
convention (see 7.5), but not all others. An example is a copy of a complete
object into a base subobject, which is an
X.baserecord. After the translation, cir2c counts the accesses that remain. If there is one or more, cir2c writes a warning with the number and the first example:cir2c: warning: the output accesses an object through a pointer cast to another type at 1 places, .... Such an output is not free of undefined behavior.
- The output is not for a person to read in place of the source. The output is not for production use. The tests compile the output only to make sure that it is correct C code.
- With the
--externalize-stdoption, a declaration of a C++ library symbol can stay in the output without a definition. cir2c replaces the calls, so this is correct. With the--no-externalize-stdoption, the models of 8.2 define the library parts that the program uses, and cir2c rejects a program that uses an undefined symbol. - C does not permit a null pointer argument to
memcpy,memmove,memset,memcmp,memchrand theirwmemforms, also when the size is zero. libc++ calls them so for an empty range. Thus cir2c writes such a call asn ? memcpy(d, s, n) : d. When the size is zero, the result is the value that the call returns:d,0or a null pointer. - The
cir2c --versioncommand prints the commit of the build. The releases include thellvm-version.txtfile. Record the two values with each result.
If you find an approximation that is not in this list, make an issue. Give the input program, the
--mliroutput and the C output. Soundness problems have a higher priority than missing functions. Write this in the title.
test/ ├── run_tests.sh # The test runner for the three suites ├── cir-merge/ # The cir-merge tests (one directory for each case) ├── integration/input/ # Small test programs (the default suite) ├── sources/llvm-test-suite/ # The LLVM SingleSource corpus (2600 programs) ├── benchmark_mapper.py # The runner for SV-COMP .yml tasks ├── generate-reference-outputs.py └── results2tex.py # Converts results.txt to LaTeX macrosYou must have
bash, GNUparallel,python3, a cir2c binary and a ClangIR toolchain.ctest --test-dir build --output-on-failure # The integration suite and the cir-merge tests bash test/cir-merge/run_tests.sh # The cir-merge tests, directly bash test/run_tests.sh # The same suite, directly RUN_LLVM=1 RUN_INTEGRATION=0 bash test/run_tests.sh JOBS=8 bash test/run_tests.sh --json-out /tmp/summary.json
Variable Default Function RUN_INTEGRATION1Run the integration tests RUN_LLVM0Run the LLVM SingleSource tests (large and slow) RUN_LLVM_MULTI0Run the LLVM MultiSource tests RUN_ESBMC0Run the esbmc-eval tests (the corpus is not in this repository) JOBSnprocThe number of parallel jobs MULTI_MERGEcThe merge strategy of the LLVM MultiSource tests: corcir(see 5.6)LLVM_EVAL_DIRtest/sources/llvm-test-suite/The LLVM corpus ESBMC_EVAL_DIRtest/sources/esbmc-eval/The esbmc-eval corpus CIR2C_LLVM_PREFIXFound automatically The toolchain prefix CIR2C_BUILD_DIRbuildThe directory of the cir2c binary The
--json-out FILEoption writes a summary for a program to read. CI uses it to make the results table. The--externalize-stdoption and the--no-externalize-stdoption select the standard library behavior.Note: A run with no tests is an error. The runner prints
No tests ranand returns a non-zero exit code. CI counts an empty suite as a problem. Thus an incorrect environment cannot show a good result.The cir-merge tests. Each directory in
test/cir-merge/cases/is one merge. The.cand.cppfiles are compiled to CIR with the toolchain clang. The.cirfiles are used directly. Theexpectfile gives the result:Line Meaning okorerror(first line)The merge must succeed or must fail a text (after error)The messages must contain this text output-count N TEXTThe merged CIR must contain TEXTNtimesrun CODETranslate the merged CIR, compile it, run it, and expect the exit code CODEreference FILELike run, but compare the output and the exit code with an LLVM test-suite reference fileA
sourcesfile in a case directory lists the inputs by their path in the repository. The cases use it for programs of the LLVM MultiSource corpus. A// cir-merge-cflags: FLAGSline in a source adds compiler flags for that source. Acflagsfile in the case directory adds compiler flags for all its sources.The result must not depend on the order of the inputs. Thus the runner merges a case with up to three inputs in all orders, and a larger case in sorted order and in reverse order. A successful merge must also pass
cir-opt. After the cases, the runner checks the command line (a missing input, an old output that a failed merge must not change,--dump-symbols,--verbose) andrun-cir2c.sh --merge cir(a successful merge and exit code 5).The runner processes each
.cfile and each.cppfile inintegration/input/. The bar has two levels:The test program What must be correct Has no main()The output C code compiles with the clang -fsyntax-onlycommand.Has a main()The output C code also links, runs, and gives the same exit code and the same output as the original program compiled natively. The reference is the native run of the original program, not the exit code 0. Some tests in this suite stop with an error on purpose, and some give a computed value. Only the original program can say what is correct.
The native run uses the default C++ library of the toolchain image, and that is libstdc++. Thus a test must not depend on a text that only libc++ gives, for example the
what()text of an exception that the library throws. With the--no-externalize-stdoption (the default of the runner), theostream-sinkmodel of 8.2 discards the output ofstd::cout,std::cerrandstd::clog. For a C++ test that names one of them, the runner compares only the exit code.The second level is what finds a wrong result. A lost destructor or an incorrect arithmetic operation makes correct C code, and thus a syntax examination cannot see it.
Add your tests to this suite. Put a small test program in
integration/input/with the nametest_<subject>.<c|cpp>. The runner finds it automatically. No registration is necessary. Give the program amain()that examines its own result, if you can.A C++ test can also require a rejection. Write the expected text of the error in a line that starts with
// cir2c-test-expect-error:. The test passes when the translation fails and its log contains each of these texts. Thetest_reject_*.cpptests examine the rejections of 8.2 in this way. These rejections occur only with the--no-externalize-stdoption. With the--externalize-stdoption, the runner skips such a test. A line that starts with// cir2c-test-expect-error-externalize-std:gives an error that only the--externalize-stdoption causes. Without that option, the test runs as usual.A test can also forbid a text in the log of the translation, for example a warning of cir2c. Write the text in a line that starts with
// cir2c-test-log-lacks:. The test fails when the log contains the text.A test can also forbid a text in the output C code. Write the text in a line that starts with
// cir2c-test-output-lacks:. The test fails when the output contains the text.A test can also require a text in the output C code. Write the text in a line that starts with
// cir2c-test-output-contains:. The test fails when the output does not contain the text.A test can also require that the output C code compiles with more compiler options, for example
-Werror=uninitialized. Write the options in a line that starts with// cir2c-test-cflags:. The test fails when theclang -fsyntax-onlycommand with these options fails. Use this to find undefined behavior that clang can report.The tests examine arithmetic, casts, comparisons, control flow, arrays, records, globals, floating-point numbers, pointers, integer promotion and bit operations. The C++ tests examine exceptions, RAII scopes, and virtual dispatch with member pointers and multiple inheritance.
The runner writes the logs and the output C code to
integration/output/. Git ignores this directory.This suite uses the
sources/llvm-test-suite/corpus. For each source with a.reference_outputfile, the runner translates it, compiles it, links it, runs it and compares the output and the exit code. With the--no-externalize-stdoption, the runner compares only the exit code of a C++ program that namesstd::cout,std::cerrorstd::clog, as in 9.3.If a difference also occurs with the
clang -fclangircommand, the cause is in ClangIR. The runner ignores such a test. cir2c cannot be more correct than its input.The
generate-reference-outputs.pyscript makes the missing.reference_outputfiles. The script compiles and runs each program with the system compiler.The SingleSource suite does not include the
MultiSource/directory.The LLVM MultiSource tests (
RUN_LLVM_MULTI=1) use the programs insources/llvm-test-suite/MultiSource/. Each program has more than one source file. The runner translates all files of a program into one C file, with the merge strategy thatMULTI_MERGEselects (corcir, see 5.6). Then it compiles, links and runs the program, and compares the output and the exit code with the reference. CI runs the suite two times, one time with each strategy.The reference outputs come from the LLVM test-suite, which builds and runs each program with its own settings.
test/llvm-multisource-options.shcontains these settings, taken from theCMakeLists.txtfile of each program: the language standard, the-Dflags, the program arguments, the file for stdin and the numeric tolerance. The runner runs each program in its directory, where the input files are. It compares stdout and stderr together, as the reference outputs contain both. With a tolerance,test/fpcmp.pycompares the numbers like thefpcmp -rtool of the LLVM test-suite.The vendored sources and input files are the same as in the LLVM test-suite, except for the license header.
This is a C++ corpus with no reference outputs. A test is successful when the output C code compiles. The corpus is not in this repository. Set the
ESBMC_EVAL_DIRvariable to your checkout.The corpus suites ignore a test when its CIR contains an operation that cir2c does not translate. The counts thus show real limits and not intentional limits.
The
BLOCKLIST_OPSlist is at the top ofrun_tests.sh. Each entry has a comment with the cause. The runner compares each entry as a fixed string with the.mlirtext. Keep this list and 8.1 Constructions that cir2c does not translate in agreement.Category Meaning Passed The C code compiled, linked, ran and gave the correct result. Compiled, not run The C code is correct, but the linker failed. This is usual for C++ library symbols. Output mismatch The program ran and gave an incorrect result. This is an error. Mapper failed cir2c made no C code. Compile failed cir2c made incorrect C code. This is an error. Skipped A blocklisted operation, a Clang failure, a known ClangIR difference, or a documented limit of cir2c. Three reasons have their own counter: "several TUs", an esbmc-eval task with more than one source file, which the suite does not translate (one translation unit for each task); "C++ model limit", the #errorof a header that the models of 8.2 do not cover (only with--no-externalize-std); and "cir2c limit", an error that cir2c gives on purpose instead of a wrong or undefined translation: the definition check of 8.2, a read through the vtable pointer of a library object with--externalize-std(#3), or a test that tells a quiet NaN from a signaling NaN (8.1).Timed out The test used more than 60 seconds. Always examine the "Output mismatch" category and the "Compile failed" category.
For SV-COMP tasks in
.ymlfiles:python3 test/benchmark_mapper.py <input-dir> [set-file-or-glob ...]
Option Function -c,--c-modeUse C mode ( clang -x c) and not the default C++ mode-o DIR,--output-dir DIRKeep the .mlirfile and theoutput.cfile for each taskThe script writes the results to
output.txtin the current directory.
The
mainbranch is protected. Make a branch and open a pull request. CI must be successful. A person must approve the pull request.- Make a branch from
main. - Make the change and add a test.
- Run the integration suite.
- Open a pull request. CI builds cir2c, runs the test configurations, and writes a results table as a comment.
The results table is the review record. It shows skipped tests, and this is correct. The important condition is that the "mapper failed", "compile failed" and "output mismatch" counts do not increase. If a count increases, give the cause in the pull request.
Each commit message is one line. Do not write a body. Do not write a list. Do not write a trailer of any type. This includes the
Co-Authored-By:trailer. Do not write the name of an AI tool.Use the present tense. Make one logical change in each commit. Give the issue number in the subject, for example
Fix #7: ….Correct: Emit real assignment for trivial defaulted operator= Incorrect: Emit real assignment for trivial defaulted operator= <empty line> CIR marks these with func_info<#cir.cxx_assign<…, trivial true>> …If you cannot describe a change in one line, divide it into more commits.
An explanation that is too long for the subject goes into a code comment, into this README, or into the pull request.
Each commit has the name of a person. The person who is responsible for the change is the author. An AI tool that helps you is not the author. This rule applies to the author field and to the committer field.
git config user.name "Your Name" git config user.email you@example.comCI examines the two rules for each pull request. Refer to
.github/workflows/commit-messages.yml.Correctness has a higher priority than coverage. The output of cir2c goes to tools that make conclusions from it. An operation with an incorrect translation is worse than an operation that stops the program. Do not write C code for an operation that you do not understand. Stop instead. If a translation is an approximation, record it in 8. Limits. Write a comment in the output C code when this is important.
Comments give the cause and not the operation. The code has many comments in the positions where a reader can think that there is an error. Examples are the trivial-assignment rule, the sequence of the module output, and the exception model. Do the same. If a subsequent reader can "correct" your code and cause an error, write a comment.
Style. Use the style of the adjacent code: two spaces for each indent level,
camelCasefor local variables and methods,PascalCasefor types, and a final underscore for private members. There is no automatic formatter. Do not change the format of unrelated lines.License headers. Each source file has the Apache 2.0 header. CI examines this. To add the missing headers:
python3 .github/scripts/add-license-header.py .github/scripts/license-header-apache . git restore test/sources # The LLVM corpus keeps its own header
Task Command The integration suite ctest --test-dir build --output-on-failureThe LLVM SingleSource suite RUN_LLVM=1 RUN_INTEGRATION=0 bash test/run_tests.shOne program, with the CIR ./run-cir2c.sh --mlir /tmp/c.mlir in.cpp /tmp/c.cEach change in behavior needs a test in
test/integration/input/. Each correction needs a test that fails before the correction and is successful after it.Give the input program, the
--mliroutput, the C output and the result of thecir2c --versioncommand. Soundness problems have a higher priority. Write this in the title.
Apache License 2.0. Refer to the LICENSE file. The CONTRIBUTORS.md file gives the list of contributors.
The binary releases include LLVM and Clang binaries. The Apache License 2.0 with LLVM Exceptions applies to them. The releases include this license as the
LICENSE.LLVMfile.