(**
   Run-time portion of the ocaml to C foreign function interface.

   The C module implements the The major elements are external
   functions to return size and alignment information about the
   primitive types, and a variant type t representing different
   flavors of pointers.  This links with the C code in cffi.c

   @author Copyright (c) 2001 David Fox *)

(** Type t is used to hold actual pointer values in the resulting
    interface.   When a Pointer type is passed the function receives a
    pointer to the first character of the argument string.  This is for
    data that is managed by the ML garbage collector.  When a PointerRef
    type is passed the string is interpreted as a four bytes pointer,
    so an additional dereferencing is performed.  This is for pointers
    that are returned by C functions.

    Example: passing Null has the same effect as passing
    PointerRef("\000\000\000\000") *)

type uint = unit
type short = unit
type ushort = unit
type uint32 = unit
type uchar = unit
type double = unit
type longdouble = unit
type long = unit
type ulong = unit
type longlong = unit
type void = unit

type 'a p =
    Null
      (** The NULL pointer *)
  | Pointer of string
      (** A pointer to the beginning of STRING *)
  | PointerOff of string * int
      (** A pointer to Nth character of STRING. *)
  | PointerRef of string
      (** A string which holds the bytes of a pointer.  This is the
	  only type of pointer which can be used to point to storage
	  outside of Ocaml space. *)

exception Size_mismatch of int * int * string
(** Raised by the foreign function preprocessor *)
exception Null_pointer
(** Raised by invalid pointer arithmetic *)

val is_null : 'a p -> bool

(** {2 Return the sizes of all the built-in C types} *)

external sizeof_bool : unit -> int = "c_sizeof_bool"
external sizeof_char : unit -> int = "c_sizeof_char"
external sizeof_short : unit -> int = "c_sizeof_short"
external sizeof_long : unit -> int = "c_sizeof_long"
external sizeof_long_long : unit -> int = "c_sizeof_long_long"
external sizeof_int : unit -> int = "c_sizeof_int"
external sizeof_float : unit -> int = "c_sizeof_float"
external sizeof_double : unit -> int = "c_sizeof_double"
external sizeof_long_double : unit -> int = "c_sizeof_long_double"
external sizeof_pointer : unit -> int = "c_sizeof_pointer"
external sizeof_enum : unit -> int = "c_sizeof_enum"
external sizeof_int32 : unit -> int = "c_sizeof_int32"
external sizeof_int64 : unit -> int = "c_sizeof_int64"

(** {2 Return the alignment of all the built-in C types}

    That is, in a struct whose first element is a char and whose
    second element is an X, at what byte position does the X begin? *)

external align_bool : unit -> int = "c_align_bool"
external align_char : unit -> int = "c_align_char"
external align_short : unit -> int = "c_align_short"
external align_int : unit -> int = "c_align_int"
external align_float : unit -> int = "c_align_float"
external align_long : unit -> int = "c_align_long"
external align_double : unit -> int = "c_align_double"
external align_long_double : unit -> int = "c_align_long_double"
external align_pointer : unit -> int = "c_align_pointer"
external align_enum : unit -> int = "c_align_enum"
external align_int32 : unit -> int = "c_align_int32"
external align_int64 : unit -> int = "c_align_int64"

(** {2 Generate a pointer} *)

external make_null : unit -> void p = "c_make_null"
external make_pointeroff : string -> int -> void p = "c_make_pointeroff"
external make_pointerref : string -> void p = "c_make_pointerref"

(** {2 Return the object a pointer refers to} *)

external int_ref : int p -> int = "c_int_ref"
external uint_ref : uint p -> int = "c_uint_ref"
external long_ref : long p -> int32 = "c_long_ref"
external ulong_ref : ulong p -> int32 = "c_ulong_ref"
external short_ref : short p -> int = "c_short_ref"
external ushort_ref : ushort p -> int = "c_ushort_ref"
external char_ref : char p -> char = "c_char_ref"
external byte_ref : char p -> char = "c_byte_ref"
external ubyte_ref : uchar p -> char = "c_ubyte_ref"
external float_ref : float p -> float = "c_float_ref"
external double_ref : double p -> float = "c_double_ref"
external long_double_ref : longdouble p -> float = "c_long_double_ref"
external bool_ref : bool p -> bool = "c_bool_ref"
external enum_ref : void p -> int = "c_enum_ref"
external int32_ref : long p -> int32 = "c_int32_ref"
external uint32_ref : ulong p -> int64 = "c_uint32_ref"
external int64_ref : longlong p -> int64 = "c_int64_ref"
external string_ref : char p -> string = "c_string_ref"

(** {2 Modify the value a pointer refers to} *)

external int_set : int p -> int -> unit = "c_int_set"
external uint_set : uint p -> int -> unit = "c_uint_set"
external long_set : long p -> int32 -> unit = "c_long_set"
external ulong_set : ulong p -> int32 -> unit = "c_ulong_set"
external short_set : short p -> int -> unit = "c_short_set"
external ushort_set : ushort p -> int -> unit = "c_ushort_set"
external char_set : char p -> char -> unit = "c_char_set"
external byte_set : char p -> char -> unit = "c_byte_set"
external ubyte_set : uchar p -> char -> unit = "c_ubyte_set"
external float_set : float p -> float -> unit = "c_float_set"
external double_set : double p -> float -> unit = "c_double_set"
external long_double_set : longdouble p -> float -> unit = "c_long_double_set"
external bool_set : bool p -> bool -> unit = "c_bool_set"
external enum_set : void p -> int -> unit = "c_enum_set"
external pointer_set : ('a p) p -> 'a p -> unit = "c_pointer_set"
external int32_set : long p -> int32 -> unit = "c_int32_set"
external uint32_set : ulong p -> int64 -> unit = "c_uint32_set"
external int64_set : longlong p -> int64 -> unit = "c_int64_set"

(** {2 Primitive allocators for various types} These functions
    allocate Ocaml strings suitable for holding various C types.  The
    int argument is a dimension, so they really allocate arrays rather
    than individual objects.  Note that the storage is controlled by
    ocaml and may be garbage collected or moved, so it is important
    not to allow C to retain any pointers into this storage. *)

val make_bool : int -> bool p
val make_char : int -> char p
val make_uchar : int -> uchar p
val make_short : int -> short p
val make_ushort : int -> ushort p
val make_long : int -> long p
val make_ulong : int -> ulong p
val make_int : int -> int p
val make_uint : int -> uint p
val make_float : int -> float p
val make_double : int -> double p
val make_long_double : int -> longdouble p
val make_pointer : int -> (void p) p
val make_enum : int -> void p
val make_int32 : int -> long p
val make_int64 : int -> longlong p

(** {2 Other pointer operations} *)

val cast : 'a p -> 'b p -> 'b p
(** [cast a b] Return a, but change its phantom type to that of b *)

(** Pointer arithmetic: add n bytes to the pointer's address. *)
val pointer_sum : 'a p -> int -> 'a p
(** @raise Null_pointer attempt to dereference NULL *)

external make_pointersum : string -> int -> string = "c_make_pointersum"

val pointer_ref : ('a p) p -> 'a p
(** @raise Null_pointer attempt to dereference NULL *)

val pointer_deref : 'a p -> ('a p) p

(** C.int32_ref (C.make_int32_pointer 123l) = 123l *)
external string_of_int32 : int32 -> string = "c_string_of_int32"
val make_int32_pointer : int32 -> long p