Add a command-line flag for selecting the scheduling strategy.

docs_src/bazel_rules_macros.md

@@ -639,7 +639,7 @@ currently produced should be considered INCOMPLETE.
 load("//xls/build_rules:xls_build_defs.bzl", "cc_xls_ir_jit_wrapper")
 
 cc_xls_ir_jit_wrapper(<a href="#cc_xls_ir_jit_wrapper-name">name</a>, <a href="#cc_xls_ir_jit_wrapper-src">src</a>, <a href="#cc_xls_ir_jit_wrapper-jit_wrapper_args">jit_wrapper_args</a>, <a href="#cc_xls_ir_jit_wrapper-wrapper_type">wrapper_type</a>, <a href="#cc_xls_ir_jit_wrapper-top">top</a>, <a href="#cc_xls_ir_jit_wrapper-llvm_opt_level">llvm_opt_level</a>,
-                      <a href="#cc_xls_ir_jit_wrapper-exec_properties">exec_properties</a>, <a href="#cc_xls_ir_jit_wrapper-kwargs">**kwargs</a>)
+                      <a href="#cc_xls_ir_jit_wrapper-exec_properties">exec_properties</a>, <a href="#cc_xls_ir_jit_wrapper-tags">tags</a>, <a href="#cc_xls_ir_jit_wrapper-aot_tags">aot_tags</a>, <a href="#cc_xls_ir_jit_wrapper-kwargs">**kwargs</a>)
 </pre>
 
 Invokes the JIT wrapper generator and compiles the result as a cc_library.
@@ -661,6 +661,8 @@ identical to this macro.
 | <a id="cc_xls_ir_jit_wrapper-top"></a>top |  Name of the top function/proc/block.   |  `""` |
 | <a id="cc_xls_ir_jit_wrapper-llvm_opt_level"></a>llvm_opt_level |  what opt level to configure aot compiled code to use.   |  `3` |
 | <a id="cc_xls_ir_jit_wrapper-exec_properties"></a>exec_properties |  normal exec-properties to pass to actions.   |  `{}` |
+| <a id="cc_xls_ir_jit_wrapper-tags"></a>tags |  normal tags to pass to actions.   |  `[]` |
+| <a id="cc_xls_ir_jit_wrapper-aot_tags"></a>aot_tags |  Tags to apply to the AOT compiler only.   |  `[]` |
 | <a id="cc_xls_ir_jit_wrapper-kwargs"></a>kwargs |  Keyword arguments. Named arguments.   |  none |
 
 

docs_src/codegen_options.md

@@ -199,6 +199,22 @@ control the scheduler.
     node order and other metadata which can be used to minimize the differences
     between generated Verilog from different invocations of codegen.
 
+-   `--scheduling_strategy` controls what scheduling algorithm will be used for
+    the design.
+
+    -   `sdc`: The default constraint solver scheduler which minimizes register
+        use while respecting clock period.
+
+    -   `asap`: Fast scheduler which places nodes as early as possible. Does not
+        respect io constraints. This scheduler is meant for use during
+        development to quickly approximate the cycle accurate behavior of the
+        pipeline.
+
+    -   `min_cut`: Approximates the minimum number of registers using a min-cut
+        based algorithm. Does not respect io_constraints.
+
+    -   `random`: Internal testing algorithm that selects stages randomly.
+
 # Feedback-driven Optimization (FDO) Options
 
 The following flags control the feedback-driven optimizations in XLS. For now,

xls/build_rules/xls_internal_aot_rules.bzl

@@ -156,6 +156,7 @@ def _xls_aot_generate_impl(ctx):
         mnemonic = "AOTCompiling",
         progress_message = "Aot(JIT)Compiling %{label}: %{input}",
         toolchain = None,
+        execution_requirements = {tag: "" for tag in ctx.attr.tags},
     )
 
     # Skeleton run to create the proto file.
@@ -167,6 +168,7 @@ def _xls_aot_generate_impl(ctx):
         mnemonic = "AotSkeleton",
         progress_message = "Generating AOT skeleton %{label}: %{input}",
         toolchain = None,
