Merge branch 'doc/api-guides-add-hypertargets' into 'master'

Add hypertargets to all TRM references

Closes DOC-713

See merge request espressif/esp-idf!11952

docs/conf_common.py

@@ -14,17 +14,17 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from __future__ import print_function
-from __future__ import unicode_literals
-import sys
+from __future__ import print_function, unicode_literals
+
 import os
 import os.path
 import re
 import subprocess
-from sanitize_version import sanitize_version
-from idf_extensions.util import download_file_if_missing
-from get_github_rev import get_github_rev
+import sys
 
+from get_github_rev import get_github_rev
+from idf_extensions.util import download_file_if_missing
+from sanitize_version import sanitize_version
 
 # build_docs on the CI server sometimes fails under Python3. This is a workaround:
 sys.setrecursionlimit(3500)
@@ -140,7 +140,8 @@ BT_DOCS = ['api-guides/blufi.rst',
 SDMMC_DOCS = ['api-reference/peripherals/sdmmc_host.rst',
               'api-reference/peripherals/sd_pullup_requirements.rst']
 
-SDIO_SLAVE_DOCS = ['api-reference/peripherals/sdio_slave.rst']
+SDIO_SLAVE_DOCS = ['api-reference/peripherals/sdio_slave.rst',
+                   'api-reference/protocols/esp_sdio_slave_protocol.rst']
 
 MCPWM_DOCS = ['api-reference/peripherals/mcpwm.rst']
 
@@ -242,7 +243,7 @@ versions_url = 'https://dl.espressif.com/dl/esp-idf/idf_versions.js'
 idf_targets = ['esp32', 'esp32s2']
 languages = ['en', 'zh_CN']
 
-project_homepage = "https://github.com/espressif/esp-idf"
+project_homepage = 'https://github.com/espressif/esp-idf'
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -250,11 +251,11 @@ project_homepage = "https://github.com/espressif/esp-idf"
 #
 # Redirects should be listed in page_redirects.xt
 #
-with open("../page_redirects.txt") as f:
-    lines = [re.sub(" +", " ", line.strip()) for line in f.readlines() if line.strip() != "" and not line.startswith("#")]
+with open('../page_redirects.txt') as f:
+    lines = [re.sub(' +', ' ', line.strip()) for line in f.readlines() if line.strip() != '' and not line.startswith('#')]
     for line in lines:  # check for well-formed entries
         if len(line.split(' ')) != 2:
-            raise RuntimeError("Invalid line in page_redirects.txt: %s" % line)
+            raise RuntimeError('Invalid line in page_redirects.txt: %s' % line)
 html_redirect_pages = [tuple(line.split(' ')) for line in lines]
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -264,10 +265,10 @@ html_theme = 'sphinx_idf_theme'
 
 # context used by sphinx_idf_theme
 html_context = {
-    "display_github": True,  # Add 'Edit on Github' link instead of 'View page source'
-    "github_user": "espressif",
-    "github_repo": "esp-idf",
-    "github_version": get_github_rev(),
+    'display_github': True,  # Add 'Edit on Github' link instead of 'View page source'
+    'github_user': 'espressif',
+    'github_repo': 'esp-idf',
+    'github_version': get_github_rev(),
 }
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -287,7 +288,7 @@ html_context = {
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "../_static/espressif-logo.svg"
+html_logo = '../_static/espressif-logo.svg'
 
 
 # The name of an image file (within the static path) to use as favicon of the
@@ -380,7 +381,7 @@ latex_elements = {
 
 # The name of an image file (relative to this directory) to place at the bottom of
 # the title page.
-latex_logo = "../_static/espressif2.pdf"
+latex_logo = '../_static/espressif2.pdf'
 latex_engine = 'xelatex'
 latex_use_xindy = False
 
@@ -427,7 +428,7 @@ def setup(app):
     app.add_stylesheet('theme_overrides.css')
 
     # these two must be pushed in by build_docs.py
-    if "idf_target" not in app.config:
+    if 'idf_target' not in app.config:
         app.add_config_value('idf_target', None, 'env')
         app.add_config_value('idf_targets', None, 'env')
 
@@ -436,8 +437,8 @@ def setup(app):
 
     # Breathe extension variables (depend on build_dir)
     # note: we generate into xml_in and then copy_if_modified to xml dir
-    app.config.breathe_projects = {"esp32-idf": os.path.join(app.config.build_dir, "xml_in/")}
-    app.config.breathe_default_project = "esp32-idf"
+    app.config.breathe_projects = {'esp32-idf': os.path.join(app.config.build_dir, 'xml_in/')}
+    app.config.breathe_default_project = 'esp32-idf'
 
     setup_diag_font(app)
 
@@ -455,13 +456,13 @@ def setup_config_values(app, config):
 
     app.add_config_value('idf_target_title_dict', idf_target_title_dict, 'env')
 
-    pdf_name = "esp-idf-{}-{}-{}".format(app.config.language, app.config.version, app.config.idf_target)
+    pdf_name = 'esp-idf-{}-{}-{}'.format(app.config.language, app.config.version, app.config.idf_target)
     app.add_config_value('pdf_file', pdf_name, 'env')
 
 
 def setup_html_context(app, config):
     # Setup path for 'edit on github'-link
-    config.html_context['conf_py_path'] = "/docs/{}/".format(app.config.language)
+    config.html_context['conf_py_path'] = '/docs/{}/'.format(app.config.language)
 
 
 def setup_diag_font(app):
@@ -476,7 +477,7 @@ def setup_diag_font(app):
     font_dir = os.path.join(config_dir, '_static')
     assert os.path.exists(font_dir)
 
-    print("Downloading font file %s for %s" % (font_name, app.config.language))
+    print('Downloading font file %s for %s' % (font_name, app.config.language))
     download_file_if_missing('https://dl.espressif.com/dl/esp-idf/docs/_static/{}'.format(font_name), font_dir)
 
     font_path = os.path.abspath(os.path.join(font_dir, font_name))

docs/en/api-guides/general-notes.rst

@@ -68,7 +68,13 @@ Application code in ESP-IDF can be placed into one of the following memory regio
 IRAM (instruction RAM)
 ^^^^^^^^^^^^^^^^^^^^^^
 
-ESP-IDF allocates part of `Internal SRAM0` region (defined in the Technical Reference Manual) for instruction RAM. Except for the first 64 kB block which is used for PRO and APP CPU caches, the rest of this memory range (i.e. from ``0x40080000`` to ``0x400A0000``) is used to store parts of application which need to run from RAM.
+.. only:: esp32
+
+    ESP-IDF allocates part of `Internal SRAM0` region for instruction RAM. The region is defined in *{IDF_TARGET_NAME} Technical Reference Manual* > *System and Memory* > *Embedded Memory* [`PDF <{IDF_TARGET_TRM_EN_URL}#sysmem>`__]. Except for the first 64 kB block which is used for PRO and APP CPU caches, the rest of this memory range (i.e. from ``0x40080000`` to ``0x400A0000``) is used to store parts of application which need to run from RAM.
+
+.. only:: esp32s2
+
+    ESP-IDF allocates part of `Internal SRAM0` region for instruction RAM. The region is defined in *{IDF_TARGET_NAME} Technical Reference Manual* > *System and Memory* > *Internal Memory* [`PDF <{IDF_TARGET_TRM_EN_URL}#sysmem>`__]. Except for the first 64 kB block which is used for PRO and APP CPU caches, the rest of this memory range (i.e. from ``0x40080000`` to ``0x400A0000``) is used to store parts of application which need to run from RAM.
 
 A few components of ESP-IDF and parts of WiFi stack are placed into this region using the linker script.
 
@@ -90,7 +96,13 @@ Here are the cases when parts of application may or should be placed into IRAM.
 IROM (code executed from Flash)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If a function is not explicitly placed into IRAM or RTC memory, it is placed into flash. The mechanism by which Flash MMU is used to allow code execution from flash is described in the Technical Reference Manual. ESP-IDF places the code which should be executed from flash starting from the beginning of ``0x400D0000 — 0x40400000`` region. Upon startup, second stage bootloader initializes Flash MMU to map the location in flash where code is located into the beginning of this region. Access to this region is transparently cached using two 32kB blocks in ``0x40070000`` — ``0x40080000`` range.
+.. only:: SOC_SDIO_SLAVE_SUPPORTED
+
+    If a function is not explicitly placed into IRAM or RTC memory, it is placed into flash. The mechanism by which Flash MMU is used to allow code execution from flash is described in *{IDF_TARGET_NAME} Technical Reference Manual* > *Memory Management and Protection Units (MMU, MPU)* [`PDF <{IDF_TARGET_TRM_EN_URL}#mpummu>`__]. ESP-IDF places the code which should be executed from flash starting from the beginning of ``0x400D0000 — 0x40400000`` region. Upon startup, second stage bootloader initializes Flash MMU to map the location in flash where code is located into the beginning of this region. Access to this region is transparently cached using two 32kB blocks in ``0x40070000`` — ``0x40080000`` range.
+
+.. only:: not SOC_SDIO_SLAVE_SUPPORTED
+
+    If a function is not explicitly placed into IRAM or RTC memory, it is placed into flash. The mechanism by which Flash MMU is used to allow code execution from flash is described in `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`__. ESP-IDF places the code which should be executed from flash starting from the beginning of ``0x400D0000 — 0x40400000`` region. Upon startup, second stage bootloader initializes Flash MMU to map the location in flash where code is located into the beginning of this region. Access to this region is transparently cached using two 32kB blocks in ``0x40070000`` — ``0x40080000`` range.
 
 Note that the code outside ``0x40000000 — 0x40400000`` region may not be reachable with Window ABI ``CALLx`` instructions, so special care is required if ``0x40400000 — 0x40800000`` or ``0x40800000 — 0x40C00000`` regions are used by the application. ESP-IDF doesn't use these regions by default.
 

docs/en/api-guides/jtag-debugging/debugging-examples.rst

@@ -154,7 +154,7 @@ To display or set contents of memory use "Memory" tab at the bottom of "Debug" p
 
 With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's.
 
-For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`__, chapter IO_MUX and GPIO Matrix.
+For more information, see *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__].
 
 Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Click "Memory" tab and then "Add Memory Monitor" button. Enter ``0x3FF44004`` in provided dialog.
 
@@ -516,7 +516,7 @@ Displaying the contents of memory is done with command ``x``. With additional pa
 
 We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's.
 
-For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`__, chapter IO_MUX and GPIO Matrix.
+For more information, see *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__].
 
 Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Enter two times ``c`` to get to the break point followed by ``x /1wx 0x3FF44004`` to display contents of ``GPIO_OUT_REG`` memory location::
 

docs/en/api-reference/peripherals/dedic_gpio.rst

@@ -73,7 +73,7 @@ GPIO Bundle Operations
      - :cpp:func:`dedic_gpio_bundle_read_in`
 
 .. note::
-    The functions above just wrap the customized instructions defined for {IDF_TARGET_NAME}, for the details of those instructions, please refer to {IDF_TARGET_NAME} TRM.
+    The functions above just wrap the customized instructions defined for {IDF_TARGET_NAME}, for the details of those instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__].
 
 .. only:: esp32s2
 
@@ -113,7 +113,7 @@ For advanced users, they can always manipulate the GPIOs by writing assembly cod
 2. Query the mask occupied by that bundle: :cpp:func:`dedic_gpio_get_out_mask` or/and :cpp:func:`dedic_gpio_get_in_mask`
 3. Call CPU LL apis (e.g. `cpu_ll_write_dedic_gpio_mask`) or write assembly code with that mask
 
-For details of supported dedicated GPIO instructions, please refer to {IDF_TARGET_NAME} TRM.
+For details of supported dedicated GPIO instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__].
 
 .. note::
     Writing assembly code in application could make your code hard to port between targets, because those customized instructions are not guaranteed to remain the same format in different targets.

