docs/internal-calls

   1                          Internal Call Topics
   2
   3 * Introduction
   4
   5         The Common Language Infrastructure allows for methods to be
   6         implemented in unmanaged code.  Unlike the Platform Invocation
   7         services which provide marshalling and unmarshalling of data
   8         from managed to unmanaged and viceversa the Internal calls do
   9         not perform any kind of marshalling.
  10
  11 * Basic Type mapping
  12
  13         The following lists how the C# types are exposed to the C API.
  14
  15         C# type         C type
  16         -----------------------------
  17         char            gunichar2
  18         bool            MonoBoolean
  19         sbyte           signed char
  20         byte            guchar
  21         short           gint16
  22         ushort          guint16
  23         int             gint32
  24         uint            guint32
  25         long            gint64
  26         ulong           guint64
  27         IntPtr/UIntPtr  gpointer
  28         object          MonoObject*
  29         string          MonoString*
  30
  31 * Pointers
  32
  33         For ref and out paramaters you'll use the corresponding
  34         pointer type.
  35
  36         So if you have a C# type listed as "ref int", you should use
  37         "int *" in your implementation.
  38
  39 * Arrays
  40
  41         Arrays of any type must be described with a MonoArray* and the
  42         elements must be accessed with the mono_array_* macros.
  43
  44 * Other Structures
  45
  46         Any other type that has a matching C structure representation,
  47         should use a pointer to the struct instead of a generic
  48         MonoObject pointer.
  49
  50 * Instance Methods.
  51
  52         Instance methods that are internal calls will receive as first argument
  53         the instance object, so you must account for it in the C method signature:
  54
  55                 [MethodImplAttribute(MethodImplOptions.InternalCall)]
  56                 public extern override int GetHashCode ();
  57
  58         becomes:
  59
  60                 gint32 ves_icall_System_String_GetHashCode (MonoString *this);
  61
  62 * How to hook internal calls with the runtime
  63
  64         Once you require an internal call in corlib, you need to
  65         create a C implementation for it and register it in a static
  66         table in metadata/icall.c.  Add an entry in the table like:
  67
  68                 "System.String::GetHashCode", ves_icall_System_String_GetHashCode,
  69
  70         Note that you need to include the full namespace.name of the
  71         class.  If there are overloaded methods, you need also to
  72         specify the signature of _all_ of them:
  73
  74                 [MethodImplAttribute(MethodImplOptions.InternalCall)]
  75                 public extern override void DoSomething ();
  76                 [MethodImplAttribute(MethodImplOptions.InternalCall)]
  77                 public extern override void DoSomething (bool useful);
  78
  79         should be mapped with:
  80
  81                 "Namespace.ClassName::DoSomething()", ves_icall_Namespace_ClassName_DoSomething,
  82                 "Namespace.ClassName::DoSomething(bool)", ves_icall_Namespace_ClassName_DoSomething_bool,
  83
  84