+        execution_requirements = {tag: "" for tag in ctx.attr.tags},
     )
 
     obj_file_outputs = cc_common.create_compilation_outputs(

xls/build_rules/xls_jit_wrapper_rules.bzl

@@ -350,6 +350,8 @@ def cc_xls_ir_jit_wrapper(
         top = "",
         llvm_opt_level = 3,
         exec_properties = {},
+        tags = [],
+        aot_tags = [],
         **kwargs):
     """Invokes the JIT wrapper generator and compiles the result as a cc_library.
 
@@ -370,6 +372,8 @@ def cc_xls_ir_jit_wrapper(
       top: Name of the top function/proc/block.
       llvm_opt_level: what opt level to configure aot compiled code to use.
       exec_properties: normal exec-properties to pass to actions.
+      tags: normal tags to pass to actions.
+      aot_tags: Tags to apply to the AOT compiler only.
       **kwargs: Keyword arguments. Named arguments.
     """
 
@@ -400,6 +404,7 @@ def cc_xls_ir_jit_wrapper(
         llvm_opt_level = llvm_opt_level,
         top_type = wrapper_type,
         exec_properties = exec_properties,
+        tags = tags + aot_tags,
         aot_target = select({
             "@platforms//cpu:aarch64": "aarch64",
             "@platforms//cpu:x86_64": "x86_64",
@@ -419,13 +424,15 @@ def cc_xls_ir_jit_wrapper(
         source_file = source_filename,
         header_file = header_filename,
         exec_properties = exec_properties,
+        tags = tags,
         **kwargs
     )
     cc_library(
         name = name,
         srcs = [":" + source_filename],
         hdrs = [":" + header_filename],
         exec_properties = exec_properties,
+        tags = tags,
         deps = extra_lib_deps +
                _BASE_JIT_WRAPPER_DEPS[wrapper_type] + [
             "@com_google_absl//absl/status",

xls/build_rules/xls_providers.bzl

@@ -243,6 +243,14 @@ SCHEDULING_FIELDS = {
                              "is inverted.",
     "assertion_macro_names": "Names of the Verilog macros used to guard assertions. If prefixed " +
                              "with `!` the polarity of the guard is inverted.",
+    "scheduling_strategy": "The scheduler algorithm to use. Either 'SDC', 'min-cut', 'asap' or " +
+                           "'random'. The SDC scheduler is the default and is constraint based " +
+                           "to minimize registers. The others are all testing/development " +
+                           "focused schedulers. 'asap' is a fast scheduler which places each " +
+                           "node as early as possible. 'min_cut' is a scheduler which uses " +
+                           "min-cut aproximate the minimum number of registers but does not " +
+                           "respect io_constraints. 'random' is a scheduler which randomly " +
+                           "schedules nodes and is only for internal testing.",
 }
 
 _VERILOG_FIELDS = {

xls/scheduling/BUILD

@@ -99,6 +99,7 @@ cc_library(
         "//xls/passes:optimization_pass",
         "//xls/tools:scheduling_options_flags_cc_proto",
         "@com_google_absl//absl/container:flat_hash_map",
+        "@com_google_absl//absl/log",
         "@com_google_absl//absl/log:check",
         "@com_google_absl//absl/status",
         "@com_google_absl//absl/status:statusor",

xls/scheduling/scheduling_options.cc

@@ -17,14 +17,17 @@
 #include <cstdint>
 #include <limits>
 #include <string>
+#include <string_view>
 #include <utility>
 #include <variant>
 #include <vector>
 
 #include "absl/container/flat_hash_map.h"
+#include "absl/log/log.h"
 #include "absl/status/status.h"
 #include "absl/status/statusor.h"
 #include "absl/strings/numbers.h"
+#include "absl/strings/str_cat.h"
 #include "absl/strings/str_format.h"
 #include "absl/strings/str_split.h"
 #include "xls/common/status/status_macros.h"
@@ -37,13 +40,81 @@
 
 namespace xls {
 
+ProtoSchedulingStrategy ToProtoSchedulingStrategy(SchedulingStrategy strategy) {
+  switch (strategy) {
+    case SchedulingStrategy::ASAP:
+      return ProtoSchedulingStrategy::SCHEDULER_TYPE_ASAP;
+    case SchedulingStrategy::MIN_CUT:
+      return ProtoSchedulingStrategy::SCHEDULER_TYPE_MIN_CUT;
+    case SchedulingStrategy::SDC:
+      return ProtoSchedulingStrategy::SCHEDULER_TYPE_SDC;
+    case SchedulingStrategy::RANDOM:
+      return ProtoSchedulingStrategy::SCHEDULER_TYPE_RANDOM;
+  }
+}
+SchedulingStrategy FromProtoSchedulingStrategy(
+    ProtoSchedulingStrategy strategy) {
+  switch (strategy) {
+    case ProtoSchedulingStrategy::SCHEDULER_TYPE_ASAP:
+      return SchedulingStrategy::ASAP;
+    case ProtoSchedulingStrategy::SCHEDULER_TYPE_MIN_CUT:
+      return SchedulingStrategy::MIN_CUT;
+    case ProtoSchedulingStrategy::SCHEDULER_TYPE_SDC:
+    case ProtoSchedulingStrategy::SCHEDULER_TYPE_UNSPECIFIED:
+      return SchedulingStrategy::SDC;
+    case ProtoSchedulingStrategy::SCHEDULER_TYPE_RANDOM:
+      return SchedulingStrategy::RANDOM;
+    default:
+      LOG(FATAL) << "Unknown scheduling strategy: " << strategy;
+  }
+}
+bool AbslParseFlag(std::string_view text, SchedulingStrategy* strategy,
+                   std::string* error) {
+  if (text.empty()) {
+    *error = "Empty scheduling strategy";
+    return false;
+  }
+  if (text == "asap") {
+    *strategy = SchedulingStrategy::ASAP;
+  } else if (text == "min_cut") {
+    *strategy = SchedulingStrategy::MIN_CUT;
+  } else if (text == "sdc") {
+    *strategy = SchedulingStrategy::SDC;
+  } else if (text == "random") {
+    *strategy = SchedulingStrategy::RANDOM;
+  } else {
+    *error = absl::StrCat("Unknown scheduling strategy: ", text);
+    return false;
+  }
+  return true;
+}
+
+std::string AbslUnparseFlag(const SchedulingStrategy& strategy) {
+  switch (strategy) {
+    case SchedulingStrategy::ASAP:
+      return "asap";
+    case SchedulingStrategy::MIN_CUT:
+      return "min_cut";
+    case SchedulingStrategy::SDC:
+      return "sdc";
+    case SchedulingStrategy::RANDOM:
+      return "random";
+  }
+}
+
 namespace {
 
 absl::StatusOr<SchedulingOptions> OptionsFromFlagProto(
     const Package* p, const SchedulingOptionsFlagsProto& proto) {
   // Some fields are pre-initialized with defaults
   SchedulingOptions scheduling_options;
 
+  if (proto.has_scheduling_strategy() &&
+      proto.scheduling_strategy() !=
+          ProtoSchedulingStrategy::SCHEDULER_TYPE_UNSPECIFIED) {
+    scheduling_options.strategy(
+        FromProtoSchedulingStrategy(proto.scheduling_strategy()));
+  }
   if (proto.has_opt_level()) {
     scheduling_options.opt_level(proto.opt_level());
   }

xls/scheduling/scheduling_options.h

@@ -1,3 +1,5 @@
+#include "absl/strings/str_cat.h"
+#include "absl/strings/str_join.h"
 #include "ortools/math_opt/cpp/math_opt.h"
 // Copyright 2022 The XLS Authors
 //
@@ -56,6 +58,14 @@ enum class SchedulingStrategy : int8_t {
   RANDOM,
 };
 
+ProtoSchedulingStrategy ToProtoSchedulingStrategy(SchedulingStrategy strategy);
+SchedulingStrategy FromProtoSchedulingStrategy(
+    ProtoSchedulingStrategy strategy);
+
+bool AbslParseFlag(std::string_view text, SchedulingStrategy* strategy,
+                   std::string* error);
+std::string AbslUnparseFlag(const SchedulingStrategy& strategy);
+
 enum class PathEvaluateStrategy : int8_t {
   PATH,
   CONE,
@@ -277,6 +287,10 @@ class SchedulingOptions {
 
   // Returns the scheduling strategy.
   SchedulingStrategy strategy() const { return strategy_; }
+  SchedulingOptions& strategy(SchedulingStrategy strategy) {
+    strategy_ = strategy;
+    return *this;
+  }
 
   // Sets/gets the target delay model
   SchedulingOptions& opt_level(int64_t value) {

xls/tools/scheduling_options_flags.cc

@@ -82,6 +82,28 @@ ABSL_FLAG(int64_t, pipeline_stages, 0,
           "https://google.github.io/xls/scheduling for details.");
 ABSL_FLAG(std::string, delay_model, "",
           "Delay model name to use from registry.");
+ABSL_FLAG(xls::SchedulingStrategy, scheduling_strategy,
+          xls::SchedulingStrategy::SDC,
+          "Scheduler algorithm to use.\n"
+          "\n"
+          "Options: [sdc, asap, min_cut, random]\n"
+          "\n"
+          "Standard Scheduler:\n"
+          "sdc: Default. Constraint based scheduling to minimize registers.\n"
+          "\n"
+          "Testing/Development Schedulers:\n"
+          "\n"
+          "These are meant for testing and rapid iteration only.\n"
+          "\n"
+          "asap: Fast scheduler which schedules nodes as early as possible. "
+          "Good for development and rapid iteration.\n"
+          // TODO(allight): Fix this missing feature.
+          "      Does not respect io_constraints.\n"
+          "min_cut: Approximates the minimum number of registers using a "
+          "min-cut based algorithm.\n"
+          "         Does not respect io_constraints.\n"
+          "random: Randomly schedules nodes. For internal testing only.\n"
+          "        Does not respect io_constraints.");
 ABSL_FLAG(int64_t, clock_margin_percent, 0,
           "The percentage of clock period to set aside as a margin to ensure "
           "timing is met. Effectively, this lowers the clock period by this "
@@ -262,6 +284,12 @@ static absl::StatusOr<bool> SetOptionsFromFlags(
   }
   bool any_flags_set = false;
   POPULATE_FLAG(opt_level);
+  {
+    any_flags_set |= FLAGS_scheduling_strategy.IsSpecifiedOnCommandLine();
+    ProtoSchedulingStrategy scheduling_strategy =
+        ToProtoSchedulingStrategy(absl::GetFlag(FLAGS_scheduling_strategy));
+    proto.set_scheduling_strategy(scheduling_strategy);
+  }
   POPULATE_FLAG(clock_period_ps);
   POPULATE_FLAG(pipeline_stages);
   POPULATE_FLAG(delay_model);

xls/tools/scheduling_options_flags.proto

@@ -19,6 +19,37 @@ package xls;
 import "google/api/field_behavior.proto";
 import "ortools/math_opt/parameters.proto";
 
+enum ProtoSchedulingStrategy {
+  // This is aliased to SCHEDULER_TYPE_SDC.
+  SCHEDULER_TYPE_UNSPECIFIED = 0;
+  // The SDC (system-of-difference-constraints) scheduler.
+  //
+  // This scheduler is based on the work in:
+  //   https://www.csl.cornell.edu/~zhiruz/pdfs/sdcmod-iccad2013.pdf
+  // and is a general-purpose constraint optimizer.
+  //
+  // This is the default scheduler.
+  SCHEDULER_TYPE_SDC = 1;
+  // An alternative scheduler which simply attempts to create a feasible
+  // schedule.
+  //
+  // Unlike SDC this scheduler does not attempt to minimize the number of
+  // registers or evenly spread delay across the pipeline. Instead this simply
+  // forces all computation into the earliest stage where it fits and all
+  // predicates are available. As this scheduler is less constrained it is
+  // faster to run than the SDC scheduler.
+  //
+  // This scheduler is primarily intended for use during development when
+  // iteration speed is paramount. It should not be used to create the final
+  // schedule for a design.
+  SCHEDULER_TYPE_ASAP = 2;
+  // An alternative scheduler which approximates the minimum number of registers
+  // using a min-cut based algorithm.
+  SCHEDULER_TYPE_MIN_CUT = 3;
+  // A scheduler which randomly schedules nodes. For internal testing only.
+  SCHEDULER_TYPE_RANDOM = 4;
+}
+
 message SchedulingFailureBehaviorProto {
   optional bool explain_infeasibility = 1
       [(google.api.field_behavior) = REQUIRED];
@@ -70,4 +101,6 @@ message SchedulingOptionsFlagsProto {
   optional operations_research.math_opt.SolverTypeProto solver_type = 36;
   optional operations_research.math_opt.SolveParametersProto solve_parameters =
       37;
+  // What sort of scheduler one should use.
+  optional ProtoSchedulingStrategy scheduling_strategy = 38;
 }