6 files changed, 58 insertions, 15 deletions
diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
index dc35e7905e..24831c58d6 100644
--- a/docs/library/esp32.rst
+++ b/docs/library/esp32.rst
@@ -80,6 +80,29 @@ Functions
        The result of :func:`gc.mem_free()` is the total of the current "free"
        and "max new split" values printed by :func:`micropython.mem_info()`.
 
+.. function:: idf_task_info()
+
+    Returns information about running ESP-IDF/FreeRTOS tasks, which include
+    MicroPython threads. This data is useful to gain insight into how much time
+    tasks spend running or if they are blocked for significant parts of time,
+    and to determine if allocated stacks are fully utilized or might be reduced.
+
+    ``CONFIG_FREERTOS_USE_TRACE_FACILITY=y`` must be set in the board
+    configuration to make this method available. Additionally configuring
+    ``CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS=y`` and
+    ``CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID=y`` is recommended to be able to
+    retrieve the total and per-task runtime and the core ID respectively.
+
+    The return value is a 2-tuple where the first value is the total runtime,
+    and the second a list of tasks. Each task is a 7-tuple containing: the task
+    ID, name, current state, priority, runtime, stack high water mark, and the
+    ID of the core it is running on. Runtime and core ID will be None when the
+    respective FreeRTOS configuration option is not enabled.
+
+    .. note:: For an easier to use output based on this function you can use the
+       `utop library <https://github.com/micropython/micropython-lib/tree/master/micropython/utop>`_,
+       which implements a live overview similar to the Unix ``top`` command.
+
 
 Flash partitions
 ----------------
diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst
index f22a3613bd..e2a231207d 100644
--- a/docs/library/framebuf.rst
+++ b/docs/library/framebuf.rst
@@ -137,6 +137,18 @@ Other methods
     is compared to the value from *palette*, not to the value directly from
     *fbuf*.)
 
+    *fbuf* can be another FrameBuffer instance, or a tuple or list of the form::
+
+        (buffer, width, height, format)
+
+    or::
+
+        (buffer, width, height, format, stride)
+
+    This matches the signature of the FrameBuffer constructor, and the elements
+    of the tuple/list are the same as the arguments to the constructor except that
+    the *buffer* here can be read-only.
+
     The *palette* argument enables blitting between FrameBuffers with differing
     formats. Typical usage is to render a monochrome or grayscale glyph/icon to
     a color display. The *palette* is a FrameBuffer instance whose format is
diff --git a/docs/library/machine.PWM.rst b/docs/library/machine.PWM.rst
index 5f592b8dff..c2b606affd 100644
--- a/docs/library/machine.PWM.rst
+++ b/docs/library/machine.PWM.rst
@@ -11,20 +11,20 @@ Example usage::
     from machine import PWM
 
     pwm = PWM(pin, freq=50, duty_u16=8192)  # create a PWM object on a pin
-                                            # and set freq and duty
-    pwm.duty_u16(32768)     # set duty to 50%
+                                            # and set freq 50 Hz and duty 12.5%
+    pwm.duty_u16(32768)                     # set duty to 50%
 
     # reinitialise with a period of 200us, duty of 5us
     pwm.init(freq=5000, duty_ns=5000)
 
-    pwm.duty_ns(3000)       # set pulse width to 3us
+    pwm.duty_ns(3000)                       # set pulse width to 3us
 
     pwm.deinit()
 
 Constructors
 ------------
 
-.. class:: PWM(dest, *, freq, duty_u16, duty_ns, invert)
+.. class:: PWM(dest, *, freq, duty_u16, duty_ns, invert=False)
 
    Construct and return a new PWM object using the following parameters:
 
@@ -40,7 +40,7 @@ Constructors
    Setting *freq* may affect other PWM objects if the objects share the same
    underlying PWM generator (this is hardware specific).
    Only one of *duty_u16* and *duty_ns* should be specified at a time.
-   *invert* is not available at all ports.
+   *invert* is available only on the esp32, mimxrt, nrf, rp2, samd and zephyr ports.
 
 Methods
 -------
@@ -116,10 +116,10 @@ Limitations of PWM
   resolution of 8 bit, not 16-bit as may be expected.  In this case, the lowest
   8 bits of *duty_u16* are insignificant. So::
 
