Merge pull request #1 from ferrous-systems/add-slides

Add slides

README.md

@@ -3,63 +3,13 @@
 An introduction to the Ferrocene toolchain, what is is (and isn't) and what it
 can do.
 
-## Introduction
-
-In our one hour session on _Why Ferrocene?_ you will learn what Ferrocene is
-about, where it is from and where it is going, and whether it is right for you
-to look at Ferrocene for your next security-related or safety-critical project.
-The agenda includes a short lecture, a live programming demonstration, and a
-Q&A session.
-
-We conduct all training sessions remotely using modern video-conferencing tools
-to ensure the best learning experience.
-
-This repository contains the teaching material for this course.
+The table of contents is at [`./book/src/SUMMARY.md`](./src/SUMMARY.md).
 
 ## Booking
 
 See <https://ferrous-systems.com/training> to book or to discuss customising
 this material to your needs.
 
-## Learning Goals
-
-These are the questions you will be able to answer after attending this course:
-
-- What is Ferrocene?
-- Is Ferrocene a fork of Rust?
-- What support is available for Ferrocene?
-- What is it like using Ferrocene?
-
-## Timetable
-
-Our standard timetable for this course is as follows:
-
-| Duration | Contents                                             |
-| :------: | :--------------------------------------------------- |
-|   0:05   | Room open, meet and greet                            |
-|   0:20   | Session 1 - [What is Ferrocene?](#what-is-ferrocene) |
-|   0:20   | Session 2 - [A Live Demo](#a-live-demo)              |
-|   0:15   | Q&A                                                  |
-
-## Content
-
-### What is Ferrocene?
-
-- Ferrocene is just Rust
-- The downstream model
-- The supported host platforms
-- The supported target platforms
-- ISO 26262 Qualification
-- Commercial Support
-- The supported platforms
-
-### A Live Demo
-
-- Installing Ferrocene today
-- Exploring the installation
-- Writing and running an `aarch64-unknown-none` program
-- Q&A
-
 ## Licence
 
 Ferrous Systems offers our training material under

build.sh

@@ -3,8 +3,16 @@
 set -euo pipefail
 
 rm -rf ./slides || true
+rm -rf ./book || true
 mkdir ./slides
 mkdir ./slides/images
-mdslides --output-dir ./slides --template ./template.html --index-template ./index-template.html
-cp ./src/images/*.png ./slides/images
+# Check the examples are OK
+mdbook test
+# book goes into ./book
 mdbook build
+# slides go into ./slides
+mdslides \
+    --output-dir ./slides \
+    --template ./template.html \
+    --index-template ./index-template.html
+cp ./src/images/*.png ./slides/images

example-code/README.md

@@ -169,18 +169,8 @@ $ qemu-system-aarch64 \
     -nographic \
     -kernel ./target/production/basic-rust
 Hello, world!
-PANIC: PanicInfo {
-    payload: Any { .. },
-    message: Some(
-        Let's try a panic?,
-    ),
-    location: Location {
-        file: "src/main.rs",
-        line: 28,
-        col: 5,
-    },
-    can_unwind: true,
-}
+PANIC: PanicInfo { payload: Any { .. }, message: Some(I am a panic),
+location: Location { file: "src/main.rs", line: 72, col: 5 }, can_unwind: true }
 ```
 
 ## Creating a Docker Container

example-code/src/boot.S

@@ -10,7 +10,6 @@ _start:
     // Set FPEN bits [21:20] to 0b11 to prevent trapping.
     mov x0, #3 << 20
     msr cpacr_el1, x0   
-0:
     // Clear interrupt bit
     msr daifclr, #0x4   
     // Jump to application

example-code/src/main.rs

@@ -80,7 +80,7 @@ fn main() -> Result<(), core::fmt::Error> {
 fn panic(info: &core::panic::PanicInfo) -> ! {
     const SYS_REPORTEXC: u64 = 0x18;
     let mut c = Uart::uart0();
-    let _ = writeln!(c, "PANIC: {:#?}", info);
+    let _ = writeln!(c, "PANIC: {:?}", info);
     loop {
         // Exit, using semihosting
         unsafe {

index-template.html

@@ -2462,11 +2462,6 @@ <h1>$TITLE</h1>
         </div>
 
         <div class="sect1">
-            <h1>Credits</h1>
-            <p>The development of this course is financed by Ferrous Systems. They are open sourced as a contribution to
-                the growth of the Rust language.</p>
-            <p>If you wish to fund further development of the course, <a
-                    href="https://ferrous-systems.com/training">book a training</a>!</p>
             <h1>License</h1>
             <p>
                 <a href="http://creativecommons.org/licenses/by-sa/4.0/">
@@ -2479,7 +2474,6 @@ <h1>License</h1>
                 delivery of commercial or open-source Rust training programmes.</p>
             <p>Copyright (c) Ferrous Systems, 2023</p>
         </div>
-
     </div>
 </body>
 

src/SUMMARY.md

@@ -2,12 +2,23 @@
 
 [Front Matter](./front-matter.md)
 
+# What is Ferrocene?
+
 - [Ferrocene is just Rust](./just-rust.md)
 - [The downstream model](./downstream-model.md)
 - [The supported host platforms](./supported-hosts.md)
 - [The supported target platforms](./supported-targets.md)
 - [ISO 26262 Qualification](./iso26262.md)
 - [Commercial Support](./support.md)
-- [The Demo](./demo.md)
+
+# A Live Demo
+
+- [Installing Ferrocene today](./installing.md)
+- [Exploring the installation](./exploring.md)
+- [Writing and running a program](./writing.md)
+
+# Q&A
+
+- [Q&A](./q-and-a.md)
 
 [Wash-up](./wash-up.md)

src/downstream-model.md

@@ -1 +1,36 @@
 # The downstream model
+
+## Some examples
+
+* Enterprise Linux Distributions are a downstream of The Linux Kernel
+* The Linux Kernel makes kernel releases
+* The Enterprise Linux Vendor then:
+  * takes the source code,
+  * runs their test suite,
+  * adds any required fixes or backports,
+  * publishes it as open source, and
+  * sells their customers binaries with a long-term support package
+
+Note:
+
+They are a downstream of a whole bunch of open source packages - GCC, glibc, LibreOffice, bash, etc.
+
+## It's the same model
+
+* Ferrocene is a downstream of The Rust Project
+* The Rust Project makes toolchain releases
+* Ferrous Systems then:
+  * takes the source code,
+  * runs their test suite,
+  * adds any required fixes or backports,
+  * publishes it as open source, and
+  * sells their customers binaries with a long-term support package
+
+## Yes, Ferrocene is Open Source
+
+We think it's the world's first open-source qualified toolchain
+
+## Yes, there's Long Term Support
+
+* You can buy support on a commercial basis
+* More on this later

src/exploring.md

@@ -0,0 +1,45 @@
+# Exploring the installation
+
+## What do you get?
+
+```console
+$ ls -F /opt/ferrocene-23.06
+bin/  etc/  lib/  libexec/  share/
+$ ls -F /opt/ferrocene-23.06/bin
+cargo*  ferrocene-self-test*  rust-gdb*  rust-gdbgui*  rust-lldb*  rustc*  rustdoc*
+$ ls -F /opt/ferrocene-23.06/etc
+bash_completion.d/
+$ ls -F /opt/ferrocene-23.06/lib
+librustc_driver-c3ee1e25139c0393.so  libstd-8aa647671c2dc036.so
+libtest-eab3dde10cbeff80.so          rustlib/
+$ ls -F /opt/ferrocene-23.06/libexec
+cargo-credential-1password*  rust-analyzer-proc-macro-srv*
+$ ls -F /opt/ferrocene-23.06/share
+doc/ man/ zsh/
+```
+
+## Is that docs?
+
+```console
+$ ls -F /opt/ferrocene-23.06/share/doc/
+cargo/  ferrocene/  rust/
+$ ls -F /opt/ferrocene-23.06/share/doc/cargo/
+LICENSE-APACHE  LICENSE-MIT  LICENSE-THIRD-PARTY  README.md
+$ ls -F /opt/ferrocene-23.06/share/doc/rust/
+COPYRIGHT  LICENSE-APACHE  LICENSE-MIT  README.md
+$ ls -F /opt/ferrocene-23.06/share/doc/ferrocene/
+html/
+$ open /opt/ferrocene-23.06/share/doc/ferrocene/html/index.html
+```
+
+---
+
+![The docs page](./images/docs1.png)
+
+---
+
+![The docs page](./images/docs2.png)
+
+---
+
+![The docs page](./images/docs3.png)

src/front-matter.md

@@ -1 +1,34 @@
 # Front Matter
+
+## Introduction
+
+In our one hour session on _Why Ferrocene?_ you will learn what Ferrocene is
+about, where it is from and where it is going, and whether it is right for you
+to look at Ferrocene for your next security-related or safety-critical project.
+The agenda includes a short lecture, a live programming demonstration, and a
+Q&A session.
+
+We conduct all training sessions remotely using modern video-conferencing tools
+to ensure the best learning experience.
+
+This repository contains the teaching material for this course.
+
+## Learning Goals
+
+These are the questions you will be able to answer after attending this course:
+
+- What is Ferrocene?
+- Is Ferrocene a fork of Rust?
+- What support is available for Ferrocene?
+- What is it like using Ferrocene?
+
+## Timetable
+
+Our standard timetable for this course is as follows:
+
+| Duration | Contents                                             |
+| :------: | :--------------------------------------------------- |
+|   0:05   | Room open, meet and greet                            |
+|   0:20   | Session 1 - What is Ferrocene?                       |
+|   0:20   | Session 2 - A Live Demo                              |
+|   0:15   | Q&A                                                  |

src/installing.md

@@ -0,0 +1,27 @@
+# Installing Ferrocene today
+
+## Ferrocene 23.06
+
+* Ships as tarballs
+* Unpack tarballs into, e.g. `/opt/ferrocene-23.06`
+
+## Step-by-step
+
+1. Set up Ubuntu 18.04 for AMD64
+2. Install:
+   * `gcc-aarch64-linux-gnu`
+   * `gcc` and `build-essential`
+   * `xz-utils`
+3. `mkdir /opt/ferrocene-23.06`
+4. `tar xvf <tarball> -C /opt/ferrocene-23.06`
+5. Modify `~/.bashrc` to put `/opt/ferrocene-23.06/bin` in your `$PATH`
+
+I use Docker for this. YMMV.
+
+## Installing in the future
+
+We have `criticalup` - like `rustup` but for fetching, verifying and installing
+digitally signed Ferrocene tarballs using your subscriber credentials.
+
+You can also use `criticalup` to fetch and verify the install tarballs, ready
+for transfer to a non-Internet-connected computer for installation there.

src/iso26262.md

@@ -1 +1,72 @@
 # ISO 26262 Qualification
+
+## Quality is a process
+
+* You can't pour a bucket of quality into a finished product
+* It's a process you follow throughout the product life-cycle
+* You might follow a process that is in accordance with a published ISO standard
+
+## Certification and Qualification
+
+* You are responsible for __certifying__ that the development of *your* product
+  was in accordance with such a standard.
+* You might choose tools that are __qualified__ as being suitable for use with
+  such a standards compliant process.
+
+## What is ISO 26262?
+
+> (ISO 26262-1:2018) is intended to be applied to safety-related systems that
+> include one or more electrical and/or electronic (E/E) systems and that are
+> installed in series production road vehicles, excluding mopeds.
+>
+> The document addresses possible hazards caused by malfunctioning behaviour of
+> safety-related E/E systems, including interaction of these systems.
+
+From [iso.org](https://www.iso.org/standard/68383.html)
+
+## And that has qualified tools?
+
+ISO 26262-8:2018(E), Section 11.1.b says:
+
+> to provide means for the qualification of the software tool when applicable,
+> in order to create evidence that the software tool is suitable to be used to
+> support the activities or tasks required by the ISO 26262 series of standards
+> (i.e. the user can rely on the correct functioning of a software tool for
+> those activities or tasks required by the ISO 26262 series of standards).
+
+## Confidence in your Tools
+
+* What is the tool supposed to do?
+* Does it do what it is supposed to do?
+* Does someone I trust believe it does what it is supposed to do?
+
+## What is the tool supposed to do?
+
+* Rust doesn't have a written specification ... yet.
+* So we wrote the Ferrocene Language Specification
+  * <https://spec.ferrocene.dev>
+
+## Does it do what it is supposed to do?
+
+* Rust already had an __excellent__ test suite
+* Our work was mainly __joining the dots__ between the tests and the
+  specification, and __automating everything__
+* Nothing hits our main branch unless the tests pass
+* We then documented everything in a Safety Manual
+
+## Does someone I trust believe it does what it is supposed to do?
+
+We sent all our evidence to TÜV SÜD for ISO 26262 and IEC 61508 qualification.
+
+So, far they say:
+
+> ...from the general approach, structure, format and contents of the
+> provided artifacts there no major questions or anything missing.
+
+The final qualification results will be announced in due course.
+
+## And I get?
+
+You can purchase from us the digitally-signed Qualification Documents. You can
+then provide these to *your* assessor when certifying *your* development
+process.