docs/reference/isr_rules: Describe issue with hard ISRs and globals.

peterhinch · dpgeorge · commit 624bd48d2fd9 · 2025-01-16T16:44:00.000+11:00
Signed-off-by: Damien George &lt;damien@micropython.org&gt;
diff --git a/docs/reference/isr_rules.rst b/docs/reference/isr_rules.rst
@@ -170,11 +170,17 @@ is partially updated. When the ISR tries to read the object, a crash results. Be
 on rare, random occasions they can be hard to diagnose. There are ways to circumvent this issue, described in
 :ref:`Critical Sections <Critical>` below.
 
-It is important to be clear about what constitutes the modification of an object. An alteration to a built-in type
-such as a dictionary is problematic. Altering the contents of an array or bytearray is not. This is because bytes
-or words are written as a single machine code instruction which is not interruptible: in the parlance of real time
-programming the write is atomic. A user defined object might instantiate an integer, array or bytearray. It is valid
-for both the main loop and the ISR to alter the contents of these.
+It is important to be clear about what constitutes the modification of an object. Altering the contents of an array
+or bytearray is safe. This is because bytes or words are written as a single machine code instruction which is not
+interruptible: in the parlance of real time programming the write is atomic. The same is true of updating a
+dictionary item because items are machine words, being integers or pointers to objects. A user defined object might
+instantiate an array or bytearray. It is valid for both the main loop and the ISR to alter the contents of these.
+
+The hazard arises when the structure of an object is altered, notably in the case of dictionaries. Adding or deleting
+keys can trigger a rehash. If a hard ISR runs while a rehash is in progress and attempts to access an item, a crash
+may occur. Internally globals are implemented as a dictionary. Consequently the main program should create all
+necessary globals before starting a process that generates hard interrupts. Application code should also avoid
+deleting globals.
 
 MicroPython supports integers of arbitrary precision. Values between 2**30 -1 and -2**30 will be stored in
 a single machine word. Larger values are stored as Python objects. Consequently changes to long integers cannot
