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 100