1 /*
  2  * Copyright (c) 2018, 2020, 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_ACCESSDECORATORS_HPP
 26 #define SHARE_OOPS_ACCESSDECORATORS_HPP
 27 
 28 #include "gc/shared/barrierSetConfig.hpp"
 29 #include "memory/allocation.hpp"
 30 #include "metaprogramming/integralConstant.hpp"
 31 #include "utilities/globalDefinitions.hpp"
 32 
 33 // A decorator is an attribute or property that affects the way a memory access is performed in some way.
 34 // There are different groups of decorators. Some have to do with memory ordering, others to do with,
 35 // e.g. strength of references, strength of GC barriers, or whether compression should be applied or not.
 36 // Some decorators are set at buildtime, such as whether primitives require GC barriers or not, others
 37 // at callsites such as whether an access is in the heap or not, and others are resolved at runtime
 38 // such as GC-specific barriers and encoding/decoding compressed oops.
 39 typedef uint64_t DecoratorSet;
 40 
 41 // The HasDecorator trait can help at compile-time determining whether a decorator set
 42 // has an intersection with a certain other decorator set
 43 template <DecoratorSet decorators, DecoratorSet decorator>
 44 struct HasDecorator: public IntegralConstant<bool, (decorators & decorator) != 0> {};
 45 
 46 // == General Decorators ==
 47 // * DECORATORS_NONE: This is the name for the empty decorator set (in absence of other decorators).
 48 const DecoratorSet DECORATORS_NONE                   = UCONST64(0);
 49 
 50 // == Internal Decorators - do not use ==
 51 // * INTERNAL_CONVERT_COMPRESSED_OOPS: This is an oop access that will require converting an oop
 52 //   to a narrowOop or vice versa, if UseCompressedOops is known to be set.
 53 // * INTERNAL_VALUE_IS_OOP: Remember that the involved access is on oop rather than primitive.
 54 const DecoratorSet INTERNAL_CONVERT_COMPRESSED_OOP   = UCONST64(1) << 1;
 55 const DecoratorSet INTERNAL_VALUE_IS_OOP             = UCONST64(1) << 2;
 56 
 57 // == Internal run-time Decorators ==
 58 // * INTERNAL_RT_USE_COMPRESSED_OOPS: This decorator will be set in runtime resolved
 59 //   access backends iff UseCompressedOops is true.
 60 const DecoratorSet INTERNAL_RT_USE_COMPRESSED_OOPS   = UCONST64(1) << 5;
 61 
 62 const DecoratorSet INTERNAL_DECORATOR_MASK           = INTERNAL_CONVERT_COMPRESSED_OOP | INTERNAL_VALUE_IS_OOP |
 63                                                        INTERNAL_RT_USE_COMPRESSED_OOPS;
 64 
 65 // == Memory Ordering Decorators ==
 66 // The memory ordering decorators can be described in the following way:
 67 // === Decorator Rules ===
 68 // The different types of memory ordering guarantees have a strict order of strength.
 69 // Explicitly specifying the stronger ordering implies that the guarantees of the weaker
 70 // property holds too. The names come from the C++11 atomic operations, and typically
 71 // have a JMM equivalent property.
 72 // The equivalence may be viewed like this:
 73 // MO_UNORDERED is equivalent to JMM plain.
 74 // MO_RELAXED is equivalent to JMM opaque.
 75 // MO_ACQUIRE is equivalent to JMM acquire.
 76 // MO_RELEASE is equivalent to JMM release.
 77 // MO_SEQ_CST is equivalent to JMM volatile.
 78 //
 79 // === Stores ===
 80 //  * MO_UNORDERED (Default): No guarantees.
 81 //    - The compiler and hardware are free to reorder aggressively. And they will.
 82 //  * MO_RELAXED: Relaxed atomic stores.
 83 //    - The stores are atomic.
 84 //    - The stores are not reordered by the compiler (but possibly the HW) w.r.t
 85 //      other ordered accesses in program order.
 86 //    - Also used for C++ volatile stores, since actual usage of volatile
 87 //      requires no word tearing.
 88 //  * MO_RELEASE: Releasing stores.
 89 //    - The releasing store will make its preceding memory accesses observable to memory accesses
 90 //      subsequent to an acquiring load observing this releasing store.
 91 //    - Guarantees from relaxed stores hold.
 92 //  * MO_SEQ_CST: Sequentially consistent stores.
 93 //    - The stores are observed in the same order by MO_SEQ_CST loads on other processors
 94 //    - Preceding loads and stores in program order are not reordered with subsequent loads and stores in program order.
 95 //    - Guarantees from releasing stores hold.
 96 // === Loads ===
 97 //  * MO_UNORDERED (Default): No guarantees
 98 //    - The compiler and hardware are free to reorder aggressively. And they will.
 99 //  * MO_RELAXED: Relaxed atomic loads.
100 //    - The loads are atomic.
101 //    - The loads are not reordered by the compiler (but possibly the HW) w.r.t.
102 //      other ordered accesses in program order.
103 //    - Also used for C++ volatile loads, since actual usage of volatile
104 //      requires no word tearing.
105 //  * MO_ACQUIRE: Acquiring loads.
106 //    - An acquiring load will make subsequent memory accesses observe the memory accesses
107 //      preceding the releasing store that the acquiring load observed.
108 //    - Guarantees from relaxed loads hold.
109 //  * MO_SEQ_CST: Sequentially consistent loads.
110 //    - These loads observe MO_SEQ_CST stores in the same order on other processors
111 //    - Preceding loads and stores in program order are not reordered with subsequent loads and stores in program order.
112 //    - Guarantees from acquiring loads hold.
113 // === Atomic Cmpxchg ===
114 //  * MO_RELAXED: Atomic but relaxed cmpxchg.
115 //    - Guarantees from MO_RELAXED loads and MO_RELAXED stores hold unconditionally.
116 //  * MO_SEQ_CST: Sequentially consistent cmpxchg.
117 //    - Guarantees from MO_SEQ_CST loads and MO_SEQ_CST stores hold unconditionally.
118 // === Atomic Xchg ===
119 //  * MO_RELAXED: Atomic but relaxed atomic xchg.
120 //    - Guarantees from MO_RELAXED loads and MO_RELAXED stores hold.
121 //  * MO_SEQ_CST: Sequentially consistent xchg.
122 //    - Guarantees from MO_SEQ_CST loads and MO_SEQ_CST stores hold.
123 const DecoratorSet MO_UNORDERED      = UCONST64(1) << 6;
124 const DecoratorSet MO_RELAXED        = UCONST64(1) << 7;
125 const DecoratorSet MO_ACQUIRE        = UCONST64(1) << 8;
126 const DecoratorSet MO_RELEASE        = UCONST64(1) << 9;
127 const DecoratorSet MO_SEQ_CST        = UCONST64(1) << 10;
128 const DecoratorSet MO_DECORATOR_MASK = MO_UNORDERED | MO_RELAXED |
129                                        MO_ACQUIRE | MO_RELEASE | MO_SEQ_CST;
130 
131 // === Barrier Strength Decorators ===
132 // * AS_RAW: The access will translate into a raw memory access, hence ignoring all semantic concerns
133 //   except memory ordering and compressed oops. This will bypass runtime function pointer dispatching
134 //   in the pipeline and hardwire to raw accesses without going trough the GC access barriers.
135 //  - Accesses on oop* translate to raw memory accesses without runtime checks
136 //  - Accesses on narrowOop* translate to encoded/decoded memory accesses without runtime checks
137 //  - Accesses on HeapWord* translate to a runtime check choosing one of the above
138 //  - Accesses on other types translate to raw memory accesses without runtime checks
139 // * AS_NO_KEEPALIVE: The barrier is used only on oop references and will not keep any involved objects
140 //   alive, regardless of the type of reference being accessed. It will however perform the memory access
141 //   in a consistent way w.r.t. e.g. concurrent compaction, so that the right field is being accessed,
142 //   or maintain, e.g. intergenerational or interregional pointers if applicable. This should be used with
143 //   extreme caution in isolated scopes.
144 // * AS_NORMAL: The accesses will be resolved to an accessor on the BarrierSet class, giving the
145 //   responsibility of performing the access and what barriers to be performed to the GC. This is the default.
146 //   Note that primitive accesses will only be resolved on the barrier set if the appropriate build-time
147 //   decorator for enabling primitive barriers is enabled for the build.
148 const DecoratorSet AS_RAW                  = UCONST64(1) << 11;
149 const DecoratorSet AS_NO_KEEPALIVE         = UCONST64(1) << 12;
150 const DecoratorSet AS_NORMAL               = UCONST64(1) << 13;
151 const DecoratorSet AS_DECORATOR_MASK       = AS_RAW | AS_NO_KEEPALIVE | AS_NORMAL;
152 
153 // === Reference Strength Decorators ===
154 // These decorators only apply to accesses on oop-like types (oop/narrowOop).
155 // * ON_STRONG_OOP_REF: Memory access is performed on a strongly reachable reference.
156 // * ON_WEAK_OOP_REF: The memory access is performed on a weakly reachable reference.
157 // * ON_PHANTOM_OOP_REF: The memory access is performed on a phantomly reachable reference.
158 //   This is the same ring of strength as jweak and weak oops in the VM.
159 // * ON_UNKNOWN_OOP_REF: The memory access is performed on a reference of unknown strength.
160 //   This could for example come from the unsafe API.
161 // * Default (no explicit reference strength specified): ON_STRONG_OOP_REF
162 const DecoratorSet ON_STRONG_OOP_REF  = UCONST64(1) << 14;
163 const DecoratorSet ON_WEAK_OOP_REF    = UCONST64(1) << 15;
164 const DecoratorSet ON_PHANTOM_OOP_REF = UCONST64(1) << 16;
165 const DecoratorSet ON_UNKNOWN_OOP_REF = UCONST64(1) << 17;
166 const DecoratorSet ON_DECORATOR_MASK  = ON_STRONG_OOP_REF | ON_WEAK_OOP_REF |
167                                         ON_PHANTOM_OOP_REF | ON_UNKNOWN_OOP_REF;
168 
169 // === Access Location ===
170 // Accesses can take place in, e.g. the heap, old or young generation, different native roots, or native memory off the heap.
171 // The location is important to the GC as it may imply different actions. The following decorators are used:
172 // * IN_HEAP: The access is performed in the heap. Many barriers such as card marking will
173 //   be omitted if this decorator is not set.
174 // * IN_NATIVE: The access is performed in an off-heap data structure.
175 const DecoratorSet IN_HEAP            = UCONST64(1) << 18;
176 const DecoratorSet IN_NATIVE          = UCONST64(1) << 19;
177 const DecoratorSet IN_DECORATOR_MASK  = IN_HEAP | IN_NATIVE;
178 
179 // == Boolean Flag Decorators ==
180 // * IS_ARRAY: The access is performed on a heap allocated array. This is sometimes a special case
181 //   for some GCs.
182 // * IS_DEST_UNINITIALIZED: This property can be important to e.g. SATB barriers by
183 //   marking that the previous value is uninitialized nonsense rather than a real value.
184 // * IS_NOT_NULL: This property can make certain barriers faster such as compressing oops.
185 const DecoratorSet IS_ARRAY              = UCONST64(1) << 20;
186 const DecoratorSet IS_DEST_UNINITIALIZED = UCONST64(1) << 21;
187 const DecoratorSet IS_NOT_NULL           = UCONST64(1) << 22;
188 
189 // == Arraycopy Decorators ==
190 // * ARRAYCOPY_CHECKCAST: This property means that the class of the objects in source
191 //   are not guaranteed to be subclasses of the class of the destination array. This requires
192 //   a check-cast barrier during the copying operation. If this is not set, it is assumed
193 //   that the array is covariant: (the source array type is-a destination array type)
194 // * ARRAYCOPY_DISJOINT: This property means that it is known that the two array ranges
195 //   are disjoint.
196 // * ARRAYCOPY_ARRAYOF: The copy is in the arrayof form.
197 // * ARRAYCOPY_ATOMIC: The accesses have to be atomic over the size of its elements.
198 // * ARRAYCOPY_ALIGNED: The accesses have to be aligned on a HeapWord.
199 const DecoratorSet ARRAYCOPY_CHECKCAST            = UCONST64(1) << 23;
200 const DecoratorSet ARRAYCOPY_DISJOINT             = UCONST64(1) << 24;
201 const DecoratorSet ARRAYCOPY_ARRAYOF              = UCONST64(1) << 25;
202 const DecoratorSet ARRAYCOPY_ATOMIC               = UCONST64(1) << 26;
203 const DecoratorSet ARRAYCOPY_ALIGNED              = UCONST64(1) << 27;
204 const DecoratorSet ARRAYCOPY_DECORATOR_MASK       = ARRAYCOPY_CHECKCAST | ARRAYCOPY_DISJOINT |
205                                                     ARRAYCOPY_DISJOINT | ARRAYCOPY_ARRAYOF |
206                                                     ARRAYCOPY_ATOMIC | ARRAYCOPY_ALIGNED;
207 
208 // == Resolve barrier decorators ==
209 // * ACCESS_READ: Indicate that the resolved object is accessed read-only. This allows the GC
210 //   backend to use weaker and more efficient barriers.
211 // * ACCESS_WRITE: Indicate that the resolved object is used for write access.
212 const DecoratorSet ACCESS_READ                    = UCONST64(1) << 28;
213 const DecoratorSet ACCESS_WRITE                   = UCONST64(1) << 29;
214 
215 // Keep track of the last decorator.
216 const DecoratorSet DECORATOR_LAST = UCONST64(1) << 29;
217 
218 namespace AccessInternal {
219   // This class adds implied decorators that follow according to decorator rules.
220   // For example adding default reference strength and default memory ordering
221   // semantics.
222   template <DecoratorSet input_decorators>
223   struct DecoratorFixup: AllStatic {
224     // If no reference strength has been picked, then strong will be picked
225     static const DecoratorSet ref_strength_default = input_decorators |
226       (((ON_DECORATOR_MASK & input_decorators) == 0 && (INTERNAL_VALUE_IS_OOP & input_decorators) != 0) ?
227        ON_STRONG_OOP_REF : DECORATORS_NONE);
228     // If no memory ordering has been picked, unordered will be picked
229     static const DecoratorSet memory_ordering_default = ref_strength_default |
230       ((MO_DECORATOR_MASK & ref_strength_default) == 0 ? MO_UNORDERED : DECORATORS_NONE);
231     // If no barrier strength has been picked, normal will be used
232     static const DecoratorSet barrier_strength_default = memory_ordering_default |
233       ((AS_DECORATOR_MASK & memory_ordering_default) == 0 ? AS_NORMAL : DECORATORS_NONE);
234     static const DecoratorSet value = barrier_strength_default;
235   };
236 
237   // This function implements the above DecoratorFixup rules, but without meta
238   // programming for code generation that does not use templates.
239   inline DecoratorSet decorator_fixup(DecoratorSet input_decorators) {
240     // If no reference strength has been picked, then strong will be picked
241     DecoratorSet ref_strength_default = input_decorators |
242       (((ON_DECORATOR_MASK & input_decorators) == 0 && (INTERNAL_VALUE_IS_OOP & input_decorators) != 0) ?
243        ON_STRONG_OOP_REF : DECORATORS_NONE);
244     // If no memory ordering has been picked, unordered will be picked
245     DecoratorSet memory_ordering_default = ref_strength_default |
246       ((MO_DECORATOR_MASK & ref_strength_default) == 0 ? MO_UNORDERED : DECORATORS_NONE);
247     // If no barrier strength has been picked, normal will be used
248     DecoratorSet barrier_strength_default = memory_ordering_default |
249       ((AS_DECORATOR_MASK & memory_ordering_default) == 0 ? AS_NORMAL : DECORATORS_NONE);
250     return barrier_strength_default;
251   }
252 }
253 
254 #endif // SHARE_OOPS_ACCESSDECORATORS_HPP