New module members and refactorings (#42)

* Removed redundant arg validator now that ValidateNotDefault is in nuget pkg
* Added GlobalIndirectSymbol
* Added GlobalIfunc
* Added WriteOnce<T> class and applied to several places
* Added Module.GetMDKind()
* Added Module.Aliases
* Added Module.NamedMetadata
* Added docs on internal marshal support for LLVMBool and strings
* Added Context bindings to support ODR unique debug types
* removed obsoleted P/Invoke APIs
* Changed typ of values enumerated from BitCodeModule.Globals to reflect actual underlying type as GlobalVariable. This non-breaking as it is a more derived type and makes it easier to get at the additional info from the GlobalVariable type.
* Minor refactorings and corrections

Author: smaillet

Directory.Build.props

@@ -69,7 +69,7 @@
                 <PackageReference Include="StyleCop.Analyzers" Version="1.0.2" PrivateAssets="All" />
                 <AdditionalFiles Include="$(MSBuildThisFileDirectory)stylecop.json" Link="stylecop.json" />
             </ItemGroup>
-            <ItemGroup>
+            <ItemGroup Condition="'$(NoCommonAnalyzers)'!='true'">
                 <None Include="$(MSBuildThisFileDirectory)Ubiquity.NET.ruleset" Link="Ubiquity.NET.ruleset" />
             </ItemGroup>
         </When>

docfx/articles/InternalDetails/marshal-LLVMBool.md

@@ -0,0 +1,36 @@
+# Marshaling LLVMBool
+
+LLVMBool is a typdef in the LLVM-C API that is both simple and problematic. In it's
+simplest sense an LLVMBool is a representation of a bi-modal value. However, the
+problematic part is that the semantics for the value are different depending on any
+given API. That is, in some cases LLVMBool != 0 is a failure case, and others it is
+a success! The confusion stems from LLVMBool serving a dual role:
+  1) A real boolean true/false
+  2) A status code where 0 == success and non-zero indicates an error
+
+This duality is confusing and can lead to subtle errors in usage of APIs if translated
+directly into language projections. This makes hands-off automatic generation of P/Invoke
+calls to LLVM either imposible or error prone. Thus, Llvm.NET uses manually updated P/Invoke
+calls that were initially auto generated to get things started but not maintined via any
+generation tools. In the case of LLVMBool Llvm.NET uses distinct types for the different 
+semantics and declares the interop signatures with the form appropriate to the function
+being called. The two types are LLVMStatus and standard `System.Boolean` or `bool` in C#
+
+## LLVMStatus
+This is a status value where 0 == Success and non-zero is a failure or false status.
+LLVMStatus is used whenever the 0 == success semantics apply to the API. For example:
+
+```C#
+[DllImport( LibraryPath, EntryPoint = "LLVMWriteBitcodeToFD", CallingConvention = CallingConvention.Cdecl )]
+internal static extern LLVMStatus LLVMWriteBitcodeToFD( LLVMModuleRef @M, int @FD, int @ShouldClose, int @Unbuffered );
+```
+
+## LLVMBool
+This is the traditioanl boolean value where 0==false and non-zero is true and uses the
+standard boolean marshaling support for System.Boolean
+```C#
+[DllImport( LibraryPath, EntryPoint = "LLVMTypeIsSized", CallingConvention = CallingConvention.Cdecl )]
+[return: MarshalAs( UnmanagedType.Bool )]
+internal static extern bool LLVMTypeIsSized( LLVMTypeRef @Ty );
+```
+

docfx/articles/InternalDetails/marshal-string.md

