a13def7df6
* RMT: add HIL test that exercises all channels to ensure that there are no issues with channel/register indexing; see also the code comments. no user-facing changes * RMT: store ch_idx instead of channel number `ConstChannelAccess` and `DynChannelAccess` used to store the channel number and have a `Direction` generic parameter. However, there are invalid combinations of `Direction` and the channel number on some chips (e.g. on esp32c3, there is no channel with (Tx, 2), because channel 2 and 3 only support Rx). In constrast, the tuple `(Dir, ch_idx)` also uniquely identifies a channel and its configuration, and any combination of it is valid as long as the channel index is in bounds. This makes it somewhat easier to work with; in particular, it will allow removing bounds checks on ch_idx in a later commit by replacing `ch_idx: u8` with an enum type. This also refactors the `async_interrupt_handler` accordingly. This is user-visible via the `ConstChannelAccess` type, however a later commit in this PR will remove that entirely. * RMT: elide bounds checks via ChannelIndex enum If the channel index is not known at compile time in a given function, the compiler will insert bounds checks on - indexing the STATE global - register access via the PAC The compiler seems to be able to deduplicate them since low-level functions are mostly inlined, but each function will retain at least one bounds check. This change helps the compiler to elide these checks by using a custom type for channel indices that can only take values for which a channel exists. Specifically, this uses an enum to serve as a refinement of u8 to help the compiler restrict value ranges. Due to inlining, this restricted value range is propagated by the compiler until the potential bounds checks, even if there's intermediate cast to u8, cf. https://github.com/rust-lang/rust/issues/109958 There are no user-facing changes. (`ChannelIndex` is `pub` because it appears in a `[doc(hidden)]` trait member.) * RMT: always type-erase channels - remove the `Raw` generic on `Channel`: This simplifies the types, should have negligible performance impact (helped by elided bounds checks via the recently introduced `ChannelIndex` enum), and greatly reduce code size if several channels are used (by avoiding monomorphization per channel) - this also changed the arguments to configure_(tx,rx)_channel such that they don't contain generics, again avoiding code bloat due to monomorphization This requires user code to change type annotations for channels and transactions, and remove any manual type erasure (via `channel.degrade()`). * RMT: impl blocking tx/rx methods directly on Channel There's now only a single type that should implement these methods due to erasing the channel index const generic, so the indirection via a trait serves no purpose. Implementing methods directly on the channel probably also helps to make the docs more discoverable. This requires user code to remove the `TxChannel` and `RxChannel` imports. * RMT: impl async tx/rx methods directly on Channel There's now only a single type that should implement these methods due to erasing the channel index const generic, so the indirection via a trait serves no purpose. Implementing methods directly on the channel probably also helps to make the docs more discoverable. This requires user code to remove the `TxChannelAsync` and `RxChannelAsync` imports. * RMT: impl *ChannelInternal traits only on DynChannelAccess rather than as a blanket impl for RawChannelAccess, which includes ConstChannelAccess: We don't intend to perform any accesses via ConstChannelAccess anymore, so enforce that. We could also get rid of the traits entirely and directly impl their methods for DynChannelAccess, but it seems somewhat useful to keep them around to guarantee that the interfaces in both chip_specific modules are consistent. There are no user-facing changes here. * RMT: remove `pub` on various internal types that used to be visible somewhere in the API's trait bounds, but are not part of the API themselves This is user-visible, but user code should not have used these types in the first place. * RMT: rm ConstChannelAccess, RawChannelAccess, private DynChannelAccess now that Channel has no `Raw: RawChannelAccess` type parameter: - we don't need low-level channel methods to be implemented for ConstChannelAccess, since all accesses go through DynChannelAccess. Thus, remove the *ChannelInternal traits and implement their methods directly on DynChannelAccess - none of these types need to be public (although one might consider actually making them public with an unsafe constructor to provide an unsafe low-level interface to the hardware) This is user-visible (imports need to be removed; they're not used anymore since the previous commit that always type-erased the `Raw` parameter of `Channel`) * RMT: changelog and migration guide for type-erased channels * RMT: (review) remove stray comment * RMT: (review) remove is_tx() from Direction trait we can simply use the const item directly
Examples
This directory contains a number of binary applications demonstrating the use of various hardware peripherals found within the ESP32 family of devices from Espressif.
Each device has its own unique set of peripherals, and as such not every example will run on every device. We recommend building and flashing the examples using the xtask method shown below (no need to install any additional external tools), which will greatly simplify the process.
To check if a device is compatible with a given example, check the features in the Cargo.toml file for the example application, which will include a feature for each supported device.
For more information regarding the examples, refer to the README.md file in any of the subdirectories within the examples/ directory.
Building Examples
You can build all examples for a given device using the build examples subcommand:
cargo xtask build examples esp-hal esp32
Note that we must specify which package to build the examples for, since this repository contains multiple packages. Specifying esp-hal will build the examples in the examples/ directory instead.
Running Examples
You can also build and then subsequently flash and run an example using the run example subcommand. With a target device connected to your host system, run:
cargo xtask run example esp-hal esp32c6 --example embassy_hello_world
Again, note that we must specify which package to build the example from, plus which example to build and flash to the target device.
Adding Examples
If you are contributing to esp-hal and would like to add an example, the process is generally the same as any other project. The Cargo.toml file should include a feature for each supported chip, which itself should enable any dependency's features required for the given chip.
Another thing to be aware of is the GPIO pins being used. We have tried to use pins available the DevKit-C boards from Espressif, however this is being done on a best-effort basis.
In general, the following GPIO are recommended for use, though be conscious of whether certain pins are used for UART, strapping pins, etc. on some devices:
- GPIO0
- GPIO1
- GPIO2
- GPIO3
- GPIO4
- GPIO5
- GPIO8
- GPIO9
- GPIO10