docs: improve language in bare-metal section (#2891)

I asked Gemini to review the English for inconsistencies and grammar
mistakes. This is the result and I hope it's useful!

As a non-native speaker, it is hard for me to evaluate the finer
details, so let me know if you would like to see changes (or even
better: make them directly in the PR with the suggestion function).

---------

Co-authored-by: Dmitri Gribenko <[email protected]>

Author: mgeisler

src/bare-metal/aps/better-uart.md

@@ -1,8 +1,8 @@
 # A better UART driver
 
-The PL011 actually has [a bunch more registers][1], and adding offsets to
-construct pointers to access them is error-prone and hard to read. Plus, some of
-them are bit fields which would be nice to access in a structured way.
+The PL011 actually has [more registers][1], and adding offsets to construct
+pointers to access them is error-prone and hard to read. Additionally, some of
+them are bit fields, which would be nice to access in a structured way.
 
 | Offset | Register name | Width |
 | ------ | ------------- | ----- |
@@ -23,7 +23,7 @@ them are bit fields which would be nice to access in a structured way.
 
 <details>
 
-- There are also some ID registers which have been omitted for brevity.
+- There are also some ID registers that have been omitted for brevity.
 
 </details>
 

src/bare-metal/aps/entry-point.md

@@ -1,6 +1,6 @@
 # Getting Ready to Rust
 
-Before we can start running Rust code, we need to do some initialisation.
+Before we can start running Rust code, we need to do some initialization.
 
 ```armasm
 {{#include examples/src/entry.S:entry}}
@@ -12,36 +12,36 @@ This code is in `src/bare-metal/aps/examples/src/entry.S`. It's not necessary to
 understand this in detail -- the takeaway is that typically some low-level setup
 is needed to meet Rust's expectations of the system.
 
-- This is the same as it would be for C: initialising the processor state,
+- This is the same as it would be for C: initializing the processor state,
   zeroing the BSS, and setting up the stack pointer.
   - The BSS (block starting symbol, for historical reasons) is the part of the
-    object file which containing statically allocated variables which are
-    initialised to zero. They are omitted from the image, to avoid wasting space
+    object file that contains statically allocated variables that are
+    initialized to zero. They are omitted from the image, to avoid wasting space
     on zeroes. The compiler assumes that the loader will take care of zeroing
     them.
-- The BSS may already be zeroed, depending on how memory is initialised and the
+- The BSS may already be zeroed, depending on how memory is initialized and the
   image is loaded, but we zero it to be sure.
 - We need to enable the MMU and cache before reading or writing any memory. If
   we don't:
   - Unaligned accesses will fault. We build the Rust code for the
-    `aarch64-unknown-none` target which sets `+strict-align` to prevent the
-    compiler generating unaligned accesses, so it should be fine in this case,
-    but this is not necessarily the case in general.
+    `aarch64-unknown-none` target that sets `+strict-align` to prevent the
+    compiler from generating unaligned accesses, so it should be fine in this
+    case, but this is not necessarily the case in general.
   - If it were running in a VM, this can lead to cache coherency issues. The
     problem is that the VM is accessing memory directly with the cache disabled,
     while the host has cacheable aliases to the same memory. Even if the host
     doesn't explicitly access the memory, speculative accesses can lead to cache
     fills, and then changes from one or the other will get lost when the cache
     is cleaned or the VM enables the cache. (Cache is keyed by physical address,
     not VA or IPA.)
-- For simplicity, we just use a hardcoded pagetable (see `idmap.S`) which
+- For simplicity, we just use a hardcoded pagetable (see `idmap.S`) that
   identity maps the first 1 GiB of address space for devices, the next 1 GiB for
   DRAM, and another 1 GiB higher up for more devices. This matches the memory
   layout that QEMU uses.
 - We also set up the exception vector (`vbar_el1`), which we'll see more about
   later.
 - All examples this afternoon assume we will be running at exception level 1
-  (EL1). If you need to run at a different exception level you'll need to modify
-  `entry.S` accordingly.
+  (EL1). If you need to run at a different exception level, you'll need to
+  modify `entry.S` accordingly.
 
 </details>

src/bare-metal/aps/inline-assembly.md

@@ -16,15 +16,15 @@ for all these functions.)
 - PSCI is the Arm Power State Coordination Interface, a standard set of
   functions to manage system and CPU power states, among other things. It is
   implemented by EL3 firmware and hypervisors on many systems.
-- The `0 => _` syntax means initialise the register to 0 before running the
+- The `0 => _` syntax means initialize the register to 0 before running the
   inline assembly code, and ignore its contents afterwards. We need to use
   `inout` rather than `in` because the call could potentially clobber the
   contents of the registers.
 - This `main` function needs to be `#[unsafe(no_mangle)]` and `extern "C"`
   because it is called from our entry point in `entry.S`.
   - Just `#[no_mangle]` would be sufficient but
     [RFC3325](https://rust-lang.github.io/rfcs/3325-unsafe-attributes.html) uses
-    this notation to draw reviewer attention to attributes which might cause
+    this notation to draw reviewer attention to attributes that might cause
     undefined behavior if used incorrectly.
 - `_x0`–`_x3` are the values of registers `x0`–`x3`, which are conventionally
   used by the bootloader to pass things like a pointer to the device tree.

src/bare-metal/aps/logging.md

@@ -9,7 +9,7 @@ We can do this by implementing the `Log` trait.
 
 <details>
 
-- The first unwrap in `log` will succeed because we initialise `LOGGER` before
+- The first unwrap in `log` will succeed because we initialize `LOGGER` before
   calling `set_logger`. The second will succeed because `Uart::write_str` always
   returns `Ok`.
 

src/bare-metal/aps/mmio.md

@@ -28,7 +28,7 @@ unsafe {
     compiler may assume that the value read is the same as the value just
     written, and not bother actually reading memory.
 - Some existing crates for volatile access to hardware do hold references, but
-  this is unsound. Whenever a reference exist, the compiler may choose to
+  this is unsound. Whenever a reference exists, the compiler may choose to
   dereference it.
 - Use `&raw` to get struct field pointers from a pointer to the struct.
 - For compatibility with old versions of Rust you can use the [`addr_of!`] macro

src/bare-metal/aps/other-projects.md

@@ -5,9 +5,9 @@
   - Supports x86, aarch64 and RISC-V.
   - Relies on LinuxBoot rather than having many drivers itself.
 - [Rust RaspberryPi OS tutorial](https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials)
-  - Initialisation, UART driver, simple bootloader, JTAG, exception levels,
+  - Initialization, UART driver, simple bootloader, JTAG, exception levels,
     exception handling, page tables.
-  - Some dodginess around cache maintenance and initialisation in Rust, not
+  - Some caveats around cache maintenance and initialization in Rust, not
     necessarily a good example to copy for production code.
 - [`cargo-call-stack`](https://crates.io/crates/cargo-call-stack)
   - Static analysis to determine maximum stack usage.

src/bare-metal/aps/safemmio/driver.md

@@ -17,14 +17,14 @@ Now let's use the new `Registers` struct in our driver.
 - These MMIO accesses are generally a wrapper around `read_volatile` and
   `write_volatile`, though on aarch64 they are instead implemented in assembly
   to work around a bug where the compiler can emit instructions that prevent
-  MMIO virtualisation.
+  MMIO virtualization.
 - The `field!` and `field_shared!` macros internally use `&raw mut` and
   `&raw const` to get pointers to individual fields without creating an
   intermediate reference, which would be unsound.
 - `field!` needs a mutable reference to a `UniqueMmioPointer`, and returns a
-  `UniqueMmioPointer` which allows reads with side effects and writes.
+  `UniqueMmioPointer` that allows reads with side effects and writes.
 - `field_shared!` works with a shared reference to either a `UniqueMmioPointer`
-  or a `SharedMmioPointer`. It returns a `SharedMmioPointer` which only allows
+  or a `SharedMmioPointer`. It returns a `SharedMmioPointer` that only allows
   pure reads.
 
 </details>

src/bare-metal/aps/safemmio/registers.md

@@ -1,6 +1,6 @@
 # safe-mmio
 
-The [`safe-mmio`] crate provides types to wrap registers which can be read or
+The [`safe-mmio`] crate provides types to wrap registers that can be read or
 written safely.
 
 |             | Can't read    | Read has no side-effects | Read has side-effects |
@@ -23,7 +23,7 @@ written safely.
   operations; we recommend the `safe-mmio` crate.
 - The difference between `ReadPure` or `ReadOnly` (and likewise between
   `ReadPureWrite` and `ReadWrite`) is whether reading a register can have
-  side-effects which change the state of the device. E.g. reading the data
+  side-effects that change the state of the device, e.g., reading the data
   register pops a byte from the receive FIFO. `ReadPure` means that reads have
   no side-effects, they are purely reading data.
 

src/bare-metal/microcontrollers/board-support.md

@@ -12,7 +12,7 @@ for convenience.
 <details>
 
 - In this case the board support crate is just providing more useful names, and
-  a bit of initialisation.
+  a bit of initialization.
 - The crate may also include drivers for some on-board devices outside of the
   microcontroller itself.
   - `microbit-v2` includes a simple driver for the LED matrix.

src/bare-metal/microcontrollers/embedded-hal.md

@@ -16,8 +16,8 @@ accelerometer driver might need an I2C or SPI device instance.
 
 <details>
 
-- The traits cover using the peripherals but not initialising or configuring
-  them, as initialisation and configuration is usually highly platform-specific.
+- The traits cover using the peripherals but not initializing or configuring
+  them, as initialization and configuration is usually highly platform-specific.
 - There are implementations for many microcontrollers, as well as other
   platforms such as Linux on Raspberry Pi.
 - [`embedded-hal-async`] provides async versions of the traits.