Skip to content

Commit 5d0e101

Browse files
malacalypsemalacalypse
committed
Initial commit
0 parents  commit 5d0e101

9 files changed

+1662
-0
lines changed

‎CMakeLists.txt

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# CMakeLists.txt
2+
#
3+
# Copyright (c) 2022 Daniel Collins
4+
#
5+
# This file is part of rp2040_i2s_example.
6+
#
7+
# rp2040_i2s_example is free software: you can redistribute it and/or modify it under
8+
# the terms of the GNU General Public License, version 3 as published by the
9+
# Free Software Foundation.
10+
#
11+
# rp2040_i2s_example is distributed in the hope that it will be useful, but
12+
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+
# FITNESS FOR A PARTICULAR PURPOSE.
14+
#
15+
# See the GNU General Public License for more details.
16+
#
17+
# You should have received a copy of the GNU General Public License along with
18+
# rp2040_i2s_example. If not, see <https://www.gnu.org/licenses/>.
19+
20+
cmake_minimum_required(VERSION 3.13)
21+
22+
set(CMAKE_C_STANDARD 11)
23+
set(CMAKE_CXX_STANDARD 17)
24+
25+
# Initialise pico_sdk from installed location
26+
# (note this can come from environment, CMake cache etc)
27+
set(PICO_SDK_PATH "/Users/studiodc/Development/raspi/pico/sdk")
28+
29+
# Pull in Raspberry Pi Pico SDK (must be before project)
30+
include(pico_sdk_import.cmake)
31+
32+
project(i2s_example C CXX ASM)
33+
34+
# Initialise the Raspberry Pi Pico SDK
35+
pico_sdk_init()
36+
37+
# Add executable. Default name is the project name, version 0.1
38+
39+
add_executable(i2s_example i2s.c)
40+
41+
pico_generate_pio_header(i2s_example ${CMAKE_CURRENT_LIST_DIR}/i2s.pio)
42+
43+
target_sources(i2s_example PRIVATE i2s_example.c)
44+
45+
pico_set_program_name(i2s_example "i2s_test")
46+
pico_set_program_version(i2s_example "0.1")
47+
48+
# no_flash means the target is to run from RAM
49+
# pico_set_binary_type(i2s_test no_flash)
50+
51+
pico_enable_stdio_uart(i2s_example 1)
52+
pico_enable_stdio_usb(i2s_example 0)
53+
54+
# Add the standard library to the build
55+
target_link_libraries(i2s_example pico_stdlib)
56+
57+
# Add any user requested libraries
58+
target_link_libraries(i2s_example
59+
hardware_i2c
60+
hardware_dma
61+
hardware_pio
62+
hardware_clocks
63+
)
64+
65+
pico_add_extra_outputs(i2s_example)

‎LICENSE.txt

+674
Large diffs are not rendered by default.

‎README.md

