NXC  Version 1.2.1 r5
 All Data Structures Files Functions Variables Groups Pages
The asm statement

The asm statement is used to define many of the NXC API calls.

The syntax of the statement is shown below.

asm {
one or more lines of NBC assembly language
}

The statement simply emits the body of the statement as NeXT Byte Codes (NBC) code and passes it directly to the NBC compiler's backend. The asm statement can often be used to optimize code so that it executes as fast as possible on the NXT firmware. The following example shows an asm block containing variable declarations, labels, and basic NBC statements as well as comments.

asm {
// jmp __lbl00D5
dseg segment
sl0000 slong
sl0005 slong
bGTTrue byte
dseg ends
mov sl0000, 0x0
mov sl0005, sl0000
mov sl0000, 0x1
cmp GT, bGTTrue, sl0005, sl0000
set bGTTrue, FALSE
brtst EQ, __lbl00D5, bGTTrue
__lbl00D5:
}

A few NXC keywords have meaning only within an asm statement. These keywords provide a means for returning string or scalar values from asm statements and for using temporary variables of byte, word, long, and float types.

ASM KeywordMeaning
__RETURN__, RETURNSUsed to return a signed value other than RETVAL or STRRETVAL
__RETURNU__Used to return an unsigned value.
__RETURNF__Used to return a floating point value.
__RETVAL__Writing to this 4-byte signed value returns it to the calling program
__GENRETVAL__Writing to this generic value returns it to the calling program
__URETVAL__Writing to this 4-byte unsigned value returns it to the calling program
__STRRETVAL__Writing to this string value returns it to the calling program
__FLTRETVAL__Writing to this 4-byte floating point value returns it to the calling program
__STRBUFFER__This is primary string buffer which can be used to store intermediate string values.
__STRTMPBUFFER__This is a secondary string buffer.
__TMPBYTE__Use this temporary variable to write and return single byte signed values
__TMPWORD__Use this temporary variable to write and return 2-byte signed values
__TMPLONG__Use this temporary variable to write and return 4-byte signed values
__TMPULONG__Use this temporary variable to write and return 4-byte unsigned values
__TMPFLOAT__Use this temporary variable to write and return 4-byte floating point values
__I__A local counter variable
__J__A second local counter variable
__IncI__Increment the local counter variable named I
__IncJ__Increment the local counter variable named J
__DecI__Decrement the local counter variable named I
__DecJ__Deccrement the local counter variable named J
__ResetI__Reset the local counter variable named I to zero
__ResetJ__Reset the local counter variable named J to zero
__THREADNAME__The current thread name
__LINE__The current line number
__FILE__The current file name
__VER__The product version number
Table 4. ASM Keywords

The asm block statement and these special ASM keywords are used throughout the NXC API. You can have a look at the NXCDefs.h header file for several examples of how they are used. To keep the main NXC code as "C-like" as possible and for the sake of better readability NXC asm block statements can be wrapped in preprocessor macros and placed in custom header files which are included using #include. The following example demonstrates using a macro wrapper around an asm block.

#define SetMotorSpeed(port, cc, thresh, fast, slow) \
asm { \
set theSpeed, fast \
brcmp cc, EndIfOut__I__, SV, thresh \
set theSpeed, slow \
EndIfOut__I__: \
OnFwd(port, theSpeed) \
__IncI__ \
}