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