Merge pull request #15 from Neotron-Compute/release/v0.2.0

Release/v0.2.0

.github/workflows/build.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: true
           fetch-depth: 0
@@ -23,7 +23,7 @@ jobs:
           rustup component add llvm-tools
           cargo install cargo-binutils
 
-      - name: Add targets
+      - name: Add C tools
         run: |
           sudo apt-get -y install gcc-arm-none-eabi binutils-arm-none-eabi
 
@@ -70,7 +70,7 @@ jobs:
           zip -r ./neotron-sdk-${{ env.slug }}.zip ./neotron-sdk-${{ env.slug }}
 
       - name: Upload Artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: ${{success()}}
         with:
           name: Artifacts

.github/workflows/clippy.yml

@@ -10,17 +10,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: true
           fetch-depth: 0
 
       - name: Install Rust
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-          components: clippy
-          target: thumbv6m-none-eabi
+        run: |
+          rustup component add clippy
+          rustup target add thumbv6m-none-eabi
 
       - name: Run Clippy
         uses: actions-rs/clippy-check@v1

.github/workflows/format.yml

@@ -7,16 +7,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: true
           fetch-depth: 0
 
       - name: Install Rust
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-          components: rustfmt
+        run: rustup component add rustfmt
 
       - name: Check Format
         run: cargo fmt -- --check

CHANGELOG.md

@@ -1,9 +1,19 @@
 # Change Log
 
-## Unreleased changes ([Source](https://github.com/neotron-compute/neotron-sdk/tree/develop) | [Changes](https://github.com/neotron-compute/neotron-sdk/compare/v0.1.0...develop))
+## Unreleased changes ([Source](https://github.com/neotron-compute/neotron-sdk/tree/develop) | [Changes](https://github.com/neotron-compute/neotron-sdk/compare/v0.2.0...develop))
 
 * None
 
+## v0.2.0 - 2024-05-19 ([Source](https://github.com/neotron-compute/neotron-sdk/tree/v0.2.0) | [Release](https://github.com/neotron-compute/neotron-sdk/releases/tag/v0.2.0))
+
+* Adds a bare-metal target to docs.rs
+* Document the `init` function
+* Moved the Cortex-M linker script into the SDK so applications don't have to
+  have a copy
+* Update GitHub Actions to avoid Node.js 16 warnings
+* Fixed the asmhello sample (it was crashing)
+* Added more docs to the linker script
+
 ## v0.1.0 - 2024-05-19 ([Source](https://github.com/neotron-compute/neotron-sdk/tree/v0.1.0) | [Release](https://github.com/neotron-compute/neotron-sdk/releases/tag/v0.1.0))
 
-First version. Supports cross-platform terminal output and some basic file APIs.
+* First version. Supports cross-platform terminal output and some basic file APIs.

Cargo.toml

@@ -3,7 +3,7 @@ description = "SDK for writing applications for Neotron OS"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 name = "neotron-sdk"
-version = "0.1.0"
+version = "0.2.0"
 authors = ["Jonathan 'theJPster' Pallant <[email protected]>"]
 
 [dependencies]
@@ -19,3 +19,6 @@ crossterm = "0.26"
 [features]
 # Prints panic info. Costs you about 14K of code.
 fancy-panic = []
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu", "thumbv6m-none-eabi"]

build.rs

@@ -0,0 +1,36 @@
+//! Build script for the Neotron SDK
+//!
+//! Sets up Rust to link with a Cortex-M linker script if you are building for
+//! an Arm bare-metal target.
+
+use std::io::prelude::*;
+
+fn main() {
+    let arch = std::env::var("CARGO_CFG_TARGET_ARCH").expect("CARGO_CFG_TARGET_ARCH variable");
+    let os = std::env::var("CARGO_CFG_TARGET_OS").expect("CARGO_CFG_TARGET_OS variable");
+    match (arch.as_str(), os.as_str()) {
+        ("arm", "none") => {
+            setup_cortexm_linker();
+        }
+        _ => {
+            // no script required
+        }
+    }
+}
+
+fn setup_cortexm_linker() {
+    // Put `neotron-cortex-m.ld` in our output directory and ensure it's
+    // on the linker search path.
+    let out = &std::path::PathBuf::from(std::env::var_os("OUT_DIR").unwrap());
+    std::fs::File::create(out.join("neotron-cortex-m.ld"))
+        .unwrap()
+        .write_all(include_bytes!("./neotron-cortex-m.ld"))
+        .unwrap();
+    println!("cargo:rustc-link-search={}", out.display());
+
+    // By default, Cargo will re-run a build script whenever
+    // any file in the project changes. By specifying `neotron-cortex-m.ld`
+    // here, we ensure the build script is only re-run when
+    // `neotron-cortex-m.ld` is changed.
+    println!("cargo:rerun-if-changed=./neotron-cortex-m.ld");
+}

