Volume setting properties don't work right

[samblenny]

In the past several days, there's been some discussion on the forum and discord about people having trouble using the TLV320 volume settings on Fruit Jam, including issues with blowing out speakers. I'll leave it to someone else to describe all that stuff. The tldr version is the dac.speaker_volume and dac.headphone_volume setters don't work as expected. This issue is about what I've found while looking for mismatches between the code in Adafruit_CircuitPython_TLV320/adafruit_tlv320.py and the register descriptions in the TLV320 datasheet.

Gain Staging Register Cheat Sheet [edited 8/21]

For all of the stuff below, it's helpful to familiarize yourself with the Functional Block Diagram shown in sections 1.4 and 6.2 of the datasheet. In particular, for each speaker channel and the headphone jack, there are three important gain stages:

1. Before the DAC, the sample values go through a digital volume stage with attenuation set by Page 0 Registers 64-66
2. After the DAC, the signals go through an analog attenuation stage with attenuation set by Page 1 Registers 38, 36, and 37
3. After analog attenuation stage, the signals go through an analog amplifier stage with gain set by Page 1 Registers 42, 40, and 41

Analog Signal Chain Cheat Sheet [edited 8/21]

1. The DAC (digital to analog converter) output has two analog channels, L and R.
2. There are two analog inputs, AIN1 and AIN2. These are available as solder pads on the Adafruit TLV320DAC3100 breakout but unused on Fruit Jam.
3. The DAC outputs and analog inputs go through an analog mixing stage to configure which signals go to which outputs. This is controlled by register P1/R35=0x23. CAUTION: Depending on the setting of bits in P1/R35=0x23, it may be possible to intentionally or accidentally bypass the analog attenuation stage.
4. After the mixing stage, there are three analog signal chains which the datasheet calls SPK for the mono speaker output, HPL for headphone jack left output, and HPR for headphone jack right output.
5. Each signal chain has an analog attenuation stage (0 to -78 dB) followed by an amplifier stage (+6 dB to +24 dB for SPK; 0 dB to +9 dB for HPL and HPR).
6. The signal chains for SPK and HPL share a mixer. That means the speaker and left headphone channel share the same signal source, but their attenuation and amplifier gain settings to control the volume of that signal are independently adjustable.
7. The signal chain for HPR gets its own mixer.

Problems [edited 8/21, 8/22]

In adafruit_tlv320.py, def speaker_volume() calls self._page1._set_spk_volume(), which includes the line:

self._write_register(_SPK_VOL, value)

Then, _SPK_VOL is defined as _SPK_VOL = const(0x26) (page 1, register 38). On the Functional Block Diagram in section 1.4, Page 1 / Register 38 is "Analog Attenuation" for the left speaker channel (range 0 dB to -78 dB). That path also goes through the "Mono Class-D Speaker Driver" stage (Page 1 / Register 42=0x2A, range +6 dB to +24 dB). That register gets set by _configure_spk_pga(), which gets called by speaker_gain().

It looks to me like the bitfield shifting and masking for Page 1 / Register 42=0x2A are implemented correctly for the amplifier gain bits and mute bit. But, it's not clear to me why the registers for the right channel attenuation and speaker gain seem to be ignored. Perhaps there's some setting that makes the right channel follow the left channel, or maybe it's an oversight. [edit 8/21: it's because Fruit Jam and breakout board speaker jacks are mono]

The most suspicious thing I see is this:

    @speaker_volume.setter
    def speaker_volume(self, db: float) -> None:
        """

        :param db: Volume in dB (0 = max, -63.5 = min)
        """
        if db > 0:
            db = 0
        gain = int(55 + (db * 1.14))
        gain = max(0, min(gain, 127))
        self._page1._set_spk_volume(route_enabled=True, gain=gain)

