Usage clarifications and updates. (#288)

Author: smaillet

src/Interop/Ubiquity.NET.Llvm.Interop/ABI/StringMarshaling/LLVMErrorRef.cs

@@ -48,7 +48,8 @@ public LLVMErrorRef( nint handle )
         /// <summary>Gets a value indicating whether this instance represents a failure</summary>
         public bool Failed => !Success;
 
-        /// <inheritdoc/>
+        /// <summary>Gets a string representation of the error message</summary>
+        /// <returns>String representation of the error message</returns>
         public override string ToString( )
         {
             return LazyMessage.Value?.ToString() ?? string.Empty;

src/Ubiquity.NET.Llvm.Tests/CallTests.cs

@@ -6,6 +6,7 @@
 
 using Microsoft.VisualStudio.TestTools.UnitTesting;
 
+using Ubiquity.NET.Llvm.DebugInfo;
 using Ubiquity.NET.Llvm.Instructions;
 using Ubiquity.NET.Llvm.Values;
 
@@ -43,5 +44,27 @@ public void Create_varargs_function_with_arbitrary_params_succeeds( )
             Assert.AreEqual( 1UL, callInstruction.Operands.GetOperand<ConstantInt>( 1 )!.ZeroExtendedValue );
             Assert.AreEqual( 2UL, callInstruction.Operands.GetOperand<ConstantInt>( 2 )!.ZeroExtendedValue );
         }
+
+        [TestMethod]
+        [TestCategory( "Instruction" )]
+        public void Create_indirect_function_call_succeeds( )
+        {
+            using var ctx = new Context();
+            using var module = ctx.CreateBitcodeModule();
+            var voidType = module.Context.VoidType;
+            var voidPtrType = voidType.CreatePointerType();
+
+            // Func sig: void (*)(int32_t, double);
+            var targetSig = ctx.GetFunctionType(returnType: voidType, ctx.Int32Type, ctx.DoubleType);
+            var callerSig = ctx.GetFunctionType(returnType: voidType, voidPtrType);
+            var caller = module.CreateFunction("CallIndirect"u8, callerSig);
+
+            using var bldr = new InstructionBuilder( caller.PrependBasicBlock( "entry" ) );
+
+            var callInstruction = bldr.Call( targetSig, caller.Parameters[0], ctx.CreateConstant(1), ctx.CreateConstant(2.0));
+            bldr.Return();
+            Assert.IsNotNull( callInstruction );
+            Assert.IsTrue(module.Verify(out string? msg), msg);
+        }
     }
 }

src/Ubiquity.NET.Llvm.Tests/ContextTests.cs

@@ -41,7 +41,7 @@ public void SimpleConstructorDisposeTest( )
         public void GetPointerTypeForTest( )
         {
             using var context = new Context();
-            var int8PtrType = context.GetPointerTypeFor( context.Int8Type );
+            var int8PtrType = context.Int8Type.CreatePointerType();
             Assert.IsNotNull( int8PtrType );
             Assert.AreEqual( context, int8PtrType.Context );
 

src/Ubiquity.NET.Llvm/Context.cs

@@ -81,9 +81,6 @@ public Context( )
         /// <inheritdoc/>
         public void SetDiagnosticHandler( DiagnosticInfoCallbackAction handler ) => Impl.SetDiagnosticHandler( handler );
 
-        /// <inheritdoc/>
-        public IPointerType GetPointerTypeFor( ITypeRef elementType ) => Impl.GetPointerTypeFor( elementType );
-
         /// <inheritdoc/>
         public ITypeRef GetIntType( uint bitWidth ) => Impl.GetIntType( bitWidth );
 

src/Ubiquity.NET.Llvm/ContextAlias.cs

@@ -155,15 +155,6 @@ public void SetDiagnosticHandler( DiagnosticInfoCallbackAction handler )
             }
         }
 
