Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add a tips and tricks section to the interrupt docs #378

Merged
merged 1 commit into from
Jan 6, 2024
Merged

doc: add a tips and tricks section to the interrupt docs #378

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions content/docs/concepts/compiler-internals/interrupts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,17 @@ func (uart *UART) handleInterrupt(intr interrupt.Interrupt) {
}
```

## Tips, Tricks and Gotchas

When writing an interrupt handler you have to take care that your code does not block. This is important because the interrupt execution typically has higher priority than your regular code. This means in case your interrupt handler code needs to wait for anything it will wait forever. In general, it is good advice to avoid the following:

* Memory allocation, for details see [heap allocation]({{<ref "heap-allocation.md">}}).
* Blocking on channels, better use a select with a default clause to implement non-blocking send and receives.
Comment on lines +83 to +86
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's stronger than this.

typically has higher priority than your regular code

This is always the case. An interrupt always runs instead of regular code, and unless you use very weird hacks you can't continue normal code. (This is true for all architectures I've looked at: Cortex-M, AVR, Xtensa, RISC-V). In fact, the runtime now checks for these things and if it is inside an interrupt handler when any of these things occur (blocking operations, memory allocations) it will simply panic.

The reason memory allocations are not allowed is a bit more subtle: if an interrupt happens while the GC is running, it will mess with the internal state of the heap. (I've looked for possible ways to fix this but couldn't find anything that was acceptable for TinyGo).

In general, it is good advice to avoid

I'd rather word this as something like "never use these things".

fmt.Printf

That falls under the general category of "too big for an interrupt". LEDs are a way to indicate things, and on some chips println will also work - but not on all (it will usually work when using UART, but USB-CDC is generally too complex to use inside an interrupt handler).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, I ALWAYS avoid interrupts. Inconditionally. Unless you are writing real-time critical code down to the nanosecond, interrupts are a needless source of breakage.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Now realizing this has been merged by no one other than yours truly 🤦)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interrupts can also be useful to avoid polling and conserve battery life :)
But yeah, most users should not use interrupts. Instead, all that functionality should be hidden inside packages like the machine package.

* Any IO operations like `fmt.Printf`, maybe an `LED` is more appropriate than a debug print statement.

One design goal of your interrupt handler shall be to be as lean as possible. In a modern OS techniques like Bottom-Half Processing is used. This basically splits your interrupt handler in two parts the one which handles the interrupt and the part which performs the heavy lift.

In languages like C/C++, there is a keyword `volatile` to instruct the compiler that a variable can change or have side effects the compiler is not aware of. This comes in handy when an interrupt handler shares variables with the rest of your code. How to handle this in tinygo see [The volatile keyword]({{<ref "volatile.md">}}).

## Troubleshooting

Expand Down