[runtime] Add some documentation for the offsets stuff.

diff --git a/mono/metadata/abi-details.h b/mono/metadata/abi-details.h
index 3f61191b3146cbdf38a3cac5aabd935bc63152ae..43361fed57c5f12546b05ef6dd4d8c3e72c8a89e 100644 (file)
--- a/mono/metadata/abi-details.h
+++ b/mono/metadata/abi-details.h
@@ -8,6 +8,20 @@
 #include <config.h>
 #include <glib.h>
 
+/*
+ * This file defines macros to compute sizes/alignments/field offsets which depend on
+ * the ABI. It is needed during cross compiling since the generated code needs to
+ * contain offsets which correspond to the ABI of the target, not the host.
+ * It defines the following macros:
+ * - MONO_ABI_SIZEOF(type) for every basic type
+ * - MONO_ABI_ALIGNOF(type) for every basic type
+ * - MONO_STRUCT_OFFSET(struct, field) for various runtime structures
+ * When not cross compiling, these correspond to the host ABI (i.e. sizeof/offsetof).
+ * When cross compiling, these are defined in a generated header file which is
+ * generated by the offsets tool in tools/offsets-tool. The name of the file
+ * is given by the --with-cross-offsets= configure argument.
+ */
+
 #define MONO_ABI_ALIGNOF(type) MONO_ALIGN_ ## type
 #define MONO_CURRENT_ABI_ALIGNOF_TYPEDEF(type) typedef struct { char c; type x; } Mono_Align_Struct_ ##type;
 #define MONO_CURRENT_ABI_ALIGNOF(type) ((int)G_STRUCT_OFFSET(Mono_Align_Struct_ ##type, x))

diff --git a/mono/metadata/metadata-cross-helpers.c b/mono/metadata/metadata-cross-helpers.c
index 561e9968838f4a69d24e7c6eb77e273118386a88..8253059523687b8120643f7e375d60974707bf23 100644 (file)
--- a/mono/metadata/metadata-cross-helpers.c
+++ b/mono/metadata/metadata-cross-helpers.c
@@ -97,6 +97,12 @@ mono_dump_metadata_offsets (void)
 void
 mono_metadata_cross_helpers_run (void);
 
+/*
+ * mono_metadata_cross_helpers_run:
+ *
+ *   Check that the offsets given by object-offsets.h match the offsets
+ * on the host. This only checks the metadata offsets.
+ */
 void
 mono_metadata_cross_helpers_run (void)
 {

diff --git a/mono/metadata/object-offsets.h b/mono/metadata/object-offsets.h
index f304361d4bd4129d9996f6c2cd5891906e146e0d..07a0342f9f48734f07d624c88220025e68bf80b9 100644 (file)
--- a/mono/metadata/object-offsets.h
+++ b/mono/metadata/object-offsets.h
@@ -1,3 +1,4 @@
+
 /*
 This is a parameterized header. It's supposed/ok to be included multiple times.
 
@@ -12,6 +13,12 @@ DECL_ALIGN2(name,alignment)
 Optional:
 USE_CROSS_COMPILE_OFFSETS - if defined, force the cross compiler offsets to be used, otherwise
        they will only be used if MONO_CROSS_COMPILE is defined
+DISABLE_METADATA_OFFSETS - Disable the definition of offsets for structures defined in metadata/.
+DISABLE_JIT_OFFSETS - Disable the definition of offsets for structures defined in mini/.
+
+The last two are needed because metadata shouldn't include JIT offsets since the structures
+are not defined, while the JIT shouldn't include metadata offsets, since some of them
+are GC specific, and the JIT needs to remain GC agnostic.
 
 Output defines:
 
@@ -51,8 +58,8 @@ DECL_SIZE(float)
 DECL_SIZE(double)
 DECL_SIZE(gpointer)
 
+// Offsets for structures defined in metadata/
 #ifndef DISABLE_METADATA_OFFSETS
-//object offsets
 DECL_OFFSET(MonoObject, vtable)
 DECL_OFFSET(MonoObject, synchronisation)
 
@@ -141,6 +148,7 @@ DECL_OFFSET(SgenThreadInfo, tlab_temp_end)
 
 #endif //DISABLE METADATA OFFSETS
 
+// Offsets for structures defined in mini/
 #ifndef DISABLE_JIT_OFFSETS
 DECL_OFFSET(MonoLMF, previous_lmf)
 

diff --git a/mono/mini/mini-cross-helpers.c b/mono/mini/mini-cross-helpers.c
index 28e04d6d6288388a8ca141a481b7262cd1b7ea5a..6c6ead8c4d2e204cd451f913386fccb891100e0f 100644 (file)
--- a/mono/mini/mini-cross-helpers.c
+++ b/mono/mini/mini-cross-helpers.c
@@ -44,6 +44,12 @@ mono_dump_jit_offsets (void)
 #endif
 }
 
+/*
+ * mono_cross_helpers_run:
+ *
+ *   Check that the offsets given by object-offsets.h match the offsets
+ * on the host.
+ */
 void
 mono_cross_helpers_run (void)
 {
@@ -59,6 +65,7 @@ mono_cross_helpers_run (void)
 #if defined (HAS_CROSS_COMPILER_OFFSETS) && !defined (MONO_CROSS_COMPILE)
        mono_metadata_cross_helpers_run ();
 
+       /* The metadata offsets are already checked above */
 #define DISABLE_METADATA_OFFSETS
 #define USE_CROSS_COMPILE_OFFSETS
 #define DECL_OFFSET(struct,field) this_should_not_happen_for_cross_fields