Echelon Neuron - Manual (Page 50)

the device’s hardware template), the interrupts run on the application processor,
and share stacks and common registers with the Neuron C application.
Recommendation: To ensure that shared and global data is updated correctly
by both the application and an interrupt, use the locking construct (__lock
keyword in Neuron C; io_iaccess() and io_irelease() functions in Neuron
assembly) to provide semaphore access to shared and global data.
See the Neuron C Programmer’s Guide for more information about interrupts and
the __lock keyword. See io_iaccess (Acquire Semaphore) and io_irelease (Release
Semaphore) for information about these functions.
Documenting Changes to the Stack
Commenting source code can greatly improve the readability and maintainability
of the code. The time that you spend writing a useful comment will be repaid
when you need to maintain or debug the code.
In addition to plain-language comments that describe the purpose, assumptions,
and side effects of the code, Neuron assembly language code can greatly benefit
from comments that show how the stack changes. Including comments that
describe stack changes can help you to:
• Improve the readability of the code by showing its expected behavior
• Find potential stack errors, such as unbalanced stacks or data that is on
the wrong stack
• Determine offset values for DSP-relative addressing
Although the Neuron Assembler does not enforce a particular commenting style
for stack-related comments, this section describes a recommended comment style.
This recommended style is also used throughout this book in the code examples.
There are two types of stack-related comments:
• Stack-effect comments
• Stack-transformation comments
Stack-effect comments describe how a particular instruction or system-provided
function call alters the stack. For example, the PUSH instruction adds a value
to the top of the stack, and thus alters the stack.
Stack-transformation comments describe how an entire assembly function alters
the stack. These comments show the expected contents of the stack before and
after the function runs. For example, before a function runs, the stack contains
the function arguments, and after it runs, the stack contains the function result
or return code.
Both types of stack-related comments use parentheses to denote the boundary of
the stack. The data stack is shown first, and if the return stack is affected, it is
shown second with an R prefix. For example, the following comment shows a
change to both stacks:
; (cs, pData) R(size)
The example shows two elements on the data stack, and one element on the
return stack. The following sections describe how to read these comments.
40 Writing a Neuron Assembly Utility Function