docs/en/api-reference/peripherals/ds.rst

@@ -7,7 +7,8 @@ The parameters are encrypted using HMAC as a key-derivation function.
 In turn, the HMAC uses eFuses as input key.
 The whole process happens in hardware so that neither the decryption key for the RSA parameters nor the input key for the HMAC key derivation function can be seen by the software while calculating the signature.
 
-Look into the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF) for more detailed information about the involved hardware during the signature calculation process and the used registers.
+For more detailed information on the hardware involved in signature calculation and the registers used, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
+
 
 Private Key Parameters
 ----------------------
@@ -24,11 +25,12 @@ Both the HMAC key and the RSA private key have to be created and stored before t
 This needs to be done in software on the {IDF_TARGET_NAME} or alternatively on a host.
 For this context, the IDF provides :cpp:func:`esp_efuse_write_block` to set the HMAC key and :cpp:func:`esp_hmac_calculate` to encrypt the private RSA key parameters.
 
-Instructions on how to calculate and assemble the private key parameters are described in the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
+You can find instructions on how to calculate and assemble the private key parameters in *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
 
 Signature Calculation with IDF
 ------------------------------
-*For thorough information about involved registers and the workflow, please have a look at the* `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
+
+For more detailed information on the workflow and the registers used, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
 
 Three parameters need to be prepared to calculate the digital signature:
 
@@ -57,7 +59,7 @@ The configuration involves the following steps -
 3) Calculate the encrypted private key paramters from the client private key (RSA) and the parameters generated in the above steps.
 4) Then burn the 256 bit `HMAC_KEY` on the efuse, which can only be read by the DS peripheral.
 
-For more technical details visit the `Digital Signature` chapter in `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
+For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
 
 To configure the DS peripheral for development purposes, you can use the python script :example_file:`configure_ds.py<protocols/mqtt/ssl_ds/configure_ds.py>`.
 More details about the `configure_ds.py` script can be found at :example_file:`mqtt example README <protocols/mqtt/ssl_ds/README.md>`.

docs/en/api-reference/peripherals/gpio.rst

@@ -6,14 +6,14 @@ Overview
 
 .. only:: esp32
 
-    The {IDF_TARGET_NAME} chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
+    The {IDF_TARGET_NAME} chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package. For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__]. Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
 
     - Note that GPIO6-11 are usually used for SPI flash.
     - GPIO34-39 can only be set as input mode and do not have software pullup or pulldown functions.
 
 .. only:: esp32s2
 
-    The {IDF_TARGET_NAME} chip features 43 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
+    The {IDF_TARGET_NAME} chip features 43 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package. For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__]. Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
 
     - Note that GPIO26-32 are usually used for SPI flash.
     - GPIO46 is fixed to pull-down and is input only

docs/en/api-reference/peripherals/hmac.rst

@@ -4,7 +4,7 @@ HMAC
 The HMAC (Hash-based Message Authentication Code) module provides hardware acceleration for SHA256-HMAC generation using a key burned into an eFuse block.
 HMACs work with pre-shared secret keys and provide authenticity and integrity to a message.
 
-Look into the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF) for more detailed information about the application workflow and the HMAC calculation process.
+For more detailed information on the application workflow and the HMAC calculation process, see *{IDF_TARGET_NAME} Technical Reference Manual* > *HMAC Accelerator (HMAC)* [`PDF <{IDF_TARGET_TRM_EN_URL}#hmac>`__].
 
 Generalized Application Scheme
 ------------------------------
@@ -57,7 +57,7 @@ Each key has a corresponding eFuse parameter *key purpose* determining for which
 
 This is to prevent the usage of a key for a different function than originally intended.
 
-To calculate an HMAC, the software has to provide the ID of the key block containing the secret key as well as the *key purpose* (see chapter *eFuse Controller* in the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_).
+To calculate an HMAC, the software has to provide the ID of the key block containing the secret key as well as the *key purpose* (see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__]).
 Before the HMAC key calculation, the HMAC module looks up the purpose of the provided key block. 
 The calculation only proceeds if the provided key purpose matches the purpose stored in the eFuses of the key block provided by the ID.
 
@@ -81,7 +81,7 @@ The user only needs to provide the eFuse key block and purpose on the HMAC side
 Neither the key nor the actual HMAC are ever exposed to outside the HMAC module and DS component.
 The calculation of the HMAC and its hand-over to the DS component happen internally.
 
-For more details, check the chapter *Digital Signature* in the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
+For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
 
 HMAC for Enabling JTAG
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -103,7 +103,7 @@ JTAG enable
 2. Pass this key value when calling the :cpp:func:`esp_hmac_jtag_enable` function from the firmware.
 3. To re-disable JTAG in the firmware, reset the system or call :cpp:func:`esp_hmac_jtag_disable`.
 
-For more details, check the chapter *HMAC Module* in the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
+For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *HMAC Accelerator (HMAC)* [`PDF <{IDF_TARGET_TRM_EN_URL}#hmac>`__].
 
 
 Application Outline

docs/en/api-reference/peripherals/i2c.rst

@@ -260,7 +260,7 @@ A code example showing how to use these functions can be found in :example:`peri
 Interrupt Handling
 ^^^^^^^^^^^^^^^^^^
 
-During driver installation, an interrupt handler is installed by default. However, you can register your own interrupt handler instead of the default one by calling the function :cpp:func:`i2c_isr_register`. When implementing your own interrupt handler, refer to the `{IDF_TARGET_NAME} Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>`_ for the description of interrupts triggered by the I2C controller.
+During driver installation, an interrupt handler is installed by default. However, you can register your own interrupt handler instead of the default one by calling the function :cpp:func:`i2c_isr_register`. When implementing your own interrupt handler, refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *I2C Controller (I2C)* > *Interrupts* [`PDF <{IDF_TARGET_TRM_EN_URL}#i2c>`__] for the description of interrupts triggered by the I2C controller.
 
 To delete an interrupt handler, call :cpp:func:`i2c_isr_free`.
 

docs/en/api-reference/peripherals/i2s.rst

@@ -38,7 +38,7 @@ The I2S peripherals also support LCD mode for communicating data over a parallel
 
 .. only:: esp32
 
-    For more information, see the `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=306>`_.
+    For more information, see *{IDF_TARGET_NAME} Technical Reference Manual* > *I2S Controller (I2S)* > LCD Mode [`PDF <{IDF_TARGET_TRM_EN_URL}#camlcdctrl>`__].
 
 .. note::
 

docs/en/api-reference/peripherals/ledc.rst

@@ -157,7 +157,7 @@ LEDC High and Low Speed Mode
 
     The advantage of high speed mode is glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called. 
 
-    For additional details regarding speed modes, refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
+    For additional details regarding speed modes, see *{IDF_TARGET_NAME} Technical Reference Manual* > *LED PWM Controller (LEDC)* [`PDF <{IDF_TARGET_TRM_EN_URL}#ledpwm>`__]. Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
 
 .. only:: esp32s2
 

docs/en/api-reference/peripherals/mcpwm.rst

@@ -92,7 +92,7 @@ There are couple of ways to adjust a signal on the outputs and changing how the
     Synchronization signals are referred to using two different enumerations. First one :cpp:type:`mcpwm_io_signals_t` is used together with function :cpp:func:`mcpwm_gpio_init` when selecting a GPIO as the signal input source. The second one :cpp:type:`mcpwm_sync_signal_t` is used when enabling or disabling synchronization with :cpp:func:`mcpwm_sync_enable` or :cpp:func:`mcpwm_sync_disable`.
 
 
-* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `{IDF_TARGET_NAME} Technical Reference Manual`_.
+* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Motor Control PWM (MCPWM)* [`PDF <{IDF_TARGET_TRM_EN_URL}#mcpwm>`__].
 
 Capture
 -------
@@ -150,7 +150,7 @@ To use the carrier submodule, it should be first initialized by calling :cpp:fun
 
 The carrier parameters may be then alerted at a runtime by calling dedicated functions to change individual fields of the :cpp:type:`mcpwm_carrier_config_t` structure, like :cpp:func:`mcpwm_carrier_set_period`, :cpp:func:`mcpwm_carrier_set_duty_cycle`, :cpp:func:`mcpwm_carrier_output_invert`, etc.
 
-This includes enabling and setting duration of the first pulse of the career with :cpp:func:`mcpwm_carrier_oneshot_mode_enable`. For more details please refer to "PWM Carrier Submodule" section of the `{IDF_TARGET_NAME} Technical Reference Manual`_.
+This includes enabling and setting duration of the first pulse of the career with :cpp:func:`mcpwm_carrier_oneshot_mode_enable`. For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *Motor Control PWM (MCPWM)* > *PWM Carrier Submodule* [`PDF <{IDF_TARGET_TRM_EN_URL}#mcpwm>`__].
 
 To disable carrier functionality call :cpp:func:`mcpwm_carrier_disable`.
 
@@ -171,8 +171,6 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`:
 * Brushed DC motor control - :example:`peripherals/mcpwm/mcpwm_brushed_dc_control`
 * Servo motor control - :example:`peripherals/mcpwm/mcpwm_servo_control`
 
-.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_EN_URL}
-
 
 API Reference
 -------------

docs/en/api-reference/peripherals/sd_pullup_requirements.rst

@@ -217,7 +217,7 @@ To resolve the conflict, you have the following options:
 
    If running from an automated flashing script, ``espefuse.py`` has an option ``--do-not-confirm``.
 
-   For more details, see the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF).
+   For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
 
 2. **If using 1-bit SD mode or SPI mode**, disconnect the DAT2 pin and make sure it is pulled high. For this, do one the following:
 

docs/en/api-reference/peripherals/sdio_slave.rst

@@ -94,7 +94,8 @@ The SDIO slave driver uses the following terms:
 - Sending: slave to host transfers.
 - Receiving: host to slave transfers.
 
-.. note:: Register names in ESP Rechnical Reference Manual are oriented from the point of view of the host, i.e. 'rx'
+.. note:: Register names in *{IDF_TARGET_NAME} Technical Reference Manual* > *SDIO Slave Controller* 
+  [`PDF <{IDF_TARGET_TRM_EN_URL}#sdioslave>`__] are oriented from the point of view of the host, i.e. 'rx'
   registers refer to sending, while 'tx' registers refer to receiving. We're not using `tx` or `rx` in the driver to
   avoid ambiguities.
 

docs/en/api-reference/peripherals/touch_pad.rst

@@ -18,7 +18,7 @@ A touch sensor system is built on a substrate which carries electrodes and relev
 
  The sensing pads can be arranged in different combinations (e.g., matrix, slider), so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer.
 
-Design, operation, and control registers of a touch sensor are discussed in `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF). Please refer to this manual for additional details on how this subsystem works.
+For design, operation, and control registers of a touch sensor, see *{IDF_TARGET_NAME} Technical Reference Manual* > *On-Chip Sensors and Analog Signal Processing* [`PDF <{IDF_TARGET_TRM_EN_URL}#sensor>`__].
 
 In-depth design details of touch sensors and firmware development guidelines for {IDF_TARGET_NAME} are available in `Touch Sensor Application Note <https://github.com/espressif/esp-iot-solution/blob/master/documents/touch_pad_solution/touch_sensor_design_en.md>`_.
 

docs/en/api-reference/peripherals/uart.rst

@@ -232,7 +232,7 @@ The UART controller supports a number of communication modes. A mode can be sele
 Using Interrupts
 ^^^^^^^^^^^^^^^^
 
-There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided  `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF).. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively. The mask of all interrupts is available as :c:macro:`UART_INTR_MASK`.
+There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided in *{IDF_TARGET_NAME} Technical Reference Manual* > *UART Controller (UART)* > *UART Interrupts* and *UHCI Interrupts* [`PDF <{IDF_TARGET_TRM_EN_URL}#uart>`__]. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively. The mask of all interrupts is available as :c:macro:`UART_INTR_MASK`.
 
 By default, the :cpp:func:`uart_driver_install` function installs the driver's internal interrupt handler to manage the Tx and Rx ring buffers and provides high-level API functions like events (see below). It is also possible to register a lower level interrupt handler instead using :cpp:func:`uart_isr_register`, and to free it again using :cpp:func:`uart_isr_free`. Some UART driver functions which use the Tx and Rx ring buffers, events, etc. will not automatically work in this case - it is necessary to handle the interrupts directly in the ISR. Inside the custom handler implementation, clear the interrupt status bits using :cpp:func:`uart_clear_intr_status`.
 
@@ -271,7 +271,7 @@ Overview of RS485 specific communication options
 
 .. note::
 
-    The following section will use ``[UART_REGISTER_NAME].[UART_FIELD_BIT]`` to refer to UART register fields/bits. To find more information on a specific option bit, open the Register Summary section of the SoC Technical Reference Manual. Use the register name to navigate to the register description and then find the field/bit.
+    The following section will use ``[UART_REGISTER_NAME].[UART_FIELD_BIT]`` to refer to UART register fields/bits. For more information on a specific option bit, see *{IDF_TARGET_NAME} Technical Reference Manual* > *UART Controller (UART)* > *Register Summary* [`PDF <{IDF_TARGET_TRM_EN_URL}#uart-reg-summ>`__]. Use the register name to navigate to the register description and then find the field/bit.
 
 - ``UART_RS485_CONF_REG.UART_RS485_EN``: setting this bit enables RS485 communication mode support.
 - ``UART_RS485_CONF_REG.UART_RS485TX_RX_EN``: if this bit is set, the transmitter's output signal loops back to the receiver's input signal.

docs/en/api-reference/protocols/esp_sdio_slave_protocol.rst

@@ -10,26 +10,30 @@ The ESP SDIO Slave protocol was created to implement the communication between S
 SDIO Slave Capabilities of Espressif chips
 ------------------------------------------
 
-The services provided by SDIO Slave peripherals of Espressif chips are different. See the table below:
-
-+-----------------------------------------------------------+-------+----------+
-|                                                           | ESP32 | ESP32-S2 |
-+===========================================================+=======+==========+
-| SDIO slave                                                | Y     | N        |
-+-----------------------------------------------------------+-------+----------+
-| :ref:`Tohost intr <esp_sdio_slave_interrupts>`            | 8     |          |
-+-----------------------------------------------------------+-------+----------+
-| :ref:`Frhost intr <esp_sdio_slave_interrupts>`            | 8     |          |
-+-----------------------------------------------------------+-------+----------+
-| :ref:`TX DMA <esp_sdio_slave_send_fifo>`                  | Y     |          |
-+-----------------------------------------------------------+-------+----------+
-| :ref:`RX DMA <esp_sdio_slave_rcv_fifo>`                   | Y     |          |
-+-----------------------------------------------------------+-------+----------+
-| :ref:`Shared registers <esp_sdio_slave_shared_registers>` | 56\*  |          |
-+-----------------------------------------------------------+-------+----------+
+The services provided by the SDIO Slave peripheral of the {IDF_TARGET_NAME} chip are listed in the table below:
+
+.. list-table::
+   :widths: 70 30
+   :header-rows: 1
+
+   * - Services
+     - {IDF_TARGET_NAME}
+   * - SDIO slave
+     - Y
+   * - :ref:`Tohost intr <esp_sdio_slave_interrupts>`
+     - 8
+   * - :ref:`Frhost intr <esp_sdio_slave_interrupts>`
+     - 8
+   * - :ref:`TX DMA <esp_sdio_slave_send_fifo>`
+     - Y
+   * - :ref:`RX DMA <esp_sdio_slave_rcv_fifo>`
+     - Y
+   * - :ref:`Shared registers <esp_sdio_slave_shared_registers>`
+     - 56\*
 
 - \* Not including the interrupt registers
 
+
 .. _esp_slave_init:
 
 ESP SDIO Slave Initialization
@@ -103,7 +107,7 @@ ESP SDIO Slave Protocol
 The ESP SDIO Slave protocol is based on the SDIO Specification's I/O Read/Write commands, i.e., CMD52 and CMD53. The protocol offers the following services:
 
 - Sending FIFO and receiving FIFO
