Project U-Ray is an attempt at documenting the bitstream format for the AMD (Xilinx) UltraScale and UltraScale+ parts including all parts from the following lines;
- Kintex UltraScale
- Virtex UltraScale
- Kintex UltraScale+
- Artix UltraScale+
- Virtex UltraScale+
- Zynq UltraScale+ MPSoC
The same flow also covers the 7-series (Spartan-7, Artix-7, Kintex-7 and Zynq-7000) parts, so that one pipeline produces bit databases for all three architectures.
It takes a lot of the learning from Project X-Ray and Project Trellis, and is part of F4PGA (formerly SymbiFlow). The upstream repository is f4pga/prjuray.
The bit databases are generated by the generic/ flow.
It uses random designs and feature correlation, with no per tile type code,
and covers every die in the free tier. It runs with Vivado 2025.2 and
Vivado 2026.1, and both are kept working: 2026.1 needs a (free, node
locked) BASIC licence and adds Spartan UltraScale+ to the free parts; on the
test dies it produces the same bits and the same timing as 2025.2 (see
generic/README.md).
The generic/ flow also extracts timing data from Vivado's speed models:
the delay model of every pip and wire of every tile and the timing arcs of
every BEL, for every speed grade (generic/python/timing.py). So far only
test data for one die per architecture has been generated.
The timing fuzzer in fuzzers/007-timing writes SDF
timing models for the SLICEL, SLICEM, block RAM and UltraRAM sites. It runs
in the environment set up by utils/ and settings/.
The generated databases are published in one repository per architecture:
| Architecture | Repository |
|---|---|
| 7-series | mithro/prjuray-db-series7 |
| UltraScale | mithro/prjuray-db-ultrascale |
| UltraScale+ | mithro/prjuray-db-ultrascaleplus |
Each repository holds the per tile type bit files (segbits_*.db,
defaults_*.db), the configuration register settings (registers.db) and a
tilegrid.json and colmap.json per die, and its README gives the source
commit, the file formats and per die check results. They are snapshots of
work in progress (see "Current status"), exported from a local build with
generic/export_db.sh.
The generic/ flow documents the bitstream of every
7-series, UltraScale and UltraScale+ die available in the Vivado 2025.2
WebPACK edition, using one architecture independent pipeline. No hand
written, per tile type fuzzers are involved. The steps are:
- Generate random designs for each die.
- Have Vivado report the features (PIPs, site and cell settings) each design uses.
- Learn the tile grid (which frames and words belong to each tile) from the designs.
- Correlate the features with the bits of the bitstreams (
mkdb.py).
The resulting bit databases are checked against held-out designs that were
not used to build them (check.py).
Coverage: all 29 distinct dies of the Vivado 2025.2 WebPACK edition (102 devices; devices that share a die share its tile grid and database), grouped into three bit databases. 28 of these dies (100 devices) are also free in Vivado 2026.1; XCU25 and XCU30 are free in 2025.2 only. Parts free only in 2026.1 are not covered yet (see "Target Parts").
| Database | Dies |
|---|---|
| Series7 (14) | xa7s15, xa7a12t, xa7s25, xa7a15t, xa7z010, xc7z012s, xa7s50, xa7z020, xa7a100t, xa7s100, xa7z030, xc7k70t, xc7k160t, xc7a200t |
| UltraScale (2) | xcku025, xcku035 |
| UltraScale+ (13) | xaau7p, xazu1eg, xaau10p, xazu2eg, xazu3teg, xcku3p, xczu4cg, xazu4ev, xcau20p, xck26, xazu7ev, xczu7cg, xcu25 |
build/meta/die_groups.json lists which device uses which die.
Each database is checked against held-out designs. A set bit is undocumented when no feature of that design explains it. A bit is unowned when it isn't covered by any tile in the tile grid. The table shows the median number of distinct undocumented bits per held-out design (8-20 designs per die, each with 0.2-4 million set bits):
| Database | Median distinct undocumented bits per design | Unowned bits |
|---|---|---|
| Series7 | 2 (xa7s15) to 45 (xc7k160t); most dies 6-36 | 0, except xc7a200t (210 in 3 of 20 designs, GTP column placement, being fixed) |
| UltraScale+, large dies | 44 (xazu3teg) to 110 (xazu7ev) | 0, except xazu3teg (7) |
| UltraScale+, small dies and xcu25 | 260 (xazu1eg) to 511 (xazu2eg); xcu25 307 | 0 |
| UltraScale | xcku035 1050, xcku025 2109 | 462 / 868 |
Series7 is close to complete. The remaining bits are mostly rare routing
bits in INT/CLB tiles, plus the CFG_CENTER bits that depend on whether the
STARTUPE2 GTS pin is driven or tied. The new hard block pin driver features
(<site>.PIN.<pin>=SIGNAL|GND|VCC) are expected to explain the CFG_CENTER
bits once new design rounds are dumped with them.
UltraScale is the least complete. Recent fixes to the model of parked (undriven) interconnect muxes cut xcku025's distinct undocumented bits in the CI regression run from 78,097 to 49,446. The open classes are:
- INT and RCLK_INT_L leaf clock bits.
- XIPHY/HPIO unused pin programming.
- Designs that fail to place or route on xcku025.
The last full production check on xcku025 covered only 9 designs.
- No independent review of the databases has been done yet. That review is the final acceptance step.
- The remaining undocumented bit classes listed above.
- The databases do not yet include the mux groups (bits that must be clear when another input of the same mux is selected), tile connectivity or package pins that tools need to write bitstreams.
See generic/README.md for how to run the flow. It
covers the steps and tools, memory limits (generic/vrun.sh), the CI
regression (generic/ci.sh) and the rebuild scripts in generic/runs/.
The target is every 7-series, UltraScale and UltraScale+ part that is free in either supported Vivado version, so that anyone can reproduce the databases and contribute: the WebPACK edition of Vivado 2025.2 or the (free, licensed) BASIC tier of Vivado 2026.1. These are 157 devices: 100 free in both, 9 in 2025.2 only (marked †) and 48 in 2026.1 only (marked ‡). Devices that share a die (a different speed grade, temperature grade, package, or feature subset such as CG/EG/EV) share its tile grid and bit database.
The generic/ flow covers 102 of them, on 29 distinct dies (see "Current
status" above for how complete each database is); the others are listed
under "Not yet covered".
Which devices are free was checked per version (2026-09-29): in 2025.2 from
the parts' LICENSE property (Webpack, or no licence for the older 7-series
parts, except XC7Z045, which synthesis rejects without a licence); in 2026.1,
where every part reports LICENSE=Full and the tier is decided by the
licence, by synthesising a small design on every installed device with the
BASIC licence (all 148 installed devices pass) and taking a few of the larger
ones through to a bitstream.
In the lists below, devices separated by ; are on different dies and devices
separated by , share a die. The die that the flow fuzzes is named first.
build/meta/die_groups.json has the full mapping, including the packages
used.
- XCKU025; XCKU035
- None. Virtex UltraScale devices are not free and are not targeted.
- XCKU3P, XCKU5P
- XAAU7P, XCAU7P; XAAU10P, XAAU15P, XCAU10P, XCAU15P; XCAU20P, XCAU25P
- None as such; the Alveo cards below use Virtex UltraScale+ dies.
- XAZU1EG, XCZU1CG, XCZU1EG
- XAZU2EG, XAZU3EG, XCZU2CG, XCZU2EG, XCZU3CG, XCZU3EG, XCK24
- XAZU3TEG, XCZU3TCG, XCZU3TEG
- XCZU4CG, XCZU4EG, XCZU5CG, XCZU5EG
- XAZU4EV, XAZU5EV, XCZU4EV, XCZU5EV
- XCZU7CG, XCZU7EG
- XAZU7EV, XCZU7EV, XCU30†
- XCK26 (Kria K26 SOM)
- XCU25† (Alveo)
- Spartan-7: XA7S15, XA7S6, XC7S15, XC7S6; XA7S25, XC7S25; XA7S50, XC7S50; XA7S100, XA7S75, XC7S100, XC7S75
- Artix-7: XA7A12T, XA7A25T, XC7A12T, XC7A25T; XA7A15T, XA7A35T, XA7A50T, XC7A15T, XC7A35T, XC7A50T; XA7A100T, XA7A75T, XC7A100T, XC7A75T; XC7A200T (all with their -I/-L variants)
- Kintex-7: XC7K70T; XC7K160T
- Zynq-7000: XA7Z010, XC7Z007S, XC7Z010; XC7Z012S, XC7Z015; XA7Z020, XC7Z014S, XC7Z020; XA7Z030, XC7Z030
Free parts the generic/ flow does not build databases for yet (their dies
have not been grouped or fuzzed):
- Spartan UltraScale+‡: XCSU10P, XCSU25P, XCSU35P, XASU35P, XCSU45P, XCSU60P, XCSU150P, XCSU200P (a new architecture family for the flow)
- Kintex-7‡: XC7K325T, XC7K355T, XC7K410T, XC7K420T, XC7K480T (with -I/-L variants), XQ7K325T(L), XQ7K410T(L)
- Zynq-7000‡: XC7Z035, XC7Z045, XC7Z100 (with -I variants), XQ7Z045, XQ7Z100
- Zynq UltraScale+ MPSoC‡: XCZU6CG, XCZU6EG
- Alveo† (Virtex UltraScale+, HBM and 58G dies; large, multi-SLR): XCU26, XCUX35, XCU50, XCU55C, XCU55N, XCU200, XCU250
- Variants‡ of devices on dies the flow already covers (by device name; the die grouping has not been run with 2026.1): XA7K160T, XQ7A50T, XQ7A100T, XQ7A200T, XQ7Z020, XQ7Z030, XQKU5P, XQZU3EG, XQZU4EG, XQZU5EV, XQZU7EV
The † parts are not part of the 2026.1 install, the ‡ parts not part of the 2025.2 WebPACK edition. The Versal XCV80 (free in 2025.2) is not targeted.
Some boards with parts on the covered dies:
| Board | Maker | Part |
|---|---|---|
| Ultra96-V2 | Avnet | Zynq UltraScale+ MPSoC ZU3EG |
| Genesys ZU | Digilent | Zynq UltraScale+ MPSoC ZU3EG |
| Kria KV260 Vision AI Starter Kit | AMD | Kria K26 SOM (XCK26) |
There are a couple of guidelines when contributing to Project U-Ray which are listed here.
All contributions should be sent as GitHub Pull requests against f4pga/prjuray.
Changes to the generic/ flow should keep the regression run unchanged,
or improve it, on its three small test dies (xa7s15, xazu1eg, xcku025):
run generic/ci.sh, and include its before/after table in the pull
request whenever the numbers change. Run Vivado and the database tools
through generic/vrun.sh, which gives each job its own memory capped
systemd scope; see generic/README.md.
All software (code, associated documentation, support files, etc) in the
Project U-Ray repository are licensed under the very permissive
Apache-2.0 License. A copy can be found in the LICENSE file.
All new contributions must also be released under this license.
By contributing you agree to follow our code of conduct. We follow the open source best practice of using the Contributor Covenant as our Code of Conduct.
To improve tracking of who did what, we follow the Linux Kernel's "sign your work" system. This is also called a "DCO" or "Developer's Certificate of Origin".
All commits are required to include this sign off and we use the Probot DCO App to check pull requests for this.
The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as a open-source patch. The rules are pretty simple: if you can certify the below:
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
then you just add a line saying
Signed-off-by: Random J Developer <random@developer.example.org>
using your real name (sorry, no pseudonyms or anonymous contributions.)
You can add the signoff as part of your commit statement. For example:
git commit --signoff -a -m "Fixed some errors."
Hint: If you've forgotten to add a signoff to one or more commits, you can use the following command to add signoffs to all commits between you and the upstream master:
git rebase --signoff upstream/master
The Sphinx documentation lives in docs/. Build it with
make -C docs html after installing docs/requirements.txt.