Some info for runtime hackers that need to implement internal calls.

svn path=/trunk/mono/; revision=3857

1 files changed, 58 insertions, 0 deletions

diff --git a/docs/internal-calls b/docs/internal-calls
new file mode 100644
index 00000000000..69c6c3e76cc
--- /dev/null
+++ b/docs/internal-calls
@@ -0,0 +1,58 @@
+
+* How to map C# types for use in the C implementation of internal calls
+
+	C# type 	C type
+	bool 		MonoBoolean
+	sbyte 		signed char
+	byte 		guchar
+	short 		gint16
+	ushort 		guint16
+	int 		gint32
+	uint 		guint32
+	long 		gint64
+	ulong 		guint64
+	IntPtr/UIntPtr	gpointer
+	object 		MonoObject*
+	string 		MonoString*
+
+For ref and out paramaters you'll use the corresponding pointer type.
+Arrays of any type must be described with a MonoArray* and the elements 
+must be accessed with the mono_array_* macros.
+Any other type that has a matching C structure representation, should use
+a pointer to the struct instead of a generic MonoObject pointer.
+
+Instance methods that are internal calls will receive as first argument
+the instance object, so you must account for it in the C method signature:
+
+	[MethodImplAttribute(MethodImplOptions.InternalCall)]
+	public extern override int GetHashCode ();
+
+becaomes:
+
+	gint32 ves_icall_System_String_GetHashCode (MonoString *this);
+
+
+
+* How to hook internal calls with the runtime
+
+Once you require an internal call in corlib, you need to create a C
+implementation for it and register it in a static table in metadata/icall.c.
+Add an entry in the table like:
+
+	"System.String::GetHashCode", ves_icall_System_String_GetHashCode,
+
+Note that you need to include the full namespace.name of the class.
+If there are overloaded methods, you need also to specify the signature
+of _all_ of them:
+
+	[MethodImplAttribute(MethodImplOptions.InternalCall)]
+	public extern override void DoSomething ();
+	[MethodImplAttribute(MethodImplOptions.InternalCall)]
+	public extern override void DoSomething (bool useful);
+
+should be mapped with:
+
+	"Namespace.ClassName::DoSomething()", ves_icall_Namespace_ClassName_DoSomething,
+	"Namespace.ClassName::DoSomething(bool)", ves_icall_Namespace_ClassName_DoSomething_bool,
+
+