samples/neotron-cortex-m.ld → neotron-cortex-m.ld

@@ -4,7 +4,7 @@
  * Based on the [Rust Embedded Cortex-M crate](https://github.com/rust-embedded/cortex-m).
  * 
  * Copyright (c) 2016 Jorge Aparicio.
- * Copyright (c) 2023 Jonathan 'theJPster' Pallant and the Neotron Developers.
+ * Copyright (c) 2024 Jonathan 'theJPster' Pallant and the Neotron Developers.
  */
 
 MEMORY
@@ -26,52 +26,67 @@ ENTRY(app_entry);
 /* # Sections */
 SECTIONS
 {
-  /* ### .text */
+  /* ## .text */
+  /* All the executable code for our program */
   .text : ALIGN(4)
   {
     . = ALIGN(4);
     *(.text .text.*);
     . = ALIGN(4);
   } > RAM
 
-  /* ### .rodata */
+  /* ## .rodata */
+  /* All the read-only static data for our program */
   .rodata : ALIGN(4)
   {
     . = ALIGN(4);
     *(.rodata .rodata.*);
     . = ALIGN(4);
   } > RAM
 
-  /* ### .data */
+  /* ## .data */
+  /* All the read-write non-zero-initialised static data for our program */
   .data : ALIGN(4)
   {
     . = ALIGN(4);
     *(.data .data.*);
     . = ALIGN(4);
   } > RAM
 
-  /* ### .bss */
+  /* ## .bss */
+  /* All the read-write zero-initialised static data for our program */
   .bss : ALIGN(4)
   {
     . = ALIGN(4);
     *(.bss .bss.*);
     . = ALIGN(4);
   } > RAM
 
-  /* ### .uninit */
+  /* ## .uninit */
+  /* All the read-write uninitialised static data for our program */
   .uninit (NOLOAD) : ALIGN(4)
   {
     . = ALIGN(4);
     *(.uninit .uninit.*);
     . = ALIGN(4);
   } > RAM
 
+  /* ## Start of Heap */
+  /* Newlib's `sbrk` syscall uses the `end` symbol to mark the start of heap
+     memory. The `sbrk` syscall has a static variable tracking the edge of the
+     heap (`heap_end`) and that value moves upwards as more heap memory is
+     required. The `heap_end` value is initialised with the address of the `end`
+     symbol on first allocation.
+
+     See https://github.com/bminor/newlib/blob/master/libgloss/libnosys/sbrk.c
+     */
   . = ALIGN(4);
   end = .;
 
   /* ## .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 */
+  /* 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.*));

samples/.cargo/config.toml

@@ -1,11 +1,23 @@
 [target.thumbv7em-none-eabihf]
-rustflags = ["-C", "link-arg=-Tneotron-cortex-m.ld", "-C", "link-arg=--nmagic"]
+rustflags = [
+    "-Clink-arg=-Tneotron-cortex-m.ld", 
+    "-Clink-arg=--nmagic"
+]
 
 [target.thumbv7em-none-eabi]
-rustflags = ["-C", "link-arg=-Tneotron-cortex-m.ld", "-C", "link-arg=--nmagic"]
+rustflags = [
+    "-Clink-arg=-Tneotron-cortex-m.ld", 
+    "-Clink-arg=--nmagic"
+]
 
 [target.thumbv7m-none-eabi]
-rustflags = ["-C", "link-arg=-Tneotron-cortex-m.ld", "-C", "link-arg=--nmagic"]
+rustflags = [
+    "-Clink-arg=-Tneotron-cortex-m.ld", 
+    "-Clink-arg=--nmagic"
+]
 
 [target.thumbv6m-none-eabi]
-rustflags = ["-C", "link-arg=-Tneotron-cortex-m.ld", "-C", "link-arg=--nmagic"]
+rustflags = [
+    "-Clink-arg=-Tneotron-cortex-m.ld", 
+    "-Clink-arg=--nmagic"
+]

samples/Cargo.toml

@@ -8,6 +8,9 @@ members = [
 ]
 resolver = "2"
 
+[workspace.dependencies]
+neotron-sdk = { path = "..", version = "0.2" }
+
 [profile.release]
 opt-level = "z"
 lto = "fat"

samples/asmhello/asmhello.S

@@ -26,11 +26,13 @@ app_entry:
     ldr r3, [r0, #8]
     // Set up file handle
     movs r0, #1
-    // Set up data pointer
+    // Get address of string
     ldr r1, =message
-    // Set up data length
+    // Get address of data length
     ldr r4, =message_len
-    ldr r2, [r4]
+    // Read data length (might not be aligned, as it follows the string, so only
+    // read one byte)
+    ldrb r2, [r4]
     // Call write function
     blx r3
     // Set return value
@@ -55,6 +57,6 @@ message:
 // Must come immediately after `message:`
 .type message_len,%object
 message_len:
-.long . - message  
+.byte . - message  
 
 // End of file

samples/asmhello/build.sh

@@ -19,6 +19,6 @@ arm-none-eabi-gcc \
     -nostartfiles \
     -ffreestanding \
     -mcpu=$CPU \
-    -Wl,-T../neotron-cortex-m.ld \
+    -Wl,-T../../neotron-cortex-m.ld \
     -o asmhello.elf \
     asmhello.S \

samples/chello/build.sh

@@ -28,7 +28,7 @@ arm-none-eabi-gcc \
     -Wdouble-promotion \
     -Wextra \
     -Wl,-gc-sections \
-    -Wl,-T../neotron-cortex-m.ld \
+    -Wl,-T../../neotron-cortex-m.ld \
     -Wshadow \
     --specs=nano.specs \
     --specs=nosys.specs \

samples/chello/chello.c

@@ -15,11 +15,11 @@ const NeotronApi *g_api;
 int app_entry(const NeotronApi *f, size_t argc, const FfiString* argv) {
   g_api = f;
   // allocate a buffer
-  void *buffer = calloc(1024, 1);
+  char *buffer = (char*) calloc(1024, 1);
   // write a string into it
-  snprintf(buffer, 1023, "Hello, world!\n");
+  snprintf(buffer, 1023, "Hello, world!");
   // print the buffer
-  printf(buffer);
+  printf("Buffer %p contains: '%s'\n", buffer, buffer);
   // free the buffer
   free(buffer);
   for(size_t i = 0; i < argc; i++) {

samples/fault/Cargo.toml

@@ -7,6 +7,6 @@ authors = ["Jonathan 'theJPster' Pallant <[email protected]>"]
 description = "Hello World for Neotron systems"
 
 [dependencies]
-neotron-sdk = { path = "../.." }
+neotron-sdk = { workspace = true }
 
 # See workspace for profile settings

samples/hello/Cargo.toml

@@ -7,6 +7,6 @@ authors = ["Jonathan 'theJPster' Pallant <[email protected]>"]
 description = "Hello World for Neotron systems"
 
 [dependencies]
-neotron-sdk = { path = "../.." }
+neotron-sdk = { workspace = true }
 
 # See workspace for profile settings

samples/hexdump/Cargo.toml

@@ -7,6 +7,6 @@ authors = ["Jonathan 'theJPster' Pallant <[email protected]>"]
 description = "Prints information about files"
 
 [dependencies]
-neotron-sdk = { path = "../.." }
+neotron-sdk = { workspace = true }
 
 # See workspace for profile settings

samples/hexdump/src/main.rs

@@ -50,7 +50,7 @@ fn real_main() -> Result<(), neotron_sdk::Error> {
         // print ascii (with padding)
         for b in valid {
             let ch = *b as char;
-            let _ = write!(stdout, "{}", if !ch.is_control() { ch } else { '?' });
+            let _ = write!(stdout, "{}", if !ch.is_control() { ch } else { '.' });
         }
         for _padding in 0..(buffer.len() - valid.len()) {
             let _ = write!(stdout, ".");