1 /*
   2  * Copyright (c) 2017, 2018, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.
   8  *
   9  * This code is distributed in the hope that it will be useful, but WITHOUT
  10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * version 2 for more details (a copy is included in the LICENSE file that
  13  * accompanied this code).
  14  *
  15  * You should have received a copy of the GNU General Public License version
  16  * 2 along with this work; if not, write to the Free Software Foundation,
  17  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  18  *
  19  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  20  * or visit www.oracle.com if you need additional information or have any
  21  * questions.
  22  *
  23  */
  24 
  25 #ifndef SHARE_OOPS_ACCESS_HPP
  26 #define SHARE_OOPS_ACCESS_HPP
  27 
  28 #include "memory/allocation.hpp"
  29 #include "oops/accessBackend.hpp"
  30 #include "oops/accessDecorators.hpp"
  31 #include "oops/oopsHierarchy.hpp"
  32 #include "utilities/debug.hpp"
  33 #include "utilities/globalDefinitions.hpp"
  34 
  35 
  36 // = GENERAL =
  37 // Access is an API for performing accesses with declarative semantics. Each access can have a number of "decorators".
  38 // A decorator is an attribute or property that affects the way a memory access is performed in some way.
  39 // There are different groups of decorators. Some have to do with memory ordering, others to do with,
  40 // e.g. strength of references, strength of GC barriers, or whether compression should be applied or not.
  41 // Some decorators are set at buildtime, such as whether primitives require GC barriers or not, others
  42 // at callsites such as whether an access is in the heap or not, and others are resolved at runtime
  43 // such as GC-specific barriers and encoding/decoding compressed oops. For more information about what
  44 // decorators are available, cf. oops/accessDecorators.hpp.
  45 // By pipelining handling of these decorators, the design of the Access API allows separation of concern
  46 // over the different orthogonal concerns of decorators, while providing a powerful way of
  47 // expressing these orthogonal semantic properties in a unified way.
  48 //
  49 // == OPERATIONS ==
  50 // * load: Load a value from an address.
  51 // * load_at: Load a value from an internal pointer relative to a base object.
  52 // * store: Store a value at an address.
  53 // * store_at: Store a value in an internal pointer relative to a base object.
  54 // * atomic_cmpxchg: Atomically compare-and-swap a new value at an address if previous value matched the compared value.
  55 // * atomic_cmpxchg_at: Atomically compare-and-swap a new value at an internal pointer address if previous value matched the compared value.
  56 // * atomic_xchg: Atomically swap a new value at an address if previous value matched the compared value.
  57 // * atomic_xchg_at: Atomically swap a new value at an internal pointer address if previous value matched the compared value.
  58 // * arraycopy: Copy data from one heap array to another heap array.
  59 // * clone: Clone the contents of an object to a newly allocated object.
  60 // * resolve: Resolve a stable to-space invariant oop that is guaranteed not to relocate its payload until a subsequent thread transition.
  61 // * equals: Object equality, e.g. when different copies of the same objects are in use (from-space vs. to-space)
  62 //
  63 // == IMPLEMENTATION ==
  64 // Each access goes through the following steps in a template pipeline.
  65 // There are essentially 5 steps for each access:
  66 // * Step 1:   Set default decorators and decay types. This step gets rid of CV qualifiers
  67 //             and sets default decorators to sensible values.
  68 // * Step 2:   Reduce types. This step makes sure there is only a single T type and not
  69 //             multiple types. The P type of the address and T type of the value must
  70 //             match.
  71 // * Step 3:   Pre-runtime dispatch. This step checks whether a runtime call can be
  72 //             avoided, and in that case avoids it (calling raw accesses or
  73 //             primitive accesses in a build that does not require primitive GC barriers)
  74 // * Step 4:   Runtime-dispatch. This step performs a runtime dispatch to the corresponding
  75 //             BarrierSet::AccessBarrier accessor that attaches GC-required barriers
  76 //             to the access.
  77 // * Step 5.a: Barrier resolution. This step is invoked the first time a runtime-dispatch
  78 //             happens for an access. The appropriate BarrierSet::AccessBarrier accessor
  79 //             is resolved, then the function pointer is updated to that accessor for
  80 //             future invocations.
  81 // * Step 5.b: Post-runtime dispatch. This step now casts previously unknown types such
  82 //             as the address type of an oop on the heap (is it oop* or narrowOop*) to
  83 //             the appropriate type. It also splits sufficiently orthogonal accesses into
  84 //             different functions, such as whether the access involves oops or primitives
  85 //             and whether the access is performed on the heap or outside. Then the
  86 //             appropriate BarrierSet::AccessBarrier is called to perform the access.
  87 //
  88 // The implementation of step 1-4 resides in in accessBackend.hpp, to allow selected
  89 // accesses to be accessible from only access.hpp, as opposed to access.inline.hpp.
  90 // Steps 5.a and 5.b require knowledge about the GC backends, and therefore needs to
  91 // include the various GC backend .inline.hpp headers. Their implementation resides in
  92 // access.inline.hpp. The accesses that are allowed through the access.hpp file
  93 // must be instantiated in access.cpp using the INSTANTIATE_HPP_ACCESS macro.
  94 
  95 template <DecoratorSet decorators = INTERNAL_EMPTY>
  96 class Access: public AllStatic {
  97   // This function asserts that if an access gets passed in a decorator outside
  98   // of the expected_decorators, then something is wrong. It additionally checks
  99   // the consistency of the decorators so that supposedly disjoint decorators are indeed
 100   // disjoint. For example, an access can not be both in heap and on root at the
 101   // same time.
 102   template <DecoratorSet expected_decorators>
 103   static void verify_decorators();
 104 
 105   template <DecoratorSet expected_mo_decorators>
 106   static void verify_primitive_decorators() {
 107     const DecoratorSet primitive_decorators = (AS_DECORATOR_MASK ^ AS_NO_KEEPALIVE ^ AS_DEST_NOT_INITIALIZED) |
 108                                               IN_HEAP | IN_HEAP_ARRAY;
 109     verify_decorators<expected_mo_decorators | primitive_decorators>();
 110   }
 111 
 112   template <DecoratorSet expected_mo_decorators>
 113   static void verify_oop_decorators() {
 114     const DecoratorSet oop_decorators = AS_DECORATOR_MASK | IN_DECORATOR_MASK |
 115                                         (ON_DECORATOR_MASK ^ ON_UNKNOWN_OOP_REF) | // no unknown oop refs outside of the heap
 116                                         OOP_DECORATOR_MASK;
 117     verify_decorators<expected_mo_decorators | oop_decorators>();
 118   }
 119 
 120   template <DecoratorSet expected_mo_decorators>
 121   static void verify_heap_oop_decorators() {
 122     const DecoratorSet heap_oop_decorators = AS_DECORATOR_MASK | ON_DECORATOR_MASK |
 123                                              OOP_DECORATOR_MASK | (IN_DECORATOR_MASK ^
 124                                                                    (IN_ROOT | IN_CONCURRENT_ROOT)); // no root accesses in the heap
 125     verify_decorators<expected_mo_decorators | heap_oop_decorators>();
 126   }
 127 
 128   static const DecoratorSet load_mo_decorators = MO_UNORDERED | MO_VOLATILE | MO_RELAXED | MO_ACQUIRE | MO_SEQ_CST;
 129   static const DecoratorSet store_mo_decorators = MO_UNORDERED | MO_VOLATILE | MO_RELAXED | MO_RELEASE | MO_SEQ_CST;
 130   static const DecoratorSet atomic_xchg_mo_decorators = MO_SEQ_CST;
 131   static const DecoratorSet atomic_cmpxchg_mo_decorators = MO_RELAXED | MO_SEQ_CST;
 132 
 133 public:
 134   // Primitive heap accesses
 135   static inline AccessInternal::LoadAtProxy<decorators> load_at(oop base, ptrdiff_t offset) {
 136     verify_primitive_decorators<load_mo_decorators>();
 137     return AccessInternal::LoadAtProxy<decorators>(base, offset);
 138   }
 139 
 140   template <typename T>
 141   static inline void store_at(oop base, ptrdiff_t offset, T value) {
 142     verify_primitive_decorators<store_mo_decorators>();
 143     AccessInternal::store_at<decorators>(base, offset, value);
 144   }
 145 
 146   template <typename T>
 147   static inline T atomic_cmpxchg_at(T new_value, oop base, ptrdiff_t offset, T compare_value) {
 148     verify_primitive_decorators<atomic_cmpxchg_mo_decorators>();
 149     return AccessInternal::atomic_cmpxchg_at<decorators>(new_value, base, offset, compare_value);
 150   }
 151 
 152   template <typename T>
 153   static inline T atomic_xchg_at(T new_value, oop base, ptrdiff_t offset) {
 154     verify_primitive_decorators<atomic_xchg_mo_decorators>();
 155     return AccessInternal::atomic_xchg_at<decorators>(new_value, base, offset);
 156   }
 157 
 158   template <typename T>
 159   static inline void arraycopy(arrayOop src_obj, size_t src_offset_in_bytes, const T* src_raw,
 160                                arrayOop dst_obj, size_t dst_offset_in_bytes, T* dst_raw,
 161                                size_t length) {
 162     verify_decorators<ARRAYCOPY_DECORATOR_MASK | IN_HEAP | IN_HEAP_ARRAY |
 163                       AS_DECORATOR_MASK>();
 164     AccessInternal::arraycopy<decorators>(src_obj, src_offset_in_bytes, src_raw,
 165                                           dst_obj, dst_offset_in_bytes, dst_raw,
 166                                           length);
 167   }
 168 
 169   // Oop heap accesses
 170   static inline AccessInternal::OopLoadAtProxy<decorators> oop_load_at(oop base, ptrdiff_t offset) {
 171     verify_heap_oop_decorators<load_mo_decorators>();
 172     return AccessInternal::OopLoadAtProxy<decorators>(base, offset);
 173   }
 174 
 175   template <typename T>
 176   static inline void oop_store_at(oop base, ptrdiff_t offset, T value) {
 177     verify_heap_oop_decorators<store_mo_decorators>();
 178     typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType;
 179     OopType oop_value = value;
 180     AccessInternal::store_at<decorators | INTERNAL_VALUE_IS_OOP>(base, offset, oop_value);
 181   }
 182 
 183   template <typename T>
 184   static inline T oop_atomic_cmpxchg_at(T new_value, oop base, ptrdiff_t offset, T compare_value) {
 185     verify_heap_oop_decorators<atomic_cmpxchg_mo_decorators>();
 186     typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType;
 187     OopType new_oop_value = new_value;
 188     OopType compare_oop_value = compare_value;
 189     return AccessInternal::atomic_cmpxchg_at<decorators | INTERNAL_VALUE_IS_OOP>(new_oop_value, base, offset, compare_oop_value);
 190   }
 191 
 192   template <typename T>
 193   static inline T oop_atomic_xchg_at(T new_value, oop base, ptrdiff_t offset) {
 194     verify_heap_oop_decorators<atomic_xchg_mo_decorators>();
 195     typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType;
 196     OopType new_oop_value = new_value;
 197     return AccessInternal::atomic_xchg_at<decorators | INTERNAL_VALUE_IS_OOP>(new_oop_value, base, offset);
 198   }
 199 
 200   template <typename T>
 201   static inline bool oop_arraycopy(arrayOop src_obj, size_t src_offset_in_bytes, const T* src_raw,
 202                                    arrayOop dst_obj, size_t dst_offset_in_bytes, T* dst_raw,
 203                                    size_t length) {
 204     verify_decorators<ARRAYCOPY_DECORATOR_MASK | IN_HEAP |  IN_HEAP_ARRAY |
 205                       AS_DECORATOR_MASK>();
 206     return AccessInternal::arraycopy<decorators | INTERNAL_VALUE_IS_OOP>(src_obj, src_offset_in_bytes, src_raw,
 207                                                                          dst_obj, dst_offset_in_bytes, dst_raw,
 208                                                                          length);
 209   }
 210 
 211   // Clone an object from src to dst
 212   static inline void clone(oop src, oop dst, size_t size) {
 213     verify_decorators<IN_HEAP>();
 214     AccessInternal::clone<decorators>(src, dst, size);
 215   }
 216 
 217   // Primitive accesses
 218   template <typename P>
 219   static inline P load(P* addr) {
 220     verify_primitive_decorators<load_mo_decorators>();
 221     return AccessInternal::load<decorators, P, P>(addr);
 222   }
 223 
 224   template <typename P, typename T>
 225   static inline void store(P* addr, T value) {
 226     verify_primitive_decorators<store_mo_decorators>();
 227     AccessInternal::store<decorators>(addr, value);
 228   }
 229 
 230   template <typename P, typename T>
 231   static inline T atomic_cmpxchg(T new_value, P* addr, T compare_value) {
 232     verify_primitive_decorators<atomic_cmpxchg_mo_decorators>();
 233     return AccessInternal::atomic_cmpxchg<decorators>(new_value, addr, compare_value);
 234   }
 235 
 236   template <typename P, typename T>
 237   static inline T atomic_xchg(T new_value, P* addr) {
 238     verify_primitive_decorators<atomic_xchg_mo_decorators>();
 239     return AccessInternal::atomic_xchg<decorators>(new_value, addr);
 240   }
 241 
 242   // Oop accesses
 243   template <typename P>
 244   static inline AccessInternal::OopLoadProxy<P, decorators> oop_load(P* addr) {
 245     verify_oop_decorators<load_mo_decorators>();
 246     return AccessInternal::OopLoadProxy<P, decorators>(addr);
 247   }
 248 
 249   template <typename P, typename T>
 250   static inline void oop_store(P* addr, T value) {
 251     verify_oop_decorators<store_mo_decorators>();
 252     typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType;
 253     OopType oop_value = value;
 254     AccessInternal::store<decorators | INTERNAL_VALUE_IS_OOP>(addr, oop_value);
 255   }
 256 
 257   template <typename P, typename T>
 258   static inline T oop_atomic_cmpxchg(T new_value, P* addr, T compare_value) {
 259     verify_oop_decorators<atomic_cmpxchg_mo_decorators>();
 260     typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType;
 261     OopType new_oop_value = new_value;
 262     OopType compare_oop_value = compare_value;
 263     return AccessInternal::atomic_cmpxchg<decorators | INTERNAL_VALUE_IS_OOP>(new_oop_value, addr, compare_oop_value);
 264   }
 265 
 266   template <typename P, typename T>
 267   static inline T oop_atomic_xchg(T new_value, P* addr) {
 268     verify_oop_decorators<atomic_xchg_mo_decorators>();
 269     typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType;
 270     OopType new_oop_value = new_value;
 271     return AccessInternal::atomic_xchg<decorators | INTERNAL_VALUE_IS_OOP>(new_oop_value, addr);
 272   }
 273 
 274   static oop resolve(oop obj) {
 275     verify_decorators<INTERNAL_EMPTY>();
 276     return AccessInternal::resolve<decorators>(obj);
 277   }
 278 
 279   static bool equals(oop o1, oop o2) {
 280     verify_decorators<INTERNAL_EMPTY>();
 281     return AccessInternal::equals<decorators>(o1, o2);
 282   }
 283 };
 284 
 285 // Helper for performing raw accesses (knows only of memory ordering
 286 // atomicity decorators as well as compressed oops)
 287 template <DecoratorSet decorators = INTERNAL_EMPTY>
 288 class RawAccess: public Access<AS_RAW | decorators> {};
 289 
 290 // Helper for performing normal accesses on the heap. These accesses
 291 // may resolve an accessor on a GC barrier set
 292 template <DecoratorSet decorators = INTERNAL_EMPTY>
 293 class HeapAccess: public Access<IN_HEAP | decorators> {};
 294 
 295 // Helper for performing normal accesses in roots. These accesses
 296 // may resolve an accessor on a GC barrier set
 297 template <DecoratorSet decorators = INTERNAL_EMPTY>
 298 class RootAccess: public Access<IN_ROOT | decorators> {};
 299 
 300 // Helper for array access.
 301 template <DecoratorSet decorators = INTERNAL_EMPTY>
 302 class ArrayAccess: public HeapAccess<IN_HEAP_ARRAY | decorators> {
 303 public:
 304   template <typename T>
 305   static inline void arraycopy(arrayOop src_obj, size_t src_offset_in_bytes,
 306                                arrayOop dst_obj, size_t dst_offset_in_bytes,
 307                                size_t length) {
 308     HeapAccess<decorators | IN_HEAP_ARRAY>::arraycopy(src_obj, src_offset_in_bytes, (const T*) NULL,
 309                                                       dst_obj, dst_offset_in_bytes, (T*) NULL,
 310                                                       length);
 311   }
 312 
 313   template <typename T>
 314   static inline void arraycopy_to_native(arrayOop src_obj, size_t src_offset_in_bytes, T* dst, size_t length) {
 315     HeapAccess<decorators | IN_HEAP_ARRAY>::arraycopy(src_obj, src_offset_in_bytes, (const T*) NULL,
 316                                                       NULL, 0, dst,
 317                                                       length);
 318   }
 319 
 320   template <typename T>
 321   static inline void arraycopy_from_native(const T* src, arrayOop dst_obj, size_t dst_offset_in_bytes, size_t length) {
 322     HeapAccess<decorators | IN_HEAP_ARRAY>::arraycopy(NULL, 0, src, dst_obj, dst_offset_in_bytes, (T*) NULL, length);
 323   }
 324 
 325   template <typename T>
 326   static inline bool oop_arraycopy(arrayOop src_obj, size_t src_offset_in_bytes,
 327                                    arrayOop dst_obj, size_t dst_offset_in_bytes,
 328                                    size_t length) {
 329     return HeapAccess<decorators | IN_HEAP_ARRAY>::oop_arraycopy(src_obj, src_offset_in_bytes, (const T*) NULL,
 330                                                                  dst_obj, dst_offset_in_bytes, (T*) NULL, length);
 331   }
 332 
 333   template <typename T>
 334   static inline bool oop_arraycopy_raw(T* src, T* dst, size_t length) {
 335     return HeapAccess<decorators | IN_HEAP_ARRAY>::oop_arraycopy(NULL, 0, src, NULL, 0, dst, length);
 336   }
 337 
 338 };
 339 
 340 template <DecoratorSet decorators>
 341 template <DecoratorSet expected_decorators>
 342 void Access<decorators>::verify_decorators() {
 343   STATIC_ASSERT((~expected_decorators & decorators) == 0); // unexpected decorator used
 344   const DecoratorSet barrier_strength_decorators = decorators & AS_DECORATOR_MASK;
 345   STATIC_ASSERT(barrier_strength_decorators == 0 || ( // make sure barrier strength decorators are disjoint if set
 346     (barrier_strength_decorators ^ AS_NO_KEEPALIVE) == 0 ||
 347     (barrier_strength_decorators ^ AS_DEST_NOT_INITIALIZED) == 0 ||
 348     (barrier_strength_decorators ^ AS_RAW) == 0 ||
 349     (barrier_strength_decorators ^ AS_NORMAL) == 0
 350   ));
 351   const DecoratorSet ref_strength_decorators = decorators & ON_DECORATOR_MASK;
 352   STATIC_ASSERT(ref_strength_decorators == 0 || ( // make sure ref strength decorators are disjoint if set
 353     (ref_strength_decorators ^ ON_STRONG_OOP_REF) == 0 ||
 354     (ref_strength_decorators ^ ON_WEAK_OOP_REF) == 0 ||
 355     (ref_strength_decorators ^ ON_PHANTOM_OOP_REF) == 0 ||
 356     (ref_strength_decorators ^ ON_UNKNOWN_OOP_REF) == 0
 357   ));
 358   const DecoratorSet memory_ordering_decorators = decorators & MO_DECORATOR_MASK;
 359   STATIC_ASSERT(memory_ordering_decorators == 0 || ( // make sure memory ordering decorators are disjoint if set
 360     (memory_ordering_decorators ^ MO_UNORDERED) == 0 ||
 361     (memory_ordering_decorators ^ MO_VOLATILE) == 0 ||
 362     (memory_ordering_decorators ^ MO_RELAXED) == 0 ||
 363     (memory_ordering_decorators ^ MO_ACQUIRE) == 0 ||
 364     (memory_ordering_decorators ^ MO_RELEASE) == 0 ||
 365     (memory_ordering_decorators ^ MO_SEQ_CST) == 0
 366   ));
 367   const DecoratorSet location_decorators = decorators & IN_DECORATOR_MASK;
 368   STATIC_ASSERT(location_decorators == 0 || ( // make sure location decorators are disjoint if set
 369     (location_decorators ^ IN_ROOT) == 0 ||
 370     (location_decorators ^ IN_HEAP) == 0 ||
 371     (location_decorators ^ (IN_HEAP | IN_HEAP_ARRAY)) == 0 ||
 372     (location_decorators ^ (IN_ROOT | IN_CONCURRENT_ROOT)) == 0 ||
 373     (location_decorators ^ (IN_ROOT | IN_ARCHIVE_ROOT)) == 0
 374   ));
 375 }
 376 
 377 #endif // SHARE_OOPS_ACCESS_HPP