@@ -0,0 +1,27 @@
+# Marshaling strings in LLVM.NET
+LLVM provides strings in several forms and this leads to complexities for
+P/Invoke signatures as sometimes the strings require some form of release
+and in other cases, they do not. Standard .NET marshaling of strings makes
+some assumptions with regard to strings as a return type that make the LLVM
+APIs difficult. (e.g. in some LLVM APIs the returned string must be released
+via LLVMDisposeMessage() or some other call, while in other cases it is just
+a pointer to an internal const string that does not need any release.)
+
+To resolve these issues and make the requirements explicitly clear and consistent
+Llvm.NET uses custom marshaling of the strings to mark the exact behavior directly
+on the P/Invoke signature so it is both clear and easy to use for the upper layers
+(it's just a `System.String`)
+
+The current forms of string marshalling are:
+
+```C#
+// const char* owned by native LLVM, and never disposed by managed callers (just copy to managed string)
+[MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef=typeof(StringMarshaler))]
+
+// const char* allocated in native LLVM, released by managed caller via LLVMDisposeMessage
+[MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef=typeof(StringMarshaler), MarshalCookie="DisposeMessage")]
+
+// const char* allocated in native LLVM, released by managed caller via LLVMDisposeMangledSymbol
+[MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef=typeof(StringMarshaler), MarshalCookie="MangledSymbol")]
+
+```

docfx/articles/InternalDetails/toc.md

@@ -1,2 +1,4 @@
 # [LLVM Handles](llvm-handles.md)
 # [Interning Handles](handleref-interning.md)
+# [Marshaling Strings](marshal-string.md)
+# [Marshaling LLVMBool](marshal-LLVMBool.md)

src/LibLLVM/ContextBindings.cpp

@@ -0,0 +1,25 @@
+#include "ContextBindings.h"
+#include <llvm\IR\LLVMContext.h>
+
+using namespace llvm;
+
+extern "C"
+{
+    LLVMBool LLVMContextGetIsODRUniquingDebugTypes( LLVMContextRef context )
+    {
+        return unwrap( context )->isODRUniquingDebugTypes( );
+    }
+
+    void LLVMContextSetIsODRUniquingDebugTypes( LLVMContextRef context, LLVMBool state )
+    {
+        auto pContext = unwrap( context );
+        if ( state )
+        {
+            pContext->enableDebugTypeODRUniquing( );
+        }
+        else
+        {
+            pContext->disableDebugTypeODRUniquing( );
+        }
+    }
+}

src/LibLLVM/ContextBindings.h

@@ -0,0 +1,17 @@
+#ifndef _CONTEXT_BINDINGS_H_
+#define _CONTEXT_BINDINGS_H_
+
+#include "llvm-c/Core.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+    LLVMBool LLVMContextGetIsODRUniquingDebugTypes( LLVMContextRef context );
+    void LLVMContextSetIsODRUniquingDebugTypes( LLVMContextRef context, LLVMBool state );
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

src/LibLLVM/EXPORTS.DEF

@@ -31,6 +31,14 @@ LLVMComdatGetName
 LLVMGlobalObjectGetComdat
 LLVMGlobalObjectSetComdat
 
+LLVMModuleGetFirstGlobalAlias
+LLVMModuleGetNextGlobalAlias
+LLVMModuleGetFirstNamedMD
+LLVMModuleGetNextNamedMD
+
+LLVMContextGetIsODRUniquingDebugTypes
+LLVMContextSetIsODRUniquingDebugTypes
+
 LLVMCreatePassRegistry
 LLVMPassRegistryDispose
 LLVMAddModuleFlag

src/LibLLVM/LibLLVM.vcxproj

@@ -178,6 +178,7 @@
   <ItemGroup>
     <ClCompile Include="AnalysisBindings.cpp" />
     <ClCompile Include="AttributeBindings.cpp" />
+    <ClCompile Include="ContextBindings.cpp" />
     <ClCompile Include="DIBuilderBindings.cpp" />
     <ClCompile Include="DITypeBindings.cpp" />
     <ClCompile Include="InlinedExports.cpp" />
@@ -190,6 +191,7 @@
   <ItemGroup>
     <ClInclude Include="AnalysisBindings.h" />
     <ClInclude Include="AttributeBindings.h" />
+    <ClInclude Include="ContextBindings.h" />
     <ClInclude Include="DIBuilderBindings.h" />
     <ClInclude Include="DITypeBindings.h" />
     <ClInclude Include="InlinedExports.h" />

src/LibLLVM/LibLLVM.vcxproj.filters

@@ -61,6 +61,9 @@
     <ClCompile Include="AttributeBindings.cpp">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="ContextBindings.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
   </ItemGroup>
   <ItemGroup>
     <ClInclude Include="DIBuilderBindings.h">
@@ -102,6 +105,9 @@
     <ClInclude Include="AttributeBindings.h">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="ContextBindings.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
   </ItemGroup>
   <ItemGroup>
     <ResourceCompile Include="Resource.rc">

src/LibLLVM/ModuleBindings.cpp

@@ -163,4 +163,44 @@ extern "C"
         Comdat const& comdat = *unwrap( comdatRef );
         return LLVMCreateMessage( comdat.getName( ).str( ).c_str( ) );
     }
+
+    LLVMValueRef LLVMModuleGetFirstGlobalAlias( LLVMModuleRef M )
+    {
+        Module *Mod = unwrap( M );
+        Module::alias_iterator I = Mod->alias_begin( );
+        if ( I == Mod->alias_end( ) )
+            return nullptr;
+
+        return wrap( &*I );
+    }
+
+    LLVMValueRef LLVMModuleGetNextGlobalAlias( LLVMValueRef valueRef )
+    {
+        GlobalAlias *pGA = unwrap<GlobalAlias>( valueRef );
+        Module::alias_iterator I( pGA );
+        if ( ++I == pGA->getParent( )->alias_end( ) )
+            return nullptr;
+
+        return wrap( &*I );
+    }
+
+    LLVMNamedMDNodeRef LLVMModuleGetFirstNamedMD( LLVMModuleRef M )
+    {
+        Module *Mod = unwrap( M );
+        Module::named_metadata_iterator I = Mod->named_metadata_begin( );
+        if ( I == Mod->named_metadata_end( ) )
+            return nullptr;
+
+        return wrap( &*I );
+    }
+
+    LLVMNamedMDNodeRef LLVMModuleGetNextNamedMD( LLVMNamedMDNodeRef /*NamedMDNode*/ valueRef )
+    {
+        NamedMDNode *pMD = unwrap( valueRef );
+        Module::named_metadata_iterator I( pMD );
+        if ( ++I == pMD->getParent( )->named_metadata_end( ) )
+            return nullptr;
+
+        return wrap( &*I );
+    }
 }