The comment says 0 dB to -63.5 dB, but that's the range for the digital volume control (Page 0 / Register 65=0x41 and Page 0 / Register 66=0x42). Also, the gain scaling and clipping does not seem appropriate. The correct range for Page 1 / Register 38=0x26 is 0 dB to -78 dB (table 6-106 in the datasheet). So, it looks like the driver is conflating the digital volume adjustment stage (Page 0, registers 64..66) with the analog attenuation stage (Page 1, registers 38, 37, and 36).

The proper values for setting Page 1 / Register 38=0x26 are listed in Table 6-24.

I made a scatter plot of TLV320 datasheet table 6-24 for the speaker volume register value vs. analog gain dB. It turns out to be a non-linear piecewise function, so the linear formula in speaker_volume() can't be right.

This is as far as I've gotten so far with checking the driver's volume setting code against the datasheet. It will take me a while to read the rest of the relevant stuff, so I'm starting this issue now before I forget all the details. I kinda expect there may be a similar problem with the setter for dac.headphone_volume.

[samblenny]

Suddenly dawned on me why speaker_volume doesn't set anything for the right speaker signal chain... The Fruit Jam and TLV320DAC3100 breakout board both have a mono speaker jack.

[samblenny]

Note: As I've been reading about the headphone outputs today in the datasheet, I realized some of the stuff I wrote yesterday in the original post of this issue was incorrect. I edited that today to reflect my new understanding. Main difference is that I was confused about the roles of the 3 analog attenuation and amplifier gain signal chains. The SPK output chain is for the speaker, which is mono. The HPL and HPR output chains are for the headphones, which are stereo.

[samblenny]

It turns out that the setter and getter for headphone_volume are using a rough linear approximation of Table 6-24 that's pretty close to right in the range of 0 dB to -40 dB but increasingly inaccurate at lower volumes (where the table's curve goes non-linear).

For example:

    @headphone_volume.setter
    def headphone_volume(self, db: float) -> None:
        if db > 0:
            db = 0
        elif db < -78.3:
            db = -78.3
        gain = int(-2 * db)
        gain = max(0, min(gain, 127))
        self._page1._set_hpl_volume(route_enabled=True, gain=gain)
        self._page1._set_hpr_volume(route_enabled=True, gain=gain)

The approximation is int(-2 * db).

I wrote some dB to register value conversion functions for Table 6-24 along with test code to verify that they agree with the table values. The full code is available at samblennytlv320dac-stuff/table-6-24.py. These are the Table 6-24 conversion functions which should be usable to accurately do the dB to register value conversions for SPK, HPL, and HPR analog volume (attenuation) registers:

def convert_dB_to_uint7_table_6_24(dB):
    """
    Convert analog gain dB to 7-bit unsigned int to match datasheet Table 6-24.
    Valid gain dB range is -78.3 dB to 0 dB.
    """
    if dB > 0:
        raise ValueError()
    elif -52.7 <= dB <= 0:
        # This segment is approximately a line, but the table values have
        # jitter on the order of ±0.3 away from from a straight line. By using
        # round(), we can pretend like this segment is straight. Note that
        # round() is not invertible. So, to invert this function, we will need
        # to use a different approach to get from uint7 register value to dB.
        return round((-1.99 * dB) - 0.2)
    elif -53.7 <= dB:
        # This is the beginning of the weird curved segment. I wasn't able to
        # find a good formula to fit this curve, and there aren't many points.
        # We'll use a lookup table built from elif comparisons because dB is
        # floating point.
        return 106
    elif -54.2 <= dB:
        return 107
    elif -55.3 <= dB:
        return 108
    elif -56.7 <= dB:
        return 109
    elif -58.3 <= dB:
        return 110
    elif -60.2 <= dB:
        return 111
    elif -62.7 <= dB:
        return 112
    elif -64.3 <= dB:
        return 113
    elif -66.2 <= dB:
        return 114
    elif -68.7 <= dB:
        return 115
    elif -72.2 <= dB:
        return 116
    elif -78.3 <= dB:
        # Final segment is constant. Table 6-24 says that register values
        # 117-127 are all -78.3 dB. Because we need to compute a single value
        # for the register as a function of the dB argument, we will pick 117.
        return 117
    else:
        raise ValueError()

