Documentation Requests/Feedback

ESP_Sprite
Posts: 2832
Joined: Thu Nov 26, 2015 4:08 am

Re: Document Requests

You may want to email sales at espressif dot com for that, they can probably help you.

Fulembar
Posts: 2
Joined: Thu Sep 27, 2018 5:16 pm

Re: Document Requests

Solved, thank you.

DEMandell
Posts: 1
Joined: Wed Feb 07, 2018 6:16 pm

Re: Document Requests

Greetings,

I'm working on an audio application and would like to be able to dynamically update the APLL settings to servo its clock rate to match an external reference. It's not at all clear how to do this.

The function rtc_clk_apll_enable() sets some registers and then waits for "calibration". What's happening here? Can we please get some detailed documentation of what these APLL-related registers do and how to set them?

Also, the function i2s_apll_calculate_fi2s() in i2s.c is not at all correctly written. I have a new version of it (including comments describing the math behind it) that does this calculation in a sensible fashion based upon the equations in the documentation:

Code: Select all

``````static esp_err_t i2s_apll_calculate_fi2s(int rate, int bits_per_sample, int *sdm0, int *sdm1, int *sdm2, int *odir)
{
if (rate / (bits_per_sample * 2 * 8) < APLL_I2S_MIN_RATE)
return ESP_FAIL;

/* For maximum flexibility, we need to target the APLL frequency, fout, to be in the middle of its range,
or its geometric mean. Thus start with fout = sqrt(APLL_I2S_MIN_RATE * APLL_I2S_MIN_RATE).

In order to produce our target rate, we figure the divisor needed to get close from the mean APLL frequency.
Starting with the equation relating fout, rate, and o_div:

rate = fout / ((o_div + 2) * 2)

We solve for o_div:

(o_div + 2) * 2 = fout / rate
o_div + 2 = fout / (2 * rate)
o_div = fout / (2 * rate) - 2

and can now calculate it directly.  After rounding o_div to the nearest integer, we plug it back into the
formula and solve for sdm, which is really just a fixed-point number with 6 bits of integer part and 16
bits of fraction. It only needs to be split into sdm0, sdm1, and sdm2 when we load it into the hardware
registers.

First, recalculate the actual fout using the integer version of o_div:

fout = rate * ((o_div + 2) * 2)

then use this value to calculate sdm by solving the following for sdm:

fout = xtal_freq * (4 + sdm / 65536)
4 + sdm / 65536 = fout / xtal_freq
sdm / 65536 = fout / xtal_freq - 4
sdm = 65536 * (fout / xtal_freq - 4)

sdm, rounded and converted to an integer, can now be broken into sub-registers:

sdm2 = sdm >> 16
sdm1 = (sdm >> 8) & 0x000000ff
sdm0 = sdm & 0x000000ff
*/

/* not sure why a factor of 4 is needed in two places below; the docs imply it should be 2 */

float o_div_f = (float) APLL_GEO_MEAN_FREQ / (float)(4 * rate) - 2.0;
*odir = (int)floorf(o_div_f + 0.5f);
float fout = (float)(rate * (*odir + 2) * 4);

float f_xtal = (float)rtc_clk_xtal_freq_get() * 1000000.0f;

int sdm = (int)floorf(65536.0f * (fout / f_xtal - 4.0f) + 0.5f);

*sdm2 = sdm >> 16;
*sdm1 = (sdm >> 8) & 0x000000ff;
*sdm0 = sdm & 0x000000ff;

return ESP_OK;
}
``````
Thanks,
--Douglas Mandell
Dolby Laboratories, Inc.
San Francisco

michprev
Posts: 92
Joined: Fri Aug 04, 2017 8:57 pm

Re: Document Requests

There are many HW bugs in ESP32 peripherals that should be mentioned in the "ECO and Workarounds for Bugs in ESP32" document.
For instance:

ESP_Sprite
Posts: 2832
Joined: Thu Nov 26, 2015 4:08 am

Re: Document Requests

michprev wrote:There are many HW bugs in ESP32 peripherals that should be mentioned in the "ECO and Workarounds for Bugs in ESP32" document.
FWIW, a fair few of them already are documented in the TRM; at least the I2C one is. We're going to look into the others as well, and check if we need to put them in the TRM or the ECO document.

michprev
Posts: 92
Joined: Fri Aug 04, 2017 8:57 pm

Re: Document Requests

ESP_Sprite wrote: FWIW, a fair few of them already are documented in the TRM; at least the I2C one is. We're going to look into the others as well, and check if we need to put them in the TRM or the ECO document.
In that case there should be another document describing all known HW bugs like it is common among other manufacturers.

ESP_Sprite
Posts: 2832
Joined: Thu Nov 26, 2015 4:08 am

Re: Document Requests

michprev wrote: In that case there should be another document describing all known HW bugs like it is common among other manufacturers.
Not sure if having another document helps here, but we're always open to suggestions. Do you have an example of what you would expect a document like that to look at?

michprev
Posts: 92
Joined: Fri Aug 04, 2017 8:57 pm

Re: Document Requests

ESP_Sprite wrote: Not sure if having another document helps here, but we're always open to suggestions. Do you have an example of what you would expect a document like that to look at?
Sent PM.

Also it does not make sense to name SPI pins SPI*_WP and SPI*_HOLD. WP nor HOLD functions do not work. It should be either noted in the errata document or SPI*_WP should be renamed to SPI*_IO2 and SPI*_HOLD to SPI*_IO3.

permal
Posts: 379
Joined: Sun May 14, 2017 5:36 pm

Re: Document Requests

ESP_Sprite wrote:
michprev wrote: Not sure if having another document helps here, but we're always open to suggestions.
Please put a hard-to-miss note in the API/Programming guides wherever there is known H/W bug.

michprev
Posts: 92
Joined: Fri Aug 04, 2017 8:57 pm

Re: Document Requests

• SPI flash options in SPI registers are not documented (e. g. SPI_FLASH_READ, SPI_FLASH_WREN in SPI_CMD_REG register)
bump SPI flash commands

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 1 guest