Echelon Neuron - Manual (Page 52)

the code element might still be on the stack (if the equality test fails), or might no
longer be on the stack (if the equality test succeeds):
brneq #d’123,next_test ; ({code})
Showing the Return Stack
Because most instructions and functions only affect the data stack, stack
comments refer to the data stack by default. For those cases where data
elements are handled on both the data and return stacks, show the effect to both
stacks in the comment. Use the R prefix to denote the effect to the return stack.
The following example shows the data stack containing element a, and the return
stack containing data element b following the POPPUSH instruction:
poppush ; (a) R(b)
Recommendation: Show return stack comments only where necessary. When
the return stack is no longer affected, the first instruction that no longer uses the
return stack should show an empty return stack as “R()”. In this way, the code
shows that the return stack is empty of local variables and is not needed, and
shows that the return stack is not accidentally forgotten.
The following code saves a copy of the value in TOS on the return stack
temporarily, and restores it after a function call:
push tos ; (z, z)
poppush ; (z) R(z)
callf myFunction ; ( ) R(z)
pushpop ; (z) R()
Stack-Transformation Comments
A stack-transformation comment does not apply to an individual operation, but to
an entire function, and typically follows the EXPORT or APEXP directive. The
stack transformation comment shows the expected stack layout at the beginning
of the function (the function arguments), a double hyphen (as a separator), and
the data stack elements of relevance after the function completes.
For example, the stack transformation comment for the assembly version of a
strlen() equivalent function, which takes a pointer argument and returns an
unsigned integer result, would be:
%strlen APEXP ; (pString(2) –- length)
Thus, pString(2) represents the 2-byte function argument, and length
represents the function return value.
You could think of stack transformation comments as the Neuron Assembly
equivalent of Neuron C function prototypes. However, the Neuron Assembler
does not verify the “prototype” against the actual implementation.
Integrating the Program
The most common method of integrating Neuron assembly language functions in
a Neuron C program is to use the #pragma include_assembly_file compiler
directive. During compilation of the Neuron C program, this directive causes the
42 Writing a Neuron Assembly Utility Function