Merge #321

321: Update 9160 HAL with latest memory map. r=jonas-schievink a=jonathanpallant

Also adds a README to explain why we need SPM.

Co-authored-by: Jonathan Pallant (42 Technology) <[email protected]>
Co-authored-by: Jonas Schievink <[email protected]>

Author: 3 people

nrf9160-hal/README.md

@@ -0,0 +1,78 @@
+# Hardware Abstration Layer for the Nordic nRF9160
+
+This crate is a Hardware Abstraction Layer (HAL) for the Nordic nRF9160. It
+wraps the PAC (`nrf9160-pac`) and provides high level wrappers for the chip's
+peripherals.
+
+This crate knows nothing about your PCB layout, or which pins you have assigned
+to which functions. The only exception are the examples, which are written to
+run on the official nRF9160-DK developer kit.
+
+## Usage
+
+You will require the `thumbv8m.main-none-eabihf` target installed.
+
+```console
+$ rustup target add thumbv8m.main-none-eabihf
+```
+
+## Secure vs Non-Secure
+
+This HAL is designed to run in non-secure mode, as should most of your
+application code. You will therefore need a 'bootloader' which starts in secure
+mode, moves the required peripherals into 'non-secure' world, and then jumps to
+your application.
+
+We have succesfully used Nordic's [Secure Partition Manager](https://github.com/nrfconnect/sdk-nrf/tree/v1.5.1/samples/spm)
+from nRF SDK v1.5.1. SPM v1.5.1 is configured to expect your application at address
+`0x0005_0000` and so that is what `memory.x` must specify as the start of Flash.
+
+_Note:_ Other versions of SPM might expect a different start address -
+especially those compiled as a child image of another application (like
+`at_sample`)! You can see the start address on boot-up:
+
+```
+SPM: NS image at 0x50000
+```
+
+This tells you SPM is looking for a non-secure (NS) image at `0x0005_0000`.
+
+To build SPM, run:
+
+```console
+$ west init -m https://github.com/nrfconnect/sdk-nrf --mr v1.5.1 ncs
+$ cd ncs
+$ west update # This takes *ages*
+$ cd nrf/examples/spm
+$ west build --board=nrf9160dk_nrf9160
+$ west flash
+```
+
+West is a Python tool supplied by Nordic for building the nRF Connect SDK. See
+[Nordic's website](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/1.5.1/nrf/gs_installing.html)
+for more details.
+
+Your nRF9160-DK will now have SPM installed between `0x0000_0000` and
+`0x0004_FFFF`. Flashing your application at `0x0005_0000` should not affect SPM,
+provided you do not select *erase entire chip* or somesuch!
+
+If you want to change the flash address, supply your own `memory.x` file in your
+application crate (or your Board Support Crate) and write a `build.rs` file that
+copies your `memory.x` over the top of this one.
+
+## Licence
+
+Licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the Apache-2.0
+license, shall be dual licensed as above, without any additional terms or
+conditions.

nrf9160-hal/memory.x

@@ -1,28 +1,43 @@
-/* Linker script for the nRF9160 in Non-secure mode */
+/* Linker script for the nRF9160 in Non-secure mode. It assumes you have the
+Nordic Secure Partition Manager installed at the bottom of flash and that
+the SPM is set to boot a non-secure application from the FLASH origin below. */
+
 MEMORY
 {
-  /* SECURE_FLASH    : ORIGIN = 0x00000000, LENGTH = 256K */
-  /* NONSECURE_FLASH : ORIGIN = 0x00040000, LENGTH = 768K */
-  /* SECURE_RAM      : ORIGIN = 0x20000000, LENGTH = 64K */
-  /* LIBBSD_RAM      : ORIGIN = 0x20010000, LENGTH = 64K */
-  /* NONSECURE_RAM   : ORIGIN = 0x20020000, LENGTH = 128K */
-
-  FLASH : ORIGIN = 0x00040000, LENGTH = 768K
-  RAM : ORIGIN = 0x20020000, LENGTH = 128K
+    /*
+     * This is where the Bootloader, Secure Partition Manager or
+     * Trusted-Firmware-M lives.
+     */
+    SECURE_FLASH : ORIGIN = 0x00000000, LENGTH = 256K
+    /*
+     * This is where your non-secure Rust application lives. Note that SPM must agree this
+     * is where your application lives, or it will jump to garbage and crash the CPU.
+     */
+    FLASH        : ORIGIN = 0x00050000, LENGTH = 768K
+    /*
+     * This RAM is reserved for the Secure-Mode code located in the `SECURE_FLASH` region.
+     */
+    SECURE_RAM   : ORIGIN = 0x20000000, LENGTH = 64K
+    /*
+     * This RAM is available to both the Cortex-M33 and the LTE core (well,
+        technically anything between `0x2000_0000` and `0x2001_FFFF` is
+        shareable, but we just gave the first 64 KiB to Secure Mode). Shared
+        buffers must be placed here.
+     */
+    SHARED_RAM   : ORIGIN = 0x20010000, LENGTH = 64K
+    /*
+     * This RAM is available to your non-secure Rust application.
+     */
+    RAM          : ORIGIN = 0x20020000, LENGTH = 128K
 }
 
-/* This is where the call stack will be allocated. */
-/* The stack is of the full descending type. */
-/* You may want to use this variable to locate the call stack and static
-   variables in different memory regions. Below is shown the default value */
-/* _stack_start = ORIGIN(RAM) + LENGTH(RAM); */
-
-/* You can use this symbol to customize the location of the .text section */
-/* If omitted the .text section will be placed right after the .vector_table
-   section */
-/* This is required only on microcontrollers that store some configuration right
-   after the vector table */
-/* _stext = ORIGIN(FLASH) + 0x400; */
-
-/* Size of the heap (in bytes) */
-/* _heap_size = 1024; */
+SECTIONS
+{
+    /* This section contains the buffers used by `libnrf_modem` to talk between the Cortex-M33 and the LTE core */
+    .shared_ram (NOLOAD) : ALIGN(4)
+    {
+        . = ALIGN(4);
+        *(.shared_ram .shared_ram.*);
+        . = ALIGN(4);
+    } > SHARED_RAM
+}