==============================================================================

        I2S registers on the Raspberry RP1

	Laurent de Soras
	2024-02-10

==============================================================================



This is an addition to the official RP1 documentation (built on 2023-11-07).
https://datasheets.raspberrypi.com/rp1/rp1-peripherals.pdf

Register description has been extracted from the Linux driver source code.
Therefore it is probably incomplete and may contain errors.
There registers can be accessed by mmap() on the following file:
/sys/bus/pci/devices/0000:01:00.0/resource1
Its content starts at 0x40000000 in the RP1 address space (base of the
peripherals) and contains 0x00400000 bytes.

Feedback welcome.



General registers
-----------------

Offsets in bytes, relative to i2s0, i2s1 or i2s2 addresses

Name	Offset
IER	0x000
IRER	0x004
ITER	0x008
CER	0x00C
CCR	0x010
RXFFR	0x014
TXFFR	0x018
RXDMA	0x1C0
TXDMA	0x1C8
COMP_PARAM_2	0x1F0
COMP_PARAM_1	0x1F4
COMP_VERSION	0x1F8
COMP_TYPE	0x1FC
DMACR	0x200

* IER *

0 : Disables the device
1 : Enables the device

* IRER *

0 : Disables the capture interrupts
1 : Enables the capture interrupts

* ITER *

0 : Disables the playback interrupts
1 : Enables the playback interrupts

* CER *

1 : Starts the transfers
0 : Stops the transfers

* CCR *

Bit	Size	Name
3	2	?
			Sample resolution
			0 : 16 bits
			1 : 24 bits
			2 : 32 bits
			3 : undefined
Other bits are set to 0.

* RXFFR *

0 : disables capture
1 : enables capture

* TXFFR *

0 : disables playback
1 : enables playback

* RXDMA, TXDMA *

Registers for DMA access

* COMP_PARAM_1 *

R/O. Hardware features

Bit	Size	Name
25	3	TX_WORDSIZE_3
22	3	TX_WORDSIZE_2
19	3	TX_WORDSIZE_1
16	3	TX_WORDSIZE_0
			Maximum bit resolution of each playback channel pair
			0 : 12
			1 : 16
			2 : 20
			3 : 24
			4 : 32
			5-7 : undefined
9	2	TX_CHANNELS
			Maximum number of playback channels
			0 : 2 channels
			1 : 4 channels
			2 : 8 channels (not supported by RP1)
			3 : undefined
7	2	RX_CHANNELS
			Maximum number of capture channels. See TX_CHANNELS
6	1	RX_ENABLED
			Set if device is able to capture
5	1	TX_ENABLED
			Set if device is able to play
4	1	MODE_EN
			0 : Clock slave mode
			1 : Clock master mode
2	2	FIFO_DEPTH_GLOBAL
			0 : 2
			1 : 4
			2 : 8
			3 : 16
0	2	APB_DATA_WIDTH
			Bus data width for the DMA (TXDMA/RXDMA)
			0 : 8 bits
			1 : 16 bits
			2 : 32 bits
			3 : undefined

* COMP_PARAM_2 *

R/O. Hardware features

Bit	Size	Name
10	3	RX_WORDSIZE_3
7	3	RX_WORDSIZE_2
3	3	RX_WORDSIZE_1
0	3	RX_WORDSIZE_0
			Maximum bit resolution of each capture channel pair
			0 : 12
			1 : 16
			2 : 20
			3 : 24
			4 : 32
			5-7 : undefined

* DMACR *

DMA control register

Bit	Size	Name
17	1	TX
		Enables DMA transfer for playback
16	1	RX
		Enables DMA transfer for capture
11	1	TXCH3
10	1	TXCH2
9 	1	TXCH1
8 	1	TXCH0
		Enables DMA transfer for playback on the given channel pair
3 	1	RXCH3
2 	1	RXCH2
1 	1	RXCH1
0 	1	RXCH0
		Enables DMA transfer for capture on the given channel pair



Channel pair registers
----------------------

Each channel register section is actually for a pair of channels.
Offsets in bytes, relative to i2s_base + (chn>>1) * 0x40

Name	Offset
LRBR_LTHR	0x20
RRBR_RTHR	0x24
RER	0x28
TER	0x2C
RCR	0x30
TCR	0x34
ISR	0x38
IMR	0x3C
ROR	0x40
TOR	0x44
RFCR	0x48
TFCR	0x4C
RFF	0x50
TFF	0x54

* LRBR_LTHR, RRBR_RTHR *

FIFO registers (R/W) for left and right channels, for manual operations

* RER, TER *

Bit	Size	Name
0	1	?
		Enables the channel pair for capture or playback
8	?	RXSLOT_SHIFT/TXSLOT_SHIFT
		TDM mask?

* RCR, TCR *

Set to the value of 1 + RX_WORDSIZE/TX_WORDSIZE ?
2 : 16 bit words
4 : 24 bit words
5 : 32 bit words

* ISR *

Interrupt status register
To be read before aknowledging the interrupts

Bit	Size	Name
5	1	TXFO
		Playback FIFO overrun (user failed to provide enough data?)
4	1	TXFE
		Playback FIFO is empty.
		Only for the first pair of channels
1	1	RXFO
		Capture FIFO overrun (user failed to retrieve data?)
0	1	RXDA
		Capture FIFO is not empty (data is available).
		Only for the first pair of channels

* IMR *

Interrupt mask register

Bit	Size	Name
4	2	?
		0 : enables interrupts for playback (? which events?)
		3 : disables interrupts for playback
0	2	?
		0 : enables interrupts for capture (? which events?)
		3 : disables interrupts for capture

* ROR, TOR *

Reading this register acknowledges the corresponding IRQ.

* RFCR *

Threshold for the RX FIFO. TXFE is set when at least RFCR + 1 samples are present in the the queue.

* TFCR *

Threshold for the TX FIFO. RXDA is set when less than TFCR + 1 samples are present in the the queue.

* RFF, TFF *

?