Implement sancov runtime API to be able to emit features for other frameworks, and add a new interface to the dispatcher for exposed feature compatibility.

PiperOrigin-RevId: 796996087

Author: yamilmorales

centipede/BUILD

@@ -1000,21 +1000,22 @@ cc_library(
 #  e.g. feature.cc. These files are compiled by the engine and the runner
 #  separately, with different compiler flags.
 RUNNER_SOURCES_NO_MAIN = [
-    "sancov_state.cc",
-    "sancov_state.h",
     "pc_info.h",
     "reverse_pc_table.h",
     "runner.cc",
     "runner.h",
-    "runner_dl_info.h",
     "runner_dl_info.cc",
-    "sancov_object_array.h",
-    "sancov_object_array.cc",
-    "runner_utils.h",
-    "runner_utils.cc",
-    "sancov_interceptors.cc",
+    "runner_dl_info.h",
     "runner_interface.h",
+    "runner_utils.cc",
+    "runner_utils.h",
     "sancov_callbacks.cc",
+    "sancov_interceptors.cc",
+    "sancov_object_array.cc",
+    "sancov_object_array.h",
+    "sancov_runtime.h",
+    "sancov_state.cc",
+    "sancov_state.h",
     "@com_google_fuzztest//common:defs.h",
 ]
 
@@ -1194,10 +1195,11 @@ cc_library(
         "sancov_object_array.cc",
         "sancov_object_array.h",
         "sancov_state.cc",
+        "sancov_state.h",
         "@com_google_fuzztest//common:defs.h",
     ],
     hdrs = [
-        "sancov_state.h",
+        "sancov_runtime.h",
     ],
     copts = DISABLE_SANCOV_COPTS,
     deps = [

centipede/dispatcher.cc

@@ -554,6 +554,20 @@ void FuzzTestDispatcherEmitFeedbackAs32BitFeatures(const uint32_t* features,
                   "failed to write feedback");
 }
 
+void FuzzTestDispatcherEmitFeedbackAsRawFeatures(const uint64_t* features,
+                                                 size_t num_features) {
+  DispatcherCheck(GetDispatcherAction() == DispatcherAction::kTestExecute &&
+                      in_test_callback,
+                  "must be called inside test callback of executing");
+  DispatcherCheck(num_features > 0 && features != nullptr,
+                  "feature array must be non-empty with a valid pointer");
+  auto* output = GetOutputsBlobSequence();
+  DispatcherCheck(output != nullptr, "outputs blob sequence must exist");
+  DispatcherCheck(
+      BatchResult::WriteOneFeatureVec(features, num_features, *output),
+      "failed to write feedback");
+}
+
 void FuzzTestDispatcherEmitExecutionMetadata(const void* metadata,
                                              size_t size) {
   DispatcherCheck(GetDispatcherAction() == DispatcherAction::kTestExecute &&

centipede/dispatcher.h

@@ -95,6 +95,8 @@ void FuzzTestDispatcherEmitSeed(const void* data, size_t size);
 // nullptr and `size > 0` must hold.
 void FuzzTestDispatcherEmitMutant(const void* data, size_t size);
 
+// TODO: b/437901326 - Unify the feedback emission interfaces.
+
 // Emits coverage feedback for the current input as an array of 32-bit features.
 //
 // For each 32-bit feature, the bit [31] is ignored; the 4 bits [30-27]
@@ -105,6 +107,14 @@ void FuzzTestDispatcherEmitMutant(const void* data, size_t size);
 // and `num_features > 0` must hold.
 void FuzzTestDispatcherEmitFeedbackAs32BitFeatures(const uint32_t* features,
                                                    size_t num_features);
+
+// Must only pass here the "raw" features exposed by the sancov runtime.
+//
+// Must be called from the `execute` callback. `features` must not be nullptr
+// and `num_features > 0` must hold.
+void FuzzTestDispatcherEmitFeedbackAsRawFeatures(const uint64_t* features,
+                                                 size_t num_features);
+
 // Emits metadata of the current input as raw bytes. Must be called from
 // the `execute` callback.
 void FuzzTestDispatcherEmitExecutionMetadata(const void* metadata, size_t size);

centipede/runner.cc

@@ -57,6 +57,7 @@
 #include "./centipede/runner_request.h"
 #include "./centipede/runner_result.h"
 #include "./centipede/runner_utils.h"
+#include "./centipede/sancov_runtime.h"
 #include "./centipede/sancov_state.h"
 #include "./centipede/shared_memory_blob_sequence.h"
 #include "./common/defs.h"
@@ -395,10 +396,11 @@ static void ReadOneInputExecuteItAndDumpCoverage(const char *input_path,
            input_path);
   FILE *features_file = fopen(features_file_path, "w");
   PrintErrorAndExitIf(features_file == nullptr, "can't open coverage file");
-  // TODO(yamilmorales): Hide the raw sancov state objects and expose
-  // interface functions instead.
-  WriteFeaturesToFile(features_file, sancov_state->g_features.data(),
-                      sancov_state->g_features.size());
+
+  const SanCovRuntimeRawFeatureParts sancov_features =
+      SanCovRuntimeGetFeatures();
+  WriteFeaturesToFile(features_file, sancov_features.features,
+                      sancov_features.num_features);
   fclose(features_file);
 }
 
@@ -408,13 +410,15 @@ static bool StartSendingOutputsToEngine(BlobSequence &outputs_blobseq) {
   return BatchResult::WriteInputBegin(outputs_blobseq);
 }
 
-// Copy all the `g_features` to `data` with given `capacity` in bytes.
-// Returns the byte size of `g_features`.
+// Copy all the sancov features to `data` with given `capacity` in bytes.
+// Returns the byte size of sancov features.
 static size_t CopyFeatures(uint8_t *data, size_t capacity) {
+  const SanCovRuntimeRawFeatureParts sancov_features =
+      SanCovRuntimeGetFeatures();
   const size_t features_len_in_bytes =
-      sancov_state->g_features.size() * sizeof(feature_t);
+      sancov_features.num_features * sizeof(feature_t);
   if (features_len_in_bytes > capacity) return 0;
-  memcpy(data, sancov_state->g_features.data(), features_len_in_bytes);
+  memcpy(data, sancov_features.features, features_len_in_bytes);
   return features_len_in_bytes;
 }
 
@@ -441,9 +445,11 @@ static bool FinishSendingOutputsToEngine(BlobSequence &outputs_blobseq) {
     }
   }
 
+  const SanCovRuntimeRawFeatureParts sancov_features =
+      SanCovRuntimeGetFeatures();
   // Copy features to shared memory.
-  if (!BatchResult::WriteOneFeatureVec(sancov_state->g_features.data(),
-                                       sancov_state->g_features.size(),
+  if (!BatchResult::WriteOneFeatureVec(sancov_features.features,
+                                       sancov_features.num_features,
                                        outputs_blobseq)) {
     return false;
   }
@@ -749,7 +755,6 @@ GlobalRunnerState::GlobalRunnerState() {
 
   // TODO(kcc): move some code from CentipedeRunnerMain() here so that it works
   // even if CentipedeRunnerMain() is not called.
-  tls.OnThreadStart();
   state->StartWatchdogThread();
 
   SetLimits();

centipede/sancov_runtime.h

@@ -0,0 +1,57 @@
+// Copyright 2025 The Centipede Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef FUZZTEST_CENTIPEDE_SANCOV_RUNTIME_H_
+#define FUZZTEST_CENTIPEDE_SANCOV_RUNTIME_H_
+
+// Sancov runtime interface.
+//
+// This header needs to be C compatible.
+
+#include <stdbool.h>  // NOLINT
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct SanCovRuntimeRawFeatureParts {
+  const uint64_t* features;
+  size_t num_features;
+};
+
+// Clears coverage data accumulated so far from sancov callbacks and/or
+// interceptors.
+//
+// Will always clear the thread-local data updated during execution, and if
+// `full_clear==true` will clear all accumulated coverage data.
+void SanCovRuntimeClearCoverage(bool full_clear);
+
+// Post-processes all coverage data, putting it all into an array of features,
+// and returning a ptr and the length of this array.
+//
+// Will return a valid `features` pointer to a 64-bit element array of length
+// `num_features`: This feature array is initialized at process startup, and
+// its data (belonging to a global state) will remain valid for the duration of
+// the process.
+//
+// If `reject_input==true`, then it will simply empty the feature array.
+struct SanCovRuntimeRawFeatureParts SanCovRuntimeGetCoverage(bool reject_input);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif
+
+#endif  // FUZZTEST_CENTIPEDE_SANCOV_RUNTIME_H_

centipede/sancov_state.cc

@@ -31,6 +31,7 @@
 #include "./centipede/pc_info.h"
 #include "./centipede/runner_dl_info.h"
 #include "./centipede/runner_utils.h"
+#include "./centipede/sancov_runtime.h"
 
 __attribute__((weak)) extern fuzztest::internal::feature_t
     __start___centipede_extra_features;
@@ -226,6 +227,7 @@ static void DumpDsoTable(const char *absl_nonnull output_path) {
 }
 
 SancovState::SancovState() {
+  tls.OnThreadStart();
   // Compute main_object.
   main_object = GetDlInfo(flag_helper.GetStringFlag(":dl_path_suffix="));
   if (!sancov_state->main_object.IsSet()) {
@@ -484,6 +486,11 @@ bool CopyCmpTracesToMetadata(ExecutionMetadata *metadata) {
   return true;
 }
 
+SanCovRuntimeRawFeatureParts SanCovRuntimeGetFeatures() {
+  return {fuzztest::internal::sancov_state->g_features.data(),
+          fuzztest::internal::sancov_state->g_features.size()};
+}
+
 }  // namespace fuzztest::internal
 
 // Can be overridden to not depend explicitly on CENTIPEDE_RUNNER_FLAGS.
@@ -492,3 +499,15 @@ extern "C" __attribute__((weak)) const char *absl_nullable GetSancovFlags() {
     return strdup(sancov_flags_env);
   return nullptr;
 }
+
+void SanCovRuntimeClearCoverage(bool full_clear) {
+  fuzztest::internal::CleanUpSancovTls();
+  fuzztest::internal::PrepareSancov(full_clear);
+}
+
+struct SanCovRuntimeRawFeatureParts SanCovRuntimeGetCoverage(
+    bool reject_input) {
+  fuzztest::internal::PostProcessSancov(reject_input);
+
+  return fuzztest::internal::SanCovRuntimeGetFeatures();
+}

centipede/sancov_state.h

@@ -40,6 +40,7 @@
 #include "./centipede/runner_dl_info.h"
 #include "./centipede/runner_utils.h"
 #include "./centipede/sancov_object_array.h"
+#include "./centipede/sancov_runtime.h"
 
 extern "C" const char *absl_nullable GetSancovFlags();
 
@@ -287,6 +288,9 @@ void PostProcessSancov(bool reject_input = false);
 
 void MaybeAddFeature(feature_t feature);
 
+// Returns a pointer to `g_features` and its length.
+SanCovRuntimeRawFeatureParts SanCovRuntimeGetFeatures();
+
 // Check for stack limit for the stack pointer `sp` in the current thread.
 __attribute__((weak)) void CheckStackLimit(uintptr_t sp);