feature: custom signal handling probe type

this commit implements a custom signal handling probe
which will be triggered when the specified signal is
sent to the bpftrace process. the default behavior of
printing maps on `SIGUSR1` is removed.

```
bpftrace:signal:SIGUSR1 {
    print("hello");
}
```

Also trigger functions and extra checks for the special probes
are removed as BPF_PROG_TYPE_RAW_TRACEPOINT was added in 4.17 kernel:

    torvalds/linux@a0fe3e5

The oldest LTS kernel still in service is 4.19, so we are free
to assume BPF_PROG_TYPE_RAW_TRACEPOINT is always available

Author: amiremohamadi

CHANGELOG.md

@@ -18,6 +18,9 @@ and this project adheres to
 - Add lexical/block scoping for variables
   - [#3367](https://github.com/bpftrace/bpftrace/pull/3367)
   - [Migration guide](docs/migration_guide.md#added-block-scoping-for-scratch-variables)
+- Replace default map printing on `SIGUSR1` with custom signal handling probes
+  - [#3522](https://github.com/bpftrace/bpftrace/pull/3522)
+  - [Migration guide](docs/migration_guide.md#default-sigusr1-handler-removed)
 #### Added
 - Add `--dry-run` CLI option
   - [#3203](https://github.com/bpftrace/bpftrace/pull/3203)

docs/migration_guide.md

@@ -28,7 +28,7 @@ BEGIN {
 However, the value of `$x` at the print statement was considered undefined
 behavior. Issue: https://github.com/bpftrace/bpftrace/issues/3017
 
-Now variables are "block" scoped and the the above will throw an error at the 
+Now variables are "block" scoped and the the above will throw an error at the
 print statement: "ERROR: Undefined or undeclared variable: $x".
 
 If you see this error you can do multiple things to resolve it.
@@ -58,7 +58,7 @@ BEGIN {
 Declaring is useful for variables that hold internal bpftrace types
 e.g. the type returned by the `macaddr` function.
 
-This is also not valid even though `$x` is set in both branches (`$x` still 
+This is also not valid even though `$x` is set in both branches (`$x` still
 needs to exist in the outer scope):
 ```
 BEGIN {
@@ -141,3 +141,28 @@ To mitigate such an error, just typecast `pid` or `tid` to `uint64`:
 Attaching 1 probe...
 ```
 
+### default `SIGUSR1` handler removed
+
+https://github.com/bpftrace/bpftrace/pull/3522
+
+Previously, if the bpftrace process received a `SIGUSR1` signal, it would print all maps to stdout:
+```
+# bpftrace -e 'BEGIN { @b[1] = 2; }' & kill -s USR1 $(pidof bpftrace)
+...
+@b[1]: 2
+```
+
+This behavior is no longer supported and has been replaced with the ability
+to define custom handling probes:
+```
+# bpftrace -e 'self:signal:SIGUSR1 { print("hello"); }' & kill -s USR1 $(pidof bpftrace)
+...
+hello
+```
+
+To retain the previous functionality of printing maps, you need to
+manually include the print statements in your signal handler probe:
+```
+# bpftrace -e 'BEGIN { @b[1] = 2; } self:signal:SIGUSR1 { print(@b); }' & kill -s USR1 $(pidof bpftrace)
+```
+

man/adoc/bpftrace.adoc

@@ -2874,6 +2874,11 @@ Most providers also support a short name which can be used instead of the full n
 | Built-in events
 | Kernel/User
 
+| <<probes-self, `self`>>
+| -
+| Built-in events
+| Kernel/User
+
 | <<probes-hardware, `hardware`>>
 | `h`
 | Processor-level events
@@ -2952,6 +2957,22 @@ END {
 }
 ----
 
+[#probes-self]
+=== self
+
+.variants
+* `self:signal:SIGUSR1`
+
+These are special built-in events provided by the bpftrace runtime.
+The trigger function is called by the bpftrace runtime when the bpftrace process receives specific events, such as a `SIGUSR1` signal.
+When multiple signal handlers are attached to the same signal, only the first one is used.
+
+----
+self:signal:SIGUSR1 {
+  print("abc");
+}
+----
+
 [#probes-hardware]
 === hardware
 
@@ -4087,13 +4108,6 @@ will print this on exit:
 @a: 0
 ```
 
-If you want to get a snapshot of your maps while the script is running, you can send the running bpftrace process a `SIGUSR1` signal. bpftrace will then print all maps to stdout. Example:
-```
-# bpftrace -e 'BEGIN { @b[1] = 2; }' & kill -s USR1 $(pidof bpftrace)
-...
-@b[1]: 2
-```
-
 === Systemd support
 
 To run bpftrace in the background using systemd::

src/ast/attachpoint_parser.cpp

@@ -276,13 +276,22 @@ AttachPointParser::State AttachPointParser::lex_attachpoint(
 
 AttachPointParser::State AttachPointParser::special_parser()
 {
-  // Can only have reached here if provider is `BEGIN` or `END`
-  assert(ap_->provider == "BEGIN" || ap_->provider == "END");
-
-  if (parts_.size() == 2 && parts_[1] == "*")
-    parts_.pop_back();
-  if (parts_.size() != 1) {
-    return argument_count_error(0);
+  // Can only have reached here if provider is `BEGIN` or `END` or `self`
+  assert(ap_->provider == "BEGIN" || ap_->provider == "END" ||
+         ap_->provider == "self");
+
+  if (ap_->provider == "BEGIN" || ap_->provider == "END") {
+    if (parts_.size() == 2 && parts_[1] == "*")
+      parts_.pop_back();
+    if (parts_.size() != 1) {
+      return argument_count_error(0);
+    }
+  } else if (ap_->provider == "self") {
+    if (parts_.size() != 3) {
+      return argument_count_error(2);
+    }
+    ap_->target = parts_[1];
+    ap_->func = parts_[2];
   }
 
   return OK;

src/ast/passes/semantic_analyser.cpp

@@ -3347,6 +3347,13 @@ void SemanticAnalyser::visit(AttachPoint &ap)
         has_end_probe_ = true;
       }
     }
+  } else if (ap.provider == "self") {
+    if (ap.target == "signal") {
+      if (SIGNALS.find(ap.func) == SIGNALS.end())
+        LOG(ERROR, ap.loc, err_) << ap.func << " is not a supported signal";
+      return;
+    }
+    LOG(ERROR, ap.loc, err_) << ap.target << " is not a supported trigger";
   } else if (ap.provider == "fentry" || ap.provider == "fexit") {
     if (!bpftrace_.feature_->has_fentry()) {
       LOG(ERROR, ap.loc, err_)

src/attached_probe.cpp

@@ -148,18 +148,11 @@ int AttachedProbe::detach_raw_tracepoint()
 
 AttachedProbe::AttachedProbe(Probe &probe,
                              const BpfProgram &prog,
-                             bool safe_mode,
                              BPFtrace &bpftrace)
     : probe_(probe), progfd_(prog.fd()), bpftrace_(bpftrace)
 {
   LOG(V1) << "Attaching " << probe_.orig_name;
   switch (probe_.type) {
-    case ProbeType::special:
-      // If BPF_PROG_TYPE_RAW_TRACEPOINT is available, no need to attach prog
-      // to anything -- we will simply BPF_PROG_RUN it
-      if (!bpftrace_.feature_->has_raw_tp_special())
-        attach_uprobe(getpid(), safe_mode);
-      break;
     case ProbeType::kprobe:
       attach_kprobe();
       break;
@@ -312,7 +305,6 @@ std::string AttachedProbe::eventname() const
       offset_str << std::hex << offset_;
       return eventprefix() + sanitise_bpf_program_name(probe_.attach_point) +
              "_" + offset_str.str() + index_str;
-    case ProbeType::special:
     case ProbeType::uprobe:
     case ProbeType::uretprobe:
     case ProbeType::usdt:

src/attached_probe.h

@@ -22,10 +22,7 @@ std::string progtypeName(libbpf::bpf_prog_type t);
 
 class AttachedProbe {
 public:
-  AttachedProbe(Probe &probe,
-                const BpfProgram &prog,
-                bool safe_mode,
-                BPFtrace &bpftrace);
+  AttachedProbe(Probe &probe, const BpfProgram &prog, BPFtrace &bpftrace);
   AttachedProbe(Probe &probe,
                 const BpfProgram &prog,
                 int pid,

src/bpfbytecode.cpp

@@ -186,8 +186,11 @@ void BpfBytecode::load_progs(const RequiredResources &resources,
     bpf_program__set_log_buf(prog.bpf_prog(), log_buf.data(), log_buf.size());
   }
 
+  std::vector<Probe> special_probes;
+  for (auto probe : resources.special_probes)
+    special_probes.push_back(probe.second);
+  prepare_progs(special_probes, btf, feature, config);
   prepare_progs(resources.probes, btf, feature, config);
-  prepare_progs(resources.special_probes, btf, feature, config);
   prepare_progs(resources.watchpoint_probes, btf, feature, config);
 
   int res = bpf_object__load(bpf_object_.get());
@@ -264,7 +267,7 @@ void BpfBytecode::prepare_progs(const std::vector<Probe> &probes,
 {
   for (auto &probe : probes) {
     auto &program = getProgramForProbe(probe);
-    program.set_prog_type(probe, feature);
+    program.set_prog_type(probe);
     program.set_expected_attach_type(probe, feature);
     program.set_attach_target(probe, btf, config);
     program.set_no_autoattach();

src/bpffeature.cpp

@@ -564,32 +564,6 @@ bool BPFfeature::has_skb_output()
   return *has_skb_output_;
 }
 
-bool BPFfeature::has_raw_tp_special()
-{
-  if (has_raw_tp_special_.has_value())
-    return *has_raw_tp_special_;
-
-  struct bpf_insn insns[] = { BPF_MOV64_IMM(BPF_REG_0, 0), BPF_EXIT_INSN() };
-  int fd;
-
-  // Check that we can both load BPF_PROG_TYPE_RAW_TRACEPOINT and that
-  // BPF_PROG_RUN is supported by the kernel
-  if (try_load(libbpf::BPF_PROG_TYPE_RAW_TRACEPOINT,
-               insns,
-               ARRAY_SIZE(insns),
-               nullptr,
-               std::nullopt,
-               &fd)) {
-    struct bpf_test_run_opts opts = {};
-    opts.sz = sizeof(opts);
-    has_raw_tp_special_ = !::bpf_prog_test_run_opts(fd, &opts);
-    close(fd);
-  } else
-    has_raw_tp_special_ = false;
-
-  return *has_raw_tp_special_;
-}
-
 std::string BPFfeature::report()
 {
   std::stringstream buf;
@@ -643,7 +617,6 @@ std::string BPFfeature::report()
       << "  fentry: " << to_str(has_fentry())
       << "  kprobe_multi: " << to_str(has_kprobe_multi())
       << "  uprobe_multi: " << to_str(has_uprobe_multi())
-      << "  raw_tp_special: " << to_str(has_raw_tp_special())
       << "  iter: " << to_str(has_iter("task")) << std::endl;
 
   return buf.str();

src/bpffeature.h

@@ -99,7 +99,6 @@ class BPFfeature {
   bool has_uprobe_multi();
   bool has_fentry();
   bool has_skb_output();
-  bool has_raw_tp_special();
   bool has_prog_fentry();
   bool has_module_btf();
   bool has_iter(std::string name);
@@ -143,7 +142,6 @@ class BPFfeature {
   std::optional<bool> has_kprobe_multi_;
   std::optional<bool> has_uprobe_multi_;
   std::optional<bool> has_skb_output_;
-  std::optional<bool> has_raw_tp_special_;
   std::optional<bool> has_prog_fentry_;
   std::optional<bool> has_module_btf_;
   std::optional<bool> has_btf_func_global_;