From 78fda7727a351788b42625c7c964a2287ba7ecfa Mon Sep 17 00:00:00 2001
From: Martin Preuss <martin@aquamaniac.de>
Date: Mon, 24 Mar 2025 00:18:50 +0100
Subject: [PATCH] avr: added some comments.

---
 avr/modules/flash/flash1p.asm | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/avr/modules/flash/flash1p.asm b/avr/modules/flash/flash1p.asm
index 128222f..05fcf48 100644
--- a/avr/modules/flash/flash1p.asm
+++ b/avr/modules/flash/flash1p.asm
@@ -97,10 +97,14 @@ Flash_WriteData_done:
 ; @clobbers R16, R18, R24, R25, X (R0, R1, R19, R20)
 
 flashWriteData:
+  rcall flashCheckCurrentValid         ; (r18, r19)
+  brcc flashWriteData_beginPage
+
   rcall flashWriteCheckPage            ; (r18, r19)
-  brcs flashWriteData_calcPosAndLength
+  brcs flashWriteData_calcPosAndLength ; still inside current page, jump
   rcall flash1pEndPage                 ; (R0, R1, R16, R18, R19, R20, R24, R25, X)
-  rcall flash1pBeginPage               ; (r16, r24, r25, X, Z)
+flashWriteData_beginPage:
+  rcall flash1pBeginPage               ; (r16, r24, r25, X)
 flashWriteData_calcPosAndLength:
   rcall flashCalcPosAndLength          ; (r24, r25)
   ; X=abs pos in buffer, r18=bytes to read, r17=bytes initially requested
@@ -131,15 +135,15 @@ flashWriteData_copyLoop:
 flashCalcPosAndLength:
   ; calc offset into buffer
   mov r24, zl
-  andi r24, (FLASH_PAGESIZE-1) ; r24=rel pos inside buffer
+  andi r24, (FLASH_PAGESIZE-1)   ; r24=rel pos inside buffer
   ldi r25, FLASH_PAGESIZE
-  sub r25, r24                 ; r25=bytes left inside page
+  sub r25, r24                   ; r25=bytes left inside page
   mov r18, r17
-  cp r25, r17
-  brcc flashCalcPosAndLength_l1
-  mov r18, r25
+  cp r25, r17                    ; bytes to read > bytes left in page?
+  brcc flashCalcPosAndLength_l1  ; no: jump
+  mov r18, r25                   ; yes: cut r18 to number of bytes left in page
 flashCalcPosAndLength_l1:
-  ldi xl, LOW(flashPageBuffer)
+  ldi xl, LOW(flashPageBuffer)   ; set X to pos within page buffer
   ldi xh, HIGH(flashPageBuffer)
   add xl, r24
   adc xh, r24
@@ -155,6 +159,7 @@ flashCalcPosAndLength_l1:
 ; check whether the given address is inside the current page in buffer
 ;
 ; @return CFLAG set if same page, cleared otherwise
+; @param Z address to write to
 ; @clobbers r18, r19
 
 flashWriteCheckPage: