From 077335ff03e0331592aeb829097c6db920c769cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?King=20K=C3=A9vin?= <kingkevin@cuvoodoo.info>
Date: Fri, 10 Jan 2020 12:02:11 +0100
Subject: [PATCH] ld: improve documentation

---
 application.ld | 12 +++++++-----
 bootloader.ld  | 12 +++++++-----
 2 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/application.ld b/application.ld
index 6fcd7bf..c02ddd0 100644
--- a/application.ld
+++ b/application.ld
@@ -1,5 +1,8 @@
 /* linker script for application running on STM32F103x8 micro-controller
+ * the STM32F103x8 has 64 KB of flash starting at 0x0800 0000, and 20 KB of RAM starting at 0x2000 0000
  * the STM32F103xB has 128 KB of flash starting at 0x0800 0000, and 20 KB of RAM starting at 0x2000 0000
+ * STM32F103x8 most often have if fact 128 KB, instead of the specified and advertised 64 KB, like the STM32F103xB
+ * you can define the desired flash size here.
  * the USB DFU bootloader will take the first 8 KB of flash, followed by the application
  * the first 4 bytes of the RAM is reserved for the DFU magic word (DFU! to start DFU bootloader)
  */
@@ -11,13 +14,12 @@ MEMORY
 	ram (rwx) : ORIGIN = 0x20000000 + 4, LENGTH = 20K - 4
 }
 PROVIDE(__application_beginning = ORIGIN(rom));
-/* only provide application_end and/or flash_end if you want to force a flash size
-   i.e. STM32F103x8 most often have if fact 128 KB instead of the specified and advertised 64 KB
-PROVIDE(__application_end = ORIGIN(rom) + LENGTH(rom));
-PROVIDE(__flash_end = ORIGIN(rom) + LENGTH(rom));
-   else
+/* if you want the firmware to use the flash size advertised by the micro-controller itself, use the following:
 PROVIDE(__application_end = 0);
 PROVIDE(__flash_end = 0);
+   if you want to enforce a flash size, because there is more flash than advertized by the micro-controller, use to following:
+PROVIDE(__application_end = ORIGIN(rom) + LENGTH(rom));
+PROVIDE(__flash_end = ORIGIN(rom) + LENGTH(rom));
 */
 PROVIDE(__application_end = 0);
 PROVIDE(__flash_end = 0);
diff --git a/bootloader.ld b/bootloader.ld
index a70d0a9..9dbc05d 100644
--- a/bootloader.ld
+++ b/bootloader.ld
@@ -1,5 +1,8 @@
 /* linker script for application running on STM32F103x8 micro-controller
+ * the STM32F103x8 has 64 KB of flash starting at 0x0800 0000, and 20 KB of RAM starting at 0x2000 0000
  * the STM32F103xB has 128 KB of flash starting at 0x0800 0000, and 20 KB of RAM starting at 0x2000 0000
+ * STM32F103x8 most often have if fact 128 KB, instead of the specified and advertised 64 KB, like the STM32F103xB
+ * you can define the desired flash size here.
  * the USB DFU bootloader will take the first 8 KB of flash, followed by the application
  * the first 4 bytes of the RAM is reserved for the DFU magic word (DFU! to start DFU bootloader)
  */
@@ -11,13 +14,12 @@ MEMORY
 	ram (rwx) : ORIGIN = 0x20000000 + 4, LENGTH = 20K - 4
 }
 PROVIDE(__application_beginning = ORIGIN(rom) + LENGTH(rom));
-/* only provide application_end and/or flash_end if you want to force a flash size
-   i.e. STM32F103x8 most often have if fact 128 KB instead of the specified and advertised 64 KB
-PROVIDE(__application_end = __application_beginning + 128K - 8K);
-PROVIDE(__flash_end = __application_beginning + 128K - 8K);
-   else
+/* if you want the firmware to use the flash size advertised by the micro-controller itself, use the following:
 PROVIDE(__application_end = 0);
 PROVIDE(__flash_end = 0);
+   if you want to enforce a flash size, because there is more flash than advertized by the micro-controller, use to following:
+PROVIDE(__application_end = ORIGIN(rom) + LENGTH(rom));
+PROVIDE(__flash_end = ORIGIN(rom) + LENGTH(rom));
 */
 PROVIDE(__application_end = 0);
 PROVIDE(__flash_end = 0);