Merge pull request #23 from plaes/teleprobe-link-ram-docs

Add section about modifying binaries (teleprobe-meta, link_ram)

README.md

@@ -6,7 +6,7 @@ Run MCU binaries on remote targets.
 Teleprobe has three operation modes - local, server and client.
 
 ### Local Mode
-Local mode is intended to be run on the machine where the remote MCU is connected, usually for debugging purposes.
+Local mode is intended to be run on the machine where the MCU is connected, usually for debugging purposes.
 
 List available probes:
 ```
@@ -64,6 +64,41 @@ teleprobe client --host 'http://SERVER_ADDRESS:8080' --token ACCESS_TOKEN run --
 
 The `ACCESS_TOKEN` and host can be also stored into `TELEPROBE_TOKEN` and `TELEPROBE_HOST` environment variables.
 
+## Preparing MCU binaries
+
+### Automatic target discovery
+
+Using teleprobe-meta crate, it's possible to embed various metadata into target binary,
+including target name and timeout. This allows running binaries just by calling `run <ELF>`
+without additional flags.
+
+### Running from RAM
+
+Before uploading binary to target, teleprobe analyzes it to see whether it's possible
+to run it from RAM instead of uploading it to MCU's internal flash and running from there.
+
+In order to achieve that, target binary needs to be linked with a modified linker script
+which puts data into RAM instead of FLASH.
+
+* Cortex-M: [`link_ram_cortex_m.x`](link_ram_cortex_m.x)
+
+Then include the renamed `link_ram.x` linker script  via `build.rs`:
+
+```rust
+fn main() -> Result<(), Box<dyn Error>> {
+    let out = PathBuf::from(env::var("OUT_DIR").unwrap());
+    fs::write(out.join("link_ram.x"), include_bytes!("link_ram.x")).unwrap();
+    println!("cargo:rustc-link-search={}", out.display());
+
+    println!("cargo:rerun-if-changed=link_ram.x");
+    println!("cargo:rustc-link-arg-bins=-Tlink_ram.x");
+
+    // ...
+
+    Ok(())
+}
+```
+
 ## License
 
 This work is licensed under either of

link_ram_cortex_m.x

@@ -0,0 +1,280 @@
+/* ##### EMBASSY NOTE
+    Originally from https://github.com/rust-embedded/cortex-m/blob/master/cortex-m-rt/link.x.in
+    Adjusted to put everything in RAM
+*/
+
+/* # Developer notes
+
+- Symbols that start with a double underscore (__) are considered "private"
+
+- Symbols that start with a single underscore (_) are considered "semi-public"; they can be
+  overridden in a user linker script, but should not be referred from user code (e.g. `extern "C" {
+  static mut __sbss }`).
+
+- `EXTERN` forces the linker to keep a symbol in the final binary. We use this to make sure a
+  symbol if not dropped if it appears in or near the front of the linker arguments and "it's not
+  needed" by any of the preceding objects (linker arguments)
+
+- `PROVIDE` is used to provide default values that can be overridden by a user linker script
+
+- On alignment: it's important for correctness that the VMA boundaries of both .bss and .data *and*
+  the LMA of .data are all 4-byte aligned. These alignments are assumed by the RAM initialization
+  routine. There's also a second benefit: 4-byte aligned boundaries means that you won't see
+  "Address (..) is out of bounds" in the disassembly produced by `objdump`.
+*/
+
+/* Provides information about the memory layout of the device */
+/* This will be provided by the user (see `memory.x`) or by a Board Support Crate */
+INCLUDE memory.x
+
+/* # Entry point = reset vector */
+EXTERN(__RESET_VECTOR);
+EXTERN(Reset);
+ENTRY(Reset);
+
+/* # Exception vectors */
+/* This is effectively weak aliasing at the linker level */
+/* The user can override any of these aliases by defining the corresponding symbol themselves (cf.
+   the `exception!` macro) */
+EXTERN(__EXCEPTIONS); /* depends on all the these PROVIDED symbols */
+
+EXTERN(DefaultHandler);
+
+PROVIDE(NonMaskableInt = DefaultHandler);
+EXTERN(HardFaultTrampoline);
+PROVIDE(MemoryManagement = DefaultHandler);
+PROVIDE(BusFault = DefaultHandler);
+PROVIDE(UsageFault = DefaultHandler);
+PROVIDE(SecureFault = DefaultHandler);
+PROVIDE(SVCall = DefaultHandler);
+PROVIDE(DebugMonitor = DefaultHandler);
+PROVIDE(PendSV = DefaultHandler);
+PROVIDE(SysTick = DefaultHandler);
+
+PROVIDE(DefaultHandler = DefaultHandler_);
+PROVIDE(HardFault = HardFault_);
+
+/* # Interrupt vectors */
+EXTERN(__INTERRUPTS); /* `static` variable similar to `__EXCEPTIONS` */
+
+/* # Pre-initialization function */
+/* If the user overrides this using the `pre_init!` macro or by creating a `__pre_init` function,
+   then the function this points to will be called before the RAM is initialized. */
+PROVIDE(__pre_init = DefaultPreInit);
+
+/* # Sections */
+SECTIONS
+{
+  PROVIDE(_ram_start = ORIGIN(RAM));
+  PROVIDE(_ram_end = ORIGIN(RAM) + LENGTH(RAM));
+  PROVIDE(_stack_start = _ram_end);
+
+  /* ## Sections in RAM */
+  /* ### Vector table */
+  .vector_table ORIGIN(RAM) :
+  {
+    __vector_table = .;
+
+    /* Initial Stack Pointer (SP) value.
+     * We mask the bottom three bits to force 8-byte alignment.
+     * Despite having an assert for this later, it's possible that a separate
+     * linker script could override _stack_start after the assert is checked.
+     */
+    LONG(_stack_start & 0xFFFFFFF8);
+
+    /* Reset vector */
+    KEEP(*(.vector_table.reset_vector)); /* this is the `__RESET_VECTOR` symbol */
+
+    /* Exceptions */
+    __exceptions = .; /* start of exceptions */
+    KEEP(*(.vector_table.exceptions)); /* this is the `__EXCEPTIONS` symbol */
+    __eexceptions = .; /* end of exceptions */
+
+    /* Device specific interrupts */
+    KEEP(*(.vector_table.interrupts)); /* this is the `__INTERRUPTS` symbol */
+  } > RAM
+
+  PROVIDE(_stext = ADDR(.vector_table) + SIZEOF(.vector_table));
+
+  /* ### .text */
+  .text _stext :
+  {
+    __stext = .;
+    *(.Reset);
+
+    *(.text .text.*);
+
+    /* The HardFaultTrampoline uses the `b` instruction to enter `HardFault`,
+       so must be placed close to it. */
+    *(.HardFaultTrampoline);
+    *(.HardFault.*);
+
+    . = ALIGN(4); /* Pad .text to the alignment to workaround overlapping load section bug in old lld */
+    __etext = .;
+  } > RAM
+
+  /* ### .rodata */
+  .rodata : ALIGN(4)
+  {
+    . = ALIGN(4);
+    __srodata = .;
+    *(.rodata .rodata.*);
+
+    /* 4-byte align the end (VMA) of this section.
+       This is required by LLD to ensure the LMA of the following .data
+       section will have the correct alignment. */
+    . = ALIGN(4);
+    __erodata = .;
+  } > RAM
+
+  /* ## Sections in RAM */
+  /* ### .data */
+  .data : ALIGN(4)
+  {
+    . = ALIGN(4);
+    __sdata = .;
+    __edata = .; /* RAM: By setting __sdata=__edata cortex-m-rt has to copy 0 bytes as .data is already in RAM */
+
+    *(.data .data.*);
+    . = ALIGN(4); /* 4-byte align the end (VMA) of this section */
+  } > RAM
+  /* Allow sections from user `memory.x` injected using `INSERT AFTER .data` to
+   * use the .data loading mechanism by pushing __edata. Note: do not change
+   * output region or load region in those user sections! */
+  /* Link from RAM: Disabled, now __sdata == __edata
+  . = ALIGN(4);
+  __edata = .;
+  */
+
+  /* LMA of .data */
+  __sidata = LOADADDR(.data);
+
+  /* ### .gnu.sgstubs
+     This section contains the TrustZone-M veneers put there by the Arm GNU linker. */
+  /* Security Attribution Unit blocks must be 32 bytes aligned. */
+  /* Note that this pads the RAM usage to 32 byte alignment. */
+  .gnu.sgstubs : ALIGN(32)
+  {
+    . = ALIGN(32);
+    __veneer_base = .;
+    *(.gnu.sgstubs*)
+    . = ALIGN(32);
+  } > RAM
+  /* Place `__veneer_limit` outside the `.gnu.sgstubs` section because veneers are
+   * always inserted last in the section, which would otherwise be _after_ the `__veneer_limit` symbol.
+   */
+  . = ALIGN(32);
+  __veneer_limit = .;
+
+  /* ### .bss */
+  .bss (NOLOAD) : ALIGN(4)
+  {
+    . = ALIGN(4);
+    __sbss = .;
+    *(.bss .bss.*);
+    *(COMMON); /* Uninitialized C statics */
+    . = ALIGN(4); /* 4-byte align the end (VMA) of this section */
+  } > RAM
+  /* Allow sections from user `memory.x` injected using `INSERT AFTER .bss` to
+   * use the .bss zeroing mechanism by pushing __ebss. Note: do not change
+   * output region or load region in those user sections! */
+  . = ALIGN(4);
+  __ebss = .;
+
+  /* ### .uninit */
+  .uninit (NOLOAD) : ALIGN(4)
+  {
+    . = ALIGN(4);
+    __suninit = .;
+    *(.uninit .uninit.*);
+    . = ALIGN(4);
+    __euninit = .;
+  } > RAM
+
+  /* Place the heap right after `.uninit` in RAM */
+  PROVIDE(__sheap = __euninit);
+
+  /* ## .got */
+  /* Dynamic relocations are unsupported. This section is only used to detect relocatable code in
+     the input files and raise an error if relocatable code is found */
+  .got (NOLOAD) :
+  {
+    KEEP(*(.got .got.*));
+  }
+
+  /* ## Discarded sections */
+  /DISCARD/ :
+  {
+    /* Unused exception related info that only wastes space */
+    *(.ARM.exidx);
+    *(.ARM.exidx.*);
+    *(.ARM.extab.*);
+  }
+}
+
+/* Do not exceed this mark in the error messages below                                    | */
+/* # Alignment checks */
+ASSERT(ORIGIN(RAM) % 4 == 0, "
+ERROR(cortex-m-rt): the start of the RAM region must be 4-byte aligned");
+
+ASSERT(__sdata % 4 == 0 && __edata % 4 == 0, "
+BUG(cortex-m-rt): .data is not 4-byte aligned");
+
+ASSERT(__sidata % 4 == 0, "
+BUG(cortex-m-rt): the LMA of .data is not 4-byte aligned");
+
+ASSERT(__sbss % 4 == 0 && __ebss % 4 == 0, "
+BUG(cortex-m-rt): .bss is not 4-byte aligned");
+
+ASSERT(__sheap % 4 == 0, "
+BUG(cortex-m-rt): start of .heap is not 4-byte aligned");
+
+ASSERT(_stack_start % 8 == 0, "
+ERROR(cortex-m-rt): stack start address is not 8-byte aligned.
+If you have set _stack_start, check it's set to an address which is a multiple of 8 bytes.
+If you haven't, stack starts at the end of RAM by default. Check that both RAM
+origin and length are set to multiples of 8 in the `memory.x` file.");
+
+/* # Position checks */
+
+/* ## .vector_table
+ *
+ * If the *start* of exception vectors is not 8 bytes past the start of the
+ * vector table, then we somehow did not place the reset vector, which should
+ * live 4 bytes past the start of the vector table.
+ */
+ASSERT(__exceptions == ADDR(.vector_table) + 0x8, "
+BUG(cortex-m-rt): the reset vector is missing");
+
+ASSERT(__eexceptions == ADDR(.vector_table) + 0x40, "
+BUG(cortex-m-rt): the exception vectors are missing");
+
+ASSERT(SIZEOF(.vector_table) > 0x40, "
+ERROR(cortex-m-rt): The interrupt vectors are missing.
+Possible solutions, from most likely to less likely:
+- Link to a svd2rust generated device crate
+- Check that you actually use the device/hal/bsp crate in your code
+- Disable the 'device' feature of cortex-m-rt to build a generic application (a dependency
+may be enabling it)
+- Supply the interrupt handlers yourself. Check the documentation for details.");
+
+/* ## .text */
+ASSERT(ADDR(.vector_table) + SIZEOF(.vector_table) <= _stext, "
+ERROR(cortex-m-rt): The .text section can't be placed inside the .vector_table section
+Set _stext to an address greater than the end of .vector_table (See output of `nm`)");
+
+ASSERT(_stext + SIZEOF(.text) < ORIGIN(RAM) + LENGTH(RAM), "
+ERROR(cortex-m-rt): The .text section must be placed inside the RAM memory.
+Set _stext to an address smaller than 'ORIGIN(RAM) + LENGTH(RAM)'");
+
+/* # Other checks */
+ASSERT(SIZEOF(.got) == 0, "
+ERROR(cortex-m-rt): .got section detected in the input object files
+Dynamic relocations are not supported. If you are linking to C code compiled using
+the 'cc' crate then modify your build script to compile the C code _without_
+the -fPIC flag. See the documentation of the `cc::Build.pic` method for details.");
+/* Do not exceed this mark in the error messages above                                    | */
+
+/* Provides weak aliases (cf. PROVIDED) for device specific interrupt handlers */
+/* This will usually be provided by a device crate generated using svd2rust (see `device.x`) */
+INCLUDE device.x