add DFU upload methods

Author: benedekkupper

DeviceProgramming.csproj

@@ -5,18 +5,21 @@
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
     <Authors>Benedek Kupper</Authors>
-    <Version>1.0.3</Version>
     <Description>Standalone C# library for device firmware programming</Description>
-    <Copyright>Copyright © Benedek Kupper 2021</Copyright>
-    <PackageLicenseExpression></PackageLicenseExpression>
+    <Copyright>Copyright © Benedek Kupper 2024</Copyright>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageProjectUrl>https://github.com/IntergatedCircuits/DeviceProgramming</PackageProjectUrl>
     <RepositoryUrl>https://github.com/IntergatedCircuits/DeviceProgramming</RepositoryUrl>
     <PackageTags>Device Firmware Programming S19 IntelHEX DFU DFUSE</PackageTags>
-    <AssemblyVersion>1.0.3</AssemblyVersion>
-    <FileVersion>1.0.3</FileVersion>
-    <PackageReleaseNotes>Change project to multitarget</PackageReleaseNotes>
+    <PackageReleaseNotes>Add DFU Upload methods</PackageReleaseNotes>
     <Company>IntergatedCircuits</Company>
-    <PackageLicenseFile>LICENSE</PackageLicenseFile>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <Version>1.1.0</Version>
+    <FileVersion>1.1.0</FileVersion>
+    <AssemblyVersion>1.1.0</AssemblyVersion>
+    <EnablePackageValidation>true</EnablePackageValidation>
+    <!-- <PackageValidationBaselineVersion>1.0.3</PackageValidationBaselineVersion> -->
+    <EnableNETAnalyzers>True</EnableNETAnalyzers>
   </PropertyGroup>
 
   <ItemGroup>
@@ -26,4 +29,11 @@
     </None>
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="README.md">
+      <Pack>True</Pack>
+      <PackagePath>\</PackagePath>
+    </None>
+  </ItemGroup>
+
 </Project>

Dfu/Device.cs

@@ -180,12 +180,6 @@ public byte[] Upload(ushort blockNumber, uint length)
             ControlTransfer(Request.Upload, blockNumber, ref block);
             return block;
         }
-        public void Upload(ushort blockNumber, ref byte[] data, int startIndex, int length)
-        {
-            byte[] block = new byte[length];
-            ControlTransfer(Request.Upload, blockNumber, ref block);
-            Array.Copy(block, 0, data, startIndex, length);
-        }
 
         public State GetState()
         {
@@ -450,6 +444,52 @@ private void VerifyState(Status status, State expectedState)
             }
         }
 
+        /// <summary>
+        /// Upload a block of firmware from the reconfigured DFU device.
+        /// </summary>
+        /// <param name="length">The (maximum) size of memory to upload from the device.</param>
+        /// <param name="blockNr">The starting block number of memory reading.</param>
+        /// <returns>The memory dump from the device</returns>
+        public byte[] UploadBlock(uint length, ushort blockNr = 0)
+        {
+            if (!DfuDescriptor.CanUpload)
+            {
+                throw new InvalidOperationException("The device doesn't support the upload operation.");
+            }
+            ResetToIdle();
+            byte[] block = new byte[length];
+            uint transferred = 0;
+            while (transferred < length)
+            {
+                uint transferLen;
+                if ((transferred + DfuDescriptor.TransferSize) > length)
+                {
+                    transferLen = length - transferred;
+                }
+                else
+                {
+                    transferLen = (uint)DfuDescriptor.TransferSize;
+                }
+
+                var b = Upload(blockNr, transferLen);
+                Array.Copy(b, 0, block, transferred, transferLen);
+                transferred += (uint)b.Length;
+                blockNr++;
+
+                if (b.Length < transferLen)
+                {
+                    Array.Resize(ref block, (int)transferred);
+                    break;
+                }
+            }
+            // if the last transfer was also TransferSize, add a 0 length transfer to terminate the upload
+            if (GetState() == State.UploadIdle)
+            {
+                Upload(blockNr, 0);
+            }
+            return block;
+        }
+
         /// <summary>
         /// Download a contiguous memory segment to the idling DFU device. (DFU spec 1.1)
         /// </summary>
@@ -571,6 +611,16 @@ private Status SeErase(uint address)
                  /(\d+)\*(\d+)([\x20KM]{1})([a-g]{1})(?:,(\d+)\*(\d+)([\x20KM]{1})([a-g]{1}))*$",
                 RegexOptions.Compiled | RegexOptions.IgnorePatternWhitespace);
 
