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..1af08d3 --- /dev/null +++ b/src/soc-support.md @@ -0,0 +1,192 @@ +# 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 Rust Embedded 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](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 + +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](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](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 +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](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](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. + +### 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 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. + +## 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. 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 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](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. + +## 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.