Updates for latest native interop. (#260)

* Updates for latest native interop.
* Added support for retrieving Version from native interop as a string.
* Removed value cache support as it isn't needed anymore.
* Doc comment corrections and typos
* Removed unused `using`

* Updated version expectations to 20.1.7 as minimum

* Updated to 20.1.8-alpha of native libs

---------

Co-authored-by: smaillet <25911635+smaillet@users.noreply.github.com>

Author: smaillet

Directory.Packages.props

@@ -4,7 +4,7 @@
     Global references are included in ALL projects in this repository
   -->
   <ItemGroup>
-    <GlobalPackageReference Include="Ubiquity.NET.Versioning.Build.Tasks" Version="5.0.0-rc" />
+    <GlobalPackageReference Include="Ubiquity.NET.Versioning.Build.Tasks" Version="5.0.6" />
     <GlobalPackageReference Include="IDisposableAnalyzers" Version="4.0.8" Condition="'$(NoCommonAnalyzers)' !=' true'" />
     <GlobalPackageReference Include="MustUseRetVal" Version="0.0.2" />
     <!--
@@ -28,6 +28,6 @@
     <PackageVersion Include="MSTest.TestAdapter" Version="3.9.1" />
     <PackageVersion Include="MSTest.TestFramework" Version="3.9.1" />
     <PackageVersion Include="Tmds.ExecFunction" Version="0.8.0" />
-    <PackageVersion Include="Ubiquity.NET.Versioning" Version="5.0.0-rc" />
+    <PackageVersion Include="Ubiquity.NET.Versioning" Version="6.0.1" />
   </ItemGroup>
-</Project>
+</Project>

IgnoredWords.dic

@@ -1,6 +1,7 @@
 ABI
 Accessor
 Addr
+addref
 alloca
 anonymize
 antlr
@@ -49,12 +50,14 @@ dllimport
 docfx
 docfxconsole
 dotnet
+endian
 endianess
 enum
 Enums
 env
 exe
 facepalm
+finalizer
 finalizers
 foo
 fullsrc

src/Interop/InteropTests/ABI/libllvm-c/TargetRegistrationBindingsTests.cs

@@ -63,18 +63,17 @@ public void LibLLVMGetRuntimeTargetsTest( )
         [TestMethod]
         public void LibLLVMGetVersionTest( )
         {
-            UInt64 ver = LibLLVMGetVersion();
-            Assert.IsTrue( ver > 0 );
-            var csemVer = CSemVer.From(ver);
-            Assert.AreEqual( 20, csemVer.Major );
-            Assert.AreEqual( 1, csemVer.Minor );
+            var ver = SemVer.Parse(LibLLVMGetVersion()?.ToString() ?? string.Empty, SemVerFormatProvider.CaseInsensitive);
+            Assert.IsTrue( ver is SemVer or CSemVer);
+            Assert.AreEqual( 20, ver.Major );
+            Assert.AreEqual( 1, ver.Minor );
 
             // Testing for an exact match of the patch level (or anything finer grained than that)
             // in an automated test is dubious as it would require updating the tests on effectively
             // EVERY build of the native library... So, this tests for a minimum value that was valid
             // at the time of creation. The above major/minor values should be updated on changes to
             // those assumptions as any number of things may have changed.
-            Assert.IsTrue( csemVer.Patch >= 4 );
+            Assert.IsTrue( ver.Patch >= 7);
         }
     }
 }

src/Interop/Ubiquity.NET.Llvm.Interop/ABI/libllvm-c/TargetRegistrationBindings.cs

@@ -75,8 +75,17 @@ private static unsafe partial LLVMErrorRef LibLLVMGetRuntimeTargets(
             LibLLVMCodeGenTarget[] targets, Int32 lengthOfArray
         );
 
+        public static LazyEncodedString? LibLLVMGetVersion( )
+        {
+            unsafe
+            {
+                byte* p = LibLLVMGetVersion(out nuint len);
+                return LazyEncodedString.FromUnmanaged( p, len );
+            }
+        }
+
         [LibraryImport( LibraryName )]
         [UnmanagedCallConv( CallConvs = [ typeof( CallConvCdecl ) ] )]
