[tsan] Add debugging interfaces into interface header.

[pgousseau]

Remove incorrect check

[vitalybuka]

compiler-rt/include/sanitizer/tsan_interface.h

18

we don't have tsan for windows

21

common_interface_defs includes stdint.h
maybe just use uintptr_t?

[pgousseau]

Change uptr to uintptr_t
Fix doxygen return.

[pgousseau]

compiler-rt/include/sanitizer/tsan_interface.h

21

Yes makes sense, fixed now thanks!

[vitalybuka]

@dvyukov This LGTM, do you have any concerns exposing this API?

compiler-rt/include/sanitizer/tsan_interface.h

181

Would you like in a separate patch to update compiler-rt/include/sanitizer to use doxygen style?

[dvyukov]

@dvyukov This LGTM, do you have any concerns exposing this API?

They are already used by Apple debugger, so in some sense they are already exposed and the info we provide with reports did not change in the past 10 years, so I think it's OK.
If we won't have some of that data in future, we can just start returning errors, or null pointers from these functions.

[pgousseau]

Thank you for the review!

compiler-rt/include/sanitizer/tsan_interface.h

181

Yes we would be interested in adding doxygen style comments to the whole tsan header at least so future api's comments will also hopefully be using doxygen. Will put in my TODOs, thanks!

[hans]

This broke the tsan tests on Darwin, see e.g. the end of https://logs.chromium.org/logs/chromium/buildbucket/cr-buildbucket/8784015461553130001/+/u/package_clang/stdout

It seems those tests have their own declarations of some of these functions, which mismatch slightly.

[hans]

It's still broken after the follow-up, e.g. https://logs.chromium.org/logs/chromium/buildbucket/cr-buildbucket/8783975392120859201/+/u/package_clang/stdout

I'll revert this for now.

[pgousseau]

In D147337#4263990, @hans wrote:

It's still broken after the follow-up, e.g. https://logs.chromium.org/logs/chromium/buildbucket/cr-buildbucket/8783975392120859201/+/u/package_clang/stdout

I'll revert this for now.

Sorry about that, thank you for reverting. I will update the patch with hopefully better types.

compiler-rt/include/sanitizer/tsan_interface.h

 //
 // Public interface header for TSan.
 //===----------------------------------------------------------------------===//
 #ifndef SANITIZER_TSAN_INTERFACE_H
 #define SANITIZER_TSAN_INTERFACE_H
 
 #include <sanitizer/common_interface_defs.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 // __tsan_release establishes a happens-before relation with a preceding
 // __tsan_acquire on the same address.
 void __tsan_acquire(void *addr);
 void __tsan_release(void *addr);
 
 // Annotations for custom mutexes.
 // The annotations allow to get better reports (with sets of locked mutexes),
 // detect more types of bugs (e.g. mutex misuses, races between lock/unlock and

 void __tsan_flush_memory();
 
 // User-provided default TSAN options.
 const char* __tsan_default_options(void);
 
 // User-provided default TSAN suppressions.
 const char* __tsan_default_suppressions(void);
 