-        public IPointerType GetPointerTypeFor( ITypeRef elementType )
-        {
-            ArgumentNullException.ThrowIfNull( elementType );
-
-            return !Equals( elementType.Context )
-                ? throw new ArgumentException( Resources.Cannot_mix_types_from_different_contexts, nameof( elementType ) )
-                : (IPointerType)LLVMPointerType( elementType.GetTypeRef(), 0 ).CreateType();
-        }
-
         public ITypeRef GetIntType( uint bitWidth )
         {
             ArgumentOutOfRangeException.ThrowIfZero( bitWidth );

src/Ubiquity.NET.Llvm/ErrorInfo.cs

@@ -37,7 +37,8 @@ public bool Success
         /// <summary>Gets a value indicating whether this instance is disposed</summary>
         public bool IsDisposed => Handle is not null && Handle.IsClosed;
 
-        /// <inheritdoc/>
+        /// <summary>Gets a string representation of the error message</summary>
+        /// <returns>String representation of the error message or an empty string if none</returns>
         public override string ToString( )
         {
             ObjectDisposedException.ThrowIf( IsDisposed, typeof( ErrorInfo ) );

src/Ubiquity.NET.Llvm/IContext.cs

@@ -152,7 +152,7 @@ public interface IModule
         /// <returns><see langword="true"/> if the function was found or <see langword="false"/> if not</returns>
         public bool TryGetNamedGlobalIFunc( LazyEncodedString name, [MaybeNullWhen( false )] out GlobalIFunc function );
 
-        /// <summary>Gets an existing function with the specified signature to the module or creates a new one if it doesn't exist</summary>
+        /// <summary>Gets an existing function with the specified signature in the module or creates a new one if it doesn't exist</summary>
         /// <param name="name">Name of the function to add</param>
         /// <param name="signature">Signature of the function</param>
         /// <returns><see cref="Function"/>matching the specified signature and name</returns>
@@ -164,6 +164,51 @@ public interface IModule
         /// </remarks>
         public Function CreateFunction( LazyEncodedString name, IFunctionType signature );
 
+        /// <summary>Creates a Function definition with Debug information</summary>
+        /// <param name="diBuilder">The debug info builder to use to create the function (must be associated with this module)</param>
+        /// <param name="scope">Containing scope for the function</param>
+        /// <param name="name">Name of the function in source language form</param>
+        /// <param name="linkageName">Mangled linker visible name of the function (may be same as <paramref name="name"/> if mangling not required by source language</param>
+        /// <param name="file">File containing the function definition</param>
+        /// <param name="line">Line number of the function definition</param>
+        /// <param name="signature">LLVM Function type for the signature of the function</param>
+        /// <param name="isLocalToUnit">Flag to indicate if this function is local to the compilation unit</param>
+        /// <param name="isDefinition">Flag to indicate if this is a definition</param>
+        /// <param name="scopeLine">First line of the function's outermost scope, this may not be the same as the first line of the function definition due to source formatting</param>
+        /// <param name="debugFlags">Additional flags describing this function</param>
+        /// <param name="isOptimized">Flag to indicate if this function is optimized</param>
+        /// <returns>Function described by the arguments</returns>
+        public Function CreateFunction( IDIBuilder diBuilder
+                                      , DIScope? scope
+                                      , LazyEncodedString name
+                                      , LazyEncodedString? linkageName
+                                      , DIFile? file
+                                      , uint line
+                                      , DebugFunctionType signature
+                                      , bool isLocalToUnit
+                                      , bool isDefinition
+                                      , uint scopeLine
+                                      , DebugInfoFlags debugFlags
+                                      , bool isOptimized
+                                      );
+
+        /// <summary>Creates a function</summary>
+        /// <param name="diBuilder"><see cref="DIBuilder"/> for creation of debug information</param>
+        /// <param name="name">Name of the function</param>
+        /// <param name="isVarArg">Flag indicating if the function supports a variadic argument list</param>
+        /// <param name="returnType">Return type of the function</param>
+        /// <param name="argumentTypes">Arguments for the function</param>
+        /// <returns>
+        /// Function, matching the signature specified. This may be a previously declared or defined
+        /// function or a new function if none matching the name and signature is already present.
+        /// </returns>
+        public Function CreateFunction( IDIBuilder diBuilder
+                                      , LazyEncodedString name
+                                      , bool isVarArg
+                                      , IDebugType<ITypeRef, DIType> returnType
+                                      , params IEnumerable<IDebugType<ITypeRef, DIType>> argumentTypes
+                                      );
+
         /// <summary>Writes a bit-code module to a file</summary>
         /// <param name="path">Path to write the bit-code into</param>
         /// <remarks>
@@ -300,68 +345,6 @@ LazyEncodedString name
         /// <param name="version">version information to place in the llvm.ident metadata</param>
         public void AddVersionIdentMetadata( LazyEncodedString version );
 
-        /// <summary>Creates a Function definition with Debug information</summary>
-        /// <param name="diBuilder">The debug info builder to use to create the function (must be associated with this module)</param>
-        /// <param name="scope">Containing scope for the function</param>
-        /// <param name="name">Name of the function in source language form</param>
-        /// <param name="linkageName">Mangled linker visible name of the function (may be same as <paramref name="name"/> if mangling not required by source language</param>
-        /// <param name="file">File containing the function definition</param>
-        /// <param name="line">Line number of the function definition</param>
-        /// <param name="signature">LLVM Function type for the signature of the function</param>
-        /// <param name="isLocalToUnit">Flag to indicate if this function is local to the compilation unit</param>
-        /// <param name="isDefinition">Flag to indicate if this is a definition</param>
-        /// <param name="scopeLine">First line of the function's outermost scope, this may not be the same as the first line of the function definition due to source formatting</param>
-        /// <param name="debugFlags">Additional flags describing this function</param>
-        /// <param name="isOptimized">Flag to indicate if this function is optimized</param>
-        /// <returns>Function described by the arguments</returns>
-        public Function CreateFunction( IDIBuilder diBuilder
-                                      , DIScope? scope
-                                      , LazyEncodedString name
-                                      , LazyEncodedString? linkageName
-                                      , DIFile? file
-                                      , uint line
-                                      , DebugFunctionType signature
-                                      , bool isLocalToUnit
-                                      , bool isDefinition
-                                      , uint scopeLine
-                                      , DebugInfoFlags debugFlags
-                                      , bool isOptimized
-                                      );
-
-        /// <summary>Creates a function</summary>
-        /// <param name="diBuilder"><see cref="DIBuilder"/> for creation of debug information</param>
-        /// <param name="name">Name of the function</param>
-        /// <param name="isVarArg">Flag indicating if the function supports a variadic argument list</param>
-        /// <param name="returnType">Return type of the function</param>
-        /// <param name="argumentTypes">Arguments for the function</param>
-        /// <returns>
-        /// Function, matching the signature specified. This may be a previously declared or defined
-        /// function or a new function if none matching the name and signature is already present.
-        /// </returns>
-        public Function CreateFunction( IDIBuilder diBuilder
-                                      , LazyEncodedString name
-                                      , bool isVarArg
-                                      , IDebugType<ITypeRef, DIType> returnType
-                                      , IEnumerable<IDebugType<ITypeRef, DIType>> argumentTypes
-                                      );
-
-        /// <summary>Creates a function</summary>
-        /// <param name="diBuilder"><see cref="DIBuilder"/> for creation of debug information</param>
-        /// <param name="name">Name of the function</param>
-        /// <param name="isVarArg">Flag indicating if the function supports a variadic argument list</param>
-        /// <param name="returnType">Return type of the function</param>
-        /// <param name="argumentTypes">Arguments for the function</param>
-        /// <returns>
-        /// Function, matching the signature specified. This may be a previously declared or defined
-        /// function or a new function if none matching the name and signature is already present.
-        /// </returns>
-        public Function CreateFunction( IDIBuilder diBuilder
-                                      , LazyEncodedString name
-                                      , bool isVarArg
-                                      , IDebugType<ITypeRef, DIType> returnType
-                                      , params IDebugType<ITypeRef, DIType>[] argumentTypes
-                                      );
-
         /// <summary>Gets a declaration for an LLVM intrinsic function</summary>
         /// <param name="name">Name of the intrinsic</param>
         /// <param name="args">Args for the intrinsic</param>

src/Ubiquity.NET.Llvm/IModule.cs

@@ -15,8 +15,8 @@ public class CallInstruction
         , IFunctionAttributeAccessor
     {
         /// <summary>Gets the target function of the call</summary>
-        public Function TargetFunction
-            => FromHandle<Function>( LLVMGetCalledValue( Handle ).ThrowIfInvalid() )!;
+        public Value TargetFunction
+            => FromHandle<Value>( LLVMGetCalledValue( Handle ).ThrowIfInvalid() )!;
 
         /// <summary>Gets or sets a value indicating whether the call is a tail call</summary>
         public bool IsTailCall