From 624bd48d2fd90fd9e6cd95b82b8caef4121cb1c7 Mon Sep 17 00:00:00 2001 From: peterhinch Date: Sun, 29 Jan 2023 18:09:51 +0000 Subject: docs/reference/isr_rules: Describe issue with hard ISRs and globals. Signed-off-by: Damien George --- docs/reference/isr_rules.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) (limited to 'docs/reference/isr_rules.rst') diff --git a/docs/reference/isr_rules.rst b/docs/reference/isr_rules.rst index ea330acad3..14010fb207 100644 --- 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 ` 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 -- cgit v1.2.3