Mercurial > hg > graal-jvmci-8
changeset 16347:c6a1215d025b
Improve documentation of LIRKind.
author | Roland Schatz <roland.schatz@oracle.com> |
---|---|
date | Tue, 01 Jul 2014 17:04:39 +0200 |
parents | bbf051d717f5 |
children | fefb82b01d6f |
files | graal/com.oracle.graal.api.meta/src/com/oracle/graal/api/meta/LIRKind.java graal/com.oracle.graal.lir/src/com/oracle/graal/lir/gen/LIRGenerator.java graal/com.oracle.graal.lir/src/com/oracle/graal/lir/gen/LIRGeneratorTool.java |
diffstat | 3 files changed, 40 insertions(+), 8 deletions(-) [+] |
line wrap: on
line diff
--- a/graal/com.oracle.graal.api.meta/src/com/oracle/graal/api/meta/LIRKind.java Tue Jul 01 16:06:17 2014 +0200 +++ b/graal/com.oracle.graal.api.meta/src/com/oracle/graal/api/meta/LIRKind.java Tue Jul 01 17:04:39 2014 +0200 @@ -26,6 +26,32 @@ * Represents the type of values in the LIR. It is composed of a {@link PlatformKind} that gives the * low level representation of the value, and a {@link #referenceMask} that describes the location * of object references in the value. + * + * <h2>Constructing {@link LIRKind} instances</h2> + * + * During LIR generation, every new {@link Value} should get a {@link LIRKind} of the correct + * {@link PlatformKind} that also contains the correct reference information. {@linkplain LIRKind + * LIRKinds} should be created as follows: + * + * <p> + * If the result value is created from one or more input values, the {@link LIRKind} should be + * created with {@link LIRKind#derive}(inputs). If the result has a different {@link PlatformKind} + * than the inputs, {@link LIRKind#derive}(inputs).{@link #changeType}(resultKind) should be used. + * <p> + * If the result is an exact copy of one of the inputs, {@link Value#getLIRKind()} can be used. Note + * that this is only correct for move-like operations, like conditional move or compare-and-swap. + * For convert operations, {@link LIRKind#derive} should be used. + * <p> + * If it is known that the result will be a reference (e.g. pointer arithmetic where the end result + * is a valid oop), {@link LIRKind#reference} should be used. + * <p> + * If it is known that the result will neither be a reference nor be derived from a reference, + * {@link LIRKind#value} can be used. If the operation producing this value has inputs, this is very + * likely wrong, and {@link LIRKind#derive} should be used instead. + * <p> + * If it is known that the result is derived from a reference, {@link LIRKind#derivedReference} can + * be used. In most cases, {@link LIRKind#derive} should be used instead, since it is able to detect + * this automatically. */ public final class LIRKind { @@ -45,7 +71,9 @@ } /** - * Create a {@link LIRKind} of type {@code platformKind} that contains a primitive value. + * Create a {@link LIRKind} of type {@code platformKind} that contains a primitive value. Should + * be only used when it's guaranteed that the value is not even indirectly derived from a + * reference. Otherwise, {@link #derive(Value...)} should be used instead. */ public static LIRKind value(PlatformKind platformKind) { assert platformKind != Kind.Object : "Object should always be used as reference type"; @@ -64,7 +92,9 @@ /** * Create a {@link LIRKind} of type {@code platformKind} that contains a value that is derived - * from a reference. Values of this {@link LIRKind} can not be live at safepoints. + * from a reference. Values of this {@link LIRKind} can not be live at safepoints. In most + * cases, this should not be called directly. {@link #derive} should be used instead to + * automatically propagate this information. */ public static LIRKind derivedReference(PlatformKind platformKind) { return new LIRKind(platformKind, DERIVED_REFERENCE);
--- a/graal/com.oracle.graal.lir/src/com/oracle/graal/lir/gen/LIRGenerator.java Tue Jul 01 16:06:17 2014 +0200 +++ b/graal/com.oracle.graal.lir/src/com/oracle/graal/lir/gen/LIRGenerator.java Tue Jul 01 17:04:39 2014 +0200 @@ -100,12 +100,6 @@ return providers.getForeignCalls(); } - /** - * Creates a new {@linkplain Variable variable}. - * - * @param lirKind The kind of the new variable. - * @return a new variable - */ @Override public Variable newVariable(LIRKind lirKind) { return new Variable(lirKind, res.getLIR().nextVariable());
--- a/graal/com.oracle.graal.lir/src/com/oracle/graal/lir/gen/LIRGeneratorTool.java Tue Jul 01 16:06:17 2014 +0200 +++ b/graal/com.oracle.graal.lir/src/com/oracle/graal/lir/gen/LIRGeneratorTool.java Tue Jul 01 17:04:39 2014 +0200 @@ -106,6 +106,14 @@ RegisterAttributes attributes(Register register); + /** + * Create a new {@link Variable}. + * + * @param kind The type of the value that will be stored in this {@link Variable}. See + * {@link LIRKind} for documentation on what to pass here. Note that in most cases, + * simply passing {@link Value#getLIRKind()} is wrong. + * @return A new {@link Variable}. + */ Variable newVariable(LIRKind kind); Variable emitMove(Value input);