# HG changeset patch
# User Roland Schatz <roland.schatz@oracle.com>
# Date 1389349804 -3600
# Node ID 8aee7169dbe42aedfcddcf6afcb7c11694fb1811
# Parent  40e81cba9e086edbdfc014e8f55b8b9d6b8ce819
Improve documentation of data section building code.

diff -r 40e81cba9e08 -r 8aee7169dbe4 graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/CompilationResult.java
--- a/graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/CompilationResult.java	Thu Jan 09 20:14:11 2014 -0800
+++ b/graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/CompilationResult.java	Fri Jan 10 11:30:04 2014 +0100
@@ -137,6 +137,9 @@
         }
     }
 
+    /**
+     * Represents some external data that is referenced by the code.
+     */
     public abstract static class Data {
 
         public final int size;
@@ -161,7 +164,12 @@
 
         @Override
         public void emit(ByteBuffer buffer) {
-            constant.putPrimitive(buffer);
+            if (constant.getKind().isPrimitive()) {
+                buffer.putLong(constant.getPrimitive());
+            } else {
+                // emit placeholder for oop value
+                buffer.putLong(0);
+            }
         }
 
         @Override
@@ -197,9 +205,9 @@
     }
 
     /**
-     * Represents a reference to data from the code. The associated data can be either a
-     * {@link Constant} or a raw byte array. The raw byte array is patched as is, no endian swapping
-     * is done on it.
+     * Represents a code site that references some data. The associated data can be either a
+     * reference to an external {@link Data} item in the data section, or it may be an inlined
+     * {@link Constant} that needs to be patched.
      */
     public static final class DataPatch extends Site {
 
diff -r 40e81cba9e08 -r 8aee7169dbe4 graal/com.oracle.graal.api.meta/src/com/oracle/graal/api/meta/Constant.java
--- a/graal/com.oracle.graal.api.meta/src/com/oracle/graal/api/meta/Constant.java	Thu Jan 09 20:14:11 2014 -0800
+++ b/graal/com.oracle.graal.api.meta/src/com/oracle/graal/api/meta/Constant.java	Fri Jan 10 11:30:04 2014 +0100
@@ -22,8 +22,6 @@
  */
 package com.oracle.graal.api.meta;
 
-import java.nio.*;
-
 /**
  * Represents a constant (boxed) value, such as an integer, floating point number, or object
  * reference, within the compiler and across the compiler/runtime interface. Exports a set of
@@ -112,8 +110,9 @@
         return object == null && primitive == 0;
     }
 
-    public void putPrimitive(ByteBuffer buffer) {
-        buffer.putLong(primitive);
+    public long getPrimitive() {
+        assert getKind().isPrimitive();
+        return primitive;
     }
 
     @Override
diff -r 40e81cba9e08 -r 8aee7169dbe4 graal/com.oracle.graal.hotspot/src/com/oracle/graal/hotspot/HotSpotCompiledCode.java
--- a/graal/com.oracle.graal.hotspot/src/com/oracle/graal/hotspot/HotSpotCompiledCode.java	Thu Jan 09 20:14:11 2014 -0800
+++ b/graal/com.oracle.graal.hotspot/src/com/oracle/graal/hotspot/HotSpotCompiledCode.java	Fri Jan 10 11:30:04 2014 +0100
@@ -52,9 +52,22 @@
 
     public final DataSection dataSection;
 
+    /**
+     * Represents a reference to the data section. Before the code is installed, all {@link Data}
+     * items referenced by a {@link DataPatch} are put into the data section of the method, and
+     * replaced by {@link HotSpotData}.
+     */
     public static final class HotSpotData extends Data {
 
+        /**
+         * The offset of the data item in the data section.
+         */
         public int offset;
+
+        /**
+         * If the data item is an oop that needs to be patched by the runtime, this field contains
+         * the reference to the object.
+         */
         public Constant constant;
 
         public HotSpotData(int offset) {
@@ -67,16 +80,32 @@
         }
     }
 
+    /**
+     * Represents the data section of a method.
+     */
     public static final class DataSection {
 
+        /**
+         * The minimum alignment required for this data section.
+         */
         public final int sectionAlignment;
+
+        /**
+         * The raw data contained in the data section.
+         */
         public final byte[] data;
+
+        /**
+         * A list of locations where oop pointers need to be patched by the runtime.
+         */
         public final HotSpotData[] patches;
 
         public DataSection(Site[] sites) {
             int size = 0;
             int patchCount = 0;
             List<DataPatch> externalDataList = new ArrayList<>();
+
+            // find all external data items and determine total size of data section
             for (Site site : sites) {
                 if (site instanceof DataPatch) {
                     DataPatch dataPatch = (DataPatch) site;
@@ -98,6 +127,8 @@
             int index = 0;
             int patchIndex = 0;
             int alignment = 0;
+
+            // build data section
             for (DataPatch dataPatch : externalDataList) {
                 Data d = dataPatch.externalData;
 
@@ -107,6 +138,7 @@
 
                 HotSpotData hsData = new HotSpotData(index);
                 if (dataPatch.getConstant() != null && dataPatch.getConstant().getKind() == Kind.Object) {
+                    // record patch location for oop pointers
                     hsData.constant = dataPatch.getConstant();
                     patches[patchIndex++] = hsData;
                 }