+180
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# i2s_example
2+
3+
Raspberry Pi Pico full-featured I2S PIO with system clock and bi-directional, double-buffered DMA support. Intended to
4+
be used with all common codecs, but modular enough to support unidirectional DAC or ADC implementations as well.
5+
6+
# Included PIO Programs
7+
8+
This package includes multiple PIO programs which are intended to be used either alone or in combinations to accomplish
9+
common I2S tasks. They comprise:
10+
11+
- i2s_sck : A system clock (or master clock) output-only module.
12+
- i2s_out_master: An output module (for writing to a DAC) which generates BCK and LRCK synchronously with the i2s_sck
13+
module, if required, or can standalone if not.
14+
- i2s_in_slave: An input (from ADC) module which synchronizes to externally generated BCK and LRCK. Designed to
15+
synchronize to the i2s_out_master block above for internal synchronization as a bi-directional master.
16+
- i2s_bidi_slave: A bi-directional (in and out) codec interface in slave mode (requires externally generated BCK and
17+
LRCK, usually from the codec).
18+
19+
There is not a standalone output slave module, but one can easily be designed from the above options if needed.
20+
21+
## API
22+
23+
For the two most common codec use cases (bi-directional master and bi-directional slave), two helper functions exist
24+
which set up double-buffered DMA and initialize the state machines with proper clock ratios - if possible (see sections
25+
below discussing clocks, especially if you require a system or master clock output in addition to the standard BCK/LRCK
26+
clocks).
27+
28+
In order to process the audio data coming from either of these units, a dma_handler is necessary. See the example
29+
included in `i2s_example.c`
30+
31+
### i2s_program_start_slaved
32+
33+
```c
34+
void i2s_program_start_slaved(PIO pio, const i2s_config* config, void (*dma_handler)(void), pio_i2s* i2s);
35+
```
36+
37+
This sets up the i2s_bidi_slave program with an input and output module sharing the same BCK and LRCK as inputs from the
38+
codec. It can optionally generate SCK as a master **output**, since some codecs require this externally even if they are
39+
generating the BCK/LRCK signals. If sck_enable is true in the config, it will generate SCK. If not, the pin is not used.
40+
41+
### is2_program_start_synched
42+
43+
```c
44+
void i2s_program_start_synched(PIO pio, const i2s_config* config, void (*dma_handler)(void), pio_i2s* i2s);
45+
```
46+
47+
This sets up the PIO as bi-directional master for the BCK and LRCK, and can optionally generate SCK as a master **
48+
output** as well. The output and input modules are synchronized to the internally generated BCK/LRCK and these signals
49+
are output on the appropriate pins to the codec as well.
50+
51+
# Understanding I2S
52+
53+
## `fs`, the sample frequency
54+
55+
The fundamental rate at which your audio system is clocked is called the sample frequency, also referred to as `fs`.
56+
Usually this is 44.1kHz or 48kHz. I2S has other clocks that are related to this fundamental frequency by exact integer
57+
multiples. So, keep in mind that all of the actual clock frequencies are relative to `fs` by the appropriate integer
58+
multiples.
59+
60+
## I2S core signals
61+
62+
I2S has the following signals:
63+
64+
- SCK (system or master clock) : **[optional]** usually 256 or 384 * fs
65+
- BCK (bit clock) : fs * 2 * bit depth (either 24 or 32)
66+
- LRCK (word, frame, or LR clock) : fs
67+
- Data In (from the ADC) : **[optional]** runs at BCK rate
68+
- Data Out (to the DAC) : **[optional]** runs at BCK rate
69+
70+
The constant multiple of 2 in the bit clock is because the I2S standard inherently supports stereo audio and divides the
71+
audio frames into left and right words via the LRCK.
72+
73+
One of either Data In or Data Out are, of course, required for this to be useful, but not all peripherals have both -
74+
you might be talking only to a DAC or only to an ADC, not a coded (which is just a DAC and an ADC in the same package,
75+
possibly sharing clocks, possibly not).
76+
77+
Additionally, not all peripherals require master clock, some have a PLL which can generate it from the bit clock, in
78+
that case the timing is made much easier for the Pico.
79+
80+
## Master Clock (SCK/System Clock)
81+
82+
**NOTE**: For peripherals which DO require master clock, the relationship between SCK and the BCK of the I2S stream must
83+
be *exact* - that is, they must both *perfectly* divide into the word clock precisely. If you wish to hit traditional
84+
sample rates like 44.1kHz or 48kHz, you need to choose a system clock that can evenly divide both the master and the bit
85+
clock into the necessary multiples. Some combinations are therefore not possible, since the Pico PIO is only a divider
86+
and does not incorporate a multiplier. For instance, with 24-bit audio there can end up being a factor of 3 involved
87+
which can only be approximated, but not exactly reached with the divisors, so ratios of SCK and BCK that involve a
88+
relationship of 1/3 cannot be correctly implemented. In addition, some system clock speeds will not produce clean
89+
divisions for both simultaneously.
90+
91+
A table of system clocks and appropriate scaling values for some common I2S relationships are below:
92+
93+
fs | Pico system clock | SCK (mult / Hz) | BCK (bits / Hz) |
94+
-------|---------------------|-------------------|----------------------|
95+
48,000 | 129,600,000 | 384 / 18,432,000 | 24 / 2,304,000 |
96+
48,000 | 132,000,000 | 256 / 12,288,000 | 32 / 3,072,000 |
97+
98+
Note: These frequencies are *one half* of the frequency to set up the pio state machine for - since the PIO modules
99+
output one bit per TWO clocks, so the sm clocks for the above table would be:
100+
101+
fs | Pico system clock | SM_SCK (mult / Hz) | SM_BCK (bits / Hz) |
102+
-------|---------------------|--------------------|--------------------|
103+
48,000 | 129,600,000 | 384 / 36,864,000 | 24 / 4,608,000 |
104+
48,000 | 132,000,000 | 256 / 24,576,000 | 32 / 6,144,000 |
105+
106+
Note: These routines will NOT set up the system clock for you. If the system clock is off, these relationship may not
107+
result in even divisions of the word clock and your peripheral may glitch.
108+
109+
## Recommended choice for codecs
110+
111+
The most robust synchronized (out and in share BCK/LRCK) setup is to use out_master and in_slave, setting the input
112+
BCK/LRCK pins to the same as the output BCK/LRCK.
113+
114+
## Pinouts
115+
116+
Pin assignment is pretty straightforward:
117+
118+
- SCK: pretty much any pin you like
119+
- DOUT: pretty much any pin you like
120+
- DIN: the first of three consecutive, free pins
121+
- Clock_Pin_Base: the first of the two pins consecutively above DIN, if using DIN. If not, any two consecutive pins.
122+
123+
For instance, a useful set of choices on a default Pico would be:
124+
125+
- SCK: 10
126+
- DOUT: 6
127+
- DIN: 7
128+
- Clock_Pin_Base: 8
129+
130+
This consumes pins 6-10, inclusive, for a fully bidirectional codec requiring system clock. If the codec permits
131+
synchronizing both the DAC and ADC to the same clocks, this works fine. If the codec requires independent clocks for
132+
both units, just route the clock lines to both modules physically. No additional clocks or pins are needed.
133+
134+
## A note about bit depth
135+
136+
Most I2S peripherals are either 24-bit or 16-bit, however it is very common to see both of these bit depths being
137+
transported over 32-bit I2S frames. Per the I2S standard, they are MSB-first. Some peripherals allow other protocols
138+
which are similar to, but not exactly, I2S standard, such as left- or right-aligned 16, 24, or 32-bit frames.
139+
140+
This PIO module follows the Philips I2S standard and emits a 32-bit frame. The DMA data should be 32 bit words, and you
141+
should **not** pack two stereo 16-bit frames into a single word. Alignment of the data within the frame is up to you -
142+
whatever alignment it has in memory is what will be transmitted, MSB-first, on the I2S bus.
143+
144+
For the most common use case of traditional 24-bit codecs such as the TI PCM3060 or the WM8731, this PIO is already
145+
perfectly configured. Use 32-bit signed integers (int32_t) for the buffers. Received data will be in the exact same
146+
format.
147+
148+
To be very clear, if this is the I2S frame "on the wire" in 24-bit audio mode with a 32-bit frame word size:
149+
150+
```
151+
LRCK 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
152+
BCK 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01
153+
Dxx - 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 - - - - - - - - 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 - - - - - - -
154+
```
155+
156+
The bits for DXX will come from or be written to a 32-bit memory location as follows:
157+
158+
```
159+
bit MSB 31 30 29 28 27 26 25 242 3 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 LSB
160+
Dxx 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 - - - - - - - -
161+
```
162+
163+
Note that the I2S format offsets the alignment of the MSB in the frame by one bit from the edge of LRCK. This is
164+
intentional.
165+
166+
## License
167+
168+
The full text of the license should be found in LICENSE.txt, included as part of this repository.
169+
170+
This library and all accompanying code, examples, information and documentation is Copyright (C) 2019-2020 Daniel
171+
Collins
172+
173+
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
174+
License, version 3 as published by the Free Software Foundation.
175+
176+
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
177+
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
178+
179+
You should have received a copy of the GNU General Public License along with this program. If not,
180+
see <https://www.gnu.org/licenses/>.

0 commit comments

Comments
 (0)