target_flash: add note to flash mass erase api method

This is a very important restriction to ensure the method is safe to use during normal load operations

src/target/target_flash.c

@@ -157,7 +157,7 @@ bool target_flash_erase(target_s *target, target_addr_t addr, size_t len)
 		/* Align the start address to the erase block size */
 		const target_addr_t local_start_addr = addr & ~(flash->blocksize - 1U);
 
-		/* Check if we can use mass erase */
+		/* Check if we can use mass erase, i.e. if the erase range covers the entire flash address space */
 		const bool can_use_mass_erase = flash->mass_erase != NULL && local_start_addr == flash->start &&
 			(addr + len) >= (flash->start + flash->length);
 

src/target/target_internal.h

@@ -69,7 +69,7 @@ struct target_flash {
 	uint8_t operation;                /* Current Flash operation (none means it's idle/unprepared) */
 	flash_prepare_func prepare;       /* Prepare for flash operations */
 	flash_erase_func erase;           /* Erase a range of flash */
-	flash_mass_erase_func mass_erase; /* Mass erase flash (this flash only) */
+	flash_mass_erase_func mass_erase; /* Mass erase flash (this flash only¹) */
 	flash_write_func write;           /* Write to flash */
 	flash_done_func done;             /* Finish flash operations */
 	uint8_t *buf;                     /* Buffer for flash operations */
@@ -79,6 +79,11 @@ struct target_flash {
 	target_flash_s *next;             /* Next flash in list */
 };
 
+/*
+ * ¹the mass_erase method must not cause any side effects outside the scope/address space of the flash 
+ * consider using the target mass_erase method instead for such cases
+ */
+
 typedef bool (*cmd_handler_fn)(target_s *target, int argc, const char **argv);
 
 typedef struct command {