Page 228 - The Art of Designing Embedded Systems

A Firmware Standards Manual 21 5

routine. When an ISR grows too large or too slow, spawn another task and
exit. Large ISRs are a sure sign of a need to include an RTOS.
Budget time for each ISR. Before writing the routine, understand just
how much time is available to service the interrupt. Base all of your cod-
ing on this, and then measure the resulting ISR performance to see if you
met the system’s need. Since every interrupt competes for CPU resources,
that slow ISR that works is just as buggy as one with totally corrupt code.
Never allocate or free memory in an ISR unless you have a clear un-
derstanding of the behavior of the memory allocation routines. Garbage
collection or the ill-behaved behavior of many runtime packages may
make the ISR time non-deterministic.
On processors with interrupt vector tables, fill every entry of the
table. Point those entries not used by the system to an error handler, so
you’ve got a prayer of finding problems due to incorrectly programmed
vectors in peripherals.
Though non-reentrant code is always dangerous in a real-time sys-
tem, it’s often unavoidable in ISRs. Hardware interfaces, for example, are
often non-reentrant. Put all such code as close to the beginning of the ISR
as possible, so you can then re-enable interrupts. Remember that as long as
interrupts are off the system is not responding to external requests.

Comments
Code implements an algorithm; the comments communicate the
code’s operation to yourself and others. Adequate comments allow you to
understand the system’s operation without having to read the code itself.
Write comments in clear English. Use the sentence structure Miss
Grandel tried to pound into your head in grade school. Avoid writing the
Great American Novel; be concise yet explicit . . . but be complete.
Avoid long paragraphs. Use simple sentences: noun, verb, object.
Use active voice: “Start-motor actuates the induction relay after a 4 second
pause.” Be complete. Good comments capture everything important about
the problem at hand.
Use proper case. Using all caps or all lowercase simply makes the
comments harder to read.
Enter comments in C at block resolution and when necessary to clar-
ify a line. Don’t feel compelled to comment each line. It is much more nat-
ural to comment groups of lines which work together to perform a macro
function. However, never assume that long variable names create “self-
documenting code.” Self-documenting code is an oxymoron, so add
comments where needed to make the firmware’s operation crystal clear. It