Comment and explain the linker script and the way the relocation works

Author: kubamracek

stm32-lvgl/README.md

@@ -44,3 +44,7 @@ Optionally, you can also run build and run the code in a desktop OS SDL "simulat
 ```console
 $ make simulator
 ```
+
+## Additional information
+
+- The ELF linking, linker script and packaging scheme is destribed in detail [inside the linker script](Sources/Support/linkerscript.ld).

stm32-lvgl/Sources/Support/Startup.c

@@ -18,6 +18,8 @@ void enable_fpu(void) {
 
 // Reset entrypoint. Enables FPU, relocates the data sections from FLASH to DRAM
 // and jumps to main (implemented in Application/Main.swift).
+//
+// See linkerscript.ld for a detailed explanation.
 __attribute__((naked)) __attribute__((noreturn)) void ResetISR(void) {
   asm volatile("bl    enable_fpu");
   asm volatile("ldr   r0, =__data_start // dst");

stm32-lvgl/Sources/Support/linkerscript.ld

@@ -1,3 +1,62 @@
+/*===----------------------------------------------------------------------===*/
+/*                                                                            */
+/* This source file is part of the Swift open source project                  */
+/*                                                                            */
+/* Copyright (c) 2025 Apple Inc. and the Swift project authors.               */
+/* Licensed under Apache License v2.0 with Runtime Library Exception          */
+/*                                                                            */
+/* See https://swift.org/LICENSE.txt for license information                  */
+/*                                                                            */
+/*===----------------------------------------------------------------------===*/
+
+/*
+ * This application uses ELF for linking, and uses the elf2hex.py post-processing tool for package the result into a
+ * form suitable for flashing. The entire memory layout scheme (which this linker script participates in) is:
+ *
+ * - At normal application runtime, the expected memory layout is:
+ *
+ *     - 0x08000000-0x08100000 (flash) ... code + read-only globals
+ *     - 0x20000000-0x20008000 (SRAM) ... stack
+ *     - 0x20008000-0x20030000 (SRAM) ... read-write globals, and bss (zero initialized globals)
+ *     - 0x20030000-0x20050000 (SRAM) ... heap
+ *
+ * - However, this layout cannot be flashed as is (because it uses the SRAM too), so a few more steps are needed.
+ *
+ * - In a linked ELF file, the memory locations of the sections match the expected runtime layout. The ELF file does not
+ *   contain the stack and the heap, so we don't have to worry about those (there is also no expectation that the memory
+ *   for those is zeroed out at program start).
+ *
+ * - The ELF file is given to the elf2hex.py tool, which will produce a .hex output, and we use the
+ *   --relocate-data-segment flag to relocate the read-write globals region (0x20008000-0x20030000) into the flash
+ *   region, concretely the region is appended at a 4-byte-aligned location after the other contents of the flash.
+ *
+ *     - This is concretely achieved using the __flash_data_start+__flash_data_len and __data_start+__data_end symbols
+ *       defined in this linker script. The elf2hex.py script finds the addresses of these symbols and performs the
+ *       relocation of those bytes.
+ *     - Note that after the relocation, the segments in ELF headers (PT_LOAD commands) don't match the actual physical
+ *       layout. However, this relocation is reversed at early startup time, so that at "normal" runtime, the layout is
+ *       as expected. See below.
+ *
+ * - The ARM core loads the initial stack pointer, and initial program counter from the vector table which is placed at
+ *   a well-known location, concretely the very beginning of flash, 0x08000000. The linker script places the .vectors
+ *   section as the very first section into the flash to satisfy this. See Startup.c for the concrete content of the
+ *   vector table, and how the initial SP and PC are set up.
+ *
+ * - The initial startup code (ResetISR in Startup.c) only does one setup step (enabling the FPU) before performing the
+ *   reverse relocation of the data segment. The runtime back-relocation is simply a memcpy from __flash_data_start back
+ *   into __data_start (in the SRAM region).
+ *
+ *     - During this and before this (e.g. when doing the FPU enablement), read-write globals cannot be used. Reading
+ *       a read-write global won't read the correct initial value of that global.
+ *     - That's why the ResetISR code is written as attribute((naked)) asm implementation. The implementation is also
+ *       very simple and it's easy to see that it indeed does not touch any globals.
+ *     - We expect that the implementation of memcpy is also not accessing any globals. This is a reasonable expectation
+ *       on any embedded-friendly memcpy implementation.
+ *
+ * - After that, the normal runtime memory layout is matched, and the application continues to initialize itself and
+ *   run.
+ */
+
 MEMORY
 {
    flash (rx)      : ORIGIN = 0x08000000, LENGTH = 1024K  /* end: 0x08100000 */