Expand docs: Baremetal setup, update pico integration (#142)

Author: kubamracek

Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/ABI.md

@@ -30,7 +30,7 @@ The layout of Embedded Swift's class metadata is *different* from full Swift:
 - The **destructor pointer** is stored at **offset 1**. This function is invoked by Swift's deallocator when the class instance is destroyed.
 - The **ivar destroyer** is stored at **offset 2**. This function is invoked to destroy instance members when creation of the object is cancelled (e.g. in a failable initializer).
 - Lastly, the **vtable** is stored at **offset 3**: For each Swift class in the class's inheritance hierarchy, in order starting
-  from the root class and working down to the most derived class, the function pointers to the implementation of every method of the class in declaration order in stored.
+  from the root class and working down to the most derived class, the function pointers to the implementation of every method of the class in declaration order is stored.
 
 ### Witness Tables ABI
 

Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/Status.md

@@ -16,7 +16,7 @@ Implementation status of compiler and language features in Embedded Swift, compa
 | Metatypes                                             | No, currently only allowed as unused arguments (type hints)                        |
 | Untyped throwing                                      | No, intentionally unsupported long-term (typed throwing should be used instead)    |
 | Weak references, unowned references                   | No                                                                                 |
-| Non-final generic class methods                       | No, intentionally unsupported long-term, see <[Embedded Swift -- Non-final generic methods](NonFinalGenericMethods.md)>|
+| Non-final generic class methods                       | No, intentionally unsupported long-term, see <doc:NonFinalGenericMethods>|
 | Parameter packs (variadic generics)                   | No, not yet supported                                                              |
 
 ## Embedded Standard Library Breakdown

Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md

@@ -17,10 +17,13 @@ Regular Swift is not a good fit for small constrained environments like microcon
 - Using compile-time specialization (monomorphization) for generic code
 - Minimizing dependencies on external libraries
 
+It's also a good mental model to think of the Swift compiler in Embedded Swift mode as operating on a way a *traditional C compiler* does — specifically in the sense that the compiler produces an object file that does not call into or depend on symbols that are not explicitly used in the source code. This is achieved even for code that uses generics, protocols, tuples, arrays, and more — all the higher-level language features are "compiled out" (e.g. generics are specialized), and standard library code is pulled into the object file as needed (e.g. array implementation).
+
 This results in properties that are a great fit for embedded software development:
 
 - **Small binaries** that can be as tiny as a few hundred bytes for "Hello World"-like programs (fully self-contained).
-- **No hidden runtime costs** – Embedded Swift's runtime library does not manage any data structures behind your back, is itself less than a kilobyte in size, and it eligible to be removed if unused.
+- **No hidden runtime costs** – Embedded Swift's runtime library does not manage any data structures behind your back, is itself less than a kilobyte in size, and is eligible to be removed if unused.
+- **No hidden allocations** which would cause unpredictable performance cliffs.
 - **Full C/C++ interoperability** to directly interact with existing C libraries and hardware-specific code, making it easy to integrate with vendor SDKs.
 - **Modern language features** like optionals, generics, and strong type safety are all available in Embedded Swift.
 - **Full safety of Swift** is retained in Embedded Swift.
@@ -38,7 +41,7 @@ For a detailed introduction and motivation into Embedded Swift, please see "[A V
 
 The Swift toolchain has the ability to produce code for almost any standard ARM and RISC-V platform, and that makes Embedded Swift versatile and not limited to specific platforms or hardware devices. This way, Embedded Swift can potentially target many different microcontroller families and embedded devices.
 
-Boards with active community support include the Raspberry Pi Pico, various STM32 development boards, and several ESP32 variants, with more platforms being regularly added as the community grows.
+Boards with active community support include the Raspberry Pi Pico, various STM32 development boards, various nRF52840 based boards and several ESP32 variants, with more platforms being regularly added as the community grows.
 
 ## Interoperability with existing SDKs
 

Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md

@@ -14,9 +14,10 @@ Note that there are no behavior changes in Embedded Swift compared to full Swift
 - **Not available**: Values of protocol types ("existentials"), unless the protocol is restricted to be class-bound (derived from AnyObject). E.g. `let a: Hashable = ...` is not allowed. `Any` is also not allowed. See <doc:Existentials> for details and alternatives of existentials.
 - **Not available**: Throwing errors or `any Error` type (in contrast with "typed throws", which *is* supported in Embedded Swift).
 - **Not available**: Metatypes, e.g. `let t = SomeClass.Type` or `type(of: value)` are not allowed.
+- **Not available**: Standard library types that rely on the above, for example `Codable` and `KeyPath`, are not allowed.
 - **Not available**: Printing and stringification of arbitrary types (which is achieved via reflection in desktop Swift).
 - **Not available**: Using non-final generic class methods. See <doc:NonFinalGenericMethods> for details on this.
-- **Not available**: Weak and unowned references.
+- **Not available**: Weak and unowned references are not allowed (unsafe unowned references *are* available).
 
 ## Compilation facilities that are not available
 
@@ -26,4 +27,4 @@ Note that there are no behavior changes in Embedded Swift compared to full Swift
 
 ## Further resources
 
-The above lists are describing features that are removed from Embedded Swift *by design*. Since Embedded Swift is currently an experimental preview, there might also be  features that are not yet implemented. See the in-development status at [Embedded Swift -- Status](EmbeddedSwiftStatus.md).
+The above lists are describing features that are removed from Embedded Swift *by design*. Since Embedded Swift is currently an experimental preview, there might also be  features that are not yet implemented. See the in-development status at <doc:Status>.

Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/PicoGuide.md

@@ -6,13 +6,11 @@ In this guide we'll be targeting a Raspberry Pi Pico as the embedded device that
 
 ## Installing Swift
 
-If you don’t have Swift installed, [install it first](https://www.swift.org/install). Because Embedded Swift is experimental and only available in preview toolchains, make sure to install the "Development Snapshot" toolchain (main) instead of a release toolchain (6.0). If you're using a macOS machine, you will need to make sure the installed toolchain is selected as active e.g. by exporting the `TOOLCHAINS` environment variable:
+> Warning: Embedded Swift is experimental. Use the latest downloadable 'Trunk Development' snapshot from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.
 
-```shell
-$ export TOOLCHAINS=org.swift.59202405011a
-```
+To install Swift for embedded development, follow the instructions in <doc:InstallEmbeddedSwift>, which guides you through using `swiftly` to install the latest development snapshot with Embedded Swift support.
 
-To test that you have Swift installed, run `swift --version` from your shell or terminal app. It should say "6.0-dev", meaning you have a "Development Snapshot" toolchain.
+To test that you have Swift installed, run `swift --version` from your shell or terminal app. It should say "6.2-dev" or similar, confirming you have a "Development Snapshot" toolchain.
 
 ## Installing dependencies for embedded development
 
@@ -25,15 +23,15 @@ $ export PICO_SDK_PATH=...       # location to your Pico SDK
 $ export PICO_TOOLCHAIN_PATH=... # location to the Arm Embedded Toolchain
 ```
 
-If you have the Wi-Fi enabled Pico W board instead of the regular Pico, note that you will need a slightly different setup described in the [Pico W example project](https://github.com/apple/swift-embedded-examples/tree/main/pico-w-blink-sdk), and just specifying `PICO_BOARD=pico_w` is not going to work.
+If you have the Wi-Fi enabled Pico W board instead of the regular Pico, note that you will need a slightly different setup described in the [Pico W example project](https://github.com/apple/swift-embedded-examples/tree/main/rpi-picow-blink-sdk), and just specifying `PICO_BOARD=pico_w` is not going to work.
 
 Install [CMake 3.29](https://cmake.org/) or newer.
 
 To test that you have all the necessary parts installed, you can run the following commands in a terminal:
 
 ```shell
 $ swift --version
-Apple Swift version 6.0-dev (LLVM b66077aefd3be08, Swift 84d36181a762913)
+Apple Swift version 6.2-dev (LLVM 81ab6d9f7e4810f, Swift 9cc1947527bacea)
 $ cmake --version
 cmake version 3.29.2
 $ echo $PICO_BOARD
@@ -50,8 +48,8 @@ bin/                                               libexec/
 
 ## Building a "blinky" embedded app
 
-The standard "Hello, World" in embedded development is a program that repeatedly blinks an LED. Let's build one. The following setup can be also found in [swift-embedded-examples](https://github.com/apple/swift-embedded-examples/blob/main/pico-blink-sdk/README.md), but we're going to show below that all you need is just three files.
-Let's create a new empty directory and prepare a simple structure for a CMake-based project that can be used on top the Pico SDK:
+The standard "Hello, World" in embedded development is a program that repeatedly blinks an LED. Let's build one. The following setup can be also found in [swift-embedded-examples](https://github.com/apple/swift-embedded-examples/blob/main/rpi-pico-blink-sdk/README.md), but we're going to show below that all you need is just three files.
+Let's create a new empty directory and prepare a simple structure for a CMake-based project that can be used on top of the Pico SDK:
 
 ```
 embedded-swift-tutorial

Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/STM32BaremetalGuide.md

@@ -350,8 +350,14 @@ $ brew install stlink
 $ st-info --probe
 ... TODO
 $ brew install minicom
-$ minicom
-... TODO
+$ minicom --version
+minicom version 2.10 (compiled Feb 22 2025)
+Copyright (C) Miquel van Smoorenburg.
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version
+2 of the License, or (at your option) any later version.
 ```
 
 Then let's fetch the elf2hex tool: