Add mention of ESP32-S2/S3 differences to docs

Author: wnienhaus

README.rst

@@ -31,7 +31,7 @@ The following features are supported:
 
 * the entire `ESP32 ULP instruction set <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/ulp_instruction_set.html>`_
 * the entire `ESP32-S2 ULP instruction set <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/system/ulp_instruction_set.html>`_
-  (this also covers the ESP32-S3) [#f1]_
+  (this also covers the ESP32-S3) [#f1]_ [#f2]_
 * constants defined with ``.set``
 * constants defined with ``#define``
 * expressions in assembly code and constant definitions
@@ -44,6 +44,17 @@ The following features are supported:
          select the ``esp32s2`` cpu (`see docs </docs/index.rst>`_) when assembling code for
          use on an ESP32-S2/S3.
 
+.. [#f2] Note: The ESP32-S2 and ESP32-S3 have the same ULP binary format, but the peripheral
+         register addresses (those accessed with REG_RD and REG_WR) are different. For best
+         results, use the correct peripheral register addresses for the specific variant you
+         are working with. The assembler (when used with ``cpu=esp32s2``) will accept
+         addresses for any of the 3 variants, because they are translated into relative
+         offsets anyway and many registers live at the same relative offset on all 3 variants.
+         This conveniently means that the same assembly code can assembled unmodified for each
+         variant and produce a correctly working binary - as long as only peripheral registers
+         are used, which have the same relative offset across the variants. Use with care!
+
+
 Quick start
 -----------
 

docs/preprocess.rst

@@ -95,6 +95,21 @@ are not needed on the device either.)
       micropython -m esp32_ulp.parse_to_db \
         esp-idf/components/soc/esp32/include/soc/{soc,soc_ulp,rtc_cntl_reg,rtc_io_reg,sens_reg}.h
 
+
+   .. warning::
+
+      `:warning:` Ensure that you include the header files for the correct
+      variant you are working with. In the example code above, simply switch
+      ``esp32`` to ``esp32s2`` or ``esp32s3`` in the path to the include files.
+
+      There are subtle differences across the ESP32 variants such as which
+      constants are available or the value of certain constants. For example,
+      peripheral register addresses differ between the 3 variants even though
+      many constants for peripheral registers are available on all 3 variants.
+      Other constants such as those relating to the HOLD functionality of touch
+      pads are only available on the original ESP32.
+
+
 2. Using the defines database during preprocessing
 
    The preprocessor will automatically use a defines database, when using the
@@ -108,6 +123,7 @@ are not needed on the device either.)
    or instantiate the ``Preprocessor`` class directly, without passing it a
    DefinesDB instance via ``use_db``.
 
+
 Design choices
 --------------