Merge pull request #107 from Lombiq/issue/HAST-314

HAST-314: ⭐ Hast.Samples.Consumer GUI bug fixes and documentation housekeeping

Directory.Build.props

@@ -1,6 +1,13 @@
 <Project>
   <Import Project="tools/Lombiq.Analyzers/Lombiq.Analyzers/Build.props" />
 
+  <!-- Prevents error NETSDK1152 (Found multiple publish output files with the same relative path) when publishing. This
+       error shows up in projects that have multiple indirect dependencies on Hast.Vitis.HardwareFramework that copies
+       HardwareFramework/opencl/src to the build directory. -->
+  <PropertyGroup>
+    <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
+  </PropertyGroup>
+
   <PropertyGroup Condition="'$(IsPackable)' != 'false'">
     <Authors>Lombiq Technologies</Authors>
     <Copyright>Copyright © 2017, Lombiq Technologies Ltd.</Copyright>

NuGetTest/Hast.NuGet.Console/Hast.NuGet.Console.csproj

@@ -8,8 +8,8 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Hast.Algorithms" Version="2.1.1-alpha.0.hast-321" />
-    <PackageReference Include="Hast.Layer" Version="2.1.1-alpha.0.hast-321" />
+    <PackageReference Include="Hast.Algorithms" Version="2.1.1-alpha.0.hast-314" />
+    <PackageReference Include="Hast.Layer" Version="2.1.1-alpha.0.hast-314" />
     <PackageReference Include="Hast.Vitis.HardwareFramework" Version="1.2.0" />
   </ItemGroup>
 

NuGetTest/Hast.NuGet.Console/Program.cs

@@ -12,6 +12,16 @@
 
 configuration.VhdlTransformerConfiguration().VhdlGenerationConfiguration = VhdlGenerationConfiguration.Debug;
 
