Add new section 'Supporting a new SoC'

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,20 +57,20 @@ 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
 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,23 +142,23 @@ 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
 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
 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