Viaduct API for a hybrid between generic and full-custom arch

Signed-off-by: gatecat <gatecat@ds0.me>

18 files changed, 1055 insertions, 28 deletions

diff --git a/generic/arch.cc b/generic/arch.cc
index d899bd0b..ad054efd 100644
--- a/generic/arch.cc
+++ b/generic/arch.cc
@@ -25,6 +25,7 @@
 #include "router1.h"
 #include "router2.h"
 #include "util.h"
+#include "viaduct_api.h"
 
 NEXTPNR_NAMESPACE_BEGIN
 
@@ -285,6 +286,8 @@ uint32_t Arch::getBelChecksum(BelId bel) const
 
 void Arch::bindBel(BelId bel, CellInfo *cell, PlaceStrength strength)
 {
+    if (uarch)
+        uarch->notifyBelChange(bel, cell);
     bel_info(bel).bound_cell = cell;
     cell->bel = bel;
     cell->belStrength = strength;
@@ -293,6 +296,8 @@ void Arch::bindBel(BelId bel, CellInfo *cell, PlaceStrength strength)
 
 void Arch::unbindBel(BelId bel)
 {
+    if (uarch)
+        uarch->notifyBelChange(bel, nullptr);
     auto &bi = bel_info(bel);
     bi.bound_cell->bel = BelId();
     bi.bound_cell->belStrength = STRENGTH_NONE;
@@ -300,7 +305,10 @@ void Arch::unbindBel(BelId bel)
     refreshUiBel(bel);
 }
 
-bool Arch::checkBelAvail(BelId bel) const { return bel_info(bel).bound_cell == nullptr; }
+bool Arch::checkBelAvail(BelId bel) const
+{
+    return (!uarch || uarch->checkBelAvail(bel)) && (bel_info(bel).bound_cell == nullptr);
+}
 
 CellInfo *Arch::getBoundBelCell(BelId bel) const { return bel_info(bel).bound_cell; }
 
@@ -359,6 +367,8 @@ uint32_t Arch::getWireChecksum(WireId wire) const { return wire.index; }
 
 void Arch::bindWire(WireId wire, NetInfo *net, PlaceStrength strength)
 {
+    if (uarch)
+        uarch->notifyWireChange(wire, net);
     wire_info(wire).bound_net = net;
     net->wires[wire].pip = PipId();
     net->wires[wire].strength = strength;
@@ -371,16 +381,22 @@ void Arch::unbindWire(WireId wire)
 
     auto pip = net_wires.at(wire).pip;
     if (pip != PipId()) {
+        if (uarch)
+            uarch->notifyPipChange(pip, nullptr);
         pip_info(pip).bound_net = nullptr;
         refreshUiPip(pip);
     }
 
+    uarch->notifyWireChange(wire, nullptr);
     net_wires.erase(wire);
     wire_info(wire).bound_net = nullptr;
     refreshUiWire(wire);
 }
 
-bool Arch::checkWireAvail(WireId wire) const { return wire_info(wire).bound_net == nullptr; }
+bool Arch::checkWireAvail(WireId wire) const
+{
+    return (!uarch || uarch->checkWireAvail(wire)) && (wire_info(wire).bound_net == nullptr);
+}
 
 NetInfo *Arch::getBoundWireNet(WireId wire) const { return wire_info(wire).bound_net; }
 
@@ -413,6 +429,10 @@ uint32_t Arch::getPipChecksum(PipId pip) const { return pip.index; }
 void Arch::bindPip(PipId pip, NetInfo *net, PlaceStrength strength)
 {
     WireId wire = pip_info(pip).dstWire;
+    if (uarch) {
+        uarch->notifyPipChange(pip, net);
+        uarch->notifyWireChange(wire, net);
+    }
     pip_info(pip).bound_net = net;
     wire_info(wire).bound_net = net;
     net->wires[wire].pip = pip;
@@ -424,6 +444,10 @@ void Arch::bindPip(PipId pip, NetInfo *net, PlaceStrength strength)
 void Arch::unbindPip(PipId pip)
 {
     WireId wire = pip_info(pip).dstWire;
+    if (uarch) {
+        uarch->notifyPipChange(pip, nullptr);
+        uarch->notifyWireChange(wire, nullptr);
+    }
     wire_info(wire).bound_net->wires.erase(wire);
     pip_info(pip).bound_net = nullptr;
     wire_info(wire).bound_net = nullptr;
@@ -431,10 +455,15 @@ void Arch::unbindPip(PipId pip)
     refreshUiWire(wire);
 }
 
-bool Arch::checkPipAvail(PipId pip) const { return pip_info(pip).bound_net == nullptr; }
+bool Arch::checkPipAvail(PipId pip) const
+{
+    return (!uarch || uarch->checkPipAvail(pip)) && (pip_info(pip).bound_net == nullptr);
+}
 
 bool Arch::checkPipAvailForNet(PipId pip, NetInfo *net) const
 {
+    if (uarch && !uarch->checkPipAvailForNet(pip, net))
+        return false;
     NetInfo *bound_net = pip_info(pip).bound_net;
     return bound_net == nullptr || bound_net == net;
 }
@@ -488,6 +517,8 @@ const std::vector<GroupId> &Arch::getGroupGroups(GroupId group) const { return g
 
 delay_t Arch::estimateDelay(WireId src, WireId dst) const
 {
+    if (uarch)
+        return uarch->estimateDelay(src, dst);
     const WireInfo &s = wire_info(src);
     const WireInfo &d = wire_info(dst);
     int dx = abs(s.x - d.x);
@@ -497,8 +528,8 @@ delay_t Arch::estimateDelay(WireId src, WireId dst) const
 
 delay_t Arch::predictDelay(BelId src_bel, IdString src_pin, BelId dst_bel, IdString dst_pin) const
 {
-    NPNR_UNUSED(src_pin);
-    NPNR_UNUSED(dst_pin);
+    if (uarch)
+        return uarch->predictDelay(src_bel, src_pin, dst_bel, dst_pin);
     auto driver_loc = getBelLocation(src_bel);
     auto sink_loc = getBelLocation(dst_bel);
 
@@ -511,6 +542,8 @@ bool Arch::getBudgetOverride(const NetInfo *net_info, const PortRef &sink, delay
 
 ArcBounds Arch::getRouteBoundingBox(WireId src, WireId dst) const
 {
+    if (uarch)
+        return uarch->getRouteBoundingBox(src, dst);
     ArcBounds bb;
 
     int src_x = wire_info(src).x;
@@ -537,6 +570,8 @@ ArcBounds Arch::getRouteBoundingBox(WireId src, WireId dst) const
 
 bool Arch::place()
 {
+    if (uarch)
+        uarch->prePlace();
     std::string placer = str_or_default(settings, id("placer"), defaultPlacer);
     if (placer == "heap") {
         bool have_iobuf_or_constr = false;
@@ -548,7 +583,7 @@ bool Arch::place()
             }
         }
         bool retVal;
-        if (!have_iobuf_or_constr) {
+        if (!have_iobuf_or_constr && !uarch) {
             log_warning("Unable to use HeAP due to a lack of IO buffers or constrained cells as anchors; reverting to "
                         "SA.\n");
             retVal = placer1(getCtx(), Placer1Cfg(getCtx()));
@@ -557,11 +592,15 @@ bool Arch::place()
             cfg.ioBufTypes.insert(id("GENERIC_IOB"));
             retVal = placer_heap(getCtx(), cfg);
         }
+        if (uarch)
+            uarch->postPlace();
         getCtx()->settings[getCtx()->id("place")] = 1;
         archInfoToAttributes();
         return retVal;
     } else if (placer == "sa") {
         bool retVal = placer1(getCtx(), Placer1Cfg(getCtx()));
+        if (uarch)
+            uarch->postPlace();
         getCtx()->settings[getCtx()->id("place")] = 1;
         archInfoToAttributes();
         return retVal;
@@ -572,6 +611,8 @@ bool Arch::place()
 
 bool Arch::route()
 {
+    if (uarch)
+        uarch->preRoute();
     std::string router = str_or_default(settings, id("router"), defaultRouter);
     bool result;
     if (router == "router1") {
@@ -582,6 +623,8 @@ bool Arch::route()
     } else {
         log_error("iCE40 architecture does not support router '%s'\n", router.c_str());
     }
+    if (uarch)
+        uarch->postRoute();
     getCtx()->settings[getCtx()->id("route")] = 1;
     archInfoToAttributes();
     return result;
@@ -644,6 +687,8 @@ TimingClockingInfo Arch::getPortClockingInfo(const CellInfo *cell, IdString port
 
 bool Arch::isBelLocationValid(BelId bel) const
 {
+    if (uarch)
+        return uarch->isBelLocationValid(bel);
     std::vector<const CellInfo *> cells;
     Loc loc = getBelLocation(bel);
     for (auto tbel : getBelsByTile(loc.x, loc.y)) {
@@ -671,6 +716,7 @@ const std::vector<std::string> Arch::availableRouters = {"router1", "router2"};
 
 void Arch::assignArchInfo()
 {
+    int index = 0;
     for (auto &cell : getCtx()->cells) {
         CellInfo *ci = cell.second.get();
         if (ci->type == id("GENERIC_SLICE")) {
@@ -684,6 +730,8 @@ void Arch::assignArchInfo()
         for (auto &p : ci->ports)
             if (!ci->bel_pins.count(p.first))
                 ci->bel_pins.emplace(p.first, std::vector<IdString>{p.first});
+        ci->flat_index = index;
+        ++index;
     }
 }
 
diff --git a/generic/arch.h b/generic/arch.h
index 885089ca..e96853f1 100644
--- a/generic/arch.h
+++ b/generic/arch.h
@@ -23,10 +23,12 @@
 #include <map>
 
 #include "arch_api.h"
+#include "base_arch.h"
 #include "idstring.h"
 #include "idstringlist.h"
 #include "nextpnr_namespaces.h"
 #include "nextpnr_types.h"
+#include "viaduct_api.h"
 
 NEXTPNR_NAMESPACE_BEGIN
 
@@ -126,7 +128,7 @@ template <typename TId> struct linear_range
     iterator end() const { return iterator(size); }
 };
 
-struct ArchRanges
+struct ArchRanges : BaseArchRanges
 {
     using ArchArgsT = ArchArgs;
     // Bels
@@ -158,9 +160,10 @@ struct ArchRanges
     using BucketBelRangeT = std::vector<BelId>;
 };
 
-struct Arch : ArchAPI<ArchRanges>
+struct Arch : BaseArch<ArchRanges>
 {
     std::string chipName;
+    std::unique_ptr<ViaductAPI> uarch{};
 
     std::vector<WireInfo> wires;
     std::vector<PipInfo> pips;
@@ -325,6 +328,8 @@ struct Arch : ArchAPI<ArchRanges>
 
     std::vector<IdString> getCellTypes() const override
     {
+        if (uarch)
+            return uarch->getCellTypes();
         pool<IdString> cell_types;
         for (auto bel : bels) {
             cell_types.insert(bel.type);
@@ -339,9 +344,15 @@ struct Arch : ArchAPI<ArchRanges>
 
     BelBucketId getBelBucketByName(IdString bucket) const override { return bucket; }
 
-    BelBucketId getBelBucketForBel(BelId bel) const override { return getBelType(bel); }
+    BelBucketId getBelBucketForBel(BelId bel) const override
+    {
+        return uarch ? uarch->getBelBucketForBel(bel) : getBelType(bel);
+    }
 
-    BelBucketId getBelBucketForCellType(IdString cell_type) const override { return cell_type; }
+    BelBucketId getBelBucketForCellType(IdString cell_type) const override
+    {
+        return uarch ? uarch->getBelBucketForCellType(cell_type) : cell_type;
+    }
 
     std::vector<BelId> getBelsInBucket(BelBucketId bucket) const override
     {
@@ -366,19 +377,11 @@ struct Arch : ArchAPI<ArchRanges>
     // Get the TimingClockingInfo of a port
     TimingClockingInfo getPortClockingInfo(const CellInfo *cell, IdString port, int index) const override;
 
-    bool isValidBelForCellType(IdString cell_type, BelId bel) const override { return cell_type == getBelType(bel); }
-    bool isBelLocationValid(BelId bel) const override;
-
-    // TODO
-    CellInfo *getClusterRootCell(ClusterId cluster) const override { NPNR_ASSERT_FALSE("unimplemented"); }
-    ArcBounds getClusterBounds(ClusterId cluster) const override { NPNR_ASSERT_FALSE("unimplemented"); }
-    Loc getClusterOffset(const CellInfo *cell) const override { NPNR_ASSERT_FALSE("unimplemented"); }
-    bool isClusterStrict(const CellInfo *cell) const override { NPNR_ASSERT_FALSE("unimplemented"); }
-    bool getClusterPlacement(ClusterId cluster, BelId root_bel,
-                             std::vector<std::pair<CellInfo *, BelId>> &placement) const override
+    bool isValidBelForCellType(IdString cell_type, BelId bel) const override
     {
-        NPNR_ASSERT_FALSE("unimplemented");
+        return uarch ? uarch->isValidBelForCellType(cell_type, bel) : cell_type == getBelType(bel);
     }
+    bool isBelLocationValid(BelId bel) const override;
 
     static const std::string defaultPlacer;
     static const std::vector<std::string> availablePlacers;
diff --git a/generic/archdefs.h b/generic/archdefs.h
index 2d46c0a2..4e91ffd3 100644
--- a/generic/archdefs.h
+++ b/generic/archdefs.h
@@ -20,6 +20,7 @@
 #ifndef GENERIC_ARCHDEFS_H
 #define GENERIC_ARCHDEFS_H
 
+#include "base_clusterinfo.h"
 #include "hashlib.h"
 #include "idstringlist.h"
 
@@ -74,7 +75,7 @@ struct ArchNetInfo
 
 struct NetInfo;
 
-struct ArchCellInfo
+struct ArchCellInfo : BaseClusterInfo
 {
     // Custom grouping set via "PACK_GROUP" attribute. All cells with the same group
     // value may share a tile (-1 = don't care, default if not set)
@@ -83,6 +84,8 @@ struct ArchCellInfo
     bool is_slice;
     // Only packing rule for slice type primitives is a single clock per tile
     const NetInfo *slice_clk;
+    // A flat index for cells; so viaduct uarches can have their own fast flat arrays of per-cell validity-related data
+    int flat_index;
     // Cell to bel pin mapping
     dict<IdString, std::vector<IdString>> bel_pins;
 };
diff --git a/generic/family.cmake b/generic/family.cmake
index e69de29b..cd4e3801 100644
--- a/generic/family.cmake
+++ b/generic/family.cmake
@@ -0,0 +1,7 @@
+set(VIADUCT_UARCHES "example")
+foreach(uarch ${VIADUCT_UARCHES})
+    aux_source_directory(${family}/viaduct/${uarch} UARCH_FILES)
+    foreach(target ${family_targets})
+        target_sources(${target} PRIVATE ${UARCH_FILES})
+    endforeach()
+endforeach(uarch)
diff --git a/generic/main.cc b/generic/main.cc
index 387df6c6..d08ae381 100644
--- a/generic/main.cc
+++ b/generic/main.cc
@@ -44,8 +44,10 @@ GenericCommandHandler::GenericCommandHandler(int argc, char **argv) : CommandHan
 
 po::options_description GenericCommandHandler::getArchOptions()
 {
+    std::string all_uarches = ViaductArch::list();
+    std::string uarch_help = stringf("viaduct micro-arch to use (available: %s)", all_uarches.c_str());
     po::options_description specific("Architecture specific options");
-    specific.add_options()("generic", "set device type to generic");
+    specific.add_options()("uarch", po::value<std::string>(), uarch_help.c_str());
     specific.add_options()("no-iobs", "disable automatic IO buffer insertion");
     return specific;
 }
@@ -63,6 +65,17 @@ std::unique_ptr<Context> GenericCommandHandler::createContext(dict<std::string,
     auto ctx = std::unique_ptr<Context>(new Context(chipArgs));
     if (vm.count("no-iobs"))
         ctx->settings[ctx->id("disable_iobs")] = Property::State::S1;
+    if (vm.count("uarch")) {
+        std::string uarch_name = vm["uarch"].as<std::string>();
+        dict<std::string, std::string> args; // TODO
+        auto uarch = ViaductArch::create(uarch_name, args);
+        if (!uarch) {
+            std::string all_uarches = ViaductArch::list();
+            log_error("Unknown viaduct uarch '%s'; available options: '%s'\n", uarch_name.c_str(), all_uarches.c_str());
+        }
+        ctx->uarch = std::move(uarch);
+        ctx->uarch->init(ctx.get());
+    }
     return ctx;
 }
 
diff --git a/generic/pack.cc b/generic/pack.cc
index 32dae553..291a528d 100644
--- a/generic/pack.cc
+++ b/generic/pack.cc
@@ -276,12 +276,16 @@ bool Arch::pack()
     Context *ctx = getCtx();
     try {
         log_break();
-        pack_constants(ctx);
-        pack_io(ctx);
-        pack_lut_lutffs(ctx);
-        pack_nonlut_ffs(ctx);
-        ctx->settings[ctx->id("pack")] = 1;
+        if (uarch) {
+            uarch->pack();
+        } else {
+            pack_constants(ctx);
+            pack_io(ctx);
+            pack_lut_lutffs(ctx);
+            pack_nonlut_ffs(ctx);
+        }
         ctx->assignArchInfo();
+        ctx->settings[ctx->id("pack")] = 1;
         log_info("Checksum: 0x%08x\n", ctx->checksum());
         return true;
     } catch (log_execution_error_exception) {
diff --git a/generic/viaduct/example/.gitignore b/generic/viaduct/example/.gitignore
new file mode 100644
index 00000000..a6c57f5f
--- /dev/null
+++ b/generic/viaduct/example/.gitignore
@@ -0,0 +1 @@
+*.json
diff --git a/generic/viaduct/example/constids.inc b/generic/viaduct/example/constids.inc
new file mode 100644
index 00000000..b40d5be8
--- /dev/null
+++ b/generic/viaduct/example/constids.inc
@@ -0,0 +1,14 @@
+X(LUT4)
+X(DFF)
+X(CLK)
+X(D)
+X(F)
+X(Q)
+X(INBUF)
+X(OUTBUF)
+X(I)
+X(EN)
+X(O)
+X(IOB)
+X(PAD)
+X(INIT)
diff --git a/generic/viaduct/example/example.cc b/generic/viaduct/example/example.cc
new file mode 100644
index 00000000..3d1c201c
--- /dev/null
+++ b/generic/viaduct/example/example.cc
@@ -0,0 +1,306 @@
+/*
+ *  nextpnr -- Next Generation Place and Route
+ *
+ *  Copyright (C) 2021  gatecat <gatecat@ds0.me>
+ *
+ *  Permission to use, copy, modify, and/or distribute this software for any
+ *  purpose with or without fee is hereby granted, provided that the above
+ *  copyright notice and this permission notice appear in all copies.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ *  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ *  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ *  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ *  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ *  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ *  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ */
+
+#include "log.h"
+#include "nextpnr.h"
+#include "util.h"
+#include "viaduct_api.h"
+#include "viaduct_helpers.h"
+
+#define GEN_INIT_CONSTIDS
+#define VIADUCT_CONSTIDS "viaduct/example/constids.inc"
+#include "viaduct_constids.h"
+
+NEXTPNR_NAMESPACE_BEGIN
+
+namespace {
+struct ExampleImpl : ViaductAPI
+{
+    ~ExampleImpl(){};
+    void init(Context *ctx) override
+    {
+        init_uarch_constids(ctx);
+        ViaductAPI::init(ctx);
+        h.init(ctx);
+        init_wires();
+        init_bels();
+        init_pips();
+    }
+
+    void pack() override
+    {
+        // Trim nextpnr IOBs - assume IO buffer insertion has been done in synthesis
+        const pool<CellTypePort> top_ports{
+                CellTypePort(id_INBUF, id_PAD),
+                CellTypePort(id_OUTBUF, id_PAD),
+        };
+        h.remove_nextpnr_iobs(top_ports);
+        // Replace constants with LUTs
+        const dict<IdString, Property> vcc_params = {{id_INIT, Property(0xFFFF, 16)}};
+        const dict<IdString, Property> gnd_params = {{id_INIT, Property(0x0000, 16)}};
+        h.replace_constants(CellTypePort(id_LUT4, id_F), CellTypePort(id_LUT4, id_F), vcc_params, gnd_params);
+        // Constrain directly connected LUTs and FFs together to use dedicated resources
+        int lutffs = h.constrain_cell_pairs(pool<CellTypePort>{{id_LUT4, id_F}}, pool<CellTypePort>{{id_DFF, id_D}}, 1);
+        log_info("Constrained %d LUTFF pairs.\n", lutffs);
+    }
+
+    void prePlace() override { assign_cell_info(); }
+
+    bool isBelLocationValid(BelId bel) const override
+    {
+        Loc l = ctx->getBelLocation(bel);
+        if (is_io(l.x, l.y)) {
+            return true;
+        } else {
+            return slice_valid(l.x, l.y, l.z / 2);
+        }
+    }
+
+  private:
+    ViaductHelpers h;
+    // Configuration
+    // Grid size including IOBs at edges
+    const int X = 32, Y = 32;
+    // SLICEs per tile
+    const int N = 8;
+    // LUT input count
+    const int K = 4;
+    // Number of local wires
+    const int Wl = N * (K + 1) + 8;
+    // 1/Fc for bel input wire pips; local wire pips and neighbour pips
+    const int Si = 4, Sq = 4, Sl = 8;
+
+    // For fast wire lookups
+    struct TileWires
+    {
+        std::vector<WireId> clk, q, f, d, i;
+        std::vector<WireId> l;
+        std::vector<WireId> pad;
+    };
+
+    std::vector<std::vector<TileWires>> wires_by_tile;
+
+    // Create wires to attach to bels and pips
+    void init_wires()
+    {
+        log_info("Creating wires...\n");
+        wires_by_tile.resize(Y);
+        for (int y = 0; y < Y; y++) {
+            auto &row_wires = wires_by_tile.at(y);
+            row_wires.resize(X);
+            for (int x = 0; x < X; x++) {
+                auto &w = row_wires.at(x);
+                for (int z = 0; z < N; z++) {
+                    // Clock input
+                    w.clk.push_back(ctx->addWire(h.xy_id(x, y, ctx->id(stringf("CLK%d", z))), ctx->id("CLK"), x, y));
+                    // FF input
+                    w.d.push_back(ctx->addWire(h.xy_id(x, y, ctx->id(stringf("D%d", z))), ctx->id("D"), x, y));
+                    // FF and LUT outputs
+                    w.q.push_back(ctx->addWire(h.xy_id(x, y, ctx->id(stringf("Q%d", z))), ctx->id("Q"), x, y));
+                    w.f.push_back(ctx->addWire(h.xy_id(x, y, ctx->id(stringf("F%d", z))), ctx->id("F"), x, y));
+                    // LUT inputs
+                    for (int i = 0; i < K; i++)
+                        w.i.push_back(
+                                ctx->addWire(h.xy_id(x, y, ctx->id(stringf("L%dI%d", z, i))), ctx->id("I"), x, y));
+                }
+                // Local wires
+                for (int l = 0; l < Wl; l++)
+                    w.l.push_back(ctx->addWire(h.xy_id(x, y, ctx->id(stringf("LOCAL%d", l))), ctx->id("LOCAL"), x, y));
+                // Pad wires for IO
+                if (is_io(x, y) && x != y)
+                    for (int z = 0; z < 2; z++)
+                        w.pad.push_back(ctx->addWire(h.xy_id(x, y, ctx->id(stringf("PAD%d", z))), id_PAD, x, y));
+            }
+        }
+    }
+    bool is_io(int x, int y) const
+    {
+        // IO are on the edges of the device
+        return (x == 0) || (x == (X - 1)) || (y == 0) || (y == (Y - 1));
+    }
+    // Create IO bels in an IO tile
+    void add_io_bels(int x, int y)
+    {
+        auto &w = wires_by_tile.at(y).at(x);
+        for (int z = 0; z < 2; z++) {
+            BelId b = ctx->addBel(h.xy_id(x, y, ctx->id(stringf("IO%d", z))), id_IOB, Loc(x, y, z), false, false);
+            ctx->addBelInout(b, id_PAD, w.pad.at(z));
+            ctx->addBelInput(b, id_I, w.i.at(z * K + 0));
+            ctx->addBelInput(b, id_EN, w.i.at(z * K + 1));
+            ctx->addBelOutput(b, id_O, w.q.at(z));
+        }
+    }
+    PipId add_pip(Loc loc, WireId src, WireId dst, delay_t delay = 0.05)
+    {
+        IdStringList name = IdStringList::concat(ctx->getWireName(dst), ctx->getWireName(src));
+        return ctx->addPip(name, ctx->id("PIP"), src, dst, delay, loc);
+    }
+    // Create LUT and FF bels in a logic tile
+    void add_slice_bels(int x, int y)
+    {
+        auto &w = wires_by_tile.at(y).at(x);
+        for (int z = 0; z < N; z++) {
+            // Create LUT bel
+            BelId lut = ctx->addBel(h.xy_id(x, y, ctx->id(stringf("SLICE%d_LUT", z))), id_LUT4, Loc(x, y, z * 2), false,
+                                    false);
+            for (int k = 0; k < K; k++)
+                ctx->addBelInput(lut, ctx->id(stringf("I[%d]", k)), w.i.at(z * K + k));
+            ctx->addBelOutput(lut, id_F, w.f.at(z));
+            // FF data can come from LUT output or LUT I3
+            add_pip(Loc(x, y, 0), w.f.at(z), w.d.at(z));
+            add_pip(Loc(x, y, 0), w.i.at(z * K + (K - 1)), w.d.at(z));
+            // Create DFF bel
+            BelId dff = ctx->addBel(h.xy_id(x, y, ctx->id(stringf("SLICE%d_FF", z))), id_DFF, Loc(x, y, z * 2 + 1),
+                                    false, false);
+            ctx->addBelInput(dff, id_CLK, w.clk.at(z));
+            ctx->addBelInput(dff, id_D, w.d.at(z));
+            ctx->addBelOutput(dff, id_Q, w.q.at(z));
+        }
+    }
+    // Create bels according to tile type
+    void init_bels()
+    {
+        log_info("Creating bels...\n");
+        for (int y = 0; y < Y; y++) {
+            for (int x = 0; x < X; x++) {
+                if (is_io(x, y)) {
+                    if (x == y)
+                        continue; // don't put IO in corners
+                    add_io_bels(x, y);
+                } else {
+                    add_slice_bels(x, y);
+                }
+            }
+        }
+    }
+
+    // Create PIPs inside a tile; following an example synthetic routing pattern
+    void add_tile_pips(int x, int y)
+    {
+        auto &w = wires_by_tile.at(y).at(x);
+        Loc loc(x, y, 0);
+        auto create_input_pips = [&](WireId dst, int offset, int skip) {
+            for (int i = (offset % skip); i < Wl; i += skip)
+                add_pip(loc, w.l.at(i), dst, 0.05);
+        };
+        for (int z = 0; z < N; z++) {
+            create_input_pips(w.clk.at(z), 0, Si);
+            for (int k = 0; k < K; k++)
+                create_input_pips(w.i.at(z * K + k), k, Si);
+        }
+        auto create_output_pips = [&](WireId dst, int offset, int skip) {
+            for (int z = (offset % skip); z < N; z += skip) {
+                add_pip(loc, w.f.at(z), dst, 0.05);
+                add_pip(loc, w.q.at(z), dst, 0.05);
+            }
+        };
+        auto create_neighbour_pips = [&](WireId dst, int nx, int ny, int offset, int skip) {
+            if (nx < 0 || nx >= X)
+                return;
+            if (ny < 0 || ny >= Y)
+                return;
+            auto &nw = wires_by_tile.at(ny).at(nx);
+            for (int i = (offset % skip); i < Wl; i += skip)
+                add_pip(loc, dst, nw.l.at(i), 0.1);
+        };
+        for (int i = 0; i < Wl; i++) {
+            WireId dst = w.l.at(i);
+            create_output_pips(dst, i % Sq, Sq);
+            create_neighbour_pips(dst, x - 1, y - 1, (i + 1) % Sl, Sl);
+            create_neighbour_pips(dst, x - 1, y, (i + 2) % Sl, Sl);
+            create_neighbour_pips(dst, x - 1, y + 1, (i + 3) % Sl, Sl);
+            create_neighbour_pips(dst, x, y - 1, (i + 4) % Sl, Sl);
+            create_neighbour_pips(dst, x, y + 1, (i + 5) % Sl, Sl);
+            create_neighbour_pips(dst, x + 1, y - 1, (i + 6) % Sl, Sl);
+            create_neighbour_pips(dst, x + 1, y, (i + 7) % Sl, Sl);
+            create_neighbour_pips(dst, x + 1, y + 1, (i + 8) % Sl, Sl);
+        }
+    }
+    void init_pips()
+    {
+        log_info("Creating pips...\n");
+        for (int y = 0; y < Y; y++)
+            for (int x = 0; x < X; x++)
+                add_tile_pips(x, y);
+    }
+    // Validity checking
+    struct ExampleCellInfo
+    {
+        const NetInfo *lut_f = nullptr, *ff_d = nullptr;
+        bool lut_i3_used = false;
+    };
+    std::vector<ExampleCellInfo> fast_cell_info;
+    void assign_cell_info()
+    {
+        fast_cell_info.resize(ctx->cells.size());
+        for (auto &cell : ctx->cells) {
+            CellInfo *ci = cell.second.get();
+            auto &fc = fast_cell_info.at(ci->flat_index);
+            if (ci->type == id_LUT4) {
+                fc.lut_f = get_net_or_empty(ci, id_F);
+                fc.lut_i3_used = (get_net_or_empty(ci, ctx->id(stringf("I[%d]", K - 1))) != nullptr);
+            } else if (ci->type == id_DFF) {
+                fc.ff_d = get_net_or_empty(ci, id_D);
+            }
+        }
+    }
+    bool slice_valid(int x, int y, int z) const
+    {
+        const CellInfo *lut = ctx->getBoundBelCell(ctx->getBelByLocation(Loc(x, y, z * 2)));
+        const CellInfo *ff = ctx->getBoundBelCell(ctx->getBelByLocation(Loc(x, y, z * 2 + 1)));
+        if (!lut || !ff)
+            return true; // always valid if only LUT or FF used
+        const auto &lut_data = fast_cell_info.at(lut->flat_index);
+        const auto &ff_data = fast_cell_info.at(ff->flat_index);
+        // In our example arch; the FF D can either be driven from LUT F or LUT I3
+        // so either; FF D must equal LUT F or LUT I3 must be unused
+        if (ff_data.ff_d == lut_data.lut_f)
+            return true;
+        if (lut_data.lut_i3_used)
+            return false;
+        return true;
+    }
+    // Bel bucket functions
+    IdString getBelBucketForCellType(IdString cell_type) const override
+    {
+        if (cell_type.in(id_INBUF, id_OUTBUF))
+            return id_IOB;
+        return cell_type;
+    }
+    bool isValidBelForCellType(IdString cell_type, BelId bel) const override
+    {
+        IdString bel_type = ctx->getBelType(bel);
+        if (bel_type == id_IOB)
+            return cell_type.in(id_INBUF, id_OUTBUF);
+        else
+            return (bel_type == cell_type);
+    }
+};
+
+struct ExampleArch : ViaductArch
+{
+    ExampleArch() : ViaductArch("example"){};
+    std::unique_ptr<ViaductAPI> create(const dict<std::string, std::string> &args)
+    {
+        return std::make_unique<ExampleImpl>();
+    }
+} exampleArch;
+} // namespace
+
+NEXTPNR_NAMESPACE_END
diff --git a/generic/viaduct/example/example_map.v b/generic/viaduct/example/example_map.v
new file mode 100644
index 00000000..f701f0ed
--- /dev/null
+++ b/generic/viaduct/example/example_map.v
@@ -0,0 +1,12 @@
+module \$lut (A, Y);
+	parameter WIDTH = 0;
+	parameter LUT = 0;
+	input [WIDTH-1:0] A;
+	output Y;
+
+	localparam rep = 1<<(4-WIDTH);
+
+	LUT4 #(.INIT({rep{LUT}})) _TECHMAP_REPLACE_ (.I(A), .F(Y));
+endmodule
+
+module  \$_DFF_P_ (input D, C, output Q); DFF  _TECHMAP_REPLACE_ (.D(D), .Q(Q), .CLK(C)); endmodule
diff --git a/generic/viaduct/example/example_prims.v b/generic/viaduct/example/example_prims.v
new file mode 100644
index 00000000..d2813129
--- /dev/null
+++ b/generic/viaduct/example/example_prims.v
@@ -0,0 +1,35 @@
+module LUT4 #(
+    parameter [15:0] INIT = 0
+) (
+    input [3:0] I,
+    output F
+);
+    wire [7:0] s3 = I[3] ?     INIT[15:8] :     INIT[7:0];
+    wire [3:0] s2 = I[2] ?       s3[ 7:4] :       s3[3:0];
+    wire [1:0] s1 = I[1] ?       s2[ 3:2] :       s2[1:0];
+    assign F = I[0] ? s1[1] : s1[0];
+endmodule
+
+module DFF (
+    input CLK, D,
+    output reg Q
+);
+    initial Q = 1'b0;
+    always @(posedge CLK)
+        Q <= D;
+endmodule
+
+module INBUF (
+    input PAD,
+    output O,
+);
+    assign O = PAD;
+endmodule
+
+module OUTBUF (
+    output PAD,
+    input I,
+);
+    assign PAD = I;
+endmodule
+
diff --git a/generic/viaduct/example/synth_viaduct_example.tcl b/generic/viaduct/example/synth_viaduct_example.tcl
new file mode 100644
index 00000000..a9d18f56
--- /dev/null
+++ b/generic/viaduct/example/synth_viaduct_example.tcl
@@ -0,0 +1,24 @@
+# Usage
+# tcl synth_viaduct_example.tcl {out.json}
+
+yosys read_verilog -lib [file dirname [file normalize $argv0]]/example_prims.v
+yosys hierarchy -check
+yosys proc
+yosys flatten
+yosys tribuf -logic
+yosys deminout
+yosys synth -run coarse
+yosys memory_map
+yosys opt -full
+yosys iopadmap -bits -inpad INBUF O:PAD -outpad OUTBUF I:PAD
+yosys techmap -map +/techmap.v
+yosys opt -fast
+yosys dfflegalize -cell \$_DFF_P_ 0
+yosys abc -lut 4 -dress
+yosys clean
+yosys techmap -map [file dirname [file normalize $argv0]]/example_map.v
+yosys clean
+yosys hierarchy -check
+yosys stat
+
+if {$argc > 0} { yosys write_json [lindex $argv 0] }
diff --git a/generic/viaduct/example/viaduct_example.sh b/generic/viaduct/example/viaduct_example.sh
new file mode 100755
index 00000000..0842df20
--- /dev/null
+++ b/generic/viaduct/example/viaduct_example.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -ex
+# Run synthesis
+yosys -p "tcl synth_viaduct_example.tcl blinky.json" ../../examples/blinky.v
+# Run PnR
+${NEXTPNR:-../../../build/nextpnr-generic} --uarch example --json blinky.json
diff --git a/generic/viaduct_api.cc b/generic/viaduct_api.cc
new file mode 100644
index 00000000..8a7b6313
--- /dev/null
+++ b/generic/viaduct_api.cc
@@ -0,0 +1,118 @@
+/*
+ *  nextpnr -- Next Generation Place and Route
+ *
+ *  Copyright (C) 2021  gatecat <gatecat@ds0.me>
+ *
+ *  Permission to use, copy, modify, and/or distribute this software for any
+ *  purpose with or without fee is hereby granted, provided that the above
+ *  copyright notice and this permission notice appear in all copies.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ *  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ *  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ *  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ *  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ *  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ *  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ */
+
+#include "viaduct_api.h"
+#include "nextpnr.h"
+
+// Default implementations for Viaduct API hooks
+
+NEXTPNR_NAMESPACE_BEGIN
+
+void ViaductAPI::init(Context *ctx) { this->ctx = ctx; }
+
+std::vector<IdString> ViaductAPI::getCellTypes() const
+{
+    pool<IdString> cell_types;
+    for (auto bel : ctx->bels) {
+        cell_types.insert(bel.type);
+    }
+
+    return std::vector<IdString>{cell_types.begin(), cell_types.end()};
+}
+BelBucketId ViaductAPI::getBelBucketForBel(BelId bel) const { return ctx->getBelType(bel); }
+BelBucketId ViaductAPI::getBelBucketForCellType(IdString cell_type) const { return cell_type; }
+bool ViaductAPI::isValidBelForCellType(IdString cell_type, BelId bel) const
+{
+    return ctx->getBelType(bel) == cell_type;
+}
+
+delay_t ViaductAPI::estimateDelay(WireId src, WireId dst) const
+{
+    const WireInfo &s = ctx->wire_info(src);
+    const WireInfo &d = ctx->wire_info(dst);
+    int dx = abs(s.x - d.x);
+    int dy = abs(s.y - d.y);
+    return (dx + dy) * ctx->args.delayScale + ctx->args.delayOffset;
+}
+delay_t ViaductAPI::predictDelay(BelId src_bel, IdString src_pin, BelId dst_bel, IdString dst_pin) const
+{
+    NPNR_UNUSED(src_pin);
+    NPNR_UNUSED(dst_pin);
+    auto driver_loc = ctx->getBelLocation(src_bel);
+    auto sink_loc = ctx->getBelLocation(dst_bel);
+
+    int dx = abs(sink_loc.x - driver_loc.x);
+    int dy = abs(sink_loc.y - driver_loc.y);
+    return (dx + dy) * ctx->args.delayScale + ctx->args.delayOffset;
+}
+ArcBounds ViaductAPI::getRouteBoundingBox(WireId src, WireId dst) const
+{
+    ArcBounds bb;
+    int src_x = ctx->wire_info(src).x;
+    int src_y = ctx->wire_info(src).y;
+    int dst_x = ctx->wire_info(dst).x;
+    int dst_y = ctx->wire_info(dst).y;
+
+    bb.x0 = src_x;
+    bb.y0 = src_y;
+    bb.x1 = src_x;
+    bb.y1 = src_y;
+
+    auto extend = [&](int x, int y) {
+        bb.x0 = std::min(bb.x0, x);
+        bb.x1 = std::max(bb.x1, x);
+        bb.y0 = std::min(bb.y0, y);
+        bb.y1 = std::max(bb.y1, y);
+    };
+    extend(dst_x, dst_y);
+    return bb;
+}
+
+ViaductArch *ViaductArch::list_head;
+ViaductArch::ViaductArch(const std::string &name) : name(name)
+{
+    list_next = ViaductArch::list_head;
+    ViaductArch::list_head = this;
+}
+std::string ViaductArch::list()
+{
+    std::string result;
+    ViaductArch *cursor = ViaductArch::list_head;
+    while (cursor) {
+        if (!result.empty())
+            result += ", ";
+        result += cursor->name;
+        cursor = cursor->list_next;
+    }
+    return result;
+}
+std::unique_ptr<ViaductAPI> ViaductArch::create(const std::string &name, const dict<std::string, std::string> &args)
+{
+    ViaductArch *cursor = ViaductArch::list_head;
+    while (cursor) {
+        if (cursor->name != name) {
+            cursor = cursor->list_next;
+            continue;
+        }
+        return cursor->create(args);
+    }
+    return {};
+}
+
+NEXTPNR_NAMESPACE_END
diff --git a/generic/viaduct_api.h b/generic/viaduct_api.h
new file mode 100644
index 00000000..bc9b4311
--- /dev/null
+++ b/generic/viaduct_api.h
@@ -0,0 +1,114 @@
+/*
+ *  nextpnr -- Next Generation Place and Route
+ *
+ *  Copyright (C) 2021  gatecat <gatecat@ds0.me>
+ *
+ *  Permission to use, copy, modify, and/or distribute this software for any
+ *  purpose with or without fee is hereby granted, provided that the above
+ *  copyright notice and this permission notice appear in all copies.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ *  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ *  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ *  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ *  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ *  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ *  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ */
+
+#ifndef VIADUCT_API_H
+#define VIADUCT_API_H
+
+#include "nextpnr_namespaces.h"
+#include "nextpnr_types.h"
+
+NEXTPNR_NAMESPACE_BEGIN
+
+/*
+Viaduct -- a series of small arches
+
+Viaduct is a framework that provides an 'inbetween' step between nextpnr-generic
+using Python bindings and a full-custom arch.
+
+It allows an arch to programmatically build a set of bels (placement locations)
+and a routing graph in-memory at startup; and then hook into nextpnr's flow
+and validity checking rules at runtime with custom C++ code.
+
+To create a Viaduct 'uarch', the following are required:
+ - an implementation of ViaductAPI. At a minimum; you will need to use ctx->addBel, ctx->addWire and ctx->addPip to
+create the graph of placement and routing resources in-memory. Also implement any placement validity checking required -
+like rules for how LUTs and FFs can be placed together in a SLICE.
+ - an instance of a struct deriving from ViaductArch - this is how the uarch is discovered. Override create(args) to
+create an instance of your ViaductAPI implementation.
+ - these should be within C++ files in a new subfolder of 'viaduct'. Add the name of this subfolder to the list of
+VIADUCT_UARCHES in family.cmake if building in-tree.
+
+For an example of how these pieces fit together; see 'viaduct/example' which implements a small synthetic architecture
+using this framework.
+
+*/
+
+struct Context;
+
+struct ViaductAPI
+{
+    virtual void init(Context *ctx);
+    Context *ctx;
+
+    // --- Bel functions ---
+    // Called when a bel is placed/unplaced (with cell=nullptr for a unbind)
+    virtual void notifyBelChange(BelId bel, CellInfo *cell) {}
+    // This only needs to return false if a bel is disabled for a microarch-specific reason and not just because it's
+    // bound (which the base generic will deal with)
+    virtual bool checkBelAvail(BelId bel) const { return true; }
+    // Mirror the ArchAPI functions - see archapi.md
+    virtual std::vector<IdString> getCellTypes() const;
+    virtual BelBucketId getBelBucketForBel(BelId bel) const;
+    virtual BelBucketId getBelBucketForCellType(IdString cell_type) const;
+    virtual bool isValidBelForCellType(IdString cell_type, BelId bel) const;
+    virtual bool isBelLocationValid(BelId bel) const { return true; }
+
+    // --- Wire and pip functions ---
+    // Called when a wire/pip is placed/unplaced (with net=nullptr for a unbind)
+    virtual void notifyWireChange(WireId wire, NetInfo *net) {}
+    virtual void notifyPipChange(PipId pip, NetInfo *net) {}
+    // These only need to return false if a wire/pip is disabled for a microarch-specific reason and not just because
+    // it's bound (which the base arch will deal with)
+    virtual bool checkWireAvail(WireId wire) const { return true; }
+    virtual bool checkPipAvail(PipId pip) const { return true; }
+    virtual bool checkPipAvailForNet(PipId pip, NetInfo *net) const { return checkPipAvail(pip); };
+
+    // --- Route lookahead ---
+    virtual delay_t estimateDelay(WireId src, WireId dst) const;
+    virtual delay_t predictDelay(BelId src_bel, IdString src_pin, BelId dst_bel, IdString dst_pin) const;
+    virtual ArcBounds getRouteBoundingBox(WireId src, WireId dst) const;
+
+    // --- Flow hooks ---
+    virtual void pack(){}; // replaces the pack function
+    // Called before and after main placement and routing
+    virtual void prePlace(){};
+    virtual void postPlace(){};
+    virtual void preRoute(){};
+    virtual void postRoute(){};
+
+    virtual ~ViaductAPI(){};
+};
+
+struct ViaductArch
+{
+    static ViaductArch *list_head;
+    ViaductArch *list_next = nullptr;
+
+    std::string name;
+    ViaductArch(const std::string &name);
+    ~ViaductArch(){};
+    virtual std::unique_ptr<ViaductAPI> create(const dict<std::string, std::string> &args) = 0;
+
+    static std::string list();
+    static std::unique_ptr<ViaductAPI> create(const std::string &name, const dict<std::string, std::string> &args);
+};
+
+NEXTPNR_NAMESPACE_END
+
+#endif
diff --git a/generic/viaduct_constids.h b/generic/viaduct_constids.h
new file mode 100644
index 00000000..82180953
--- /dev/null
+++ b/generic/viaduct_constids.h
@@ -0,0 +1,74 @@
+/*
+ *  nextpnr -- Next Generation Place and Route
+ *
+ *  Copyright (C) 2021  gatecat <gatecat@ds0.me>
+ *
+ *  Permission to use, copy, modify, and/or distribute this software for any
+ *  purpose with or without fee is hereby granted, provided that the above
+ *  copyright notice and this permission notice appear in all copies.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ *  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ *  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ *  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ *  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ *  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ *  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ */
+
+#ifndef VIADUCT_CONSTIDS_H
+#define VIADUCT_CONSTIDS_H
+
+/*
+This enables use of 'constids' similar to a 'true' nextpnr arch in a viaduct uarch.
+To use:
+    - create a 'constids.inc' file in your uarch folder containing one ID per line; inside X( )
+    - set the VIADUCT_CONSTIDS macro to the path to this file relative to the generic arch base
+    - in your main file; also define GEN_INIT_CONSTIDS to create init_uarch_constids(Context*) which you should call in
+init
+    - include this file
+*/
+
+#include "nextpnr_namespaces.h"
+
+#ifdef VIADUCT_MAIN
+#include "idstring.h"
+#endif
+
+NEXTPNR_NAMESPACE_BEGIN
+
+namespace {
+#ifndef Q_MOC_RUN
+enum ConstIds
+{
+    ID_NONE
+#define X(t) , ID_##t
+#include VIADUCT_CONSTIDS
+#undef X
+    ,
+};
+
+#define X(t) static constexpr auto id_##t = IdString(ID_##t);
+#include VIADUCT_CONSTIDS
+#undef X
+#endif
+
+#ifdef GEN_INIT_CONSTIDS
+
+void init_uarch_constids(Context *ctx)
+{
+#define X(t) IdString::initialize_add(ctx, #t, ID_##t);
+
+#include VIADUCT_CONSTIDS
+
+#undef X
+}
+
+#endif
+
+} // namespace
+
+NEXTPNR_NAMESPACE_END
+
+#endif
diff --git a/generic/viaduct_helpers.cc b/generic/viaduct_helpers.cc
new file mode 100644
index 00000000..36bdd6be
--- /dev/null
+++ b/generic/viaduct_helpers.cc
@@ -0,0 +1,163 @@
+/*
+ *  nextpnr -- Next Generation Place and Route
+ *
+ *  Copyright (C) 2021  gatecat <gatecat@ds0.me>
+ *
+ *  Permission to use, copy, modify, and/or distribute this software for any
+ *  purpose with or without fee is hereby granted, provided that the above
+ *  copyright notice and this permission notice appear in all copies.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ *  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ *  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ *  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ *  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ *  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ *  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ */
+
+#include "viaduct_helpers.h"
+#include "design_utils.h"
+#include "log.h"
+#include "nextpnr.h"
+#include "util.h"
+
+NEXTPNR_NAMESPACE_BEGIN
+
+void ViaductHelpers::resize_ids(int x, int y)
+{
+    NPNR_ASSERT(x >= 0 && y >= 0 && x <= 20000 && y <= 20000);
+    while (int(x_ids.size()) <= x) {
+        IdString next = ctx->id(stringf("X%d", int(x_ids.size())));
+        x_ids.push_back(next);
+    }
+    while (int(y_ids.size()) <= y) {
+        IdString next = ctx->id(stringf("Y%d", int(y_ids.size())));
+        y_ids.push_back(next);
+    }
+}
+
+IdStringList ViaductHelpers::xy_id(int x, int y, IdString base)
+{
+    resize_ids(x, y);
+    std::array<IdString, 3> result{x_ids.at(x), y_ids.at(y), base};
+    return IdStringList(result);
+}
+
+IdStringList ViaductHelpers::xy_id(int x, int y, IdStringList base)
+{
+    resize_ids(x, y);
+    std::array<IdString, 2> prefix{x_ids.at(x), y_ids.at(y)};
+    return IdStringList::concat(IdStringList(prefix), base);
+}
+
+void ViaductHelpers::remove_nextpnr_iobs(const pool<CellTypePort> &top_ports)
+{
+    std::vector<IdString> to_remove;
+    for (auto &cell : ctx->cells) {
+        auto &ci = *cell.second;
+        if (!ci.type.in(ctx->id("$nextpnr_ibuf"), ctx->id("$nextpnr_obuf"), ctx->id("$nextpnr_iobuf")))
+            continue;
+        NetInfo *i = get_net_or_empty(&ci, ctx->id("I"));
+        if (i && i->driver.cell) {
+            if (!top_ports.count(CellTypePort(i->driver)))
+                log_error("Top-level port '%s' driven by illegal port %s.%s\n", ctx->nameOf(&ci),
+                          ctx->nameOf(i->driver.cell), ctx->nameOf(i->driver.port));
+        }
+        NetInfo *o = get_net_or_empty(&ci, ctx->id("O"));
+        if (o) {
+            for (auto &usr : o->users) {
+                if (!top_ports.count(CellTypePort(usr)))
+                    log_error("Top-level port '%s' driving illegal port %s.%s\n", ctx->nameOf(&ci),
+                              ctx->nameOf(usr.cell), ctx->nameOf(usr.port));
+            }
+        }
+        disconnect_port(ctx, &ci, ctx->id("I"));
+        disconnect_port(ctx, &ci, ctx->id("O"));
+        to_remove.push_back(ci.name);
+    }
+    for (IdString cell_name : to_remove)
+        ctx->cells.erase(cell_name);
+}
+
+int ViaductHelpers::constrain_cell_pairs(const pool<CellTypePort> &src_ports, const pool<CellTypePort> &sink_ports,
+                                         int delta_z)
+{
+    int constrained = 0;
+    for (auto &cell : ctx->cells) {
+        auto &ci = *cell.second;
+        if (ci.cluster != ClusterId())
+            continue; // don't constrain already-constrained cells
+        bool done = false;
+        for (auto &port : ci.ports) {
+            // look for starting source ports
+            if (port.second.type != PORT_OUT || !port.second.net)
+                continue;
+            if (!src_ports.count(CellTypePort(ci.type, port.first)))
+                continue;
+            for (auto &usr : port.second.net->users) {
+                if (!sink_ports.count(CellTypePort(usr)))
+                    continue;
+                if (usr.cell->cluster != ClusterId())
+                    continue;
+                // Add the constraint
+                ci.cluster = ci.name;
+                ci.constr_abs_z = false;
+                ci.constr_children.push_back(usr.cell);
+                usr.cell->cluster = ci.name;
+                usr.cell->constr_x = 0;
+                usr.cell->constr_y = 0;
+                usr.cell->constr_z = delta_z;
+                usr.cell->constr_abs_z = false;
+                ++constrained;
+                done = true;
+                break;
+            }
+            if (done)
+                break;
+        }
+    }
+    return constrained;
+}
+
+void ViaductHelpers::replace_constants(CellTypePort vcc_driver, CellTypePort gnd_driver,
+                                       const dict<IdString, Property> &vcc_params,
+                                       const dict<IdString, Property> &gnd_params)
+{
+    CellInfo *vcc_drv = ctx->createCell(ctx->id("$PACKER_VCC_DRV"), vcc_driver.cell_type);
+    vcc_drv->addOutput(vcc_driver.port);
+    for (auto &p : vcc_params)
+        vcc_drv->params[p.first] = p.second;
+
+    CellInfo *gnd_drv = ctx->createCell(ctx->id("$PACKER_GND_DRV"), gnd_driver.cell_type);
+    gnd_drv->addOutput(gnd_driver.port);
+    for (auto &p : gnd_params)
+        gnd_drv->params[p.first] = p.second;
+
+    NetInfo *vcc_net = ctx->createNet(ctx->id("$PACKER_VCC"));
+    NetInfo *gnd_net = ctx->createNet(ctx->id("$PACKER_GND"));
+
+    std::vector<IdString> trim_cells;
+    std::vector<IdString> trim_nets;
+    for (auto &net : ctx->nets) {
+        auto &ni = *net.second;
+        if (!ni.driver.cell)
+            continue;
+        if (ni.driver.cell->type != ctx->id("GND") && ni.driver.cell->type != ctx->id("VCC"))
+            continue;
+        NetInfo *replace = (ni.driver.cell->type == ctx->id("VCC")) ? vcc_net : gnd_net;
+        for (auto &usr : ni.users) {
+            usr.cell->ports.at(usr.port).net = replace;
+            replace->users.push_back(usr);
+        }
+        trim_cells.push_back(ni.driver.cell->name);
+        trim_nets.push_back(ni.name);
+    }
+    for (IdString cell_name : trim_cells)
+        ctx->cells.erase(cell_name);
+    for (IdString net_name : trim_nets)
+        ctx->nets.erase(net_name);
+}
+
+NEXTPNR_NAMESPACE_END
diff --git a/generic/viaduct_helpers.h b/generic/viaduct_helpers.h
new file mode 100644
index 00000000..8cba8411
--- /dev/null
+++ b/generic/viaduct_helpers.h
@@ -0,0 +1,82 @@
+/*
+ *  nextpnr -- Next Generation Place and Route
+ *
+ *  Copyright (C) 2021  gatecat <gatecat@ds0.me>
+ *
+ *  Permission to use, copy, modify, and/or distribute this software for any
+ *  purpose with or without fee is hereby granted, provided that the above
+ *  copyright notice and this permission notice appear in all copies.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ *  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ *  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ *  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ *  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ *  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ *  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ */
+
+#ifndef VIADUCT_HELPERS_H
+#define VIADUCT_HELPERS_H
+
+#include "nextpnr_namespaces.h"
+#include "nextpnr_types.h"
+
+NEXTPNR_NAMESPACE_BEGIN
+
+/*
+Viaduct -- a series of small arches
+
+See viaduct_api.h for more background.
+
+viaduct_helpers provides some features for building up arches using the viaduct API
+*/
+
+// Used to configure various generic pack functions
+struct CellTypePort
+{
+    CellTypePort() : cell_type(), port(){};
+    CellTypePort(IdString cell_type, IdString port) : cell_type(cell_type), port(port){};
+    explicit CellTypePort(const PortRef &net_port)
+            : cell_type(net_port.cell ? net_port.cell->type : IdString()), port(net_port.port){};
+    inline bool operator==(const CellTypePort &other) const
+    {
+        return cell_type == other.cell_type && port == other.port;
+    }
+    inline bool operator!=(const CellTypePort &other) const
+    {
+        return cell_type != other.cell_type || port != other.port;
+    }
+    inline unsigned hash() const { return mkhash(cell_type.hash(), port.hash()); }
+    IdString cell_type, port;
+};
+
+struct ViaductHelpers
+{
+    ViaductHelpers(){};
+    Context *ctx;
+    void init(Context *ctx) { this->ctx = ctx; }
+    // IdStringList components for x and y locations
+    std::vector<IdString> x_ids, y_ids;
+    void resize_ids(int x, int y);
+    // Get an IdStringList for a hierarchical ID
+    // Because this uses an IdStringList with seperate X and Y components; this will be much more efficient than
+    // creating unique strings for each object in each X and Y position
+    IdStringList xy_id(int x, int y, IdString base);
+    IdStringList xy_id(int x, int y, IdStringList base);
+    // Common packing functions
+    // Remove nextpnr-inserted IO buffers; where IO buffer insertion is done in synthesis
+    // expects a set of top-level port types
+    void remove_nextpnr_iobs(const pool<CellTypePort> &top_ports);
+    // Constrain cells with certain port connection patterns together with a fixed z-offset
+    int constrain_cell_pairs(const pool<CellTypePort> &src_ports, const pool<CellTypePort> &sink_ports, int delta_z);
+    // Replace constants with given driving cells
+    void replace_constants(CellTypePort vcc_driver, CellTypePort gnd_driver,
+                           const dict<IdString, Property> &vcc_params = {},
+                           const dict<IdString, Property> &gnd_params = {});
+};
+
+NEXTPNR_NAMESPACE_END
+
+#endif