+        /// <summary>
+        /// Parses the string description of a DFU alternate setting into a memory layout.
+        /// </summary>
+        /// <param name="altSel">DFU alternate setting index</param>
+        /// <returns>The parsed memory layout</returns>
+        private NamedLayout ParseLayout(byte altSel)
+        {
+            return ParseLayout(GetString(iAlternateSetting(altSel)));
+        }
+
         /// <summary>
         /// Parses the string description of a DFU alternate setting into a memory layout.
         /// </summary>
@@ -640,8 +690,7 @@ private void Download(Dictionary<byte, NamedMemory> sortedMemory)
                 byte altSel = memoryWithAltSel.Key;
                 var memory = memoryWithAltSel.Value;
 
-                string ml = GetString(iAlternateSetting(altSel));
-                var layout = ParseLayout(ml);
+                var layout = ParseLayout(altSel);
                 int segNo = 0;
                 int lastSeg = memory.Segments.Count - 1;
 
@@ -776,8 +825,7 @@ private Dictionary<byte, NamedMemory> SortMemoryByAltSetting(RawMemory memory)
                 // go through the available memories (each of which is an alternate setting)
                 for (altSel = 0; altSel < NumberOfAlternateSettings; altSel++)
                 {
-                    string ml = GetString(iAlternateSetting(altSel));
-                    var layout = ParseLayout(ml);
+                    var layout = ParseLayout(altSel);
                     int segCount = 0;
                     var newMem = new NamedMemory(layout.Name);
 
@@ -814,6 +862,56 @@ private Dictionary<byte, NamedMemory> SortMemoryByAltSetting(RawMemory memory)
 
             return sortedMemory;
         }
+
+        /// <summary>
+        /// Upload part of the firmware image from the reconfigured DFU device.
+        /// </summary>
+        /// <param name="mblock">Memory block to read from</param>
+        /// <returns>The memory segment provided by the device</returns>
+        public Segment UploadBlock(Block mblock)
+        {
+            // perform a bunch of tests first
+            if (DfuDescriptor.DfuVersion != Protocol.SeVersion)
+            {
+                throw new InvalidOperationException("The device doesn't support the DFUSE protocol.");
+            }
+
+            byte altSel = 0;
+            for (; altSel < NumberOfAlternateSettings; altSel++)
+            {
+                var layout = ParseLayout(altSel);
+                if ((mblock.StartAddress >= layout.StartAddress) && (mblock.EndAddress <= layout.EndAddress))
+                {
+                    foreach (var block in layout.Blocks)
+                    {
+                        if (block.Overlaps(mblock) && !block.Permissions.IsReadable())
+                        {
+                            throw new ArgumentOutOfRangeException("mblock", mblock, "The provided memory block is not readable on the target device.");
+                        }
+                    }
+                    break;
+                }
+            }
+            if (altSel == NumberOfAlternateSettings)
+            {
+                throw new ArgumentOutOfRangeException("mblock", mblock, "The provided memory block is not available on the target device.");
+            }
+
+            // select this memory layout for upload
+            AlternateSetting = altSel;
+
+            // select start address
+            ResetToIdle();
+
+            Status status = SeSetAddress((uint)mblock.StartAddress);
+            VerifyState(status, State.DnloadIdle);
+
+            // perform memory dump
+            // TODO: ensure block number doesn't overflow
+            byte[] memory = UploadBlock((uint)mblock.Size, 2);
+
+            return new Segment(mblock.StartAddress, memory);
+        }
         #endregion
     }
 }

Memory/Block.cs

@@ -5,13 +5,14 @@ namespace DeviceProgramming.Memory
     /// <summary>
     /// This class represents a memory unit that can be read/written/erased (depending on permissions) as a whole.
     /// </summary>
-    public struct Block : IEquatable<Block>, IComparable<Block>
+    public readonly struct Block : IEquatable<Block>, IComparable<Block>
     {
         public readonly UInt64 StartAddress;
         public readonly UInt64 Size;
         public readonly Memory.Permissions Permissions;
+        public UInt64 EndAddress { get { return StartAddress + Size - 1; } }
 
-        public Block(ulong startAddress, ulong size, Memory.Permissions permissions)
+        public Block(ulong startAddress, ulong size, Memory.Permissions permissions = Permissions.Inaccessible)
         {
             StartAddress = startAddress;
             Size = size;

Memory/Layout.cs

@@ -8,9 +8,9 @@ namespace DeviceProgramming.Memory
     /// </summary>
     public class Layout
     {
-        public UInt64 StartAddress 
-        { 
-            get 
+        public UInt64 StartAddress
+        {
+            get
             {
                 if (Blocks.Count == 0)
                 {