Tidying

src/DebugToolDrivers/WCH/WchLinkDebugInterface.cpp

@@ -54,9 +54,9 @@ namespace DebugToolDrivers::Wch
                 this->targetDescriptionFile.getProperty("wch_link_interface", "programming_opcode_key").value
             )
         )
-        , programmingPacketSize(
+        , programmingBlockSize(
             Services::StringService::toUint32(
-                this->targetDescriptionFile.getProperty("wch_link_interface", "programming_packet_size").value
+                this->targetDescriptionFile.getProperty("wch_link_interface", "programming_block_size").value
             )
         )
     {}
@@ -202,9 +202,16 @@ namespace DebugToolDrivers::Wch
         Targets::TargetMemoryBufferSpan buffer
     ) {
         if (memorySegmentDescriptor.type == TargetMemorySegmentType::FLASH) {
+            /*
+             * WCH-Link tools cannot write to flash memory via the target's debug module.
+             *
+             * They do, however, offer a set of dedicated commands for writing to flash memory. We invoke them here.
+             *
+             * See WchLinkDebugInterface::writeFlashMemory() below, for more.
+             */
             const auto bufferSize = static_cast<TargetMemorySize>(buffer.size());
-            const auto alignmentSize = bufferSize > WchLinkDebugInterface::MAX_PARTIAL_PAGE_WRITE_SIZE
-                ? this->programmingPacketSize
+            const auto alignmentSize = bufferSize > WchLinkDebugInterface::MAX_PARTIAL_BLOCK_WRITE_SIZE
+                ? this->programmingBlockSize
                 : 1;
 
             if (alignmentSize > 1) {
@@ -272,14 +279,29 @@ namespace DebugToolDrivers::Wch
     }
 
     void WchLinkDebugInterface::writeFlashMemory(TargetMemoryAddress startAddress, TargetMemoryBufferSpan buffer) {
-        if (buffer.size() <= WchLinkDebugInterface::MAX_PARTIAL_PAGE_WRITE_SIZE) {
-            return this->wchLinkInterface.writePartialPage(startAddress, buffer);
+        /*
+         * There are two commands we can choose from when writing to flash memory:
+         *
+         * - Partial block write
+         *     Writes any number of bytes to flash, but limited to a maximum of 64 bytes per write. Larger writes
+         *     must be split into multiple writes.
+         * - Full block write
+         *     Writes an entire block to flash. Where the block size is target-specific (resides in the target's
+         *     TDF). Requires alignment to the block size. Requires reattaching to the target at the end of the
+         *     programming session.
+         *
+         * The full block write is much faster for writing large buffers (KiBs), such as when we're programming the
+         * target. But the partial block write is faster and more suitable for writing buffers that are smaller than
+         * 64 bytes, such as when we're inserting software breakpoints.
+         */
+        if (buffer.size() <= WchLinkDebugInterface::MAX_PARTIAL_BLOCK_WRITE_SIZE) {
+            return this->wchLinkInterface.writeFlashPartialBlock(startAddress, buffer);
         }
 
-        this->wchLinkInterface.writeFullPage(
+        this->wchLinkInterface.writeFlashFullBlocks(
             startAddress,
             buffer,
-            this->programmingPacketSize,
+            this->programmingBlockSize,
             this->flashProgramOpcodes
         );