From 37b4d3efd9e98f081cf23f813a39d8b2e151cd8b Mon Sep 17 00:00:00 2001 From: Mathias Brossard Date: Mon, 26 May 2025 22:31:34 -0500 Subject: [PATCH 1/3] Add new section 'Supporting a new SoC' --- src/SUMMARY.md | 1 + src/soc-support.md | 183 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 184 insertions(+) create mode 100644 src/soc-support.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 2d2fcd3..61f47fa 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -12,3 +12,4 @@ --- [A note on compiler support](./compiler-support.md) [Creating a custom target](./custom-target.md) +[Supporting a new SoC](./soc-support.md) diff --git a/src/soc-support.md b/src/soc-support.md new file mode 100644 index 0000000..69ff926 --- /dev/null +++ b/src/soc-support.md @@ -0,0 +1,183 @@ +# Guide for Silicon Vendors to Enable Rust Support for Their SoCs + +## Introduction + +Rust has emerged as a powerful and safety-focused programming language, gaining +traction among embedded developers. Silicon vendors who wish to enable Rust +support for their System-on-Chip (SoC) products can benefit from this trend by +attracting a growing community of Rust developers. + +This guide aims to help silicon vendors enable Rust support, either +independently or by empowering third-party developers. It outlines the +essential resources, tasks, and priorities required to foster a robust Rust +ecosystem around their System-on-Chip (SoC). + +**Note:** For assistance with strategy in engaging with the community, we +recommend reaching out to the Embedded Rust Working Group (REWG) leads. They +can provide valuable insights and support to help you navigate the process +effectively. + +## Essential Resources + +### Documentation + +Detailed documentation is essential for effective development and debugging. It +enables developers to comprehend the System-on-Chip (SoC), including its memory +map, peripherals, interrupt handling, low-power modes, etc. Ensure that the +documentation covers all hardware aspects comprehensively, from register-level +details to system-level interactions. The documentation should be publicly +available; in cases where public availability is not feasible, any +non-disclosure agreement (NDA) must permit the publication of open-source code +derived from it. + +### Register Description Files + +Register description files are used to generate Peripheral Access Crates +(PACs). The most common format for these files is SVD +([System View Description](https://open-cmsis-pack.github.io/svd-spec)). Rust +developers have often encountered issues with SVD files, so it is crucial to +provide clear contact information for reporting any discrepancies or problems. +Up-to-date SVD files ensure that the community can collaborate effectively to +resolve issues and improve the quality of the PACs. + +### Flash Algorithms + +[Flash Algorithms](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/flashAlgorithm.html) +are integrated with debugging tools like `probe-rs`. They facilitate and speed +up firmware programming and debugging, streamlining development workflows. +Providing well-supported FlashAlgos will enhance the integration with these +tools and improve the overall developer experience. + +### Vendor Tooling + +Some System-on-Chip (SoC) devices require custom tools for generating images or +flashing them onto the device. It is beneficial to provide these tools in an +open-source manner, fostering community contributions and accelerating +ecosystem growth. Open-sourcing vendor tooling enables third-party developers +to extend and enhance the toolchain, ensuring improved compatibility with the +broader Embedded Rust ecosystem. + +### Contact Information + +Providing contact information is vital for addressing maintainer queries and +issues related to register description files or other resources. The use of a +public issue tracking system (like GitHub Issues) for reporting and tracking +problems might help. Actively engage with the community through forums, +discussions, and updates to build trust and collaboration. + +## Maintaining PAC and HAL Crates + +Peripheral Access Crates (PACs) and Hardware Abstraction Layer (HAL) crates are +at the core of enabling Rust support. + +### Generate and Maintain PACs + +Multiple tools such as `svd2rust`, `chiptool`, `raltool`, and `svd2pac` +automate the generation of PACs from register description files. Each tool has +its strengths, and selecting the right one depends on the requirements and the +complexity of the hardware. + +### Develop and Maintain HAL Crates + +Implement `embedded-hal` and `embedded-hal-async` traits in your HAL crates. +Adhering to these traits ensures compatibility across the Embedded Rust +ecosystem, enhancing interoperability. It is an essential goal that HALs use +Rust code rather than wrapping existing C code. An incremental porting +strategy, where Rust is used for all core functionality, but C with Rust +bindings is used for complex drivers, is acceptable, allowing for gradual +adoption and community contributions. + +Start with essential peripherals (clock, timer, GPIO) and expand progressively +(I2C, SPI, UART, etc.) based on community feedback. Release early and often to +engage the community and gather valuable insights for further development. + +### Common Recommendations + +- Ensure that crates are compatible with `no_std` environments, which are + common in embedded systems without an operating system. Functionality that + needs `alloc` or `std` can be included when gated with Cargo "features." +- Make your crates available on [crates.io](https://crates.io/) to maximize + visibility and ease of use for developers. +- Use semantic versioning to maintain consistency and predictability in your + releases. +- Prefer licenses like Apache 2.0 and MIT for their permissive nature, which + encourages broader adoption and collaboration. + +### Issue Tracking + +Effective issue tracking is crucial for maintaining a healthy and collaborative +ecosystem. Discuss triaging, labeling, and community involvement in issue +resolution. Implement transparent processes for: + +- Triage and prioritize issues based on severity and impact. +- Use labels to categorize issues (e.g., bugs, feature requests). +- Encourage community members to contribute to resolving issues by providing + feedback or submitting pull requests (PRs). + +### Facilitate Debugging and Testing + +The use of `probe-rs` is prevalent in the Embedded Rust ecosystem for debugging +and testing. Combined with debug-based facilities like `defmt-rtt`, which +offers logging capabilities for embedded systems, the Embedded Rust ecosystem +has developed numerous tools. `probe-rs` supports a wide range of target +architectures, debug interfaces, and debug probe protocols. + +Thorough testing ensures hardware-software reliability, and leveraging these +tools can significantly enhance development workflows. + +## Nice-to-Have Features for Enhanced Ecosystem Support + +### Examples + +Including some basic examples as part of the HAL is essential for helping +developers get started. These examples should demonstrate key functionalities, +such as initializing peripherals or handling interrupts. They serve as +practical starting points and learning aids. + +### BSP (Board Support Package) Crates + +BSP crates are relevant when you need to provide board-specific configurations +and initializations. Unlike HALs, which focus on hardware abstraction, BSPs +handle the integration of multiple components for a specific board. Having both +BSP and HAL crates offers a layered approach, making it easier for developers +to build applications targeting a particular hardware board. + +### Project Templates + +Project templates are boilerplate code structures that provide a starting point +for new projects. They include prevalent configurations, dependencies, and +setup steps, saving developers time and reducing the learning curve. Examples +of project templates include bare-metal (using the HAL without any framework), +Embassy, RTIC, and others. + +### Integration with Popular IDEs and Tools + +Offer guides on setting up development environments for Embedded Rust projects +with popular tools such as: + +- `rust-analyzer`: for Rust syntax highlighting and error checking. +- `probe-rs`: for flashing and debugging firmware. +- `defmt`: a logging framework optimized for embedded systems. +- `defmt-test`: testing utilities for `defmt`. + +Providing setup instructions for these tools will help developers integrate +them into their workflows, enhancing productivity and collaboration. + +## Conclusion + +Enabling Rust support for your SoC opens the door to a vibrant community of +developers who value safety, performance, and reliability. By providing +essential resources, maintaining high-quality PACs and HAL crates, and +fostering a supportive ecosystem, you empower both internal teams and +third-party developers to unlock the full potential of your hardware. + +As the Rust embedded ecosystem continues to grow, embracing these practices +positions your company at the forefront of this movement, attracting developers +passionate about building robust and innovative systems. Encourage ongoing +engagement with the Rust community to stay updated on best practices and tools, +ensuring your System-on-Chip (SoC) remains a preferred choice for Rust +developers. + +By following this guide, you can create a comprehensive and supportive +environment that not only enables Rust support but also nurtures a thriving +developer ecosystem around your products. From 02b473e57549f40797a179ff4fca88fe6810d4fb Mon Sep 17 00:00:00 2001 From: Mathias Brossard Date: Thu, 19 Jun 2025 22:38:09 -0500 Subject: [PATCH 2/3] Enhancements based on feedback from @rursprung and @felipebalbi --- src/soc-support.md | 71 ++++++++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 31 deletions(-) diff --git a/src/soc-support.md b/src/soc-support.md index 69ff926..1af08d3 100644 --- a/src/soc-support.md +++ b/src/soc-support.md @@ -13,7 +13,7 @@ essential resources, tasks, and priorities required to foster a robust Rust ecosystem around their System-on-Chip (SoC). **Note:** For assistance with strategy in engaging with the community, we -recommend reaching out to the Embedded Rust Working Group (REWG) leads. They +recommend reaching out to the Rust Embedded Working Group (REWG) leads. They can provide valuable insights and support to help you navigate the process effectively. @@ -43,10 +43,10 @@ resolve issues and improve the quality of the PACs. ### Flash Algorithms [Flash Algorithms](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/flashAlgorithm.html) -are integrated with debugging tools like `probe-rs`. They facilitate and speed -up firmware programming and debugging, streamlining development workflows. -Providing well-supported FlashAlgos will enhance the integration with these -tools and improve the overall developer experience. +are integrated with debugging tools like [probe-rs](https://probe.rs). They +facilitate and speed up firmware programming and debugging, streamlining +development workflows. Providing well-supported FlashAlgos will enhance the +integration with these tools and improve the overall developer experience. ### Vendor Tooling @@ -72,20 +72,23 @@ at the core of enabling Rust support. ### Generate and Maintain PACs -Multiple tools such as `svd2rust`, `chiptool`, `raltool`, and `svd2pac` -automate the generation of PACs from register description files. Each tool has -its strengths, and selecting the right one depends on the requirements and the -complexity of the hardware. +Multiple tools such as [svd2rust](https://crates.io/crates/svd2rust), +[chiptool](https://github.com/embassy-rs/chiptool), +[raltool](https://github.com/imxrt-rs/imxrt-ral/tree/master/raltool), and +[svd2pac](https://github.com/Infineon/svd2pac) automate the generation of PACs +from register description files. Each tool has its strengths, and selecting the +right one depends on the requirements and the complexity of the hardware. ### Develop and Maintain HAL Crates -Implement `embedded-hal` and `embedded-hal-async` traits in your HAL crates. -Adhering to these traits ensures compatibility across the Embedded Rust -ecosystem, enhancing interoperability. It is an essential goal that HALs use -Rust code rather than wrapping existing C code. An incremental porting -strategy, where Rust is used for all core functionality, but C with Rust -bindings is used for complex drivers, is acceptable, allowing for gradual -adoption and community contributions. +Implement [embedded-hal](https://crates.io/crates/embedded-hal) and +[embedded-hal-async](https://crates.io/crates/embedded-hal-async) traits in +your HAL crates. Adhering to these traits ensures compatibility across the +Embedded Rust ecosystem, enhancing interoperability. It is an essential goal +that HALs use Rust code rather than wrapping existing C code. An incremental +porting strategy, where all core functionality is implemented in Rust, but C +with Rust bindings is used for complex drivers, is acceptable, allowing for +gradual adoption and community contributions. Start with essential peripherals (clock, timer, GPIO) and expand progressively (I2C, SPI, UART, etc.) based on community feedback. Release early and often to @@ -95,11 +98,12 @@ engage the community and gather valuable insights for further development. - Ensure that crates are compatible with `no_std` environments, which are common in embedded systems without an operating system. Functionality that - needs `alloc` or `std` can be included when gated with Cargo "features." -- Make your crates available on [crates.io](https://crates.io/) to maximize + needs `alloc` or `std` can be included when gated with Cargo + [features](https://doc.rust-lang.org/cargo/reference/features.html). +- Make your crates available on [crates.io](https://crates.io) to maximize visibility and ease of use for developers. -- Use semantic versioning to maintain consistency and predictability in your - releases. +- Use [semantic versioning](https://semver.org) to maintain consistency and + predictability in your releases. - Prefer licenses like Apache 2.0 and MIT for their permissive nature, which encourages broader adoption and collaboration. @@ -116,11 +120,14 @@ resolution. Implement transparent processes for: ### Facilitate Debugging and Testing -The use of `probe-rs` is prevalent in the Embedded Rust ecosystem for debugging -and testing. Combined with debug-based facilities like `defmt-rtt`, which -offers logging capabilities for embedded systems, the Embedded Rust ecosystem -has developed numerous tools. `probe-rs` supports a wide range of target -architectures, debug interfaces, and debug probe protocols. +The Embedded Rust ecosystem offers various tools used for debugging +and testing, with [probe-rs](https://probe.rs) being one of the most widely +used. [probe-rs](https://probe.rs) supports a wide range +of target architectures, debug interfaces, and debug probe protocols. +Combined with debug-based facilities like +[defmt-rtt](https://crates.io/crates/defmt-rtt), which provide logging +capabilities for embedded systems, these tools form a robust foundation for +development. Thorough testing ensures hardware-software reliability, and leveraging these tools can significantly enhance development workflows. @@ -138,8 +145,8 @@ practical starting points and learning aids. BSP crates are relevant when you need to provide board-specific configurations and initializations. Unlike HALs, which focus on hardware abstraction, BSPs -handle the integration of multiple components for a specific board. Having both -BSP and HAL crates offers a layered approach, making it easier for developers +handle the integration of multiple components for a specific board. Separation +in BSP and HAL crates offers a layered approach, making it easier for developers to build applications targeting a particular hardware board. ### Project Templates @@ -155,10 +162,12 @@ Embassy, RTIC, and others. Offer guides on setting up development environments for Embedded Rust projects with popular tools such as: -- `rust-analyzer`: for Rust syntax highlighting and error checking. -- `probe-rs`: for flashing and debugging firmware. -- `defmt`: a logging framework optimized for embedded systems. -- `defmt-test`: testing utilities for `defmt`. +- [rust-analyzer](https://rust-analyzer.github.io): for Rust syntax + highlighting and error checking. +- [probe-rs](https://probe.rs): for flashing and debugging firmware. +- [defmt](https://crates.io/crates/defmt): a logging framework optimized for + embedded systems, including a test harness called + [defmt-test](https://crates.io/crates/defmt-test). Providing setup instructions for these tools will help developers integrate them into their workflows, enhancing productivity and collaboration. From a124ee3e5564aed0379b875961ebd5f08fbeb9ac Mon Sep 17 00:00:00 2001 From: Mathias Brossard Date: Tue, 15 Jul 2025 21:30:34 -0500 Subject: [PATCH 3/3] Add suggested flow and minor edits Suggested flow based on @jamesmunns's guide in Embassy FAQ --- src/soc-support.md | 86 +++++++++++++++++++++++++++++++++------------- 1 file changed, 63 insertions(+), 23 deletions(-) diff --git a/src/soc-support.md b/src/soc-support.md index 1af08d3..345d201 100644 --- a/src/soc-support.md +++ b/src/soc-support.md @@ -1,4 +1,4 @@ -# Guide for Silicon Vendors to Enable Rust Support for Their SoCs +# Guide for silicon vendors to enable Rust support for their SoCs ## Introduction @@ -17,7 +17,7 @@ recommend reaching out to the Rust Embedded Working Group (REWG) leads. They can provide valuable insights and support to help you navigate the process effectively. -## Essential Resources +## Essential resources ### Documentation @@ -30,7 +30,7 @@ available; in cases where public availability is not feasible, any non-disclosure agreement (NDA) must permit the publication of open-source code derived from it. -### Register Description Files +### Register description files Register description files are used to generate Peripheral Access Crates (PACs). The most common format for these files is SVD @@ -48,7 +48,7 @@ facilitate and speed up firmware programming and debugging, streamlining development workflows. Providing well-supported FlashAlgos will enhance the integration with these tools and improve the overall developer experience. -### Vendor Tooling +### Vendor tooling Some System-on-Chip (SoC) devices require custom tools for generating images or flashing them onto the device. It is beneficial to provide these tools in an @@ -57,7 +57,7 @@ ecosystem growth. Open-sourcing vendor tooling enables third-party developers to extend and enhance the toolchain, ensuring improved compatibility with the broader Embedded Rust ecosystem. -### Contact Information +### Contact information Providing contact information is vital for addressing maintainer queries and issues related to register description files or other resources. The use of a @@ -65,12 +65,12 @@ public issue tracking system (like GitHub Issues) for reporting and tracking problems might help. Actively engage with the community through forums, discussions, and updates to build trust and collaboration. -## Maintaining PAC and HAL Crates +## Maintaining PAC and HAL crates Peripheral Access Crates (PACs) and Hardware Abstraction Layer (HAL) crates are at the core of enabling Rust support. -### Generate and Maintain PACs +### Generate and maintain PACs Multiple tools such as [svd2rust](https://crates.io/crates/svd2rust), [chiptool](https://github.com/embassy-rs/chiptool), @@ -79,22 +79,23 @@ Multiple tools such as [svd2rust](https://crates.io/crates/svd2rust), from register description files. Each tool has its strengths, and selecting the right one depends on the requirements and the complexity of the hardware. -### Develop and Maintain HAL Crates +### Develop and maintain HAL crates -Implement [embedded-hal](https://crates.io/crates/embedded-hal) and -[embedded-hal-async](https://crates.io/crates/embedded-hal-async) traits in -your HAL crates. Adhering to these traits ensures compatibility across the -Embedded Rust ecosystem, enhancing interoperability. It is an essential goal -that HALs use Rust code rather than wrapping existing C code. An incremental -porting strategy, where all core functionality is implemented in Rust, but C -with Rust bindings is used for complex drivers, is acceptable, allowing for -gradual adoption and community contributions. +Implement [embedded-hal](https://crates.io/crates/embedded-hal), +[embedded-hal-async](https://crates.io/crates/embedded-hal-async), and +[embedded-io](https://crates.io/crates/embedded-io) traits in your HAL crates. +Adhering to these traits ensures compatibility across the Embedded Rust +ecosystem, enhancing interoperability. It is an essential goal that HALs use +Rust code rather than wrapping existing C code. An incremental porting +strategy, where all core functionality is implemented in Rust, but C with Rust +bindings is used for complex drivers, is acceptable, allowing for gradual +adoption and community contributions. Start with essential peripherals (clock, timer, GPIO) and expand progressively (I2C, SPI, UART, etc.) based on community feedback. Release early and often to engage the community and gather valuable insights for further development. -### Common Recommendations +### Common recommendations - Ensure that crates are compatible with `no_std` environments, which are common in embedded systems without an operating system. Functionality that @@ -107,7 +108,7 @@ engage the community and gather valuable insights for further development. - Prefer licenses like Apache 2.0 and MIT for their permissive nature, which encourages broader adoption and collaboration. -### Issue Tracking +### Issue tracking Effective issue tracking is crucial for maintaining a healthy and collaborative ecosystem. Discuss triaging, labeling, and community involvement in issue @@ -118,7 +119,7 @@ resolution. Implement transparent processes for: - Encourage community members to contribute to resolving issues by providing feedback or submitting pull requests (PRs). -### Facilitate Debugging and Testing +### Facilitate debugging and testing The Embedded Rust ecosystem offers various tools used for debugging and testing, with [probe-rs](https://probe.rs) being one of the most widely @@ -132,7 +133,7 @@ development. Thorough testing ensures hardware-software reliability, and leveraging these tools can significantly enhance development workflows. -## Nice-to-Have Features for Enhanced Ecosystem Support +## Nice-to-have features for enhanced ecosystem support ### Examples @@ -141,7 +142,7 @@ developers get started. These examples should demonstrate key functionalities, such as initializing peripherals or handling interrupts. They serve as practical starting points and learning aids. -### BSP (Board Support Package) Crates +### BSP (Board Support Package) crates BSP crates are relevant when you need to provide board-specific configurations and initializations. Unlike HALs, which focus on hardware abstraction, BSPs @@ -149,7 +150,7 @@ handle the integration of multiple components for a specific board. Separation in BSP and HAL crates offers a layered approach, making it easier for developers to build applications targeting a particular hardware board. -### Project Templates +### Project templates Project templates are boilerplate code structures that provide a starting point for new projects. They include prevalent configurations, dependencies, and @@ -157,7 +158,7 @@ setup steps, saving developers time and reducing the learning curve. Examples of project templates include bare-metal (using the HAL without any framework), Embassy, RTIC, and others. -### Integration with Popular IDEs and Tools +### Integration with popular IDEs and tools Offer guides on setting up development environments for Embedded Rust projects with popular tools such as: @@ -172,6 +173,45 @@ with popular tools such as: Providing setup instructions for these tools will help developers integrate them into their workflows, enhancing productivity and collaboration. +## Suggested flow for adding SoC Support + +- A preliminary requirement of this flow is that the Rust toolchain includes + a [target](https://doc.rust-lang.org/rustc/platform-support.html) that + matches System-on-Chip (SoC). If this not the case the solution can be as simple as adding a + [custom target](https://doc.rust-lang.org/rustc/targets/custom.html) or as + difficult as adding support for the underlying architecture to + [LLVM](https://llvm.org). +- Before starting from scratch, check if any existing community efforts for + already exist (e.g. checking on + [awesome-embedded-rust](https://github.com/rust-embedded/awesome-embedded-rust) + or joining the + [Rust Embedded Matrix room](https://matrix.to/#/#rust-embedded:matrix.org)). + This could save significant development time. +- Ensure that your target is supported by [probe-rs](https://probe.rs). The + ability to debug using SWD or JTAG is highly beneficial. Support for flashing + programming can be added with a Flash Algorithm (e.g. from a CMSIS-Pack). +- Generate Peripheral Access Crates (PACs) from register description files with + SVD (System View Description) being the most common and preferred format. + Alternatives include extracting the register descriptions from PDF datasheets + or C header files, but this much more labor-intensive. +- Create a minimal project containing the PAC and/or an empty Hardware + Abstraction Layer (HAL). The goal is to get a minimal working binary that + either blinks an LED or sends messages through + [defmt-rtt](https://crates.io/crates/defmt-rtt) using only the PAC crate or + with a minimal HAL. This will require a linker script and exercise the + availability to flash and debug programs. Additional crates for core + registers and peripheral, or startup code and interrupt handling will also be + required (see [Cortex-M](https://github.com/rust-embedded/cortex-m) or + [RISC-V](https://github.com/rust-embedded/riscv)). +- Add core functionality in HAL: clocks, timers, interrupts. Verify the + accuracy of timers and interrupts with external tools like a logic analyzer + or an oscilloscope. +- Progressively add drivers for other peripherals (GPIO, I2C, SPI, UART, etc.) + implementing standard Rust Embedded traits + ([embedded-hal](https://crates.io/crates/embedded-hal), + [embedded-hal-async](https://crates.io/crates/embedded-hal-async), + [embedded-io](https://crates.io/crates/embedded-io)). + ## Conclusion Enabling Rust support for your SoC opens the door to a vibrant community of