firmware: some documentation about memory maps and linkage

3 files changed, 66 insertions, 0 deletions

diff --git a/src/target/firmware/board/compal/LINKAGE.txt b/src/target/firmware/board/compal/LINKAGE.txt
new file mode 100644
index 00000000..1ae06fb3
--- /dev/null
+++ b/src/target/firmware/board/compal/LINKAGE.txt
@@ -0,0 +1,12 @@
+
+We provide the following common RAM linkages for all Compal phones:
+
+(both use the Calypso ROM loader for interrupt redirect, if required)
+
+  compalram:
+    Image for the Compal ramloader. Starts at a weird address and
+    contains various ramloader specifics.
+
+  highram:
+    Image linked to 0x820000, used for various special purposes.
+    This image is completely independent of the compal loader.
diff --git a/src/target/firmware/board/compal_e88/LINKAGE.txt b/src/target/firmware/board/compal_e88/LINKAGE.txt
new file mode 100644
index 00000000..8adaf86e
--- /dev/null
+++ b/src/target/firmware/board/compal_e88/LINKAGE.txt
@@ -0,0 +1,33 @@
+
+The Compal E88 supports the common Compal RAM linkages.
+These operate entirely from the Calypso internal RAM.
+
+Flash linkages are structured as follows:
+
+  e88loader:
+    Linked at address of original compal application (0x2000).
+    Provides interrupt vectors as expected by compal loader.
+    Allows interrupt redirection (XXX to where?).
+    
+    We introduce this for the following reasons:
+    1. We want to start our app at 0x10000, because that
+       is the first flash page after the loader page, allowing
+       us a higher degree of "unbrickability" by never reflashing
+       the bootloader.
+    2. We want to keep the compal loader so we do not need even
+       more boot options and to allow recovery of original firmware.
+    3. When there is a custom app in flash at 0xFFFF, just turning
+       the phone on with the compal loader would jump into an incomplete
+       motorola app. That might not even allow turning the phone off.
+       The loader provides this functionality.
+    4. We do not want to patch the compal loader for interrupt
+       redirect and entry vectors. So we need to place something between
+       0x2000 and 0x10000 anyway. And since there is space, why not put
+       the whole loader in there.
+    5. This loader has a good chance of being able to read crash buffers.
+       and examining RAM without it being clobbered by a ram upload.
+
+  e88flash:
+    Our main application linkage, starting at 0x10000 and going through
+    all of flash. Data storage locations are still to be determined.
+
diff --git a/src/target/firmware/board/compal_e88/MEMORY_MAP.txt b/src/target/firmware/board/compal_e88/MEMORY_MAP.txt
new file mode 100644
index 00000000..6094aa9b
--- /dev/null
+++ b/src/target/firmware/board/compal_e88/MEMORY_MAP.txt
@@ -0,0 +1,21 @@
+The Compal E88 has the following physical memory map:
+
+    /* 2 MBytes of external flash memory */
+    FLASH (rx) : ORIGIN = 0x00000000, LENGTH = 0x200000
+    /* 256 kBytes of internal zero-waitstate sram */
+    IRAM  (rw) : ORIGIN = 0x00800000, LENGTH = 0x040000
+    /* 256 kBytes of external slow sram */
+    ERAM  (rw) : ORIGIN = 0x01000000, LENGTH = 0x040000
+
+The flash layout, as distributed, is:
+
+    0x00000000 0x2000 Compal loader
+    0x00002000 >>>>>> Compal application and storage
+
+Our flash layout is:
+
+    0x00000000 0x2000 Compal loader
+    0x00002000 0xE000 OSMOCOM loader (see LINKAGE.txt for reasoning)
+    0x00010000 >>>>>> OSMOCOM application and storage
+
+(XXX: determine storage location / storage descriptor location)