+/// Returns a report's description.
+///
+/// Returns a report's description (issue type), number of duplicate issues
+/// found, counts of array data (stack traces, memory operations, locations,
+/// mutexes, threads, unique thread IDs) and a stack trace of a <c>sleep()</c>
+/// call (if one was involved in the issue).
+///
+/// \param report Opaque pointer to the current report.
+/// \param[out] description Report type description.
+/// \param[out] count Count of duplicate issues.
+/// \param[out] stack_count Count of stack traces.
+/// \param[out] mop_count Count of memory operations.
+/// \param[out] loc_count Count of locations.
+/// \param[out] mutex_count Count of mutexes.
+/// \param[out] thread_count Count of threads.
+/// \param[out] unique_tid_count Count of unique thread IDs.
+/// \param sleep_trace A buffer to store the stack trace of a <c>sleep()</c>
+/// call.
+/// \param trace_size Size in bytes of the trace buffer.
+/// \returns Returns 1 if successful, 0 if not.
+int __tsan_get_report_data(void *report, const char **description, int *count,
+                           int *stack_count, int *mop_count, int *loc_count,
+                           int *mutex_count, int *thread_count,
+                           int *unique_tid_count, void **sleep_trace,
+                           uintptr_t trace_size);
+
+/// Returns information about stack traces included in the report.
+///
+/// \param report Opaque pointer to the current report.
+/// \param idx Index to the report's stacks.
+/// \param trace A buffer to store the stack trace.
+/// \param trace_size Size in bytes of the trace buffer.
+/// \returns Returns 1 if successful, 0 if not.
+int __tsan_get_report_stack(void *report, uintptr_t idx, void **trace,
+                            uintptr_t trace_size);
+
+/// Returns information about memory operations included in the report.
+///
+/// \param report Opaque pointer to the current report.
+/// \param idx Index to the report's memory operations.
+/// \param[out] tid Thread ID of the memory operation.
+/// \param[out] addr Address of the memory operation.
+/// \param[out] size Size of the memory operation.
+/// \param[out] write Write flag of the memory operation.
+/// \param[out] atomic Atomicity flag of the memory operation.
+/// \param trace A buffer to store the stack trace.
+/// \param trace_size Size in bytes of the trace buffer.
+/// \returns Returns 1 if successful, 0 if not.
+int __tsan_get_report_mop(void *report, uintptr_t idx, int *tid, void **addr,
+                          int *size, int *write, int *atomic, void **trace,
+                          uintptr_t trace_size);
+
+/// Returns information about locations included in the report.
+///
+/// \param report Opaque pointer to the current report.
+/// \param idx Index to the report's locations.
+/// \param[out] type Type of the location.
+/// \param[out] addr Address of the location.
+/// \param[out] start Start of the location.
+/// \param[out] size Size of the location.
+/// \param[out] tid Thread ID of the location.
+/// \param[out] fd File descriptor of the location.
+/// \param[out] suppressable Suppressable flag.
+/// \param trace A buffer to store the stack trace.
+/// \param trace_size Size in bytes of the trace buffer.
+/// \returns Returns 1 if successful, 0 if not.
+int __tsan_get_report_loc(void *report, uintptr_t idx, const char **type,
+                          void **addr, uintptr_t *start, uintptr_t *size, int *tid,
+                          int *fd, int *suppressable, void **trace,
+                          uintptr_t trace_size);
+
+/// Returns information about mutexes included in the report.
+///
+/// \param report Opaque pointer to the current report.
+/// \param idx Index to the report's mutexes.
+/// \param[out] mutex_id Id of the mutex.
+/// \param[out] addr Address of the mutex.
+/// \param[out] destroyed Destroyed mutex flag.
+/// \param trace A buffer to store the stack trace.
+/// \param trace_size Size in bytes of the trace buffer.
+/// \returns Returns 1 if successful, 0 if not.
+int __tsan_get_report_mutex(void *report, uintptr_t idx, uintptr_t *mutex_id, void **addr,
+                            int *destroyed, void **trace, uintptr_t trace_size);
+
+/// Returns information about threads included in the report.
+///
+/// \param report Opaque pointer to the current report.
+/// \param idx Index to the report's threads.
+/// \param[out] tid Thread ID of the thread.
+/// \param[out] os_id Operating system's ID of the thread.
+/// \param[out] running Running flag of the thread.
+/// \param[out] name Name of the thread.
+/// \param[out] parent_tid ID of the parent thread.
+/// \param trace A buffer to store the stack trace.
+/// \param trace_size Size in bytes of the trace buffer.
+/// \returns Returns 1 if successful, 0 if not.
+int __tsan_get_report_thread(void *report, uintptr_t idx, int *tid, uintptr_t *os_id,
+                             int *running, const char **name, int *parent_tid,
+                             void **trace, uintptr_t trace_size);
+
+/// Returns information about unique thread IDs included in the report.
+///
+/// \param report Opaque pointer to the current report.
+/// \param idx Index to the report's unique thread IDs.
+/// \param[out] tid Unique thread ID of the report.
+/// \returns Returns 1 if successful, 0 if not.
+int __tsan_get_report_unique_tid(void *report, uintptr_t idx, int *tid);
+
+/// Returns the current report.
+///
+/// If TSan is currently reporting a detected issue on the current thread,
+/// returns an opaque pointer to the current report. Otherwise returns NULL.
+/// \returns An opaque pointer to the current report. Otherwise returns NULL.
+void *__tsan_get_current_report();
+
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // SANITIZER_TSAN_INTERFACE_H