-    pwm=PWM(Pin(13), freq=300_000, duty_u16=2**16//2)
+    pwm=PWM(Pin(13), freq=300_000, duty_u16=65536//2)
 
   and::
 
-    pwm=PWM(Pin(13), freq=300_000, duty_u16=2**16//2 + 255)
+    pwm=PWM(Pin(13), freq=300_000, duty_u16=65536//2 + 255)
 
   will generate PWM with the same 50% duty cycle.
diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst
index 5be79cccce..fbad3fc592 100644
--- a/docs/library/machine.UART.rst
+++ b/docs/library/machine.UART.rst
@@ -224,7 +224,8 @@ Methods
 
 
    .. note::
-     - The ESP32 port does not support the option hard=True.
+     - The ESP32 port does not support the option hard=True. It uses Timer(0)
+       for UART.IRQ_RXIDLE, so this timer cannot be used for other means.
 
      - The rp2 port's UART.IRQ_TXIDLE is only triggered when the message
        is longer than 5 characters and the trigger happens when still 5 characters
diff --git a/docs/library/socket.rst b/docs/library/socket.rst
index 944e7e631a..38e0aab704 100644
--- a/docs/library/socket.rst
+++ b/docs/library/socket.rst
@@ -227,22 +227,28 @@ Methods
    has the same "no short writes" policy for blocking sockets, and will return
    number of bytes sent on non-blocking sockets.
 
-.. method:: socket.recv(bufsize)
+.. method:: socket.recv(bufsize, [flags])
 
    Receive data from the socket. The return value is a bytes object representing the data
    received. The maximum amount of data to be received at once is specified by bufsize.
 
+   Most ports support the optional *flags* argument. Available *flags* are defined as constants
+   in the socket module and have the same meaning as in CPython. ``MSG_PEEK`` and ``MSG_DONTWAIT``
+   are supported on all ports which accept the *flags* argument.
+
 .. method:: socket.sendto(bytes, address)
 
    Send data to the socket. The socket should not be connected to a remote socket, since the
    destination socket is specified by *address*.
 
-.. method:: socket.recvfrom(bufsize)
+.. method:: socket.recvfrom(bufsize, [flags])
 
   Receive data from the socket. The return value is a pair *(bytes, address)* where *bytes* is a
   bytes object representing the data received and *address* is the address of the socket sending
   the data.
 
+  See the `recv` function for an explanation of the optional *flags* argument.
+
 .. method:: socket.setsockopt(level, optname, value)
 
    Set the value of the given socket option. The needed symbolic constants are defined in the
diff --git a/docs/library/time.rst b/docs/library/time.rst
index 8c1c1d4d6f..b53bb133ec 100644
--- a/docs/library/time.rst
+++ b/docs/library/time.rst
@@ -9,9 +9,10 @@
 The ``time`` module provides functions for getting the current time and date,
 measuring time intervals, and for delays.
 
-**Time Epoch**: Unix port uses standard for POSIX systems epoch of
-1970-01-01 00:00:00 UTC. However, some embedded ports use epoch of
-2000-01-01 00:00:00 UTC. Epoch year may be determined with ``gmtime(0)[0]``.
+**Time Epoch**: The unix, windows, webassembly, alif, mimxrt and rp2 ports
+use the standard for POSIX systems epoch of 1970-01-01 00:00:00 UTC.
+The other embedded ports use an epoch of 2000-01-01 00:00:00 UTC.
+Epoch year may be determined with ``gmtime(0)[0]``.
 
 **Maintaining actual calendar date/time**: This requires a
 Real Time Clock (RTC). On systems with underlying OS (including some
@@ -57,11 +58,11 @@ Functions
    * weekday is 0-6 for Mon-Sun
    * yearday is 1-366
 
-.. function:: mktime()
+.. function:: mktime(date_time_tuple)
 
    This is inverse function of localtime. It's argument is a full 8-tuple
    which expresses a time as per localtime. It returns an integer which is
-   the number of seconds since Jan 1, 2000.
+   the number of seconds since the time epoch.
 
 .. function:: sleep(seconds)