Merge branch 'feature/ulp_mutex' into 'master'

ulp-riscv: mutex/lock

Closes IDF-5754

See merge request espressif/esp-idf!19377

docs/en/api-reference/system/ulp-risc-v.rst

@@ -98,6 +98,18 @@ To access the ULP RISC-V program variables from the main program, the generated
         ulp_measurement_count = 64;
     }
 
+Mutual Exclusion
+^^^^^^^^^^^^^^^^
+
+If mutual exclusion is needed when accessing a variable shared between the main program and ULP then this can be achieved by using the ULP RISC-V lock API:
+
+ * :cpp:func:`ulp_riscv_lock_acquire`
+ * :cpp:func:`ulp_riscv_lock_release`
+
+The ULP does not have any hardware instructions to facilitate mutual exclusion so the lock API achieves this through a software algorithm (`Peterson's algorithm <https://en.wikipedia.org/wiki/Peterson%27s_algorithm>`_).
+
+The locks are intended to only be called from a single thread in the main program, and will not provide mutual exclusion if used simultaneously from multiple threads.
+
 Starting the ULP RISC-V Program
 -------------------------------
 
@@ -152,7 +164,6 @@ Keeping this in mind, here are some ways that may help you debug you ULP RISC-V
 
  * Trap signal: the ULP RISC-V has a hardware trap that will trigger under certain conditions, e.g., illegal instruction. This will cause the main CPU to be woken up with the wake-up cause :cpp:enumerator:`ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG`.
 
-
 Application Examples
 --------------------
 
@@ -164,3 +175,5 @@ API Reference
 -------------
 
 .. include-build-file:: inc/ulp_riscv.inc
+.. include-build-file:: inc/ulp_riscv_lock_shared.inc
+.. include-build-file:: inc/ulp_riscv_lock.inc