1  //===-- tsan_interface_java.h -----------------------------------*- C++ -*-===//
       2  //
       3  // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
       4  // See https://llvm.org/LICENSE.txt for license information.
       5  // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
       6  //
       7  //===----------------------------------------------------------------------===//
       8  //
       9  // This file is a part of ThreadSanitizer (TSan), a race detector.
      10  //
      11  // Interface for verification of Java or mixed Java/C++ programs.
      12  // The interface is intended to be used from within a JVM and notify TSan
      13  // about such events like Java locks and GC memory compaction.
      14  //
      15  // For plain memory accesses and function entry/exit a JVM is intended to use
      16  // C++ interfaces: __tsan_readN/writeN and __tsan_func_enter/exit.
      17  //
      18  // For volatile memory accesses and atomic operations JVM is intended to use
      19  // standard atomics API: __tsan_atomicN_load/store/etc.
      20  //
      21  // For usage examples see lit_tests/java_*.cpp
      22  //===----------------------------------------------------------------------===//
      23  #ifndef TSAN_INTERFACE_JAVA_H
      24  #define TSAN_INTERFACE_JAVA_H
      25  
      26  #ifndef INTERFACE_ATTRIBUTE
      27  # define INTERFACE_ATTRIBUTE __attribute__((visibility("default")))
      28  #endif
      29  
      30  #ifdef __cplusplus
      31  extern "C" {
      32  #endif
      33  
      34  typedef unsigned long jptr;
      35  
      36  // Must be called before any other callback from Java.
      37  void __tsan_java_init(jptr heap_begin, jptr heap_size) INTERFACE_ATTRIBUTE;
      38  // Must be called when the application exits.
      39  // Not necessary the last callback (concurrently running threads are OK).
      40  // Returns exit status or 0 if tsan does not want to override it.
      41  int  __tsan_java_fini() INTERFACE_ATTRIBUTE;
      42  
      43  // Callback for memory allocations.
      44  // May be omitted for allocations that are not subject to data races
      45  // nor contain synchronization objects (e.g. String).
      46  void __tsan_java_alloc(jptr ptr, jptr size) INTERFACE_ATTRIBUTE;
      47  // Callback for memory free.
      48  // Can be aggregated for several objects (preferably).
      49  void __tsan_java_free(jptr ptr, jptr size) INTERFACE_ATTRIBUTE;
      50  // Callback for memory move by GC.
      51  // Can be aggregated for several objects (preferably).
      52  // The ranges can overlap.
      53  void __tsan_java_move(jptr src, jptr dst, jptr size) INTERFACE_ATTRIBUTE;
      54  // This function must be called on the finalizer thread
      55  // before executing a batch of finalizers.
      56  // It ensures necessary synchronization between
      57  // java object creation and finalization.
      58  void __tsan_java_finalize() INTERFACE_ATTRIBUTE;
      59  // Finds the first allocated memory block in the [*from_ptr, to) range, saves
      60  // its address in *from_ptr and returns its size. Returns 0 if there are no
      61  // allocated memory blocks in the range.
      62  jptr __tsan_java_find(jptr *from_ptr, jptr to) INTERFACE_ATTRIBUTE;
      63  
      64  // Mutex lock.
      65  // Addr is any unique address associated with the mutex.
      66  // Can be called on recursive reentry.
      67  void __tsan_java_mutex_lock(jptr addr) INTERFACE_ATTRIBUTE;
      68  // Mutex unlock.
      69  void __tsan_java_mutex_unlock(jptr addr) INTERFACE_ATTRIBUTE;
      70  // Mutex read lock.
      71  void __tsan_java_mutex_read_lock(jptr addr) INTERFACE_ATTRIBUTE;
      72  // Mutex read unlock.
      73  void __tsan_java_mutex_read_unlock(jptr addr) INTERFACE_ATTRIBUTE;
      74  // Recursive mutex lock, intended for handling of Object.wait().
      75  // The 'rec' value must be obtained from the previous
      76  // __tsan_java_mutex_unlock_rec().
      77  void __tsan_java_mutex_lock_rec(jptr addr, int rec) INTERFACE_ATTRIBUTE;
      78  // Recursive mutex unlock, intended for handling of Object.wait().
      79  // The return value says how many times this thread called lock()
      80  // w/o a pairing unlock() (i.e. how many recursive levels it unlocked).
      81  // It must be passed back to __tsan_java_mutex_lock_rec() to restore
      82  // the same recursion level.
      83  int __tsan_java_mutex_unlock_rec(jptr addr) INTERFACE_ATTRIBUTE;
      84  
      85  // Raw acquire/release primitives.
      86  // Can be used to establish happens-before edges on volatile/final fields,
      87  // in atomic operations, etc. release_store is the same as release, but it
      88  // breaks release sequence on addr (see C++ standard 1.10/7 for details).
      89  void __tsan_java_acquire(jptr addr) INTERFACE_ATTRIBUTE;
      90  void __tsan_java_release(jptr addr) INTERFACE_ATTRIBUTE;
      91  void __tsan_java_release_store(jptr addr) INTERFACE_ATTRIBUTE;
      92  
      93  #ifdef __cplusplus
      94  }  // extern "C"
      95  #endif
      96  
      97  #undef INTERFACE_ATTRIBUTE
      98  
      99  #endif  // #ifndef TSAN_INTERFACE_JAVA_H