What is VSPICS0?

[Scotty2541]

Or HSPICS0 for that matter?
What is the difference between VSPI, HSPI, GP-SPI2, GP-SPI3 ?
Where is any of this documentation consistent?

I am trying to support a WROVER device, and the doc "esp32-wrover-e_esp32-wrover-ie_datasheet_en" shows that internally there is one or two SPI buses and two CS lines connect to SPIFLASH and SPIPSRAM. I can't tell because the data lines are connected, but the clock lines are separate.
They are controlled by SPICS0 and SPICS1 (figure 2). Okay, that's fine...
They also use SPIDI and SPIDO, I assume what the rest of us call MISO and MOSI as data in and data out.
I also assume that these SPI CS lines are not available externally, since they are tied to internal RAM.

The above are assumptions, since I cannot find anything in "esp32-wrover-e_esp32-wrover-ie_datasheet_en".

The document "esp32-wrover-b_datasheet_en" has one sentence that says go read "esp32_datasheet_en"... which the SPI which has one tiny paragraph (4.1.17)
But the document "esp32_datasheet_en" says there are 3 SPI: SPI, VSPI, HSPI. So that FLASH/RAM is only one SPI module? With two clocks and two CS lines? And there are two OTHER SPI modules.... what do the H and V prefixes mean?
Furthermore, this data sheet seems to describe another device, not a "WROVER" anyway, since the pin count and packaging information doesn't match. But I can find no such similar document for the WROVER.

And I am also consulting
"esp32-s2_technical_reference_manual_en" because there does not appear to be anything named
"esp32-wrover_technical_reference_manual_en"

There is no mention of VSPI or HSPI in there. They are GP-SPI2 and GP_SPI3. It does say that SPI0 and SPI1 are internal, and GP-SPI2, GP-SPI3 are available. Yet, this is more than 3 SPIs described in the "esp32_datasheet_en"

So if the "esp32-s2_technical_reference_manual_en" and "esp32_datasheet_en" documents are NOT for a WROVER, where do I find this level of detail for the WROVER? No such document is appearing in any search.

Back to "esp32-wrover-e_esp32-wrover-ie_datasheet_en", table 3 has things that are NOT explained anywhere I can find.

There are VSPIxxx and HSPIxxx signals. And they use VSPICS0 and HSPICS0.

What is "VSPIHD" in the table, like "SPIHD" in figure 2 (HD as in HighDef signal? I doubt that...). Also VSPIQ, HSPIQ, etc...

I've been spending days trying to make sense of pieces from four different documents and put them together like a puzzle because no one document seems to have all the information.

And the API reference doesn't explain what VSPI or HSPI is. Just that I can't use SPI0 or SPI1. And has a lot of other unexplained stuff
("Set DMA chan to SPI_DMA_DISABLED if only the SPI flash uses this bus". ??? The FLASH is on SPI0... which can't used used??? HUH?)

Any, and I do mean ANY, advice that can straighten this out would be appreciated.

[ESP_Sprite]

First of all, I appreciate you spelling out your confusion. It appears we can do more to be consistent in our terminology when it comes to SPI, and you point out a few good places to start. I've informed our documentation team that this is something we should look at.

Secondly, part of the confusion may be because you mix up two different chips. The ESP32-S2 and the ESP32 are not the same silicon. For your Wrover, you want to have the ESP32 technical reference manual.

SPI on the ESP32 is a bit complicated. There are 4 SPI buses in total. I'll quote another source of information that explains it a bit better: the docs for the ESP-IDF SPI master driver:

[*] SPI0 and SPI1 are used internally to access the ESP32’s attached flash memory. Both controllers share the same SPI bus signals, and there is an arbiter to determine which can access the bus.

[*] SPI2 and SPI3 are general purpose SPI controllers, sometimes referred to as HSPI and VSPI, respectively. They are open to users. SPI2 and SPI3 have independent bus signals with the same respective names. Each bus has three CS lines to drive up to same number of SPI slaves.

To expand a bit on the 1st point: SPI0 and SPI1 are not for flash and PSRAM, respectively; both control both of these chips. The trick is that SPI0 is a hardware-only thing: it is not controlled by software but gets its instructions from the cache. If you load data from a pointer that points to a flash memory address range, the hardware will control this SPI interface to grab the data from flash (given it's not already in cache). This SPI peripheral is specialized for that, though: it cannot send commands to e.g. erase flash ranges or even write flash. For that, you have SPI1, which is (as the above paragraphs state) connected to the same lines, but *is* software-controllable. Software can use this SPI bus to interact with flash/PSRAM if it requires anything else than 'dumb' retrieval or storage of data.

Then there's VSPI and HSPI. Why these are called like this is a bit of a mystery, even to Espressif people. (Vertical and Horizontal SPI? High speed and Very High speed SPI? The digital team is relentless in telling us that these are simply random letters without any meaning, but who knows...) In later chips, to avoid confusion, they're generally indicated by numbers instead for that reason (SPI2, SPI3, etc).

On the SPI signals: there's a good table in the TRM on page 117. (In case we update the document, I mean the 'Mapping Between SPI Bus Signals and Pin Function Signals' table under the 'SPI controller (SPI)' chapter. HD and WP stand for HolD and Write Protect; these are two extra lines used for quad-SPI (a spi mode that uses 4 datalines instead of only two.) If you don't use quad-SPI, you don't need to worry about those.

On '("Set DMA chan to SPI_DMA_DISABLED if only the SPI flash uses this bus". ??? The FLASH is on SPI0... which can't used used??? HUH?)' - Note that SPI devices can be accessed using DMA as well as FIFO mode (in the latter, the CPU writes data to the SPI controller 'manually'), the sentence simply indicates the main flash chip logic does not need DMA to operate.

[Scotty2541]

Thanks, that clears SOME of it up. And table 25 on page 117 helps.

But, of course, esp32_technical_reference_manual_en.pdf was yet another document that never appeared in any of my searches. At least I have it now.

Next up, which I do not look forward to, is correlating this TRM information back to the API functions. Be sure I'll be asking more.