-- 52 8-bit R/W registers shared by host and slave (For details, see Section 8.4 Register summary (table SDIO SLC Host registers) in `{IDF_TARGET_NAME} Technical reference manual`_
+- 52 8-bit R/W registers shared by host and slave (For details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *SDIO Slave Controller* > *Register Summary* > SDIO SLC Host registers [`PDF <{IDF_TARGET_TRM_EN_URL}#sdioslave-reg-summ>`__]
 - 16 general purpose interrupt sources, 8 from host to slave and 8 from slave to host
 
 To begin communication, the host needs to enable the I/O Function 1 in the slave and access its registers as described below.
@@ -112,8 +116,6 @@ Check the code example :example:`peripherals/sdio`.
 
 The :doc:`ESP Serial Slave Link </api-reference/protocols/esp_serial_slave_link>` component implements the logic of this protocol for ESP32 SDIO Host when communicating with an ESP32 SDIO slave.
 
-.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_EN_URL}
-
 .. _esp_sdio_slave_shared_registers:
 
 Slave register table

docs/en/api-reference/protocols/esp_serial_slave_link.rst

@@ -20,7 +20,7 @@ For more details about Espressif device protocols, see the following documents.
 .. toctree::
     :maxdepth: 1
 
-    esp_sdio_slave_protocol
+    :SOC_SDIO_SLAVE_SUPPORTED: esp_sdio_slave_protocol
     esp_spi_slave_protocol
 
 Terminology
@@ -80,8 +80,14 @@ There are some common services provided by the Espressif slaves:
 5. Shared registers: the master can read some part of the registers on the slave, and also write
    these registers to let the slave read.
 
-The services provided by the slave depends on the slave's model. See
-:ref:`esp_sdio_slave_caps` and :ref:`esp_spi_slave_caps` for more details.
+.. only:: SOC_SDIO_SLAVE_SUPPORTED
+
+   The services provided by the slave depends on the slave's model. See :ref:`esp_sdio_slave_caps` and :ref:`esp_spi_slave_caps` for more details.
+
+.. only:: not SOC_SDIO_SLAVE_SUPPORTED
+
+   The services provided by the slave depends on the slave's model. See :ref:`esp_spi_slave_caps` for more details.
+
 
 Initialization of ESP Serial Slave Link
 ---------------------------------------

docs/en/api-reference/protocols/esp_tls.rst

@@ -146,7 +146,7 @@ SSL/TLS libraries and with all respective configurations set to default.
     ESP-TLS provides support for using the Digital Signature (DS) with ESP32-S2.
     Use of the DS for TLS is supported only when ESP-TLS is used with mbedTLS (default stack) as its underlying SSL/TLS stack.
     For more details on Digital Signature, please refer to the :doc:`Digital Signature Documentation </api-reference/peripherals/ds>`. The technical details of Digital Signature such as
-    how to calculate private key parameters can be found at `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
+    how to calculate private key parameters can be found in *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__].
     The DS peripheral must be configured before it can be used to perform Digital Signature, see `Configure the DS Peripheral` in :doc:`Digital Signature </api-reference/peripherals/ds>`.
 
     .. note:: As the DS peripheral support is only available for ESP32-S2, the idf-target should be set to ESP32-S2. See `Selecting the Target` in :doc:`build-system.</api-guides/build-system>`.

docs/en/api-reference/system/app_image_format.rst

@@ -58,7 +58,13 @@ You can also see the information on segments in the IDF logs while your applicat
 	I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0) load
 	I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 ( 0) load
 
-For more details on the type of memory segments and their address ranges, see the {IDF_TARGET_NAME} Technical Reference Manual, Section 1.3.2 *Embedded Memory*.
+.. only:: esp32
+
+    For more details on the type of memory segments and their address ranges, see *{IDF_TARGET_NAME} Technical Reference Manual* > *System and Memory* > *Embedded Memory* [`PDF <{IDF_TARGET_TRM_EN_URL}#sysmem>`__].
+
+.. only:: esp32s2
+
+    For more details on the type of memory segments and their address ranges, see *{IDF_TARGET_NAME} Technical Reference Manual* > *System and Memory* > *Internal Memory* [`PDF <{IDF_TARGET_TRM_EN_URL}#sysmem>`__].
 
 3. The image has a single checksum byte after the last segment. This byte is written on a sixteen byte padded boundary, so the application image might need padding.
 4. If the ``hash_appended`` field from :cpp:type:`esp_image_header_t` is set then a SHA256 checksum will be appended. The value of SHA256 is calculated on the range from first byte and up to this field. The length of this field is 32 bytes.

docs/en/api-reference/system/efuse.rst

@@ -14,7 +14,7 @@ Hardware description
 The {IDF_TARGET_NAME} has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0.
 Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0).
 
-For more details, see Chapter eFuse Controller of `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_. Some eFuse bits are available for user applications.
+For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__]. Some eFuse bits are available for user applications.
 
 .. only:: esp32
 

docs/en/api-reference/system/sleep_modes.rst

@@ -29,7 +29,7 @@ Wakeup sources
 Timer
 ^^^^^
 
-RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. See chapter "Reset and Clock" of the {IDF_TARGET_NAME} Technical Reference Manual for details about RTC clock options.
+RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. For details on RTC clock options, see *{IDF_TARGET_NAME} Technical Reference Manual* > *ULP Coprocessor* [`PDF <{IDF_TARGET_TRM_EN_URL}#ulp>`__].
 
 This wakeup mode doesn't require RTC peripherals or RTC memories to be powered on during sleep.
 