compiler-rt/test/tsan/debug_mutex_bad_unlock.cpp

+// RUN: %clangxx_tsan -O1 %s -o %t && %deflake %run %t | FileCheck %s
+
+#include "test.h"
+
+extern "C" {
+void __tsan_on_report(void *report);
+void *__tsan_get_current_report();
+int __tsan_get_report_data(void *report, const char **description, int *count,
+                           int *stack_count, int *mop_count, int *loc_count,
+                           int *mutex_count, int *thread_count,
+                           int *unique_tid_count, void **sleep_trace,
+                           unsigned long trace_size);
+int __tsan_get_report_stack(void *report, uintptr_t idx, void **trace,
+                            uintptr_t trace_size);
+int __tsan_get_report_mutex(void *report, uintptr_t idx, uintptr_t *mutex_id, void **addr,
+                            int *destroyed, void **trace, uintptr_t trace_size);
+}
+
+int main() {
+  int m = 0;
+  fprintf(stderr, "&m = %p\n", &m);
+  // CHECK: &m = [[MUTEX:0x[0-9a-f]+]]
+  AnnotateRWLockReleased(__FILE__, __LINE__, &m, 1);
+  fprintf(stderr, "Done.\n");
+  return 0;
+}
+
+// Required for dyld macOS 12.0+
+#if (__APPLE__)
+__attribute__((weak))
+#endif
+__attribute__((disable_sanitizer_instrumentation))
+extern "C" void
+__tsan_on_report(void *report) {
+  fprintf(stderr, "__tsan_on_report(%p)\n", report);
+  fprintf(stderr, "__tsan_get_current_report() = %p\n",
+          __tsan_get_current_report());
+  // CHECK: __tsan_on_report([[REPORT:0x[0-9a-f]+]])
+  // CHECK: __tsan_get_current_report() = [[REPORT]]
+
+  const char *description;
+  int count;
+  int stack_count, mop_count, loc_count, mutex_count, thread_count,
+      unique_tid_count;
+  void *sleep_trace[16] = {0};
+  __tsan_get_report_data(report, &description, &count, &stack_count, &mop_count,
+                         &loc_count, &mutex_count, &thread_count,
+                         &unique_tid_count, sleep_trace, 16);
+
+  fprintf(stderr, "stack_count = %d\n", stack_count);
+  // CHECK: stack_count = 1
+
+  fprintf(stderr, "mutex_count = %d\n", mutex_count);
+  // CHECK: mutex_count = 1
+
+  void *trace[16] = {0};
+  __tsan_get_report_stack(report, 0, trace, 16);
+
+  fprintf(stderr, "trace[0] = %p, trace[1] = %p, trace[2] = %p\n", trace[0], trace[1], trace[2]);
+  // CHECK: trace[0] = 0x{{[0-9a-f]+}}, trace[1] = 0x{{[0-9a-f]+}}, trace[2] = {{0x0|\(nil\)|\(null\)}}
+
+  uintptr_t mutex_id;
+  void *addr;
+  int destroyed;
+  __tsan_get_report_mutex(report, 0, &mutex_id, &addr, &destroyed, trace, 16);
+  fprintf(stderr, "addr = %p, destroyed = %d\n", addr, destroyed);
+  // CHECK: addr = [[MUTEX]], destroyed = 0
+  fprintf(stderr, "trace[0] = %p, trace[1] = %p, trace[2] = %p\n", trace[0], trace[1], trace[2]);
+  // CHECK: trace[0] = 0x{{[0-9a-f]+}}, trace[1] = 0x{{[0-9a-f]+}}, trace[2] = {{0x0|\(nil\)|\(null\)}}
+}
+
+// CHECK: Done.
+// CHECK: ThreadSanitizer: reported 1 warnings