diff --git a/example-code/native/stdout/src/bin/8_syscalls.rs b/example-code/native/stdout/src/bin/8_syscalls.rs index 01f89db5..612b2b0e 100644 --- a/example-code/native/stdout/src/bin/8_syscalls.rs +++ b/example-code/native/stdout/src/bin/8_syscalls.rs @@ -2,7 +2,7 @@ //! //! Requires `RUSTFLAGS="-C panic=abort -lc"` (and nightly Rust for Linux targets). //! -//! Runs on Aarch64 macOS, Aarch64 Linux and x86-64 Linux. +//! Runs on AArch64 macOS, AArch64 Linux and x86-64 Linux. #![no_std] #![no_main] diff --git a/example-code/nrf52/criticalup.toml b/example-code/nrf52/criticalup.toml index 79f13ab2..57543498 100644 --- a/example-code/nrf52/criticalup.toml +++ b/example-code/nrf52/criticalup.toml @@ -1,7 +1,7 @@ manifest-version = 1 [products.ferrocene] -release = "stable-25.05.0" +release = "stable-26.05.0" packages = [ "rustc-${rustc-host}", "rust-std-${rustc-host}", diff --git a/example-code/qemu-aarch32v8r/.cargo/config.toml b/example-code/qemu-aarch32v8r/.cargo/config.toml index ea2e7e15..c1f578a1 100644 --- a/example-code/qemu-aarch32v8r/.cargo/config.toml +++ b/example-code/qemu-aarch32v8r/.cargo/config.toml @@ -7,7 +7,7 @@ runner = [ "--cpu", "cortex-r52", "--log-format", - "{[{L}]%bold} {s} {({ff}:{l:1})%dimmed}" + "oneline" ] [build] diff --git a/example-code/qemu-aarch32v8r/Cargo.lock b/example-code/qemu-aarch32v8r/Cargo.lock index 49832399..6b1b2963 100644 --- a/example-code/qemu-aarch32v8r/Cargo.lock +++ b/example-code/qemu-aarch32v8r/Cargo.lock @@ -35,7 +35,7 @@ checksum = "29bb0176de85eb569c424320f5e8c32a7e0043ab6b12d76dbc33ef093eb3fb5f" dependencies = [ "proc-macro2", "quote", - "syn 2.0.118", + "syn 2.0.119", ] [[package]] @@ -79,7 +79,7 @@ checksum = "71d2a3353d70ac1091a33cbf31fc7e77b19091538a7e306e3740712af19807ca" dependencies = [ "proc-macro2", "quote", - "syn 2.0.118", + "syn 2.0.119", ] [[package]] @@ -132,9 +132,9 @@ checksum = "790eea4361631c5e7d22598ecd5723ff611904e3344ce8720784c93e3d83d40b" [[package]] name = "defmt" -version = "1.1.0" +version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a6e524506490a1953d237cb87b1cfc1e46f88c18f10a22dfe0f507dc6bfc7f7f" +checksum = "e2953bfe4f93bbd20cc71198842756f77d161884c99ebbabc41d80231ded88d1" dependencies = [ "bitflags", "defmt-macros", @@ -142,15 +142,14 @@ dependencies = [ [[package]] name = "defmt-macros" -version = "1.1.0" +version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f0a27770e9c8f719a79d8b638281f4d828f77d8fd61e0bd94451b9b85e576a0b" +checksum = "bad9c72e7ca2137e0dc3813245a0d282fd6daad32fd800af018306a9169b5fe8" dependencies = [ "defmt-parser", - "proc-macro-error2", "proc-macro2", "quote", - "syn 2.0.118", + "syn 2.0.119", ] [[package]] @@ -176,11 +175,11 @@ dependencies = [ [[package]] name = "derive-mmio" -version = "0.6.1" +version = "0.6.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "005a6dabf68a87a460d3cb9b8e2fd5de3f474fc34e8d9451f5a1b6db518da143" +checksum = "1579d07ce933dabc3d8fe06c529f9a743174bab8a5224b03fe9f0148b5b4c4e8" dependencies = [ - "derive-mmio-macro 0.6.1", + "derive-mmio-macro 0.6.2", "rustversion", ] @@ -196,14 +195,13 @@ dependencies = [ [[package]] name = "derive-mmio-macro" -version = "0.6.1" +version = "0.6.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "584dc8e12e4aeb88000c2be8ef7db15657c817fba3e77999a24807d1efcdeefa" +checksum = "5090bbfffae089eb132236978c9ab39e3b17692f56836f1bd57822572ac030fe" dependencies = [ - "proc-macro-error2", "proc-macro2", "quote", - "syn 2.0.118", + "syn 2.0.119", ] [[package]] @@ -214,7 +212,7 @@ checksum = "12b6d4985d9657a9c8b7aa5afd3a7869b6d6740f7574d9b7bdb90689a4d1d6e8" dependencies = [ "proc-macro2", "quote", - "syn 2.0.118", + "syn 2.0.119", ] [[package]] @@ -241,7 +239,7 @@ dependencies = [ "cfg-if", "cortex-m", "critical-section", - "derive-mmio 0.6.1", + "derive-mmio 0.6.2", "document-features", "embassy-time-driver", "embassy-time-queue-utils", @@ -397,7 +395,7 @@ checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8" dependencies = [ "proc-macro2", "quote", - "syn 2.0.118", + "syn 2.0.119", ] [[package]] @@ -416,28 +414,6 @@ version = "1.13.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49" -[[package]] -name = "proc-macro-error-attr2" -version = "2.0.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "96de42df36bb9bba5542fe9f1a054b8cc87e172759a1868aa05c1f3acc89dfc5" -dependencies = [ - "proc-macro2", - "quote", -] - -[[package]] -name = "proc-macro-error2" -version = "2.0.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "11ec05c52be0a07b08061f7dd003e7d7092e0472bc731b4af7bb1ef876109802" -dependencies = [ - "proc-macro-error-attr2", - "proc-macro2", - "quote", - "syn 2.0.118", -] - [[package]] name = "proc-macro2" version = "1.0.106" @@ -512,9 +488,9 @@ dependencies = [ [[package]] name = "rustversion" -version = "1.0.22" +version = "1.0.23" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" [[package]] name = "semihosting" @@ -569,9 +545,9 @@ dependencies = [ [[package]] name = "syn" -version = "2.0.118" +version = "2.0.119" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" dependencies = [ "proc-macro2", "quote", @@ -595,7 +571,7 @@ checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5" dependencies = [ "proc-macro2", "quote", - "syn 2.0.118", + "syn 2.0.119", ] [[package]] diff --git a/example-code/qemu-aarch32v8r/README.md b/example-code/qemu-aarch32v8r/README.md index 454b4312..35502d95 100644 --- a/example-code/qemu-aarch32v8r/README.md +++ b/example-code/qemu-aarch32v8r/README.md @@ -8,9 +8,10 @@ This repository contains a small example application that can be built using the ## Supported Platforms -Ferrocene is supported on *x86-64 Linux (glibc)* -(`x86_64-unknown-linux-gnu`) as the host platform, and *Armv8-R bare-metal* -(`armv8r-none-eabihf`) as a cross-compilation target. +Ferrocene is supported on [a number of host platforms]. We are using *Armv8-R +AArch32 bare-metal* (`armv8r-none-eabihf`) as a cross-compilation target. + +[a number of host platforms]: https://public-docs.ferrocene.dev/main/user-manual/targets/index.html You must first install Ferrocene by executing `criticalup install` inside this folder. This will require a valid CriticalUp token - please see the [CriticalUp @@ -21,44 +22,55 @@ option for `cargo`. You may also want a `rust-toolchain.toml` file to set `ferrocene` as the default toolchain for this directory. You can copy `rust-toolchain.toml.ferrocene` as a starting point. +This demo will also build with standard Rust. You can use `rustup` to obtain the +`armv8r-none-eabihf` target. + ## Demo contents This demo provides a few simple applications, designed to run inside a QEMU -virtual machine that is emulating an Aarch32 Arm Cortex-R system. +virtual machine that is emulating an AArch32 Arm Cortex-R system. There are five binaries in `./src/bin`: -* `defmt` prints some demt logs at different levels -* `global_uart` sets up a UART as a global variable and prints to it -* `panic` shows the panic handling -* `uart` prints to the first UART -* `with_heap` sets up a heap allocator and uses the `format!` macro to generate +- `defmt` prints some demt logs at different levels +- `global_uart` sets up a UART as a global variable and prints to it +- `panic` shows the panic handling +- `uart` prints to the first UART +- `with_heap` sets up a heap allocator and uses the `format!` macro to generate heap-allocated strings, which it then prints. All binaries use defmt to print logging information. ## Building and Running with `cargo` -Ferrocene compiles standard Rust source code, and so this project has also been -set up as a valid Rust project. The [`.cargo/config.toml`](./.cargo/config.toml) -file configures the default target as `armv8r-none-eabihf`. It also sets up the -linker arguments to ensure that [`./memory.x`](./memory.x) is used to supplement -the standard [`aarch32-rt`](https://crates.io/crates/aarch32-rt) linker -script. +Ferrocene compiles standard Rust source code, and so this project has also +been set up as a valid Rust project. -Before the build, `cargo` will compile and execute `build.rs`, which will copy -the linker script to the `cargo` temporary output directory where the linker -will look for it. - -The compiled outputs will go into `./target/armv8r-none-eabihf/`, where -and `` is `debug` or `release`. The package contains multiple binary -crates, and the output binary name will match the name of the source file in -`./src/bin` that was compiled. +- The [`.cargo/config.toml`](./.cargo/config.toml) file configures the default + target as `armv8r-none-eabihf`. +- The [build script](./build.rs) sets up the linker arguments to ensure that the + `aarch32-rt` crate's `./link.x` is used as the linker script, along with our + local [`memory.x`](./memory.x) definition of which memory region to use. It + also copies the linker scripts to the target folder so the linker can find + them. +- The compiled outputs will go into `./target/armv8r-none-eabihf/`, + where `` is `debug` or `release`. You will need to install [qemu-run](https://crates.io/crates/qemu-run), which handles starting `qemu-system-arm` and decoding the defmt logs sent over semihosting. +```console +$ cargo run + Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.10s + Running `qemu-run --machine mps3-an536 --cpu cortex-r52 --log-format oneline target/armv8r-none-eabihf/debug/defmt` +Hello, world! +[ERROR] This is an error log (defmt src/bin/defmt.rs:10) +[WARN ] This is a warn log (defmt src/bin/defmt.rs:11) +[INFO ] This is an info log (defmt src/bin/defmt.rs:12) +[ERROR] PANIC at src/bin/defmt.rs:18: Testing panic!() in fn main (qemu_aarch32v8r src/lib.rs:23) +``` + Most of the examples will run as-is, however if want to access the virtual UART over telnet, you need to add the `-- --uart-telnet` option to the `cargo run` invocation. @@ -67,10 +79,10 @@ invocation. Licensed under either of -* Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or +- Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or ) -* MIT license ([LICENSE-MIT](../LICENSE-MIT) or -) at your option. +- MIT license ([LICENSE-MIT](../LICENSE-MIT) or + ) at your option. ## Contribution diff --git a/example-code/qemu-aarch32v8r/criticalup.toml b/example-code/qemu-aarch32v8r/criticalup.toml index b5e62454..af54d2e2 100644 --- a/example-code/qemu-aarch32v8r/criticalup.toml +++ b/example-code/qemu-aarch32v8r/criticalup.toml @@ -1,7 +1,7 @@ manifest-version = 1 [products.ferrocene] -release = "beta-26.05-2026-06-27" +release = "stable-26.05.0" packages = [ "rustc-${rustc-host}", "rust-std-${rustc-host}", diff --git a/example-code/qemu-aarch64v8a/.cargo/config.toml b/example-code/qemu-aarch64v8a/.cargo/config.toml index 477e8186..19ca50ca 100644 --- a/example-code/qemu-aarch64v8a/.cargo/config.toml +++ b/example-code/qemu-aarch64v8a/.cargo/config.toml @@ -1,5 +1,5 @@ [target.aarch64-unknown-none] -# QEMU Aarch64 boots in EL1 by default +# QEMU AArch64 boots in EL1 by default runner = [ "qemu-run", "--machine", @@ -8,7 +8,7 @@ runner = [ "cortex-a57", "--aarch64", "--log-format", - "{[{L}]%bold} {s} {({ff}:{l:1})%dimmed}" + "oneline" ] [build] diff --git a/example-code/qemu-aarch64v8a/Cargo.lock b/example-code/qemu-aarch64v8a/Cargo.lock index ac5491fb..c802850f 100644 --- a/example-code/qemu-aarch64v8a/Cargo.lock +++ b/example-code/qemu-aarch64v8a/Cargo.lock @@ -8,7 +8,7 @@ version = "0.10.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1f02b5bfa3a481fdade5948a994ce93aa6c76f67fc19f3a9b270565cf7dfc657" dependencies = [ - "bitflags 2.10.0", + "bitflags 2.13.1", "thiserror", ] @@ -24,7 +24,7 @@ version = "0.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b62040eef329ede76c8b2af149362b0fd42ec9d8c436d9eb9d47db35b71cb300" dependencies = [ - "bitflags 2.10.0", + "bitflags 2.13.1", "embedded-hal-nb", "embedded-io", "safe-mmio", @@ -61,9 +61,9 @@ checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" [[package]] name = "bitflags" -version = "2.10.0" +version = "2.13.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "812e12b5285cc515a9c72a5c1d3b6d46a19dac5acfef5265968c166106e31dd3" +checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da" [[package]] name = "cfg-if" @@ -97,9 +97,9 @@ checksum = "790eea4361631c5e7d22598ecd5723ff611904e3344ce8720784c93e3d83d40b" [[package]] name = "defmt" -version = "1.0.1" +version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "548d977b6da32fa1d1fda2876453da1e7df63ad0304c8b3dae4dbe7b96f39b78" +checksum = "e2953bfe4f93bbd20cc71198842756f77d161884c99ebbabc41d80231ded88d1" dependencies = [ "bitflags 1.3.2", "defmt-macros", @@ -107,15 +107,14 @@ dependencies = [ [[package]] name = "defmt-macros" -version = "1.0.1" +version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3d4fc12a85bcf441cfe44344c4b72d58493178ce635338a3f3b78943aceb258e" +checksum = "bad9c72e7ca2137e0dc3813245a0d282fd6daad32fd800af018306a9169b5fe8" dependencies = [ "defmt-parser", - "proc-macro-error2", "proc-macro2", "quote", - "syn 2.0.114", + "syn 2.0.119", ] [[package]] @@ -191,9 +190,9 @@ checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66" [[package]] name = "linked_list_allocator" -version = "0.10.5" +version = "0.10.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9afa463f5405ee81cdb9cc2baf37e08ec7e4c8209442b5d72c04cfb2cd6e6286" +checksum = "2b23ac50abb8261cb38c6e2a7192d3302e0836dac1628f6a93b82b4fad185897" [[package]] name = "nb" @@ -210,33 +209,11 @@ version = "1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8d5439c4ad607c3c23abf66de8c8bf57ba8adcd1f129e699851a6e43935d339d" -[[package]] -name = "proc-macro-error-attr2" -version = "2.0.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "96de42df36bb9bba5542fe9f1a054b8cc87e172759a1868aa05c1f3acc89dfc5" -dependencies = [ - "proc-macro2", - "quote", -] - -[[package]] -name = "proc-macro-error2" -version = "2.0.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "11ec05c52be0a07b08061f7dd003e7d7092e0472bc731b4af7bb1ef876109802" -dependencies = [ - "proc-macro-error-attr2", - "proc-macro2", - "quote", - "syn 2.0.114", -] - [[package]] name = "proc-macro2" -version = "1.0.105" +version = "1.0.106" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "535d180e0ecab6268a3e718bb9fd44db66bbbc256257165fc699dadf70d16fe7" +checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934" dependencies = [ "unicode-ident", ] @@ -257,9 +234,9 @@ dependencies = [ [[package]] name = "quote" -version = "1.0.43" +version = "1.0.46" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dc74d9a594b72ae6656596548f56f667211f8a97b3d4c3d467150794690dc40a" +checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368" dependencies = [ "proc-macro2", ] @@ -288,9 +265,9 @@ dependencies = [ [[package]] name = "rustversion" -version = "1.0.22" +version = "1.0.23" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" [[package]] name = "safe-mmio" @@ -303,9 +280,9 @@ dependencies = [ [[package]] name = "semihosting" -version = "0.1.24" +version = "0.1.25" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e896488941756e5de3ee8449495464dbbf2201c85d2d1ace47d4fb81c74b99ec" +checksum = "f8e4abf97879f4e80db69a9fba7bd64998e9bdad25f58ef045a778e191172fd4" [[package]] name = "semver" @@ -348,9 +325,9 @@ dependencies = [ [[package]] name = "syn" -version = "2.0.114" +version = "2.0.119" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d4d107df263a3013ef9b1879b0df87d706ff80f65a86ea879bd9c31f9b307c2a" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" dependencies = [ "proc-macro2", "quote", @@ -374,14 +351,14 @@ checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5" dependencies = [ "proc-macro2", "quote", - "syn 2.0.114", + "syn 2.0.119", ] [[package]] name = "unicode-ident" -version = "1.0.22" +version = "1.0.24" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5" +checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" [[package]] name = "unicode-width" @@ -412,20 +389,20 @@ dependencies = [ [[package]] name = "zerocopy" -version = "0.8.33" +version = "0.8.54" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "668f5168d10b9ee831de31933dc111a459c97ec93225beb307aed970d1372dfd" +checksum = "b7cbbc0a705a0fd05cc3676525980d2bf5a9bc4adac6d6475209a7887cf59d19" dependencies = [ "zerocopy-derive", ] [[package]] name = "zerocopy-derive" -version = "0.8.33" +version = "0.8.54" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2c7962b26b0a8685668b671ee4b54d007a67d4eaf05fda79ac0ecf41e32270f1" +checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5" dependencies = [ "proc-macro2", "quote", - "syn 2.0.114", + "syn 2.0.119", ] diff --git a/example-code/qemu-aarch64v8a/Cargo.toml b/example-code/qemu-aarch64v8a/Cargo.toml index 94c603df..d3c1738c 100644 --- a/example-code/qemu-aarch64v8a/Cargo.toml +++ b/example-code/qemu-aarch64v8a/Cargo.toml @@ -4,7 +4,7 @@ version = "0.1.0" edition = "2021" authors = ["Ferrous Systems"] license = "MIT OR Apache-2.0" -description = "A simple Aarch64 demo application that runs in QEMU and compiles with Ferrocene" +description = "A simple AArch64 demo application that runs in QEMU and compiles with Ferrocene" default-run = "defmt" [dependencies] diff --git a/example-code/qemu-aarch64v8a/README.md b/example-code/qemu-aarch64v8a/README.md index 2ac7bf29..3da8ff9d 100644 --- a/example-code/qemu-aarch64v8a/README.md +++ b/example-code/qemu-aarch64v8a/README.md @@ -8,10 +8,10 @@ This repository contains a small example application that can be built using the ## Supported Platforms -Ferrocene 24.08 is supported on *x86-64 Linux (glibc)* -(`x86_64-unknown-linux-gnu`), *x86-64 Windows* and *AArch64 macOS* as the host -platform. We are using *Armv8-A bare-metal* (`aarch64-unknown-none`) as a -cross-compilation target. +Ferrocene is supported on [a number of host platforms]. We are using *Armv8-A +bare-metal* (`aarch64-unknown-none`) as a cross-compilation target. + +[a number of host platforms]: https://public-docs.ferrocene.dev/main/user-manual/targets/index.html You must first install Ferrocene by executing `criticalup install` inside this folder. This will require a valid CriticalUp token - please see the [CriticalUp @@ -22,18 +22,21 @@ option for `cargo`. You may also want a `rust-toolchain.toml` file to set `ferrocene` as the default toolchain for this directory. You can copy `rust-toolchain.toml.ferrocene` as a starting point. +This demo will also build with standard Rust. You can use `rustup` to obtain the +`aarch64-unknown-none` target. + ## Demo contents This demo provides a few simple applications, designed to run inside a QEMU -virtual machine that is emulating an Aarch64 Arm Cortex-A system. +virtual machine that is emulating an AArch64 Arm Cortex-A system. There are five binaries in `./src/bin`: -* `defmt` prints some demt logs at different levels -* `global_uart` sets up a UART as a global variable and prints to it -* `panic` shows the panic handling -* `uart` prints to the first UART -* `with_heap` sets up a heap allocator and uses the `format!` macro to generate +- `defmt` prints some demt logs at different levels +- `global_uart` sets up a UART as a global variable and prints to it +- `panic` shows the panic handling +- `uart` prints to the first UART +- `with_heap` sets up a heap allocator and uses the `format!` macro to generate heap-allocated strings, which it then prints. All binaries use defmt to print logging information. @@ -41,24 +44,33 @@ All binaries use defmt to print logging information. ## Building and Running with `cargo` Ferrocene compiles standard Rust source code, and so this project has also -been set up as a valid Rust project. The -[`.cargo/config.toml`](./.cargo/config.toml) file configures the default -target as `aarch64-unknown-none`. The build script sets up the linker -arguments to ensure that the `aarch64-rt` crate's `./image.ld` is used as the -linker script, along with our local [`memory.ld`](./memory.ld) definition of -which memory region to use. - -Before the build, `cargo` will compile and execute `build.rs`, which will copy -the linker script to the `cargo` temporary output directory where the linker -will look for it. - -The compiled outputs will go into `./target/aarch64-none-eabi/`, where -`` is `debug` or `release`. +been set up as a valid Rust project. + +- The [`.cargo/config.toml`](./.cargo/config.toml) file configures the default + target as `aarch64-unknown-none`. +- The [build script](./build.rs) sets up the linker arguments to ensure that the + `aarch64-rt` crate's `./image.ld` is used as the linker script, along with our + local [`memory.ld`](./memory.ld) definition of which memory region to use. It + also copies the linker scripts to the target folder so the linker can find + them. +- The compiled outputs will go into `./target/aarch64-unknown-none/`, + where `` is `debug` or `release`. You will need to install [qemu-run](https://crates.io/crates/qemu-run), which handles starting `qemu-system-aarch64` and decoding the defmt logs sent over semihosting. +```console +$ cargo run + Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.04s + Running `qemu-run --machine virt --cpu cortex-a57 --aarch64 --log-format oneline target/aarch64-unknown-none/debug/defmt` +Hello, world! +[ERROR] This is an error log (defmt src/bin/defmt.rs:15) +[WARN ] This is a warn log (defmt src/bin/defmt.rs:16) +[INFO ] This is an info log (defmt src/bin/defmt.rs:17) +[ERROR] PANIC at src/bin/defmt.rs:23: Testing panic!() in fn main (qemu_aarch64v8a src/lib.rs:88) +``` + Most of the examples will run as-is, however if want to access the virtual UART over telnet, you need to add the `-- --uart-telnet` option to the `cargo run` invocation. @@ -67,10 +79,10 @@ invocation. Licensed under either of -* Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or +- Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or ) -* MIT license ([LICENSE-MIT](../LICENSE-MIT) or -) at your option. +- MIT license ([LICENSE-MIT](../LICENSE-MIT) or + ) at your option. ## Contribution diff --git a/example-code/qemu-aarch64v8a/criticalup.toml b/example-code/qemu-aarch64v8a/criticalup.toml index b1a61063..bfce6b24 100644 --- a/example-code/qemu-aarch64v8a/criticalup.toml +++ b/example-code/qemu-aarch64v8a/criticalup.toml @@ -1,11 +1,12 @@ manifest-version = 1 [products.ferrocene] -release = "stable-25.11.0" +release = "stable-26.05.0" packages = [ "rustc-${rustc-host}", "rust-std-${rustc-host}", "cargo-${rustc-host}", "llvm-tools-${rustc-host}", + "rust-src", "rust-std-aarch64-unknown-none", ] diff --git a/example-code/qemu-aarch64v8a/src/critical_section.rs b/example-code/qemu-aarch64v8a/src/critical_section.rs index be1b10cb..18ed3d3d 100644 --- a/example-code/qemu-aarch64v8a/src/critical_section.rs +++ b/example-code/qemu-aarch64v8a/src/critical_section.rs @@ -1,4 +1,4 @@ -//! Code that implements the `critical-section` traits on 64-bit Aarch64. +//! Code that implements the `critical-section` traits on 64-bit AArch64. struct SingleCoreCriticalSection; critical_section::set_impl!(SingleCoreCriticalSection); diff --git a/example-code/qemu-aarch64v8a/src/lib.rs b/example-code/qemu-aarch64v8a/src/lib.rs index b8dab0d2..61d221c6 100644 --- a/example-code/qemu-aarch64v8a/src/lib.rs +++ b/example-code/qemu-aarch64v8a/src/lib.rs @@ -10,7 +10,7 @@ use defmt_semihosting as _; pub mod critical_section; -/// An Aarch64 Exception Level +/// An AArch64 Exception Level #[derive(Debug, Copy, Clone, PartialEq, Eq)] pub enum ExceptionLevel { /// User code diff --git a/example-code/qemu-thumbv7em/.cargo/config.toml b/example-code/qemu-thumbv7em/.cargo/config.toml index 0df00b95..c8ce9d29 100644 --- a/example-code/qemu-thumbv7em/.cargo/config.toml +++ b/example-code/qemu-thumbv7em/.cargo/config.toml @@ -9,7 +9,7 @@ runner = [ "--cpu", "cortex-m4", "--log-format", - "{[{L}]%bold} {s} {({ff}:{l:1})%dimmed}" + "oneline" ] [env] diff --git a/example-code/qemu-thumbv7em/Cargo.lock b/example-code/qemu-thumbv7em/Cargo.lock index 393643dd..ca2250a8 100644 --- a/example-code/qemu-thumbv7em/Cargo.lock +++ b/example-code/qemu-thumbv7em/Cargo.lock @@ -32,12 +32,6 @@ dependencies = [ "rustc_version", ] -[[package]] -name = "bare-metal" -version = "1.0.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f8fe8f5a8a398345e52358e18ff07cc17a568fbca5c6f73873d3a62056309603" - [[package]] name = "bitbybit" version = "2.0.0" @@ -69,9 +63,9 @@ checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" [[package]] name = "cc" -version = "1.2.65" +version = "1.2.67" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e228eec9be7c17ccb640b59b36a5cd805ea2a564a4c5e162c2f659fea30d3b96" +checksum = "e17dd265a7d0f31ef544e1b20e03add05d3b45b491b633b10d67145d2acc1a38" dependencies = [ "find-msvc-tools", "shlex", @@ -99,7 +93,7 @@ version = "0.7.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8ec610d8f49840a5b376c69663b6369e71f4b34484b9b2eb29fb918d92516cb9" dependencies = [ - "bare-metal 0.2.5", + "bare-metal", "bitfield", "critical-section", "embedded-hal 0.2.7", @@ -179,14 +173,14 @@ version = "0.3.100" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0963443817029b2024136fc4dd07a5107eb8f977eaf18fcd1fdeb11306b64ad" dependencies = [ - "defmt 1.1.0", + "defmt 1.1.1", ] [[package]] name = "defmt" -version = "1.1.0" +version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a6e524506490a1953d237cb87b1cfc1e46f88c18f10a22dfe0f507dc6bfc7f7f" +checksum = "e2953bfe4f93bbd20cc71198842756f77d161884c99ebbabc41d80231ded88d1" dependencies = [ "bitflags", "defmt-macros", @@ -194,12 +188,11 @@ dependencies = [ [[package]] name = "defmt-macros" -version = "1.1.0" +version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f0a27770e9c8f719a79d8b638281f4d828f77d8fd61e0bd94451b9b85e576a0b" +checksum = "bad9c72e7ca2137e0dc3813245a0d282fd6daad32fd800af018306a9169b5fe8" dependencies = [ "defmt-parser", - "proc-macro-error2", "proc-macro2", "quote", "syn", @@ -222,17 +215,17 @@ checksum = "63b0302c696f9080df24a40eed6d34e34de9a610723b8176df52272798971250" dependencies = [ "cortex-m", "critical-section", - "defmt 1.1.0", + "defmt 1.1.1", "semihosting", ] [[package]] name = "derive-mmio" -version = "0.6.1" +version = "0.6.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "005a6dabf68a87a460d3cb9b8e2fd5de3f474fc34e8d9451f5a1b6db518da143" +checksum = "1579d07ce933dabc3d8fe06c529f9a743174bab8a5224b03fe9f0148b5b4c4e8" dependencies = [ - "derive-mmio-macro 0.6.1", + "derive-mmio-macro 0.6.2", "rustversion", ] @@ -248,11 +241,10 @@ dependencies = [ [[package]] name = "derive-mmio-macro" -version = "0.6.1" +version = "0.6.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "584dc8e12e4aeb88000c2be8ef7db15657c817fba3e77999a24807d1efcdeefa" +checksum = "5090bbfffae089eb132236978c9ab39e3b17692f56836f1bd57822572ac030fe" dependencies = [ - "proc-macro-error2", "proc-macro2", "quote", "syn", @@ -339,7 +331,7 @@ dependencies = [ "cfg-if", "cortex-m", "critical-section", - "derive-mmio 0.6.1", + "derive-mmio 0.6.2", "document-features", "embassy-time-driver", "embassy-time-queue-utils", @@ -505,7 +497,7 @@ version = "0.9.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "25ba4bd83f9415b58b4ed8dc5714c76e626a105be4646c02630ad730ad3b5aa4" dependencies = [ - "defmt 1.1.0", + "defmt 1.1.1", "hash32", "stable_deref_trait", ] @@ -574,9 +566,9 @@ dependencies = [ [[package]] name = "memchr" -version = "2.8.2" +version = "2.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" [[package]] name = "nb" @@ -648,28 +640,6 @@ version = "1.13.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49" -[[package]] -name = "proc-macro-error-attr2" -version = "2.0.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "96de42df36bb9bba5542fe9f1a054b8cc87e172759a1868aa05c1f3acc89dfc5" -dependencies = [ - "proc-macro2", - "quote", -] - -[[package]] -name = "proc-macro-error2" -version = "2.0.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "11ec05c52be0a07b08061f7dd003e7d7092e0472bc731b4af7bb1ef876109802" -dependencies = [ - "proc-macro-error-attr2", - "proc-macro2", - "quote", - "syn", -] - [[package]] name = "proc-macro2" version = "1.0.106" @@ -687,7 +657,7 @@ dependencies = [ "bitbybit", "cortex-m", "critical-section", - "defmt 1.1.0", + "defmt 1.1.1", "derive-mmio 0.7.0", "embassy-time", "embedded-hal 1.0.0", @@ -705,7 +675,7 @@ dependencies = [ "cortex-m-rt", "cortex-m-types", "critical-section", - "defmt 1.1.0", + "defmt 1.1.1", "defmt-semihosting", "embassy-executor", "embassy-sync", @@ -733,9 +703,9 @@ dependencies = [ [[package]] name = "regex-automata" -version = "0.4.14" +version = "0.4.16" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f" +checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad" dependencies = [ "aho-corasick", "memchr", @@ -750,11 +720,10 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" [[package]] name = "rtic" -version = "2.2.0" +version = "2.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6bc68b1fa2eefbb7ad6747b299b79c8fca92163dfa46f0e279f39109cf272186" +checksum = "16dff5e56cf22c25d0223e8abc0f60b428c577d4dd4a2459e55eeb289165106c" dependencies = [ - "bare-metal 1.0.0", "cortex-m", "critical-section", "portable-atomic", @@ -780,12 +749,11 @@ checksum = "d9369355b04d06a3780ec0f51ea2d225624db777acbc60abd8ca4832da5c1a42" [[package]] name = "rtic-macros" -version = "2.2.0" +version = "2.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f387b12bd6c01d2c9d4776dddeefaf0ae51b9497c83c0186b1693f6821ff3c4a" +checksum = "14db06b1d38d3591975d0971b2a5cde129767a93f5815fb01c99efa8d1898c16" dependencies = [ "indexmap", - "proc-macro-error2", "proc-macro2", "quote", "syn", @@ -829,9 +797,9 @@ dependencies = [ [[package]] name = "rustversion" -version = "1.0.22" +version = "1.0.23" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" [[package]] name = "scoped-tls" @@ -895,9 +863,9 @@ checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" [[package]] name = "syn" -version = "2.0.118" +version = "2.0.119" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" dependencies = [ "proc-macro2", "quote", @@ -926,9 +894,9 @@ dependencies = [ [[package]] name = "thread_local" -version = "1.1.9" +version = "1.1.10" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f60246a4944f24f6e018aa17cdeffb7818b76356965d03b07d6a9886e8962185" +checksum = "1ad99c4c6d32803332c548b1af0540b357b3f5fc0be8f6c6bfe8b2e6ae784070" dependencies = [ "cfg-if", ] diff --git a/example-code/qemu-thumbv7em/Cargo.toml b/example-code/qemu-thumbv7em/Cargo.toml index 5efb8775..b82d9c5c 100644 --- a/example-code/qemu-thumbv7em/Cargo.toml +++ b/example-code/qemu-thumbv7em/Cargo.toml @@ -26,7 +26,7 @@ rtic = { version = "2", features = ["thumbv7-backend"] } rtic-monotonics = { version = "2", features = ["cortex-m-systick"] } embassy-sync = "0.8" -embassy-executor = { version = "0.10", features = [ "platform-cortex-m", "executor-thread" ]} +embassy-executor = { version = "0.10", features = [ "platform-cortex-m", "executor-thread" ] } [dependencies.embassy-time] version = "0.5" diff --git a/example-code/qemu-thumbv7em/README.md b/example-code/qemu-thumbv7em/README.md index 0e2e182f..6a7f1898 100644 --- a/example-code/qemu-thumbv7em/README.md +++ b/example-code/qemu-thumbv7em/README.md @@ -1,19 +1,45 @@ # Examples for QEMU emulating an Armv7E-M Machine -These examples are designed to run in QEMU emulating the MPS2-AN386 machine. +This repository contains a small example application that can be built using the +[Ferrocene] toolchain from [Ferrous Systems]. -## Examples +[Ferrocene]: https://ferrocene.dev +[Ferrous Systems]: https://ferrous-systems.com + +## Supported Platforms + +Ferrocene is supported on [a number of host platforms]. We are using *Armv7E-M +bare-metal* (`thumbv7em-none-eabihf`) as a cross-compilation target. + +[a number of host platforms]: https://public-docs.ferrocene.dev/main/user-manual/targets/index.html + +You must first install Ferrocene by executing `criticalup install` inside this +folder. This will require a valid CriticalUp token - please see the [CriticalUp +documentation](https://criticalup.ferrocene.dev). + +You should also run `criticalup link create` to set up `+ferrocene` as a valid +option for `cargo`. You may also want a `rust-toolchain.toml` file to set +`ferrocene` as the default toolchain for this directory. You can copy +`rust-toolchain.toml.ferrocene` as a starting point. + +This demo will also build with standard Rust. You can use `rustup` to obtain the +`thumbv7em-none-eabihf` target. + +## Demo contents + +This demo provides a few simple applications, designed to run inside a QEMU +virtual machine that is emulating an Arm Cortex-M system. There are seven binaries in `./src/bin`: -* `defmt` prints some demt logs at different levels -* `panic` shows the panic handling -* `rtic_empty` is a simple RTIC skeleton app -* `timer` sets up the SysTick timer -* `uart_mutex` sets up a UART as a global variable and prints to it -* `uart_echo` sets up a UART and echos any input received -* `uart_buffered` sets up an interrupt-drive UART using an in-memory buffer -* `with_heap` sets up a heap allocator and uses the `format!` macro to generate +- `defmt` prints some demt logs at different levels +- `panic` shows the panic handling +- `rtic_empty` is a simple RTIC skeleton app +- `timer` sets up the SysTick timer +- `uart_mutex` sets up a UART as a global variable and prints to it +- `uart_echo` sets up a UART and echos any input received +- `uart_buffered` sets up an interrupt-drive UART using an in-memory buffer +- `with_heap` sets up a heap allocator and uses the `format!` macro to generate heap-allocated strings, which it then prints. All binaries use defmt to print logging information. @@ -37,54 +63,49 @@ The MPS-AN386 is described in Arm [Application Note AN386]. This image is based [Application Note AN386]: https://developer.arm.com/documentation/dai0386/latest/ -## Ferrocene - -This project has been setup to build with the standard Rust Project toolchain. You can also build it with Ferrocene. +## Building and Running with `cargo` -To use Ferrocene with this project: +Ferrocene compiles standard Rust source code, and so this project has also +been set up as a valid Rust project. -1. Install Ferrocene by executing `criticalup install` inside this -folder. This will require a valid CriticalUp token - please see the [CriticalUp -documentation](https://criticalup.ferrocene.dev). -2. Run `criticalup link create` to set up `+ferrocene` as a valid option for `cargo`. -3. Copy [`rust-toolchain.hide.toml`](./rust-toolchain.hide.toml) to `rust-toolchain.toml` to set the default toolchain to be `+ferrocene`. - -Alternatively, you can skip steps 2 and 3, and execute `criticalup run cargo run`. However, if you have an editor open using Rust Analyzer it will continue to build the code in the background with the standard Rust Project toolchain, and this may cause conflicts. - -## Running +- The [`.cargo/config.toml`](./.cargo/config.toml) file configures the default + target as `thumbv7em-none-eabihf`. +- The [build script](./build.rs) sets up the linker arguments to ensure that the + `cortex-m-rt` crate's `./link.x` is used as the linker script, along with our + local [`memory.x`](./memory.x) definition of which memory region to use. It + also copies the linker scripts to the target folder so the linker can find + them. +- The compiled outputs will go into `./target/thumbv7em-none-eabihf/`, + where `` is `debug` or `release`. You will need to install [qemu-run](https://crates.io/crates/qemu-run), which -handles starting `qemu-system-aarch64` and decoding the defmt logs sent over +handles starting `qemu-system-arm` and decoding the defmt logs sent over semihosting. -Most of the examples will run as-is, however if want to access the virtual UART -over telnet, you need to add the `-- --uart-telnet` option to the `cargo run` -invocation. - ```console -$ cargo run --bin uart_echo -- --uart-telnet - Finished `dev` profile [optimized + debuginfo] target(s) in 0.03s - Running `qemu-run --machine mps2-an386 --cpu cortex-m4 --log-format=oneline target/thumbv7em-none-eabihf/debug/uart_echo --uart-telnet` -[INFO ] Told QEMU to start telnet server on localhost:4321. Connect to interact with UART0. ( qemu-run/src/main.rs:157) (HOST) -qemu-system-arm: -chardev socket,id=sock0,server=on,telnet=on,port=4321,host=localhost: info: QEMU waiting for connection on: disconnected:telnet:::1:4321,server=on -[INFO ] Running uart_echo - echoing via to global buffered UART0 (uart_echo src/bin/uart_echo.rs:32) -[INFO ] Application read 1 bytes ([54]). Echoing back. (uart_echo src/bin/uart_echo.rs:76) -[INFO ] Application read 1 bytes ([48]). Echoing back. (uart_echo src/bin/uart_echo.rs:76) -[INFO ] Application read 1 bytes ([69]). Echoing back. (uart_echo src/bin/uart_echo.rs:76) -[INFO ] Application read 1 bytes ([73]). Echoing back. (uart_echo src/bin/uart_echo.rs:76) -[INFO ] Application read 1 bytes ([20]). Echoing back. (uart_echo src/bin/uart_echo.rs:76) +$ cargo run + Compiling qemu-thumbv7em v0.1.0 (/Users/jonathan/Documents/ferrous-systems/rust-training/example-code/qemu-thumbv7em) + Finished `dev` profile [optimized + debuginfo] target(s) in 0.24s + Running `qemu-run --machine mps2-an386 --cpu cortex-m4 --log-format oneline target/thumbv7em-none-eabihf/debug/defmt` +Hello, world! +[ERROR] This is an error log (defmt src/bin/defmt.rs:15) +[WARN ] This is a warn log (defmt src/bin/defmt.rs:16) +[INFO ] This is an info log (defmt src/bin/defmt.rs:17) +[ERROR] PANIC at src/bin/defmt.rs:23: Testing panic!() in fn main (qemu_thumbv7em src/lib.rs:74) ``` -You can access the telnet server with `telnet localhost:4321` or similar. +Most of the examples will run as-is, however if want to access the virtual UART +over telnet, you need to add the `-- --uart-telnet` option to the `cargo run` +invocation. ## License Licensed under either of -* Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or +- Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or ) -* MIT license ([LICENSE-MIT](../LICENSE-MIT) or -) at your option. +- MIT license ([LICENSE-MIT](../LICENSE-MIT) or + ) at your option. ## Contribution diff --git a/example-code/qemu-thumbv7em/criticalup.toml b/example-code/qemu-thumbv7em/criticalup.toml index 644b0cc6..57543498 100644 --- a/example-code/qemu-thumbv7em/criticalup.toml +++ b/example-code/qemu-thumbv7em/criticalup.toml @@ -1,7 +1,7 @@ manifest-version = 1 [products.ferrocene] -release = "stable-25.11.0" +release = "stable-26.05.0" packages = [ "rustc-${rustc-host}", "rust-std-${rustc-host}", diff --git a/example-code/qemu-thumbv7em/rust-toolchain.hide.toml b/example-code/qemu-thumbv7em/rust-toolchain.toml.ferrocene similarity index 100% rename from example-code/qemu-thumbv7em/rust-toolchain.hide.toml rename to example-code/qemu-thumbv7em/rust-toolchain.toml.ferrocene diff --git a/training-slides/src/ferrocene-installing.md b/training-slides/src/ferrocene-installing.md index a4b40a58..95c34c22 100644 --- a/training-slides/src/ferrocene-installing.md +++ b/training-slides/src/ferrocene-installing.md @@ -13,7 +13,7 @@ * `ferrocene-self-test` - checks your installation * `ferrocene-docs-xxx` - documentation -★: qualified tool ☆: certification in progress +★: qualified tool ☆: certified subset available Note: @@ -34,21 +34,17 @@ Examples of channels include: * nightly * pre-rolling * rolling -* beta-24.05 -* beta-24.08 -* stable-24.05 -* stable-24.08 +* beta-26.05 +* stable-26.02 * etc Examples of releases include: -* nightly-2024-08-29 -* pre-rolling-2024-08-28 -* rolling-2024-08-08 -* beta-24.05-2024-06-19 -* beta-24.08-2024-08-22 -* stable-24.05.0 -* stable-24.08.0 +* nightly-2026-07-16 +* pre-rolling-2026-07-03 +* rolling-2026-07-15 +* beta-26.05-2026-07-12 +* stable-26.02.0 * etc See @@ -77,8 +73,6 @@ We have two dimensions: Note: -In stable-24.08 and earlier, these were called "Supported Targets" - Each release has a User Manual and it is important to follow the instructions for that target in that release otherwise you may be outside the qualification scope. As an example, we don't let you give arbitrary arguments to the linker - @@ -86,16 +80,31 @@ you can only pass the arguments we say are OK. ## Quality Managed (QM) Targets +Quality managed targets are targets which are suitable for use in production +outside of safety critical contexts. + * Production Ready * Passes the Rust Test Suite * Support is available -* ~~Signed qualification material~~ Note: -It may be that the target is en-route to being a Qualified Target, or it may be -that it is deemed unlikely that the target would be useful in a safety critical -context. Talk to us if you would like a QM Target available as a Qualified +Talk to us if you would like a QM Target available as a Qualified +Target. + +## Supported Targets + +Supported targets are targets which are suitable for use outside of +safety-critical contexts, and may be suitable for production given adequate user +testing. + +* Maybe Production Ready +* Low-priority support is available +* Maybe passed the Rust Test Suite + +Note: + +Talk to us if you would like a Supported Target available as a QM or Qualified Target. ## Experimental Targets @@ -108,8 +117,7 @@ Target. Note: A Ferrocene 'Experimental Target' is broadly equivalent to an upstream Tier 2 or -Tier 1 target, depending on whether we're running the Test Suite in CI. And, to -be fair, plenty of people use upstream Rust in production. +Tier 1 target, depending on whether we're running the Test Suite in CI. ## Host Targets @@ -143,7 +151,7 @@ be fair, plenty of people use upstream Rust in production. manifest-version = 1 [products.ferrocene] -release = "stable-24.08.0" +release = "stable-26.05.0" packages = [ "rustc-${rustc-host}", "rust-std-${rustc-host}", "cargo-${rustc-host}", "rust-src", "rust-std-aarch64-unknown-none" @@ -163,11 +171,11 @@ packages = [ ```console $ criticalup auth set $ criticalup install -info: installing product 'ferrocene' (stable-24.08.0) -info: downloading component 'cargo-x86_64-unknown-linux-gnu' for 'ferrocene' (stable-24.08.0) +info: installing product 'ferrocene' (stable-26.02.0) +info: downloading component 'cargo-x86_64-unknown-linux-gnu' for 'ferrocene' (stable-26.02.0) ... -info: downloading component 'rustc-x86_64-unknown-linux-gnu' for 'ferrocene' (stable-24.08.0) -info: installing component 'rustc-x86_64-unknown-linux-gnu' for 'ferrocene' (stable-24.08.0) +info: downloading component 'rustc-x86_64-unknown-linux-gnu' for 'ferrocene' (stable-26.02.0) +info: installing component 'rustc-x86_64-unknown-linux-gnu' for 'ferrocene' (stable-26.02.0) $ criticalup run rustc --version ``` @@ -222,13 +230,12 @@ NB: `cargo` uses the corresponding `rustc` ## rust-analyzer in VS Code -Set `RUSTC` to tell it which `rustc` to use +VS Code uses `rustup`, so tell `rustup` to use `criticalup`: ```text -$ RUSTC=$(criticalup which rustc) code . - -PS D:\project> $Env:RUSTC=$(criticalup which rustc) -PS D:\project> code . +$ criticalup link create +$ rustup override set ferrocene +$ code . ``` Ensure you have the `rust-src` package installed. diff --git a/training-slides/src/ferrocene-what-it-is.md b/training-slides/src/ferrocene-what-it-is.md index 97eebe65..bf081045 100644 --- a/training-slides/src/ferrocene-what-it-is.md +++ b/training-slides/src/ferrocene-what-it-is.md @@ -19,8 +19,8 @@ ## A downstream of The Rust Project -* One of the Ferrocene pillars is that the standard library and the compiler must not diverge from upstream. -* We've been pulling the `master` branch of `rust-lang/rust` into our tree since 2021 +* One of the Ferrocene pillars is that the standard library and the compiler must not diverge from upstream +* We've been pulling changes from `rust-lang/rust` into our tree since 2021 ## Patches @@ -49,13 +49,13 @@ ## Long-term Stable -As of 3 September 2024, the Ferrocene releases are: +The Ferrocene releases are: -* *nightly* (upstream *nightly*) -* *pre-rolling* (upstream *beta*) +* Ferrocene Stable, four times per year +* Ferrocene Beta, ahead of each Ferrocene Stable * *rolling* (upstream *stable*) -* stable-24.05 (upstream *1.76*) -* stable-24.08 (upstream *1.79*) +* *pre-rolling* (upstream *beta*) +* *nightly* (upstream *nightly*) Note: @@ -66,17 +66,27 @@ releases. See for details. +We generally have releases numbered `YY.02`, `YY.05`, `YY.08` and `YY.11`. + ## Open Source * Ferrocene lives at * The source code is MIT || Apache-2.0 * The docs are published at -## Qualified per ISO 26262 (ASIL D) / IEC 61508 (SIL 4) +## Qualified Toolchain + +Meets ISO 26262 (ASIL D) / IEC 61508 (SIL 3) / ISO 62304 (Class C) -We're in [the TÜV SÜD database](https://www.tuvsud.com/en/services/product-certification/ps-cert?q=Z10+123030+0001+Rev.+00) +[![TÜV SÜD logo](./images/Z1_en-3D_N.png)](https://www.tuvsud.com/en/customer-hub/ps-cert/?q=Z10+123030+0001+Rev.+01) -![TÜV SÜD logo](./images/Z1_en-3D_N.png) +## Certified Rust Standard Library (subset) + +Meets ISO 26262 (ASIL B) / IEC 61508 (SIL 2) + +Our [docs](https://public-docs.ferrocene.dev/main/core/ptr/index.html) note which functions are 'validated'. + +We can also lint for use of non-validated APIs. ## `cargo` isn't qualified @@ -84,12 +94,6 @@ We're in [the TÜV SÜD database](https://www.tuvsud.com/en/services/product-cer * You don't *need* a build system... * You can just call `rustc` (which is qualified) from a simple script for production -## `libstd` isn't certified, `libcore` will be - -* It doesn't make sense to certify the Standard Library - * It's mostly "If Windows, do X; if POSIX, do Y" -* We are looking at certifying `libcore` - ## Supplied with a warranty If you find a bug in the compiler, we will fix it or give you details on how to work around it