docs/en/security/flash-encryption.rst

@@ -106,7 +106,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF
          - Yes
          - x
        * - ``KEY_PURPOSE_N``
-         - Controls the purpose of eFuse block ``KEYN``, where N is between 0 and 5. Possible values: ``2`` for ``XTS_AES_256_KEY_1`` , ``3`` for ``XTS_AES_256_KEY_2``, and ``4`` for ``XTS_AES_128_KEY``. Final AES key is derived based on the value of one or two of these purpose eFuses. For a detailed description of the possible combinations see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_, chapter Flash Encryption.
+         - Controls the purpose of eFuse block ``KEYN``, where N is between 0 and 5. Possible values: ``2`` for ``XTS_AES_256_KEY_1`` , ``3`` for ``XTS_AES_256_KEY_2``, and ``4`` for ``XTS_AES_128_KEY``. Final AES key is derived based on the value of one or two of these purpose eFuses. For a detailed description of the possible combinations, see *{IDF_TARGET_NAME} Technical Reference Manual* > *External Memory Encryption and Decryption (XTS_AES)* [`PDF <{IDF_TARGET_TRM_EN_URL}#extmemencr>`__].
          - 4
          - Yes
          - 0
@@ -168,7 +168,7 @@ Assuming that the eFuse values are in their default states and the firmware boot
 
   1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader.
 
-  2. Firmware bootloader reads the ``FLASH_CRYPT_CNT`` eFuse value (``0b00000000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. It also sets the ``FLASH_CRYPT_CONFIG`` eFuse to 0xF. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
+  2. Firmware bootloader reads the ``FLASH_CRYPT_CNT`` eFuse value (``0b00000000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. It also sets the ``FLASH_CRYPT_CONFIG`` eFuse to 0xF. For more information on the flash encryption block, see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* > *Flash Encryption Block* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
 
   3. Flash encryption block generates an AES-256 bit key and writes it into the BLOCK1 eFuse. This operation is done entirely by hardware, and the key cannot be accessed via software.
 
@@ -186,7 +186,7 @@ Assuming that the eFuse values are in their default states and the firmware boot
 
   1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader.
 
-  2. Firmware bootloader reads the ``SPI_BOOT_CRYPT_CNT`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_.
+  2. Firmware bootloader reads the ``SPI_BOOT_CRYPT_CNT`` eFuse value (``0b000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* > *Auto Encryption Block* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
 
   3. Flash encryption block generates an 256 bit or 512 bit key, depending on the value of :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>`, and writes it into respectively one or two `KEYN` eFuses. The software also updates the ``KEY_PURPOSE_N`` for the blocks where the keys where stored. This operation is done entirely by hardware, and the key cannot be accessed via software.
 
@@ -222,8 +222,6 @@ During the development stage, there is a frequent need to program different plai
 
 Hence, two different flash encryption configurations were created: for development and for production. For details on these configurations, see Section `Flash Encryption Configuration`_.
 
-.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_EN_URL}
-
 
 Flash Encryption Configuration
 ------------------------------

docs/en/security/secure-boot-v1.rst

@@ -19,7 +19,7 @@ Background
 
 - Most data is stored in flash. Flash access does not need to be protected from physical access in order for secure boot to function, because critical data is stored (non-software-accessible) in Efuses internal to the chip.
 
-- Efuses are used to store the secure bootloader key (in efuse BLOCK2), and also a single Efuse bit (ABS_DONE_0) is burned (written to 1) to permanently enable secure boot on the chip.  For more details about efuse, see Chapter 11 "eFuse Controller" in the Technical Reference Manual.
+- Efuses are used to store the secure bootloader key (in efuse BLOCK2), and also a single Efuse bit (ABS_DONE_0) is burned (written to 1) to permanently enable secure boot on the chip.  For more details on eFuses, see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
 
 - To understand the secure boot process, first familiarise yourself with the standard :doc:`ESP-IDF boot process <../api-guides/general-notes>`.
 
@@ -58,11 +58,7 @@ The following keys are used by the secure boot process:
 
   .. only:: esp32
 
-    See ESP32 Technical Reference Manual section 20.3.1.3 *System Parameter coding_scheme* for more details.
-
-  .. only:: esp32s2
-
-    See ESP32-S2 Technical Reference Manual for more details.
+    For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* > *System Parameter coding_scheme* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
 
   The algorithm operates on a 256 bit key in all cases, 192 bit keys are extended by repeating some bits (:ref:`details<secure-bootloader-digest-algorithm>`).