docs/library/machine.RTC.rst: added description of method machine.RTC.memory.

twenrich · twenrich · commit 616a1bc123df · 2022-01-22T22:06:21.000+01:00
diff --git a/docs/library/machine.RTC.rst b/docs/library/machine.RTC.rst
@@ -81,8 +81,8 @@ Methods
    The data is stored together with a magic word to detect that the RTC memory is valid.
    An uninitialized or cleared RTC memory has no magic word and will deliver ``b''``.
    Without ``data`` the method delivers the RTC memory content.
-   In the ESP8266 are max. 492 bytes and in the ESP32 are max. 2048 Bytes storeable by this method. 
-   
+   In the ESP8266 are max. 492 bytes and in the ESP32 are max. 2048 Bytes storeable by this method.
+
    Example::
 
       import machine
@@ -94,9 +94,63 @@ Methods
 
    Availability: ESP8266, ESP32
 
+.. method:: RTC.usermem()
+
+   This is similar to the RTC.memory() above, but returns a bytearray object whose data
+   gets stored directly in the user memory area.
+
+   **The bytearray uses the same memory area as** ``RTC.memory()``, so a little care is required when using both methods.
+
+   Advantages over ``RTC.memory()``:
+
+   - quick access to the entire available RTC slow memory user area
+   - Python access to details of the memory area, e.g. by using ``uctypes.sizeof()``
+     and ``uctypes.addressof()``
+   - data loggers and similar applications don't need to copy the entire (up to 3.5k)
+     memory area
+
+   The data is stored together with a magic word to detect that the RTC memory is valid.
+   An uninitialized or cleared RTC memory has no magic word; the bytearray returned
+   by ``RTC.usermem()`` will contain binary zeroes.
+
+   Example::
+
+      from machine import RTC
+      import uctypes
+
+      RESERVED = 64       # leave a little space for RTC.memory()
+
+      STRUCT = {
+        "data1":        0 | uctypes.UINT32,
+        "data2":        0 | uctypes.UINT32,
+        }
+
+      # get the RTC memory area
+      rtc_mem = RTC().usermem()
+
+      data = uctypes.struct(uctypes.addressof(rtc_mem) + RESERVED, STRUCT)
+      print(data.data1)   # get data1 out of RTC memory
+      data.data1 = 4712   # set data1 in RTC memory
+
+   Availability: ESP32
+
 Constants
 ---------
 
 .. data:: RTC.ALARM0
 
     irq trigger source
+
+
+Compile-time options
+--------------------
+
+These can be set e.g. in ``ports/esp32/boards/XXX/mpconfigboard.h``
+
+``#define MICROPY_HW_RTC_USER_MEM_MAX     2048``
+
+sets the entire size of the user memory. This can be increased up to ~3500 bytes on the ESP32.
+
+A value of 0 (zero) disables ``RTC.memory()`` as well as ``RTC.usermem()``
+
+
