Cleanup some comments in the OCaml bindings.
[oota-llvm.git] / include / llvm-c / Core.h
index 7dc1a07657b4c9515cd825924b8a90b2adecb7a6..1c3fc9ceb464a964e0ace191fb108c2ea73a67a5 100644 (file)
@@ -2,8 +2,8 @@
 |*                                                                            *|
 |*                     The LLVM Compiler Infrastructure                       *|
 |*                                                                            *|
-|* This file was developed by Gordon Henriksen and is distributed under the   *|
-|* University of Illinois Open Source License. See LICENSE.TXT for details.   *|
+|* This file is distributed under the University of Illinois Open Source      *|
+|* License. See LICENSE.TXT for details.                                      *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
@@ -45,9 +45,26 @@ extern "C" {
 
 
 /* Opaque types. */
+
+/**
+ * The top-level container for all other LLVM Intermediate Representation (IR)
+ * objects. See the llvm::Module class.
+ */
 typedef struct LLVMOpaqueModule *LLVMModuleRef;
+
+/**
+ * Each value in the LLVM IR has a type, an LLVMTypeRef. See the llvm::Type
+ * class.
+ */
 typedef struct LLVMOpaqueType *LLVMTypeRef;
+
+/**
+ * When building recursive types using LLVMRefineType, LLVMTypeRef values may
+ * become invalid; use LLVMTypeHandleRef to resolve this problem. See the
+ * llvm::AbstractTypeHolder class.
+ */
 typedef struct LLVMOpaqueTypeHandle *LLVMTypeHandleRef;
+
 typedef struct LLVMOpaqueValue *LLVMValueRef;
 typedef struct LLVMOpaqueBasicBlock *LLVMBasicBlockRef;
 typedef struct LLVMOpaqueBuilder *LLVMBuilderRef;
@@ -63,38 +80,40 @@ typedef struct LLVMOpaqueModuleProvider *LLVMModuleProviderRef;
 typedef struct LLVMOpaqueMemoryBuffer *LLVMMemoryBufferRef;
 
 typedef enum {
-  LLVMVoidTypeKind,        /* type with no size */
-  LLVMFloatTypeKind,       /* 32 bit floating point type */
-  LLVMDoubleTypeKind,      /* 64 bit floating point type */
-  LLVMX86_FP80TypeKind,    /* 80 bit floating point type (X87) */
-  LLVMFP128TypeKind,       /* 128 bit floating point type (112-bit mantissa) */
-  LLVMPPC_FP128TypeKind,   /* 128 bit floating point type (two 64-bits) */
-  LLVMLabelTypeKind,       /* Labels */
-  LLVMIntegerTypeKind,     /* Arbitrary bit width integers */
-  LLVMFunctionTypeKind,    /* Functions */
-  LLVMStructTypeKind,      /* Structures */
-  LLVMArrayTypeKind,       /* Arrays */
-  LLVMPointerTypeKind,     /* Pointers */
-  LLVMOpaqueTypeKind,      /* Opaque: type with unknown structure */
-  LLVMVectorTypeKind       /* SIMD 'packed' format, or other vector type */
+  LLVMVoidTypeKind,        /**< type with no size */
+  LLVMFloatTypeKind,       /**< 32 bit floating point type */
+  LLVMDoubleTypeKind,      /**< 64 bit floating point type */
+  LLVMX86_FP80TypeKind,    /**< 80 bit floating point type (X87) */
+  LLVMFP128TypeKind,       /**< 128 bit floating point type (112-bit mantissa)*/
+  LLVMPPC_FP128TypeKind,   /**< 128 bit floating point type (two 64-bits) */
+  LLVMLabelTypeKind,       /**< Labels */
+  LLVMIntegerTypeKind,     /**< Arbitrary bit width integers */
+  LLVMFunctionTypeKind,    /**< Functions */
+  LLVMStructTypeKind,      /**< Structures */
+  LLVMArrayTypeKind,       /**< Arrays */
+  LLVMPointerTypeKind,     /**< Pointers */
+  LLVMOpaqueTypeKind,      /**< Opaque: type with unknown structure */
+  LLVMVectorTypeKind       /**< SIMD 'packed' format, or other vector type */
 } LLVMTypeKind;
 
 typedef enum {
-  LLVMExternalLinkage,    /* Externally visible function */
-  LLVMLinkOnceLinkage,    /* Keep one copy of function when linking (inline) */
-  LLVMWeakLinkage,        /* Keep one copy of function when linking (weak) */
-  LLVMAppendingLinkage,   /* Special purpose, only applies to global arrays */
-  LLVMInternalLinkage,    /* Rename collisions when linking (static functions)*/
-  LLVMDLLImportLinkage,   /* Function to be imported from DLL */
-  LLVMDLLExportLinkage,   /* Function to be accessible from DLL */
-  LLVMExternalWeakLinkage,/* ExternalWeak linkage description */
-  LLVMGhostLinkage        /* Stand-in functions for streaming fns from bitcode*/
+  LLVMExternalLinkage,    /**< Externally visible function */
+  LLVMLinkOnceLinkage,    /**< Keep one copy of function when linking (inline)*/
+  LLVMWeakLinkage,        /**< Keep one copy of function when linking (weak) */
+  LLVMAppendingLinkage,   /**< Special purpose, only applies to global arrays */
+  LLVMInternalLinkage,    /**< Rename collisions when linking (static
+                               functions) */
+  LLVMDLLImportLinkage,   /**< Function to be imported from DLL */
+  LLVMDLLExportLinkage,   /**< Function to be accessible from DLL */
+  LLVMExternalWeakLinkage,/**< ExternalWeak linkage description */
+  LLVMGhostLinkage        /**< Stand-in functions for streaming fns from
+                               bitcode */
 } LLVMLinkage;
 
 typedef enum {
-  LLVMDefaultVisibility,  /* The GV is visible */
-  LLVMHiddenVisibility,   /* The GV is hidden */
-  LLVMProtectedVisibility /* The GV is protected */
+  LLVMDefaultVisibility,  /**< The GV is visible */
+  LLVMHiddenVisibility,   /**< The GV is hidden */
+  LLVMProtectedVisibility /**< The GV is protected */
 } LLVMVisibility;
 
 typedef enum {
@@ -106,35 +125,35 @@ typedef enum {
 } LLVMCallConv;
 
 typedef enum {
-  LLVMIntEQ = 32, /* equal */
-  LLVMIntNE,      /* not equal */
-  LLVMIntUGT,     /* unsigned greater than */
-  LLVMIntUGE,     /* unsigned greater or equal */
-  LLVMIntULT,     /* unsigned less than */
-  LLVMIntULE,     /* unsigned less or equal */
-  LLVMIntSGT,     /* signed greater than */
-  LLVMIntSGE,     /* signed greater or equal */
-  LLVMIntSLT,     /* signed less than */
-  LLVMIntSLE      /* signed less or equal */
+  LLVMIntEQ = 32, /**< equal */
+  LLVMIntNE,      /**< not equal */
+  LLVMIntUGT,     /**< unsigned greater than */
+  LLVMIntUGE,     /**< unsigned greater or equal */
+  LLVMIntULT,     /**< unsigned less than */
+  LLVMIntULE,     /**< unsigned less or equal */
+  LLVMIntSGT,     /**< signed greater than */
+  LLVMIntSGE,     /**< signed greater or equal */
+  LLVMIntSLT,     /**< signed less than */
+  LLVMIntSLE      /**< signed less or equal */
 } LLVMIntPredicate;
 
 typedef enum {
-  LLVMRealPredicateFalse, /* Always false (always folded) */
-  LLVMRealOEQ,            /* True if ordered and equal */
-  LLVMRealOGT,            /* True if ordered and greater than */
-  LLVMRealOGE,            /* True if ordered and greater than or equal */
-  LLVMRealOLT,            /* True if ordered and less than */
-  LLVMRealOLE,            /* True if ordered and less than or equal */
-  LLVMRealONE,            /* True if ordered and operands are unequal */
-  LLVMRealORD,            /* True if ordered (no nans) */
-  LLVMRealUNO,            /* True if unordered: isnan(X) | isnan(Y) */
-  LLVMRealUEQ,            /* True if unordered or equal */
-  LLVMRealUGT,            /* True if unordered or greater than */
-  LLVMRealUGE,            /* True if unordered, greater than, or equal */
-  LLVMRealULT,            /* True if unordered or less than */
-  LLVMRealULE,            /* True if unordered, less than, or equal */
-  LLVMRealUNE,            /* True if unordered or not equal */
-  LLVMRealPredicateTrue   /* Always true (always folded) */
+  LLVMRealPredicateFalse, /**< Always false (always folded) */
+  LLVMRealOEQ,            /**< True if ordered and equal */
+  LLVMRealOGT,            /**< True if ordered and greater than */
+  LLVMRealOGE,            /**< True if ordered and greater than or equal */
+  LLVMRealOLT,            /**< True if ordered and less than */
+  LLVMRealOLE,            /**< True if ordered and less than or equal */
+  LLVMRealONE,            /**< True if ordered and operands are unequal */
+  LLVMRealORD,            /**< True if ordered (no nans) */
+  LLVMRealUNO,            /**< True if unordered: isnan(X) | isnan(Y) */
+  LLVMRealUEQ,            /**< True if unordered or equal */
+  LLVMRealUGT,            /**< True if unordered or greater than */
+  LLVMRealUGE,            /**< True if unordered, greater than, or equal */
+  LLVMRealULT,            /**< True if unordered or less than */
+  LLVMRealULE,            /**< True if unordered, less than, or equal */
+  LLVMRealUNE,            /**< True if unordered or not equal */
+  LLVMRealPredicateTrue   /**< Always true (always folded) */
 } LLVMRealPredicate;
 
 
@@ -146,10 +165,21 @@ void LLVMDisposeMessage(char *Message);
 /*===-- Modules -----------------------------------------------------------===*/
 
 /* Create and destroy modules. */ 
+/** See llvm::Module::Module. */
 LLVMModuleRef LLVMModuleCreateWithName(const char *ModuleID);
+
+/** See llvm::Module::~Module. */
 void LLVMDisposeModule(LLVMModuleRef M);
 
-/* Same as Module::addTypeName. */
+/** Data layout. See Module::getDataLayout. */
+const char *LLVMGetDataLayout(LLVMModuleRef M);
+void LLVMSetDataLayout(LLVMModuleRef M, const char *Triple);
+
+/** Target triple. See Module::getTargetTriple. */
+const char *LLVMGetTarget(LLVMModuleRef M);
+void LLVMSetTarget(LLVMModuleRef M, const char *Triple);
+
+/** See Module::addTypeName. */
 int LLVMAddTypeName(LLVMModuleRef M, const char *Name, LLVMTypeRef Ty);
 void LLVMDeleteTypeName(LLVMModuleRef M, const char *Name);
 
@@ -171,7 +201,10 @@ void LLVMDeleteTypeName(LLVMModuleRef M, const char *Name);
  *     opaque type
  */
 
+/** See llvm::LLVMTypeKind::getTypeID. */
 LLVMTypeKind LLVMGetTypeKind(LLVMTypeRef Ty);
+
+/** See llvm::DerivedType::refineAbstractTypeTo. */
 void LLVMRefineAbstractType(LLVMTypeRef AbstractType, LLVMTypeRef ConcreteType);
 
 /* Operations on integer types */
@@ -262,6 +295,7 @@ int LLVMIsUndef(LLVMValueRef Val);
 LLVMValueRef LLVMConstInt(LLVMTypeRef IntTy, unsigned long long N,
                           int SignExtend);
 LLVMValueRef LLVMConstReal(LLVMTypeRef RealTy, double N);
+LLVMValueRef LLVMConstRealOfString(LLVMTypeRef RealTy, const char *Text);
 
 /* Operations on composite constants */
 LLVMValueRef LLVMConstString(const char *Str, unsigned Length,
@@ -370,6 +404,10 @@ LLVMBasicBlockRef LLVMInsertBasicBlock(LLVMBasicBlockRef InsertBeforeBB,
                                        const char *Name);
 void LLVMDeleteBasicBlock(LLVMBasicBlockRef BB);
 
+/* Operations on call sites */
+void LLVMSetInstructionCallConv(LLVMValueRef Instr, unsigned CC);
+unsigned LLVMGetInstructionCallConv(LLVMValueRef Instr);
+
 /* Operations on phi nodes */
 void LLVMAddIncoming(LLVMValueRef PhiNode, LLVMValueRef *IncomingValues,
                      LLVMBasicBlockRef *IncomingBlocks, unsigned Count);
@@ -403,6 +441,10 @@ LLVMValueRef LLVMBuildInvoke(LLVMBuilderRef, LLVMValueRef Fn,
 LLVMValueRef LLVMBuildUnwind(LLVMBuilderRef);
 LLVMValueRef LLVMBuildUnreachable(LLVMBuilderRef);
 
+/* Add a case to the switch instruction */
+void LLVMAddCase(LLVMValueRef Switch, LLVMValueRef OnVal,
+                 LLVMBasicBlockRef Dest);
+
 /* Arithmetic */
 LLVMValueRef LLVMBuildAdd(LLVMBuilderRef, LLVMValueRef LHS, LLVMValueRef RHS,
                           const char *Name);