+// To cross-compile, first run without any arguments (this will throw an exception during execution), then copy the
+// HardwareFramework directory to the remote device and pass the binary's path as the argument, e.g.:
+// dotnet Hast.NuGet.Console.dll HardwareFramework/bin/*.azure.xclbin
+var binaryPath = Environment.GetCommandLineArgs().FirstOrDefault(item => item.EndsWithOrdinalIgnoreCase(".xclbin"));
+if (File.Exists(binaryPath))
+{
+    configuration.SingleBinaryPath = binaryPath;
+    Console.WriteLine($"Using the existing binary file \"{binaryPath}\". Compilation will be skipped.");
+}
+
 hastlayer.ExecutedOnHardware += (_, e) =>
     Console.WriteLine(
         StringHelper.ConcatenateConvertiblesInvariant(

src/Hastlayer/Hast.Common/Extensions/DictionaryExtensions.cs

@@ -1,11 +1,17 @@
+using Newtonsoft.Json.Linq;
+
 namespace System.Collections.Generic;
 
 public static class DictionaryExtensions
 {
     public static T GetOrAddCustomConfiguration<T>(this IDictionary<string, object> customConfiguration, string key)
         where T : new()
     {
-        if (customConfiguration.TryGetValue(key, out var config)) return (T)config;
+        if (customConfiguration.TryGetValue(key, out var config))
+        {
+            if (config is T typedConfig) return typedConfig;
+            if (config is JToken jToken) return jToken.ToObject<T>();
+        }
 
         var newInstance = new T();
         customConfiguration[key] = newInstance;

src/Hastlayer/Hast.Layer/Hast.Layer.csproj

@@ -13,7 +13,7 @@
       <PackageCopyToOutput>true</PackageCopyToOutput>
     </Content>
   </ItemGroup>
-  
+
   <ItemGroup>
     <ProjectReference Include="..\Hast.Synthesis\Hast.Synthesis.csproj" />
     <ProjectReference Include="..\Hast.Transformer\Hast.Transformer.csproj" />
@@ -23,14 +23,13 @@
     <ProjectReference Include="..\Hast.Xilinx\Hast.Xilinx.csproj" />
     <ProjectReference Include="..\Hast.Communication\Hast.Communication.csproj" />
   </ItemGroup>
-  
+
   <ItemGroup>
     <PackageReference Include="Microsoft.CSharp" Version="4.7.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.CommandLine" Version="6.0.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="6.0.1" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="6.0.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="6.0.1" />
-    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="6.0.0" />
     <PackageReference Include="NLog" Version="4.7.15" />
     <PackageReference Include="NLog.Extensions.Logging" Version="1.7.4" />
   </ItemGroup>

src/Hastlayer/Hast.Vitis/Docs/Docker.md

@@ -1,6 +1,6 @@
 # Docker Setup
 
-This way you can compile on your Windows machine, or any machine where you don't want to install XRT permanently. Note that you still need to download the complete Vitis XDK separately for licensing reasons and it takes about 125GB (and at least 50GB more temporarily) to set up the image. Of course you need [Docker installed](https://docs.docker.com/get-docker/) too. However there are no alternatives on Windows so please bear with it. Following these steps you will get a container with Vitis XDK and .NET Core 3.1 SDK installed. Please remember not to distribute the resulting image!
+This way you can compile on your Windows machine, or any machine where you don't want to install XRT permanently. Note that you still need to download the complete Vitis XDK separately for licensing reasons and it takes about 125GB (and at least 50GB more temporarily) to set up the image. Of course you need [Docker installed](https://docs.docker.com/get-docker/) too. However there are no alternatives on Windows so please bear with it. Following these steps you will get a container with Vitis XDK and .NET SDK installed. Please remember not to distribute the resulting image!
 
 
 ## Installation Steps

src/Hastlayer/Hast.Vitis/Docs/Nimbix.md

@@ -1,6 +1,8 @@
 # Nimbix usage
 
 
+> ⚠️ The instructions below are outdated, as the mentioned Alveo trial is no longer available. Some of the names have changed since Nimbix has been acquired by Atos, and they only seem to offer enterprise solutions now. The rest of the document is retained in case it may be a useful reference for anyone who wants to use their services with Hastlayer.
+
 
 To run a Hastlayer applications on the [Nimbix HPC cloud](https://www.nimbix.net/), a compute instance must be launched, the dependencies installed and the host & device applications uploaded. You can find the necessary instructions here.
 
@@ -10,7 +12,7 @@ Be sure to also check out the [general docs](../Readme.md).
 ## Administrative steps
 
 1. Sign up for the [Nimbix Alveo Trial](https://www.nimbix.net/alveotrial).
-2. [Log into the Nimbix platform](https://platform.jarvice.com/) after the registration is complete. [Here](https://support.nimbix.net/hc/en-us/articles/360035258971-Getting-Started-With-Alveo-Trial) is also some more getting started information (note that the costs indicator only updates when you shut down your job).
+2. [Log into the Nimbix platform](https://cloud.nimbix.net/) after the registration is complete. [Here](https://support.nimbix.net/hc/en-us/articles/360035258971-Getting-Started-With-Alveo-Trial) is also some more getting started information (note that the costs indicator only updates when you shut down your job).
 3. On the right sidebar click "Compute" and find "Xilinx Vitis Unified Software Platform 2020.1" in the search bar. At the time of writing this that option lets you pick U50, U200, and U280.
 4. Activate "Desktop Mode with FPGA" and select the machine type with the appropriate board. Note that Nimbix might be overloaded and not every board you can select will actually be available, resulting in the job being queued forever. Check out the availability on the [Nimbix status page](https://status.jarvice.com/) first.
 5. You should be sent to the Dashboard section with a thumbnail for the running instance.

src/Hastlayer/Hast.Vitis/Interop/Xrt.cs

@@ -12,7 +12,7 @@ namespace Hast.Vitis.Interop;
 /// <para>Source: <see href="https://github.com/Xilinx/XRT/blob/master/src/include/1_2/CL/cl_ext_xilinx.h"/>.</para>
 /// <para>
 /// Legacy layout is used since that's the one in the examples <see
-/// href="https://github.com/Xilinx/Vitis_Accel_Examples/blob/master/host/hbm_bandwidth/src/host.cpp">here</see>.
+/// href="https://github.com/Xilinx/Vitis_Accel_Examples/blob/2021.1/host/hbm_bandwidth/src/host.cpp">here</see>.
 /// </para>
 /// </remarks>
 // LayoutKind can't be Auto because this struct is exposed to unmanaged code.

src/Hastlayer/Hast.Vitis/Readme.md

@@ -8,8 +8,6 @@ This project contains the communication service used to connect with Xilinx's [V
 
 Note that the SH scripts in this project should use LF line endings! You'll get errors such as `-bash: $'\r': command not found` otherwise.
 
-For Nimbix-specific instructions see [the Nimbix docs](Docs/Nimbix.md).
-
 ## Requirements
 
 * The system running the FPGA card must be 64-bit Linux (e.g. Ubuntu 18.04.2 LTS or CentOS 7.6). The installation instructions can be found here [in the platform documentation](https://www.xilinx.com/html_docs/xilinx2019_2/vitis_doc/vhc1571429852245.html).
@@ -20,7 +18,8 @@ For Nimbix-specific instructions see [the Nimbix docs](Docs/Nimbix.md).
 
 Even after everything is installed, you have to make sure that the executing user's environment variables are correctly set by sourcing the setup scripts [as described in the documentation](https://docs.xilinx.com/r/en-US/ug1400-vitis-embedded/Setting-Up-the-Environment-to-Run-the-Vitis-Software-Platform). You can add these commands into the `~/.bashrc` file to avoid having to type them every time. If running from the cloud, like Nimbix, this is probably handled automatically.
 
-For setup instructions on the Nimbix cloud see the [Nimbix-specific instructions](Docs/Nimbix.md).
+- For Azure-specific instructions see [the Azure NP docs](Docs/AzureReadme.md).
+- For Nimbix-specific instructions see [the Nimbix docs](Docs/Nimbix.md).
 
 
 ## Cross Compilation
@@ -45,7 +44,7 @@ Aside from general Vitis accelerator card support, there are a couple specialize
 
 ## Other Remarks
 
-If you ever get an error *\[XRT\] ERROR: some device is already programmed* due to a crashed or interrupted execution, you can reset the card using `xbutil reset` command. See more info about the Xilinx Board Utility [here](https://www.xilinx.com/html_docs/xilinx2019_1/sdaccel_doc/yrx1536963262111.html).
+If you ever get an error *\[XRT\] ERROR: some device is already programmed* due to a crashed or interrupted execution, you can reset the card using `xbutil reset` command. See more info about the Xilinx Board Utility [here](https://xilinx.github.io/XRT/master/html/xbutil.html).
 
 If you just want to generate a simulation report, you can do that without the full build by configuring the `VitisBuildConfiguration.SynthesisOnly` custom configuration in the *appsettings.json* or by adding the following command line argument:
 

src/Hastlayer/Hast.Vitis/Services/VitisHardwareImplementationComposerBuildProvider.cs

@@ -85,7 +85,7 @@ public Task BuildAsync(
             // When cross-compiling, the build machine needs Vivado and XRT, but the FPGA machine only needs XRT.
             _logger.LogWarning(
                 "XILINX_VITIS variable is not set. This is required to build using Vivado. For further instructions " +
-                "see https://www.xilinx.com/html_docs/xilinx2020_1/vitis_doc/settingupvitisenvironment.html.");
+                "see https://docs.xilinx.com/r/en-US/ug1393-vitis-application-acceleration/Building-and-Running-the-Application.");
         }
 
         GetXilinxDirectoryPathOrThrow();
@@ -364,7 +364,7 @@ private async Task BuildKernelAsync(
             var emConfigExecutable = await GetExecutablePathAsync("emconfigutil");
             var emConfigArguments = new[] { "--platform", device, "--od", tmpDirectoryPath, };
             await _buildLogger.ExecuteWithLoggingAsync(emConfigExecutable, emConfigArguments, rtlDirectoryPath);
-            File.Copy(Path.Combine(tmpDirectoryPath, "emconfig.json"), "emconfig.json");
+            Copy(Path.Combine(tmpDirectoryPath, "emconfig.json"), "emconfig.json", overwrite: false);
             ProgressMajor("Emulation configuration (emconfig) setup is finished.");
         }
     }
@@ -401,8 +401,8 @@ private void CopyBinaries(
         if (binaryDirectoryPath != null) EnsureDirectoryExists(binaryDirectoryPath);
 
         var builtFilePath = Path.Combine(GetTmpDirectoryPath(hashId), $"hastip.{target}.xclbin");
-        File.Copy(builtFilePath, binaryPath);
-        File.Copy(builtFilePath + InfoFileExtension, binaryPath + InfoFileExtension);
+        Copy(builtFilePath, binaryPath, overwrite: true);
+        Copy(builtFilePath + InfoFileExtension, binaryPath + InfoFileExtension, overwrite: true);
         if (disableHbm) File.Create(binaryPath + NoHbmFlagExtension).Dispose();
         ProgressMajor($"Files copied to binary folder ({builtFilePath}).");
     }
@@ -427,7 +427,7 @@ private async Task CollectReportsAsync(
         var reportFiles = Directory.GetFiles(reportPath, "*.rpt");
         foreach (var reportFile in reportFiles)
         {
-            File.Copy(reportFile, Path.Combine(reportSavePath, Path.GetFileName(reportFile)));
+            Copy(reportFile, Path.Combine(reportSavePath, Path.GetFileName(reportFile)), overwrite: true);
         }
 
         var reportFilePath =
@@ -635,7 +635,7 @@ private static async Task ApplyTemplatesAsync(
             if (file.EndsWith(".template", StringComparison.OrdinalIgnoreCase)) continue;
 
             var targetFilePath = Path.Combine(targetDirectoryPath, "IP", Path.GetFileName(file));
-            if (!File.Exists(targetFilePath)) File.Copy(file, targetFilePath);
+            Copy(file, targetFilePath, overwrite: false);
         }
     }
 
@@ -686,4 +686,15 @@ private static string GetXilinxDirectoryPathOrThrow()
 
         return xilinxDirectoryPath;
     }
+
+    private static void Copy(string from, string to, bool overwrite)
+    {
+        ArgumentNullException.ThrowIfNull(from);
+        ArgumentNullException.ThrowIfNull(to);
+
+        if (overwrite || !File.Exists(to))
+        {
+            File.Copy(from, to, overwrite: true);
+        }
+    }
 }

src/Hastlayer/Hast.Vitis/ubuntu-install.sh

@@ -13,8 +13,8 @@ yes | sudo apt-get --yes --force-yes install apt-transport-https
 sudo apt-get update
 # This installs the full SDK allowing you to build from source. If you only want to run the compiled application, you
 # can install just the runtime by swapping the comment on the two lines below.
-yes | sudo apt-get --yes --force-yes install dotnet-sdk-3.1
-# yes | sudo apt-get --yes --force-yes install dotnet-runtime-3.1
+yes | sudo apt-get --yes --force-yes install dotnet-sdk-7.0.x86_64
+# yes | sudo apt-get --yes --force-yes install dotnet-runtime-7.0.x86_64
 
 
 

src/Hastlayer/Hast.Xilinx/Drivers/AzureAlveoU250Driver.cs

@@ -1,4 +1,6 @@
+using Hast.Layer;
 using Hast.Synthesis.Services;
+using System;
 
 namespace Hast.Xilinx.Drivers;
 
@@ -10,7 +12,13 @@ public class AzureAlveoU250Driver : VitisDeviceDriverBase
     public override string PlatformName => "xilinx_u250_gen3x16_xdma_2_1_202010_1"; // Needs a very specific version.
     public override uint ClockFrequencyMhz => 300;
 
+    protected override string TimingReportFileName => nameof(AlveoU250Driver);
+
     public AzureAlveoU250Driver(ITimingReportParser timingReportParser)
-        : base(timingReportParser)
-    { }
+        : base(timingReportParser) =>
+        _deviceManifest = new Lazy<IDeviceManifest>(() => InitializeManifest(new AzureNpDeviceManifest
+        {
+            SupportsHbm = false,
+            RequiresDcpBinary = true,
+        }));
 }

src/Hastlayer/Hast.Xilinx/Drivers/VitisDeviceDriverBase.cs

@@ -15,17 +15,21 @@ public abstract class VitisDeviceDriverBase : DeviceDriverBase
 
     protected VitisDeviceDriverBase(ITimingReportParser timingReportParser)
         : base(timingReportParser) =>
-        _deviceManifest = new Lazy<IDeviceManifest>(() => new VitisDeviceManifest
-        {
-            Name = DeviceName,
-            ClockFrequencyHz = ClockFrequencyMhz * Mhz,
-            SupportedCommunicationChannelNames = new[] { Constants.VitisCommunicationChannelName },
-            // While there is much more DDR RAM on the device, the max object size in .NET is 2GB. So until we add
-            // paging to SimpleMemory the limit is 2GB, see: https://github.com/Lombiq/Hastlayer-SDK/issues/27
-            AvailableMemoryBytes = 2 * GigaByte,
-            SupportedPlatforms = string.IsNullOrEmpty(PlatformName) ? Array.Empty<string>() : new[] { PlatformName },
-        });
+        _deviceManifest = new Lazy<IDeviceManifest>(() => InitializeManifest(new VitisDeviceManifest()));
 
     public override void ConfigureMemory(MemoryConfiguration memory, IHardwareGenerationConfiguration hardwareGeneration) =>
         MemoryConfigurationHelper.ConfigureMemoryForVitis(memory, hardwareGeneration);
+
+    protected IDeviceManifest InitializeManifest(VitisDeviceManifest manifest)
+    {
+        manifest.Name = DeviceName;
+        manifest.ClockFrequencyHz = ClockFrequencyMhz * Mhz;
+        manifest.SupportedCommunicationChannelNames = new[] { Constants.VitisCommunicationChannelName };
+        // While there is much more DDR RAM on the device, the max object size in .NET is 2GB. So until we add
+        // paging to SimpleMemory the limit is 2GB, see: https://github.com/Lombiq/Hastlayer-SDK/issues/27.
+        manifest.AvailableMemoryBytes = 2 * GigaByte;
+        manifest.SupportedPlatforms = string.IsNullOrEmpty(PlatformName) ? Array.Empty<string>() : new[] { PlatformName };
+
+        return manifest;
+    }
 }

src/Samples/Hast.Samples.SampleAssembly/Hast.Samples.SampleAssembly.csproj

@@ -12,11 +12,11 @@
   </ItemGroup>
 
   <ItemGroup Condition="$(SolutionName) == 'Hastlayer.SDK.NuGet'">
-    <PackageReference Include="Hast.Algorithms" Version="2.1.1-alpha.0.hast-321" />
-    <PackageReference Include="Hast.Layer" Version="2.1.1-alpha.0.hast-321" />
+    <PackageReference Include="Hast.Algorithms" Version="2.1.1-alpha.0.hast-314" />
+    <PackageReference Include="Hast.Layer" Version="2.1.1-alpha.0.hast-314" />
     <PackageReference Include="Lombiq.Arithmetics" Version="0.0.1-alpha.3.hast-175" />
   </ItemGroup>
-  
+
   <ItemGroup>
     <PackageReference Include="Hast.Vitis.HardwareFramework" Version="1.2.0" />
     <PackageReference Include="SixLabors.ImageSharp" Version="2.1.3" />