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:
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 patch
PACs are also generated using an xtask
subcommand, this time the generate
subcommand. Again, the generate
subcommand accepts zero or more arguments:
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 generate
Note: 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:
device.x
linker script.gitignore
it should not be included!xtask
packageThe 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:
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.