Esp-idf: Missing / omitted structure header file for io_mux_struct (IDFGH-263)

[nkolban]

Examining the header files in soc/esp32/include/soc I find header files ending in "reg.h" and others ending in "struct.h" corresponding to various definitions. For the IO_MUX subsystem, I only find io_mux_reg.h and no corresponding io_mux_struct.h. Is there a technical reason for this? Might we add this header for structure mapping of the content of the IO_MUX subsystem?

I think there would also have to be a definition in components/.esp32/ld/esp32.peripherals.ld reading:

PROVIDE ( IO_MUX = 0x3ff49000 );

[stickbreaker]

@nkolban Security by obscurity. Compare the 3.0 readthedocs documentation and the current soc header files. They are hacking and slashing the documentation, I believe the header files are being trimmed to match the documentation. It will only get worse.

Chuck.

[negativekelvin]

It is probably because there is not that much benefit to having it in struct form. There are a limited number of fields and values.

[stickbreaker]

@nkolban I wrote an interrupt driven i2c subsystem for the ESP32. I used information from the 2.x version of readthedocs available prior to Dec 2017, after the 3.0 'update' all of the register descriptions needed for this update have been purged from documentation. Here is an example for V3.4 of the Official Technical Reference:

Here is the register structure I grabbed November 2017:

    union {
        struct {
            uint32_t rx_fifo_full:     1;           /*The enable bit for rx_fifo_full_int interrupt.*/
            uint32_t tx_fifo_empty:    1;           /*The enable bit for tx_fifo_empty_int interrupt.*/
            uint32_t rx_fifo_ovf:      1;           /*The enable bit for rx_fifo_ovf_int interrupt.*/
            uint32_t end_detect:       1;           /*The enable bit for end_detect_int interrupt.*/
            uint32_t slave_tran_comp:  1;           /*The enable bit for slave_tran_comp_int interrupt.*/
            uint32_t arbitration_lost: 1;           /*The enable bit for arbitration_lost_int interrupt.*/
            uint32_t master_tran_comp: 1;           /*The enable bit for master_tran_comp_int interrupt.*/
            uint32_t trans_complete:   1;           /*The enable bit for trans_complete_int interrupt.*/
            uint32_t time_out:         1;           /*The enable bit for time_out_int interrupt.*/
            uint32_t trans_start:      1;           /*The enable bit for trans_start_int interrupt.*/
            uint32_t ack_err:          1;           /*The enable bit for ack_err_int interrupt.*/
            uint32_t rx_rec_full:      1;           /*The enable bit for rx_rec_full_int interrupt.*/
            uint32_t tx_send_empty:    1;           /*The enable bit for tx_send_empty_int interrupt.*/
            uint32_t reserved13:      19;
        };
        uint32_t val;
} int_ena;

see any differences?
They purged any references to the i2c FIFOs.

If you review my functioning code you will notice I am using 'undocumented' function to provide a working I2C subsystem.

Chuck.

[projectgus]

Hi @nkolban ,

For the IO_MUX subsystem, I only find io_mux_reg.h and no corresponding io_mux_struct.h. Is there a technical reason for this? Might we add this header for structure mapping of the content of the IO_MUX subsystem?

I think the historical reason is that the "normal" peripheral xxx_reg.h & xxx_struct.h files are code generated from register descriptions maintained by the hardware team. The io_mux_reg.h header is not created this way (compare the layout to the other register files), I think because it's a bit of an unusual "peripheral" compared to things like I2S, SPI, or I2C.

There's no reason we can't also add a _struct header. I think the main problem adding one is that it's harder to encode all of the FUNC_xxx information in a similar way to the other _struct register headers. If you have suggestions about how to lay such a file out in a way which would work for you, that'd be useful to see.

see any differences?
They purged any references to the i2c FIFOs.

This looks like a mistake in the TRM. These same interrupt bits are still included in the headers, along with comments which match what was shown in the TRM:
https://github.com/espressif/esp-idf/blob/c7173e0/components/soc/esp32/include/soc/i2c_struct.h#L148
https://github.com/espressif/esp-idf/blob/c7173e0/components/soc/esp32/include/soc/i2c_reg.h#L445
(Link is to the current master branch commit.)

We even use many of them in the open source i2c driver in ESP-IDF!

I will bring the missing registers up with the documentation team. I assure you there is no conspiracy to prevent people from using working hardware features. :)

Compare the 3.0 readthedocs documentation and the current soc header files. They are hacking and slashing the documentation

I don't really understand what this means. If you have noticed other things missing, please let us know so that we can correct them.

There have been a couple of hardware features which are no longer supported in the chip due to issues. These have been removed from the docs to prevent people from getting the impression they can be used (the internal temp sensor for example). You can subscribe to PCNs on the espressif.com website to be notified of production changes of this kind.

But the fundamental motivation we have is to allow people to use the hardware!

[stickbreaker]

@projectgus

Compare the 3.0 readthedocs documentation and the current soc header files. They are hacking and slashing the documentation

I don't really understand what this means. If you have noticed other things missing, please let us know so that we can correct them.

Aggressive Pruning, like using a machete to deadhead(remove flower blossoms after the petals have faded) a rose bed.

I brought this up with me-no-dev last year when I first noticed it, he also described it as an 'error'. That was four revisions ago, Based on that inaction I assume it is intentional.

Chuck.

[negativekelvin]

https://gist.github.com/negativekelvin/b92988edc44cb427d4a017f855475566

[projectgus]

Aggressive Pruning, like using a machete to deadhead(remove flower blossoms after the petals have faded) a rose bed.

I brought this up with me-no-dev last year when I first noticed it, he also described it as an 'error'. That was four revisions ago, Based on that inaction I assume it is intentional.

I'm sorry but I still don't have any idea what you're referring to. Can you give any specifics at all?

Are you talking about the IDF Programming Guide on ReadTheDocs, or the Technical Reference Manual on the espressif.com website?

For the documentation on RTD, between v2.1 and v3.0 we expanded the documentation a lot, and reorganised it into subfolders. So a lot of URLs for v2.1 were changed in v3.0, and this broke links. If you search for the content, then it's still there in the newer documentation - just at a new URL (plus there's a lot more new content). The v2.x documentation is also still up at http://esp-idf.readthedocs.io/en/v2.1/ (so if you have a URL with /latest/ in it that 404s, you can switch it to /v2.1/ and it should come good.

One thing on our todo list for the RTD docs is to replace the default RTD 404 page with something more useful.

If you're talking about the TRM, I'm not as familiar with the updates from version to version, but if you have specific concerns then I'm happy to chase these up.

@negativekelvin That looks good! I forgot about the part which is common to all registers.

[negativekelvin]

@projectgus can we get listing of pin_ctrl clk_out functions? Is this right? What others missing?

#define FUNC_CLK_OUT_I2S0                        0
#define FUNC_CLK_OUT_APLL_CLK                    6
#define FUNC_CLK_OUT_APB_CLK                     8
#define FUNC_CLK_OUT_CPU_CLK                     13
#define FUNC_CLK_OUT_I2S1                        15

@nkolban did you review the gist? any comment?

[igrr]

Re CLK_OUT: there are also XTAL, RTC8M, REF_TICK, and a few internal clocks which don't seem to be very useful. Will add defines for them.