def convert_uint7_to_dB_table_6_24(u7):
    """
    Convert 7-bit unsigned int to analog gain to match datasheet Table 6-24.
    Valid values for u7 are integers in range 0 to 127.
    """
    if (u7 < 0) or (not isinstance(u7, int)):
        raise ValueError()
    if 0 == u7:
        return 0
    elif 0 < u7 <= 35:
        # First segment is a well behaved straight line
        return u7 / -2
    elif (36 <= u7 <= 69) or (u7 == 84):
        # This is the first of several special cases to compensate for jitter
        # in the middle segment
        return (u7 / -2) - 0.1
    elif u7 in (87, 88, 89, 91, 98, 100, 103):
        return (u7 / -2) - 0.3
    elif u7 in (94, 95, 102):
        return (u7 / -2) - 0.4
    elif u7 in (99, 101):
        return (u7 / -2) - 0.5
    elif 70 <= u7 <= 105:
        # For the remaining well-behaved values in the middle segment, use a
        # linear formula
        return (u7 / -2) - 0.2
    elif 106 <= u7 <= 116:
        # Next to last segment is a weird curve, so use a lookup table
        return (-53.7, -54.2, -55.3, -56.7, -58.3, -60.2, -62.7, -64.3,
            -66.2, -68.7, -72.2)[u7 - 106]
    elif 117 <= u7 <= 127:
        # Final segment is constant
        return -78.3
    else:
        raise ValueError()

[dhalbert]

Might you use a lookup table instead of a multi-arm if, and scan it linearly for the closest value? It would be less code, I think.

[samblenny]

Yeah, that would definitely be possible. I just wrote it the way I did because it makes the structure and character of the data in the table clear. Dunno if anybody but me actually cares about that angle though.

Are you saying you'd prefer a PR to be done that way? I'm gearing up to do a PR for this, so I could take that into account.

[dhalbert]

Are you saying you'd prefer a PR to be done that way?

I think a table of floats would be clearer (basically a transcription of the table in the datasheet), and it could be searched in either direction.

[samblenny]

Do you know what the most efficient way of storing a table of floats would be? Is there a way to make a tuple or something that gets stored as code in flash rather than dumping the whole thing on the heap or stack every time you touch one of the volume setter/getter functions?

[samblenny]

I suppose maybe if I just did a file level global variable along the lines of,
TABLE_6_24 = (0, -0.5, -1, ...)
then it would only hit the heap once.

[samblenny]

I just did a little before and after mem_free() test to see how much heap a 128 element tuple of floats would add to the stack heap. I came up with 528 bytes. Does that seem okay?

If so, I'll proceed with that approach.

[edit: actually, it looks like my gc.collect() + gc.mem_free() thing didn't work as expected. I don't trust that number]

[dhalbert]

Floats are stored as immediate constants, so a tuple of floats will be 4 bytes each * number of floats + a little overhead.
You could see the size of the your current code too. The mpy file is pretty much the size in RAM. So see the size of the .mpy file, and then comment out the code and check the new size after running mpy-cross again. You can get mpy-cross from here: https://adafruit-circuit-python.s3.amazonaws.com/index.html?prefix=bin/mpy-cross/. Use the directories at the top of the list, not the 8.x.x or 7.x.x versions. https://learn.adafruit.com/welcome-to-circuitpython/library-file-types-and-frozen-libraries#creating-an-mpy-file-3118108

[samblenny]

okay... I figured out what was wrong with my collect/mem_free thing and came up with heap 544 bytes for the table, which matches your 4 bytes per float + overhead estimate.

Is that big enough to worry about? It could be entertaining to compare to the other implementation, but I don't really care one way or the other as long as it works for you.

[dhalbert]

The code you pasted above is 760 bytes compiled, so 544 plus a small amount of table-lookup will probably be about the same. I was just thinking that the table-lookup code is the easiest to vet.

[samblenny]

Sounds good. Table it is.