Interrupt documentation

[pythoncoder]

When a question repeatedly crops up in the forum it suggests to me that there is a hole in the documentation. I wondered if there was any interest in my making an attempt to fill that hole. The issue is that of writing interrupt handlers. There is coverage in the tutorial, but in my view we could do with another page offering further advice. I have in mind the following outline.

The doc would be in two main sections, the first (targeted at all users) referring to Pyboard specific aspects. The second, targeted at beginners, would comprise a basic discussion of generic aspects of writing interrupt handlers. Pyboard specific topics would be:

1. The emergency exception buffer.
2. Need for simplicity of code (discussed further in section 2).
3. The benefits of using object methods as callbacks.
4. The problem of heap allocation, its consequences. Circumvention by writing to pre-allocated mutable objects. The pyb methods which support pre-allocated buffers.
5. Brief note on the use of assembler to overcome the FP restriction.

General topics:

1. Need for short, deterministic execution time. Reasons for this - locking out lower priority interrupts, risk of re-entrancy. How to achieve it: being wary of I/O to devices other than that being serviced.
2. A description of a typical ISR. How to partition the code between the ISR and the main program loop.
3. An elementary discussion of concurrency issues: awareness that variables in the main loop may change unexpectedly. Perhaps with a URL for a more advanced discussion - recommendations?

I'd welcome any comments on the structure including topics I may have missed. If this is thought worthwhile I suggest we use the same approach as with the Assembler docs: I post HTML on my webspace for review, then submit an rst file for inclusion in the document structure.

[dhylands]

Sounds like a reasonable overview to me. I wrote an example that demonstrates atomic increment:
https://github.com/dhylands/upy-example ... /atomic.py

[dbc]

A very worthy project. Comments:

Under "general topics" for beginners:

awareness that variables in the main loop may change unexpectedly.

could be expanded into an explanation/definition of what a critical section is, and why it is important to think through all the ways in which an interrupt might catch you with work half-done and in an inconsistent state.

An in advanced topics, perhaps some example assembly code for setting/clearing individual low-level mask bits that are not exposed in the API.

[pythoncoder]

@dhylands I'll reference that useful example.
@dbc My dilemma is how far to go in the second section. I don't think this is the place for a textbook on concurrent programming. My feeling based on queries which have arisen in this forum is that some users are new to the implications of true concurrency. So the aim I had in mind was to provide beginners with an insight into pertinent issues at an elementary level, pointing them elsewhere for detailed coverage. I'm hoping someone will come up with some good web references for inclusion.

But I'm entirely open to guidance from all involved.

[dbc]

I agree you can't turn it into a class in operating systems. I think an example where two pieces of a structure are expected to be self-consistent (an array and it's length, perhaps?) and talk about how an interrupt might catch you between updating the array and updating the length. Then explain further that an interrupt doesn't happen just between statements, but also within a Python statement, or even between updating two pieces of a multi-word entity that is "atomic" at the Python level.

Of course that is just scratching the surface, but it raises awareness of the key issues, I think. Then, as you say, you can point people off to other resources.

[pythoncoder]

Agreed, I think that's about the right level of detail.

[Arc]

I'm new to microcontrollers and was attracted by the prospect of pyboard "enabling anyone to quickly prototype hardware projects". So yes it'll be really helpful to have the generic aspects outlined here in addition to the specifics. As well as raising the issues can you point to solutions that novices could adapt at their own risk, even if their operation is left to the reader to unpick?

Another topic I had difficulty finding out about was the pyboard's electrical limits, perhaps these are only to be found in the STM chip manual. See http://www.rugged-circuits.com/10-ways- ... an-arduino.

And another was an overview of what the system peripherals and code do in the background (as opposed to interpreting code), which I thought might help in understanding the limitations on use of timers and imply how user code ought to be structured.

[pythoncoder]

@dbc wrote

interrupt doesn't happen just between statements, but also within a Python statement

This has potential consequences which may surprise the user. Consider a main loop which adds a record to a dictionary with:

Code: Select all

my_dictionary['foo'] = 'bar'

An interrupt occurs during the execution of that line. At that moment it might be that the dictionary object lacked internal consistency. An ISR reading another element in the dictionary could cause a crash. Is this correct?

If so the rule should be that if an interrupt handler accesses any object - even if only to read it - code which modifies that object should be regarded as a critical section. It needs protecting either by disabling interrupts or with a mechanism to guarantee mutual exclusion.

Has the team a view on where this document belongs? Options are:

1. The official documentation.
2. The Wiki.
3. On Github.

Perhaps the way forward is for me to put something on Github for review and subsequently re-format for its final destination.

[dhylands]

@dbc wrote

interrupt doesn't happen just between statements, but also within a Python statement

This has potential consequences which may surprise the user. Consider a main loop which adds a record to a dictionary with:

Code: Select all

my_dictionary['foo'] = 'bar'

An interrupt occurs during the execution of that line. At that moment it might be that the dictionary object lacked internal consistency. An ISR reading another element in the dictionary could cause a crash. Is this correct?

In general, yes.

If so the rule should be that if an interrupt handler accesses any object - even if only to read it - code which modifies that object should be regarded as a critical section. It needs protecting either by disabling interrupts or with a mechanism to guarantee mutual exclusion.

I guess you also need to clarify 'modifies an object'. If I have an instance foo and I do foo.counter += 1 I'm really modifying the counter and not foo, although most people would probably say that foo was modified.

Has the team a view on where this document belongs? Options are:

1. The official documentation.
2. The Wiki.
3. On Github.

Perhaps the way forward is for me to put something on Github for review and subsequently re-format for its final destination.

I vote for the official documentation.

[pythoncoder]

I've had a first pass at this and would welcome comments. http://hinch.me.uk/html/reference/isr_rules.html.

This is a first draft and isn't ready for formal review. I'd like to know if I'm pitching it at the right level. Also have I made any errors of fact or omitted things I should include?