Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
The diff you're trying to view is too large. We only load the first 3000 changed files.
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,9 @@ cmake -G Ninja ../llvm \
-DLLVM_ENABLE_PROJECTS="mlir;clang" \
-DLLVM_TARGETS_TO_BUILD="host" \
-DLLVM_ENABLE_ASSERTIONS=ON \
-DCMAKE_BUILD_TYPE=DEBUG
-DCMAKE_BUILD_TYPE=DEBUG \
-DLLVM_PARALLEL_LINK_JOBS=1 -DLLVM_USE_LINKER=lld

ninja
ninja check-mlir
```
Expand Down
9 changes: 9 additions & 0 deletions debug.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
T=/mnt/d/HLS/Polygeist/tools/cgeist/Test/polybench/linear-algebra/solvers/trisolv/trisolv.c
I=/mnt/d/HLS/Polygeist/tools/cgeist/Test/polybench/utilities
R=/mnt/d/HLS/Polygeist/llvm-project/build/lib/clang/18

# bare global cl::opt — no -mllvm wrapper
/mnt/d/HLS/Polygeist/build/bin/cgeist "$T" -resource-dir="$R" -I "$I" -O3 \
--print-before-all -o /tmp/t.execm 2>/tmp/cg.log
echo "exit: $? lines: $(wc -l < /tmp/cg.log)"
grep -iE "Dump (Before|After)" /tmp/cg.log | tail -6
603 changes: 603 additions & 0 deletions docs/hls-pragmas.md

Large diffs are not rendered by default.

61 changes: 61 additions & 0 deletions docs/xlx-real-headers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# cgeist on the real Vitis HLS headers

cgeist can compile HLS C++ against the headers of a Vitis HLS install
(`<Vitis>/common/technology/autopilot`, the tree the Vitis synthesis front end
reads) instead of stand-ins. Everything is opt-in; without the options below
cgeist's output is unchanged.

## Command line

The Vitis front end's own flags (`db/autopilot.flow.log` of any Vitis run):

```
-I <autopilot> -D__SYNTHESIS__ -D__VITIS_HLS__ -DAESL_SYN -D__HLS_SYN__ -D__DSP48E1__
-include <autopilot>/etc/autopilot_ssdm_op.h -std=gnu++14 (C: -std=gnu99)
```

plus cgeist's Xilinx extensions:

| Option | What |
|--------|------|
| `-Xclang -fxlx-bitwidth` | `int/unsigned __attribute__((bitwidth(N)))` (the headers' `ssdm_int`) is `_BitInt(N)`. Needs the patched clang (`patches/llvm-project/0001-xlx-bitwidth.patch`). |
| `-Xclang -fxlx-apint-promote` | a `_BitInt` no wider than `int` takes part in the integer promotions, as in Vitis' front end. |
| `--xlx-prelude` | force-includes declarations of the Xilinx bit builtins (`include/xlx/xlx_prelude.h`, compiled into cgeist); their calls are lowered to `arith` / `math` ops (`Lib/CGXlxBuiltin.cc`, ported from hls-llvm-project's `CGFPGABuiltin.cpp`). The lowering is active under `--xlx-prelude` or `--xlx-headers` only; without them a function of such a name is an ordinary call. |
| `--xlx-headers` | code generation the headers need: the proxy objects `ap_range_ref`, `ap_bit_ref`, `ap_concat_ref`, `af_range_ref`, `af_bit_ref` are inlined and scalarised, also when they are read inside the `if` / loop regions of the inlined helpers and when one proxy holds references to others (a concatenation of range or bit references), and so are the type-punning unions (`doubleToRawBits`) (`Lib/XlxProxyScalarize.cc`); a value constructed from a string literal (`ap_ufixed<25,11> t[] = {"0x1.a614p0", ...}`, the `_ssdm_string2bits` the Vitis front end folds) is a compile-time constant and such a static table a dense global (`Lib/XlxStringBits.cc`, the Vitis C simulation's conversion: prefixes, `e` / `p` exponents, all quantisation and overflow modes); struct fields of different MLIR types are kept apart; `ns::table[i]` is an ordinary global; a store that the next memory access in the same block overwrites is deleted, such as the guard `if (!op) Base::V = 0;` of the `ap_fixed` conversion (`etc/ap_fixed_base.h:691`), which Vitis' LLVM pipeline removes too (`Lib/XlxDeadStore.cc`); unused `linkonce_odr` functions are dropped. A proxy that still cannot be scalarised (e.g. one passed to a function that is not inlined) is an error (exit code 13), since a memref of a struct holding a memref is not valid MLIR. |
| `-Xclang -fnative-half-type -Xclang -fnative-half-arguments-and-returns` | `half` is `__fp16` with native arithmetic, arguments and returns (Vitis' `-fhls`). |
| `-Xclang -Wno-unknown-attributes` | silences `no_ctor`, `hls_preserve` (streams and the FFT IP only). |
| `--scalar-wrapper-abi` | `ap_int` / `ap_fixed` objects are their `iN`. |

`-Xclang <arg>` passes any argument to the clang frontend (cc1).

Under `--xlx-headers` the pragma parser also accepts the forms the headers use:
a namespace-qualified `variable=ns::name`, and `variable=this` / `*this`
(reported and ignored: it names the object a member function runs on). Without
the option both are errors, as before.

Under `-fxlx-bitwidth` a width below 1 is an error ("bit width must be at least
1") and a width above 8191, the ceiling of the open-source Xilinx front end
(hls-llvm-project `Type.h:1545,3131`), a warning; whether Vitis 2025.1 has the
same ceiling is unconfirmed.

`ap_shift_reg` (`ap_shift_reg.h`): `__fpga_shift_register_peek(Array, Addr)` is
a load of `Array[Addr]` and `__fpga_shift_register_shift(DataIn, Array, Enable)`
an `scf.if (Enable)` around a loop moving every element one place up and a
store of DataIn at 0; the depth is the extent of the array the header casts to
a pointer (`Lib/CGXlxBuiltin.cc`; test `realheaders/shift-register-builtins.cpp`).

## Tests

`Test/HLS/xlx/` (no Vitis install needed; `bitwidth.cpp` needs the patched
clang, feature `xlx-bitwidth`) and `Test/HLS/realheaders/` (the install, from
`$VITIS_AUTOPILOT` or `/mnt/a/Vitis/2025.1/...`; UNSUPPORTED without it).

## Not covered

`hls::stream` (`__fpga_fifo_*`), `hls::task`, `ap_float`, the float / double
`hls_math` functions (closed bitcode), the DSP builtins, the FFT IP, and a
string constructor whose argument is not a string literal (it stays a call to
`_ssdm_string2bits`, which per the header "only takes const string and const
radix", etc/ap_fixed_base.h:458). How Vitis' closed front end rounds a decimal string that lies within
2^-(W-I+4) of a rounding boundary is unknown (the C simulation's sticky-bit
approximation and the exact value can differ there).
Binary file added durbin_ref
Binary file not shown.
52 changes: 52 additions & 0 deletions include/polygeist/Passes/Passes.h
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,11 @@ class RewritePatternSet;
class DominanceInfo;
namespace polygeist {
std::unique_ptr<Pass> createParallelLICMPass();
/// With `keepLoops`, LICM does not hoist a loop, or an op containing one, out
/// of an enclosing loop (cgeist --hls-keep-invariant-loops).
std::unique_ptr<Pass> createParallelLICMPass(bool keepLoops);
std::unique_ptr<Pass> createPolygeistMem2RegPass();
std::unique_ptr<Pass> createPolygeistAffineScalarReplacementPass();
std::unique_ptr<Pass> createLoopRestructurePass();
std::unique_ptr<Pass> createInnerSerializationPass();
std::unique_ptr<Pass> createSerializationPass();
Expand Down Expand Up @@ -80,6 +84,54 @@ void registerGpuSerializeToCubinPass();
void registerGpuSerializeToHsacoPass();

void populateForBreakToWhilePatterns(RewritePatternSet &patterns);

// Facts about the C program that the frontend records on ops as discardable
// attributes and the raising passes trust (AffineCFG, CanonicalizeFor). cgeist
// removes the polygeist.* ones from its output unless
// -keep-frontend-assumptions is given; hls.uncounted stays.

/// On an arith.addi / subi / muli: the C operation it computes has undefined
/// behaviour when its exact result does not fit the result type (signed
/// integer arithmetic at least as wide as int, C11 6.5p5, C++ [expr.pre]p4;
/// not under -fwrapv), so its result read signed is the exact result. On an
/// arith.index_cast from index to iN: the index value fits iN read signed.
constexpr llvm::StringLiteral kNoSignedWrapAttrName = "polygeist.nsw";
/// On an arith.index_cast from index to iN: the index value fits iN read
/// unsigned.
constexpr llvm::StringLiteral kNoUnsignedWrapAttrName = "polygeist.nuw";
/// On an scf.for that CanonicalizeFor raised from a while loop by assuming
/// that the loop terminates: its counter never wraps (see
/// -canonicalize-for-assume-termination in CanonicalizeFor.cpp). A BoolAttr:
/// true when the exit test reads the counter unsigned.
constexpr llvm::StringLiteral kCounterNoWrapAttrName =
"polygeist.counter_nowrap";
/// On an scf.for / affine.for raised by that assumption whose exit test
/// compares its counter with a bound of a wider type that the counter is not
/// known to reach (`for (uint8_t i = 0; i < n; i++)`, int n): a loop whose
/// trip count the source does not bound. Kept in the output for hls-est
/// (Vitis does not collapse such a loop with its perfect inner nest,
/// hls-est-validate VITIS_NOTES.md N15).
constexpr llvm::StringLiteral kUncountedLoopAttrName = "hls.uncounted";
/// On a func.func: its body (or the body of a function inlined into it)
/// accesses a volatile-qualified object, which cgeist does not represent on
/// memref accesses. No loop in such a function, and no loop that calls it, is
/// assumed to terminate (C11 6.8.5p6 excludes loops that access volatile
/// objects; -canonicalize-for-assume-termination in CanonicalizeFor.cpp).
/// Recorded per function, not per loop: the frontend's loops become scf.while
/// only in LoopRestructure, and a mark on a loop or on an access op would not
/// survive the rewrites before CanonicalizeFor.
constexpr llvm::StringLiteral kVolatileAccessAttrName =
"polygeist.volatile_access";

/// Canonicalization patterns that fold a chain of two marked add / sub with
/// constant operands, or of two marked mul by constants, into one marked op
/// (CanonicalizeFor.cpp). The arith patterns fold such chains through new ops
/// that would lose the mark.
void populateNoSignedWrapPatterns(RewritePatternSet &patterns);
/// Accesses through a memref.reinterpret_cast of an array argument whose
/// shape differs from the parameter's only in the first dimension use the
/// argument itself (PolygeistCanonicalize.cpp).
void populateArrayArgumentPatterns(RewritePatternSet &patterns);
} // namespace polygeist
} // namespace mlir

Expand Down
Loading
Loading