From 3d58bb23c28394fedd26151ab69cc4ba793043f1 Mon Sep 17 00:00:00 2001
From: Patrick Joy <74940387+ThinkTransit@users.noreply.github.com>
Date: Wed, 13 Apr 2022 21:32:13 +1000
Subject: [PATCH] docs/library/machine: Add note on interrupts being critical
 to system.

---
 docs/library/machine.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/library/machine.rst b/docs/library/machine.rst
index d66423d0d4..c3bf438961 100644
--- a/docs/library/machine.rst
+++ b/docs/library/machine.rst
@@ -48,6 +48,23 @@ Reset related functions
 Interrupt related functions
 ---------------------------
 
+The following functions allow control over interrupts.  Some systems require
+interrupts to operate correctly so disabling them for long periods may
+compromise core functionality, for example watchdog timers may trigger
+unexpectedly.  Interrupts should only be disabled for a minimum amount of time
+and then re-enabled to their previous state.  For example::
+
+    import machine
+
+    # Disable interrupts
+    state = machine.disable_irq()
+
+    # Do a small amount of time-critical work here
+
+    # Enable interrupts
+    machine.enable_irq(state)
+
+
 .. function:: disable_irq()
 
    Disable interrupt requests.