From 91a820fd616b7fa5aabafdb3021e944329fe7055 Mon Sep 17 00:00:00 2001 From: Eric Bariaux <375613+ebariaux@users.noreply.github.com> Date: Sat, 24 May 2025 16:51:47 +0200 Subject: [PATCH 1/8] Fix typos --- Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/ABI.md | 2 +- .../Documentation.docc/GettingStarted/Introduction.md | 2 +- .../Documentation.docc/GuidedExamples/PicoGuide.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/ABI.md b/Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/ABI.md index dfb2c89..54aee6a 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/ABI.md +++ b/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 diff --git a/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md b/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md index 8bfbbc8..734d14d 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md +++ b/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md @@ -22,7 +22,7 @@ It's also a good mental model to think of the Swift compiler in Embedded Swift m 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. diff --git a/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/PicoGuide.md b/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/PicoGuide.md index c2f956f..9592c5a 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/PicoGuide.md +++ b/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/PicoGuide.md @@ -49,7 +49,7 @@ 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: +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 From e79c9ae6c77b6ede4cd377d1fabf1ef0b37c59d3 Mon Sep 17 00:00:00 2001 From: Eric Bariaux <375613+ebariaux@users.noreply.github.com> Date: Sat, 24 May 2025 16:52:26 +0200 Subject: [PATCH 2/8] Fix links --- .../Documentation.docc/CompilerDetails/Status.md | 2 +- .../Documentation.docc/GettingStarted/LanguageSubset.md | 2 +- .../Documentation.docc/GuidedExamples/PicoGuide.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/Status.md b/Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/Status.md index 96f9286..0c094d0 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/Status.md +++ b/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 <[Embedded Swift -- Non-final generic methods](NonFinalGenericMethods)>| | Parameter packs (variadic generics) | No, not yet supported | ## Embedded Standard Library Breakdown diff --git a/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md b/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md index c58e828..b3e27c4 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md +++ b/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md @@ -27,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 [Embedded Swift -- Status](status). diff --git a/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/PicoGuide.md b/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/PicoGuide.md index 9592c5a..002c8a1 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/PicoGuide.md +++ b/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/PicoGuide.md @@ -23,7 +23,7 @@ $ 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. @@ -48,7 +48,7 @@ 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. +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: ``` From fadd901db439117eaf536b0637e0dfd90a4aefb9 Mon Sep 17 00:00:00 2001 From: Eric Bariaux <375613+ebariaux@users.noreply.github.com> Date: Sat, 24 May 2025 16:52:37 +0200 Subject: [PATCH 3/8] Add nRF52840 to the list --- .../Documentation.docc/GettingStarted/Introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md b/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md index 734d14d..15d6921 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md +++ b/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md @@ -41,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 From 2cce7c243cfab271e1c475ab165ce543d75a8144 Mon Sep 17 00:00:00 2001 From: Eric Bariaux <375613+ebariaux@users.noreply.github.com> Date: Sat, 24 May 2025 16:52:52 +0200 Subject: [PATCH 4/8] Add output of running minicom --- .../GuidedExamples/STM32BaremetalGuide.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/STM32BaremetalGuide.md b/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/STM32BaremetalGuide.md index 95d7fd7..c80b19e 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/STM32BaremetalGuide.md +++ b/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: From b105eb5f38e46e272083d37c7b202f8da30d50fa Mon Sep 17 00:00:00 2001 From: Eric Bariaux <375613+ebariaux@users.noreply.github.com> Date: Sat, 24 May 2025 16:53:23 +0200 Subject: [PATCH 5/8] Making links "clickable" --- .../Documentation.docc/SDKSupport/IntegrateWithPico.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegrateWithPico.md b/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegrateWithPico.md index b56fc1d..bec9dbc 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegrateWithPico.md +++ b/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegrateWithPico.md @@ -6,8 +6,8 @@ Setting up a project that can seamlessly use C APIs from the Pico SDK. Development for [Raspberry Pi Pico and Pico W](https://www.raspberrypi.com/products/raspberry-pi-pico/) normally uses the [Pico SDK](https://github.com/raspberrypi/pico-sdk) and the vendor provides several [sample projects in the pico-examples repository](https://github.com/raspberrypi/pico-examples). The SDK and sample project setup is described in: -- https://www.raspberrypi.com/documentation/microcontrollers/c_sdk.html#sdk-setup -- https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf +- [https://www.raspberrypi.com/documentation/microcontrollers/c_sdk.html#sdk-setup](https://www.raspberrypi.com/documentation/microcontrollers/c_sdk.html#sdk-setup) +- [https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf](https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf) Before trying to use Swift with the Pico SDK, make sure your environment works and can build the provided C/C++ sample projects. From a6701d187ed7365ab74fd898fdf43ab8065a87ca Mon Sep 17 00:00:00 2001 From: Eric Bariaux <375613+ebariaux@users.noreply.github.com> Date: Sat, 24 May 2025 16:54:09 +0200 Subject: [PATCH 6/8] Complete missing sentences --- .../EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md | 2 +- .../Documentation.docc/SDKSupport/IntegratingWithPlatforms.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md b/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md index aba4b51..c4d971d 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md +++ b/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md @@ -167,7 +167,7 @@ To build an Embedded Swift baremetal project with SwiftPM, you will need a setup - Your main application target defined in Package.swift. - A helper C code helper target defined in Package.swift - this will contain your C startup code, vector table and possibly an assembly file. -- Invoke `swift build` with a `--triple` argument that specifies. +- Invoke `swift build` with a `--triple` argument that specifies the target CPU architecture and output object file format. - Use a `toolset.json` file that defines the common Swift and C compilation flags, and linking flags. This will e.g. enable the Embedded Swift mode when compiling Swift code, and point the linker at the right linker script. Example file structure: diff --git a/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegratingWithPlatforms.md b/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegratingWithPlatforms.md index ac43e34..2d14463 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegratingWithPlatforms.md +++ b/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegratingWithPlatforms.md @@ -66,7 +66,7 @@ For detailed instructions on integrating with the Raspberry Pi Pico SDK, see . Note that only chips based on RISC-V architecture (e.g. ESP32-C3, ESP32-C6, ESP32-P4) are supported with Embedded Swift. The Xtensa ISA (used in e.g. ESP8266 or ESP32-S2 and ESP32-S3). +For ESP microcontrollers using the ESP-IDF framework, see . Note that only chips based on RISC-V architecture (e.g. ESP32-C3, ESP32-C6, ESP32-P4) are supported with Embedded Swift. The Xtensa ISA (used in e.g. ESP8266 or ESP32-S2 and ESP32-S3) is not supported. ### STM32 From 27a02deac44bdb144e08913093d35c3153f95040 Mon Sep 17 00:00:00 2001 From: Eric Bariaux <375613+ebariaux@users.noreply.github.com> Date: Sat, 24 May 2025 16:55:07 +0200 Subject: [PATCH 7/8] Fixed some grammar, to be reviewed --- .../EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md b/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md index c4d971d..bb91bbb 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md +++ b/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md @@ -120,9 +120,9 @@ void ResetISR(void) { } ``` -Both these code snippets are not fully functional, they are only demonstrating the complexity of what the linker script and startup code need to do to initialize handle global variables. +Both these code snippets are not fully functional, they are only demonstrating the complexity of what the linker script and startup code need to do to initialize global variables. -Tip: If this handling is not done correctly, a typical symptom is that global variables "don't work", i.e. reading from them doesn't yield the right value, and writing to them doesn't persist. A good way to double check this is by using a debugging a dumping memory at runtime and checking if it matches the virtual memory layout of the ELF file. +Tip: If this handling is not done correctly, a typical symptom is that global variables "don't work", i.e. reading from them doesn't yield the right value, and writing to them doesn't persist. A good way to double check this is by using a debugger, dumping memory at runtime and checking if it matches the virtual memory layout of the ELF file. ## Vector table and interrupts From 8e20c87c4a63b67581579a16d691d08123cc588e Mon Sep 17 00:00:00 2001 From: Eric Bariaux <375613+ebariaux@users.noreply.github.com> Date: Wed, 28 May 2025 20:16:18 +0200 Subject: [PATCH 8/8] Use doc links instead of markdown ones --- .../EmbeddedSwift/Documentation.docc/CompilerDetails/Status.md | 2 +- .../Documentation.docc/GettingStarted/LanguageSubset.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/Status.md b/Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/Status.md index 0c094d0..a1d156f 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/Status.md +++ b/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)>| +| Non-final generic class methods | No, intentionally unsupported long-term, see | | Parameter packs (variadic generics) | No, not yet supported | ## Embedded Standard Library Breakdown diff --git a/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md b/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md index b3e27c4..1120fbb 100644 --- a/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md +++ b/Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md @@ -27,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](status). +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 .