-        public static unsafe partial UInt64 LibLLVMGetVersion( );
+        private static unsafe partial byte* LibLLVMGetVersion(out nuint len);
     }
 }

src/Interop/Ubiquity.NET.Llvm.Interop/ABI/libllvm-c/ValueBindings.cs

@@ -10,12 +10,6 @@
 
 namespace Ubiquity.NET.Llvm.Interop.ABI.libllvm_c
 {
-    // Misplaced using directive; It isn't misplaced - tooling is too brain dead to know the difference between an alias and a using directive
-#pragma warning disable IDE0065, SA1200
-    using unsafe LibLLVMValueCacheItemDeletedCallback = delegate* unmanaged[Cdecl]< nint /*ctx*/,/*LLVMValueRef*/ nint /*@ref*/, nint /*handle*/, void /*retVal*/>;
-    using unsafe LibLLVMValueCacheItemReplacedCallback = delegate* unmanaged[Cdecl]< nint /*ctx*/, /*LLVMValueRef*/ nint /*oldValue*/, nint /*handle*/, /*LLVMValueRef*/nint /*newValue*/, nint /*retVal*/ >;
-#pragma warning restore IDE0065, SA1200
-
     public enum LibLLVMValueKind
         : Int32
     {
@@ -159,18 +153,6 @@ public static partial class ValueBindings
         [UnmanagedCallConv( CallConvs = [ typeof( CallConvCdecl ) ] )]
         public static unsafe partial LLVMValueRef LibLLVMValueAsMetadataGetValue( LLVMMetadataRef vmd );
 
-        [LibraryImport( LibraryName )]
-        [UnmanagedCallConv( CallConvs = [ typeof( CallConvCdecl ) ] )]
-        public static unsafe partial LibLLVMValueCacheRef LibLLVMCreateValueCache( nint ctx, LibLLVMValueCacheItemDeletedCallback deletedCallback, LibLLVMValueCacheItemReplacedCallback replacedCallback );
-
-        [LibraryImport( LibraryName )]
-        [UnmanagedCallConv( CallConvs = [ typeof( CallConvCdecl ) ] )]
-        public static unsafe partial void LibLLVMValueCacheAdd( LibLLVMValueCacheRef cacheRef, LLVMValueRef value, nint handle );
-
-        [LibraryImport( LibraryName )]
-        [UnmanagedCallConv( CallConvs = [ typeof( CallConvCdecl ) ] )]
-        public static unsafe partial nint LibLLVMValueCacheLookup( LibLLVMValueCacheRef cacheRef, LLVMValueRef valueRef );
-
         [LibraryImport( LibraryName )]
         [UnmanagedCallConv( CallConvs = [ typeof( CallConvCdecl ) ] )]
         [return: MarshalAs( UnmanagedType.Bool )]

src/Interop/Ubiquity.NET.Llvm.Interop/GlobalHandleBase.cs

@@ -80,7 +80,7 @@ protected GlobalHandleBase( nint handle, bool ownsHandle )
             // In a debug build capture the stack for creation of this instance
             // that way it is still available if there is an access violation
             // in the dispose. Usually such a thing indicates the source did NOT
-            // properly apply a using. So it is VERY helpful in debugging odf finalizer
+            // properly apply a using. So it is VERY helpful in debugging of finalizer
             // failures to locate the source.
             CaptureStack();
 #endif
@@ -150,7 +150,7 @@ public static T CloneWithAddRef<T>( this T self )
             self.DangerousAddRef( ref success );
             if(!success)
             {
-                throw new InvalidOperationException( "Failed to addreff the SafeHandle!" );
+                throw new InvalidOperationException( "Failed to addref the SafeHandle!" );
             }
 
             Marshal.InitHandle( retVal, self.DangerousGetHandle() );

src/Interop/Ubiquity.NET.Llvm.Interop/GlobalHandleMarshaller.cs

@@ -17,7 +17,6 @@
 [assembly: SuppressMessage( "StyleCop.CSharp.NamingRules", "SA1300:Element should begin with upper-case letter", Justification = "Interop ABI naming matches source for most structures and types" )]
 [assembly: SuppressMessage( "StyleCop.CSharp.DocumentationRules", "SA1649:File name should match first type name", Justification = "Filenames match that of the native ABI header file" )]
 [assembly: SuppressMessage( "StyleCop.CSharp.NamingRules", "SA1310:Field names should not contain underscore", Justification = "Interop ABI naming matches source for most structures and types" )]
-[assembly: SuppressMessage( "StyleCop.CSharp.DocumentationRules", "SA1642:Constructor summary documentation should begin with standard text", Justification = "Dumb rule - if the summary is really **supposed** to be a fixed format then tooling should just generate it..." )]
 [assembly: SuppressMessage( "Style", "IDE1006:Naming Styles", Justification = "Interop ABI naming matches source for most structures and types" )]
 [assembly: SuppressMessage( "Redundancies in Symbol Declarations", "RECS0007:The default underlying type of enums is int, so defining it explicitly is redundant.", Justification = "ABI interop; intent is to be explicit for clarity (even if redundant)" )]
 [assembly: SuppressMessage( "Maintainability", "CA1506:Avoid excessive class coupling", Justification = "The whole point of this library is to expose the native ABI methods and types" )]

src/Interop/Ubiquity.NET.Llvm.Interop/GlobalSuppressions.cs

@@ -29,17 +29,31 @@ public interface ILibLlvm
         /// <remarks>
         /// This is a simple set of enumerated values for the known targets supported by the library. It
         /// is distinct from the registered targets. Registration of each top level enumerated target may indeed
-        /// register support for more targets (e.g., ARM includes thumb big and little endian targets).
+        /// register support for more targets (e.g., ARM includes thumb big and little endian targets). This reports
+        /// only the top level architectural targets that are supported and available to register not what is currently
+        /// registered.
         /// </remarks>
         ImmutableArray<LibLLVMCodeGenTarget> SupportedTargets { get; }
 
         /// <summary>Gets version information for the library implementation</summary>
-        /// <returns><see cref="CSemVer"/> for the native interop library</returns>
+        /// <returns><see cref="FileVersionQuad"/> for the native interop library</returns>
         /// <remarks>
-        /// Not, since it is an extension of LLVM the version is NOT guaranteed to match that of LLVM itself. Though,
-        /// to avoid confusion it usually does and would only deviate when no option is available (Such as the extension
-        /// APIs changed even though LLVM itself did not)
+        /// <note type="note">Since it is dealing with an extension of LLVM, the version is NOT guaranteed to match that
+        /// of LLVM itself. Though, to avoid confusion, the major, minor and patch usually does and would only deviate
+        /// when no option is available (Such as the extension APIs changed even though LLVM itself did not)</note>
         /// </remarks>
-        CSemVer GetVersionInfo( );
+        SemVer ExtendedAPIVersion { get; }
+
+        /// <summary>Gets version information for LLVM</summary>
+        /// <remarks>
+        /// This is a short hand wrapper around the <see cref="ABI.llvm_c.Core.LLVMGetVersion(out uint, out uint, out uint)"/>
+        /// for a given library instance. It converts the multiple out params to a <see cref="SemVer"/>.
+        /// <note type="note">
+        /// LLVM and the underlying APIs do not support any form of the pre-release information, nor do they support or provide
+        /// the build meta (which doesn't participate in ordering anyway). Therefore, any ordering from <see cref="SemVerComparer"/>
+        /// or <see cref="SemVerComparer.CaseSensitive"/> is valid for these versions and will produce the correct ordering.
+        /// </note>
+        /// </remarks>
+        SemVer LlvmVersion { get; }
     }
 }

src/Interop/Ubiquity.NET.Llvm.Interop/ILibLlvm.cs

@@ -24,9 +24,17 @@ public void RegisterTarget( LibLLVMCodeGenTarget target, LibLLVMTargetRegistrati
             LibLLVMRegisterTarget( target, registrations ).ThrowIfFailed();
         }
 
-        public CSemVer GetVersionInfo( )
+        /// <inheritdoc/>
+        public SemVer ExtendedAPIVersion { get; private set; }
+
+        /// <inheritdoc/>
+        public SemVer LlvmVersion
         {
-            return CSemVer.From( LibLLVMGetVersion() );
+            get
+            {
+                LLVMGetVersion( out UInt32 major, out UInt32 minor, out UInt32 patch );
+                return new SemVer( major, minor, patch );
+            }
         }
 
         /// <inheritdoc/>
@@ -48,26 +56,27 @@ public static ILibLlvm InitializeLLVM( )
             }
 
             // Verify the version of LibLLVM.
-            var libLLVMVersion = CSemVer.From(LibLLVMGetVersion());
-            if(libLLVMVersion.Major != SupportedVersion.Major
-             || libLLVMVersion.Minor != SupportedVersion.Minor
-             || libLLVMVersion.Patch != SupportedVersion.Patch
+            var libVersion = SemVer.Parse(LibLLVMGetVersion()?.ToString() ?? string.Empty, SemVerFormatProvider.CaseInsensitive);
+            if( libVersion.Major != SupportedVersion.Major
+             || libVersion.Minor != SupportedVersion.Minor
+             || libVersion.Patch != SupportedVersion.Patch
             )
             {
                 string msgFmt = Resources.Mismatched_LibLLVM_version_Expected_0_Actual_1;
                 string msg = string.Format( CultureInfo.CurrentCulture
                                           , msgFmt
                                           , SupportedVersion.ToString()
-                                          , libLLVMVersion.ToString()
+                                          , libVersion.ToString()
                                           );
                 throw new InvalidOperationException( msg );
             }
 
-            return new Library();
+            return new Library(libVersion);
         }
 
