Merge #265

265: Add I2S communication using SPI peripherals r=therealprof a=samcrow

# Introduction

Welcome to my first large pull request, which adds support for I2S audio communication using supported SPI peripherals. Like the way we support CAN with the bxcan library, I am proposing to support I2S using my [stm32_i2s_v12x](https://crates.io/crates/stm32_i2s_v12x) library.

Although stm32_i2s_v12x is in a separate repository, we can also talk about it here.

# Notes

* The I2S module is available if the `i2s` feature is enabled, in order to not increase compile time for applications that don't use I2S.
* All four modes are supported: master transmit, master receive, slave transmit, and slave receive.
* Basic support for DMA, interrupts, and error detection is provided.
* All STM32F4 models are supported.
* I added two examples that run on the STM32F411E-DISCO board and send audio to the on-board DAC. One of them uses DMA.

These changes are not perfect, so criticism and suggestions are welcome.

# Limitations

* No support for full-duplex communication
* I have tested master transmit mode fairly thoroughly, but have not tested the other modes.
* No support for embedded-hal I2S traits
  * [The I2S pull request](rust-embedded/embedded-hal#204) is still under review. The proposed traits look compatible with this driver code. Until that pull request gets merged and released, people can still use this driver code directly.

# Related work

* SAI driver pull request in this repository: #248
* Another, less complete, pull request for I2S in this repository: #212
  * also #145
* embedded-hal pull request for I2S traits: rust-embedded/embedded-hal#204 

Co-authored-by: Sam Crow <[email protected]>
Co-authored-by: Sam Crow <[email protected]>

Author: bors[bot]

.github/workflows/ci.yml

@@ -46,4 +46,4 @@ jobs:
       - uses: actions-rs/cargo@v1
         with:
           command: check
-          args: --features=${{ matrix.mcu }},rt,usb_fs,sdio,can --examples
+          args: --features=${{ matrix.mcu }},rt,usb_fs,sdio,can,i2s --examples

CHANGELOG.md

@@ -16,6 +16,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Update the sdio driver to match the changes in the PAC
 - Update README.md with current information
 
+### Added
+
+- Added support for I2S communication using SPI peripherals, and two examples [#265]
+
+[#265]: https://github.com/stm32-rs/stm32f4xx-hal/pull/265
+
 ## [v0.9.0] - 2021-04-04
 
 ### Changed

Cargo.toml

@@ -22,7 +22,7 @@ repository = "https://github.com/stm32-rs/stm32f4xx-hal"
 version = "0.9.0"
 
 [package.metadata.docs.rs]
-features = ["stm32f429", "rt", "usb_fs", "can"]
+features = ["stm32f429", "rt", "usb_fs", "can", "i2s"]
 targets = ["thumbv7em-none-eabihf"]
 
 [dependencies]
@@ -41,6 +41,10 @@ cast = { default-features = false, version = "0.2.2" }
 void = { default-features = false, version = "1.0.2" }
 embedded-hal = { features = ["unproven"], version = "0.2.3" }
 
+[dependencies.stm32_i2s_v12x]
+version = "0.2.0"
+optional = true
+
 [dev-dependencies]
 panic-semihosting = "0.5.3"
 cortex-m-semihosting = "0.3.3"
@@ -83,6 +87,8 @@ can = ["bxcan"]
 
 sdio = ["sdio-host"]
 
+i2s = ["stm32_i2s_v12x"]
+
 [profile.dev]
 debug = true
 lto = true
@@ -136,6 +142,14 @@ required-features = ["rt", "stm32f411"]
 name = "can-send"
 required-features = ["can", "stm32f405"]
 
+[[example]]
+name = "i2s-audio-out"
+required-features = ["stm32f411", "rt", "i2s"]
+
+[[example]]
+name = "i2s-audio-out-dma"
+required-features = ["stm32f411", "rt", "i2s"]
+
 [[example]]
 name = "rtic"
 required-features = ["rt", "stm32f407"]

examples/cs43l22/mod.rs

@@ -0,0 +1,119 @@
+//! Bare-bones driver for configuring a CS43L22 digital-analog converter
+
+use stm32f4xx_hal::hal::blocking::i2c::{Read, Write};
+
+/// Interface to the I2C control port of a Cirrus Logic CS43L22 DAC
+pub struct Cs43L22<I> {
+    /// I2C interface
+    i2c: I,
+    /// Address of DAC
+    address: u8,
+}
+
+impl<I> Cs43L22<I>
+where
+    I: Write + Read,
+{
+    pub fn new(i2c: I, address: u8) -> Self {
+        Cs43L22 { i2c, address }
+    }
+
+    /// Does basic configuration as specified in the datasheet
+    pub fn basic_setup(&mut self) -> Result<(), <I as Write>::Error> {
+        // Settings from section 4.11 of the datasheet
+        self.write(Register::Magic00, 0x99)?;
+        self.write(Register::Magic47, 0x80)?;
+        self.write(Register::Magic32, 0x80)?;
+        self.write(Register::Magic32, 0x00)?;
+        self.write(Register::Magic00, 0x00)
+    }
+
+    /// Writes the value of one register
+    pub fn write(&mut self, register: Register, value: u8) -> Result<(), <I as Write>::Error> {
+        // Set auto-increment bit
+        let map = (register as u8) | 0x80;
+        self.i2c.write(self.address, &[map, value])
+    }
+
+    /// Reads the value of one register
+    #[allow(dead_code)]
+    pub fn read(
+        &mut self,
+        register: Register,
+    ) -> Result<u8, CombinedI2cError<<I as Read>::Error, <I as Write>::Error>> {
+        let mut values = [0u8];
+        self.read_multiple(register, &mut values)?;
+        Ok(values[0])
+    }
+    /// Reads the values of zero or more consecutive registers
+    #[allow(dead_code)]
+    pub fn read_multiple(
+        &mut self,
+        register: Register,
+        values: &mut [u8],
+    ) -> Result<(), CombinedI2cError<<I as Read>::Error, <I as Write>::Error>> {
+        // Two transactions: set the memory address pointer, then read
+        // An empty write sets the address
+        // Set auto-increment bit
+        let map = (register as u8) | 0x80;
+        self.i2c
+            .write(self.address, &[map])
+            .map_err(CombinedI2cError::Write)?;
+        self.i2c
+            .read(self.address, values)
+            .map_err(CombinedI2cError::Read)
+    }
+}
+
+#[derive(Debug)]
+pub enum CombinedI2cError<R, W> {
+    Read(R),
+    Write(W),
+}
+
+/// CS43L22 registers
+#[allow(dead_code)]
+pub enum Register {
+    /// This is used in the specified startup sequence, but its actual content is not documented.
+    Magic00 = 0x00,
+    Id = 0x01,
+    PowerCtl1 = 0x02,
+    PowerCtl2 = 0x04,
+    ClockingCtl = 0x05,
+    InterfaceCtl1 = 0x06,
+    InterfaceCtl2 = 0x07,
+    PassthroughASelect = 0x08,
+    PassthroughBSelect = 0x09,
+    AnalogZcSr = 0x0a,
+    PassthroughGangCtl = 0x0c,
+    PlaybackCtl1 = 0x0d,
+    MiscCtl = 0x0e,
+    PlaybackCtl2 = 0x0f,
+    PassthroughAVol = 0x14,
+    PassthroughBVol = 0x15,
+    PcmAVol = 0x1a,
+    PcmBVol = 0x1b,
+    BeepFreqOnTime = 0x1c,
+    BeepVolOffTime = 0x1d,
+    BeepToneCfg = 0x1e,
+    ToneCtl = 0x1f,
+    MasterAVol = 0x20,
+    MasterBVol = 0x21,
+    HeadphoneAVol = 0x22,
+    HeadphoneBVol = 0x23,
+    SpeakerAVol = 0x24,
+    SpeakerBVol = 0x25,
+    ChannelMixer = 0x26,
+    LimitCtl1 = 0x27,
+    LimitClt2 = 0x28,
+    LimitAttack = 0x29,
+    Status = 0x2e,
+    BatteryComp = 0x2f,
+    VpBatteryLevel = 0x30,
+    SpeakerStatus = 0x31,
+    /// This is used in the specified startup sequence, but its actual content is not documented.
+    Magic32 = 0x32,
+    ChargePumpFreq = 0x34,
+    /// This is used in the specified startup sequence, but its actual content is not documented.
+    Magic47 = 0x47,
+}