Peripheral Access Crates (PACs) for Espressif SoCs and modules.
For information on how to use these crates, please refer to the svd2rust documentation.
We ask that you please read each of the below sections prior to contributing to this repository.
The xtask package is a binary application, based on the workflow outlined by cargo-xtask, which provides some simple utilities which make it easier to work with this repository. It is primarily used for patching SVDs and re-generating the PACs, but also provides some other functionality.
Usage: xtask <COMMAND>
Commands:
html Generate a webpage for a given SVD file
patch Patch the specified package(s)'s SVD file
generate Generate the specified package(s)
build Build the specified package(s)
bump-version Bump the version of the specified package(s)
publish Published the specified package(s)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
This application can be found in the xtask/ directory in the root of the repository.
svdtools is used to patch the SVDs rather than modifying the files directly. This makes it easier to upstream the changes to the official SVDs, which is done periodically, and then subsequently update the base SVDs here. A full description of the patching format is available in the svdtools README.
Patching is accomplished using the xtask package's patch subcommand. The patch subcommand accepts zero or more arguments:
- If zero arguments are provided, it will patch all PACs in the repository
- If one or more arguments are provided, it will patch each specified PAC
In order to apply patches to one or more chips' SVDs, from the repository's root directory you can run:
# Only patch the ESP32-C3's SVD:
cargo xtask patch esp32c3
# Patch the SVDs for the ESP32, ESP32-S2, and ESP32-S3:
cargo xtask patch esp32 esp32s2 esp32s3
# Patch all the SVDs!
cargo xtask patchPACs are also generated using an xtask subcommand, this time the generate subcommand. Again, the generate subcommand accepts zero or more arguments:
- If zero arguments are provided, it will patch and (re-)generate all PACs in the repository
- If one or more arguments are provided, it will patch and (re-)generate each specified PAC
In order to apply re-generate to one or more chips'SVDs, from the repository's root directory you can run:
# Only generate the ESP32-C3's PAC:
cargo xtask generate esp32c3
# Generate the PACs for the ESP32, ESP32-S2, and ESP32-S3:
cargo xtask generate esp32 esp32s2 esp32s3
# Generate all the PACs!
cargo xtask generateNote: It's also possible to build the PACs after patching and generating them, using the build subcommand instead of generate. This otherwise works the same as the process described above, but confirms that all generate source files build successfully. It's a good idea to do this prior to opening a pull request.
Prior to opening a pull request, we ask that you please:
- Ensure that all required files have been commited
- This include patch files (YAML), Rust source files, and (only sometimes) the
device.xlinker script - Please do not force add files to your commits; if a file is ignored in
.gitignoreit should not be included!
- This include patch files (YAML), Rust source files, and (only sometimes) the
- Ensure that you are able to patch, generate, and build each PAC using the
xtaskpackage
The Minimum Supported Rust Version is 1.76.0 for all packages.
Note that targeting the Xtensa ISA currently requires the use of the esp-rs/rust compiler fork, which can be installed using esp-rs/espup.
RISC-V is supported by the official Rust compiler.
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.