-        private Library( )
+        private Library( SemVer libVersion )
         {
+            ExtendedAPIVersion = libVersion;
             unsafe
             {
                 LLVMInstallFatalErrorHandler( &FatalErrorHandler );
@@ -78,7 +87,7 @@ private Library( )
 
         // Expected version info for verification of matched LibLLVM
         // Interop exports/signatures may not be valid if not a match.
-        private static readonly CSemVer SupportedVersion = new(20, 1, 6);
+        private static readonly CSemVer SupportedVersion = new(20, 1, 8);
 
         // Singleton initializer for the supported targets array
         private static ImmutableArray<LibLLVMCodeGenTarget> GetSupportedTargets( )
@@ -91,20 +100,20 @@ private static ImmutableArray<LibLLVMCodeGenTarget> GetSupportedTargets( )
         }
 
         // Native call back for fatal error handling.
+        // NOTE: LLVM will call exit() upon return from this function and there's no way to stop it
         [UnmanagedCallersOnly( CallConvs = [ typeof( CallConvCdecl ) ] )]
         [SuppressMessage( "Design", "CA1031:Do not catch general exception types", Justification = "REQUIRED for unmanaged callback - Managed exceptions must never cross the boundary to native code" )]
         private static unsafe void FatalErrorHandler( byte* reason )
         {
             try
             {
-                // NOTE: LLVM will call exit() upon return from this function and there's no way to stop it
                 Trace.TraceError( "LLVM Fatal Error: '{0}'; Application will exit.", ExecutionEncodingStringMarshaller.ConvertToManaged( reason ) );
             }
             catch(Exception ex)
             {
                 // No finalizers will occur after this, it's a HARD termination of the app.
                 // LLVM will do that on return but this can at least indicate a different problem
-                // from the original LLVM was reporting.
+                // from the original one LLVM was reporting.
                 Environment.FailFast( $"Unhandled exception in {nameof( FatalErrorHandler )}.", ex );
             }
         }