diff options
Diffstat (limited to 'doc/html/nasmdoc4.html')
| -rw-r--r-- | doc/html/nasmdoc4.html | 1970 |
1 files changed, 1970 insertions, 0 deletions
diff --git a/doc/html/nasmdoc4.html b/doc/html/nasmdoc4.html new file mode 100644 index 0000000..8c71881 --- /dev/null +++ b/doc/html/nasmdoc4.html @@ -0,0 +1,1970 @@ +<html><head><title>NASM Manual</title></head> +<body><h1 align=center>The Netwide Assembler: NASM</h1> + +<p align=center><a href="nasmdoc5.html">Next Chapter</a> | +<a href="nasmdoc3.html">Previous Chapter</a> | +<a href="nasmdoc0.html">Contents</a> | +<a href="nasmdoci.html">Index</a> +<h2><a name="chapter-4">Chapter 4: The NASM Preprocessor</a></h2> +<p>NASM contains a powerful macro processor, which supports conditional +assembly, multi-level file inclusion, two forms of macro (single-line and +multi-line), and a `context stack' mechanism for extra macro power. +Preprocessor directives all begin with a <code><nobr>%</nobr></code> sign. +<p>The preprocessor collapses all lines which end with a backslash (\) +character into a single line. Thus: +<p><pre> +%define THIS_VERY_LONG_MACRO_NAME_IS_DEFINED_TO \ + THIS_VALUE +</pre> +<p>will work like a single-line macro without the backslash-newline +sequence. +<h3><a name="section-4.1">4.1 Single-Line Macros</a></h3> +<h4><a name="section-4.1.1">4.1.1 The Normal Way: <code><nobr>%define</nobr></code></a></h4> +<p>Single-line macros are defined using the +<code><nobr>%define</nobr></code> preprocessor directive. The definitions +work in a similar way to C; so you can do things like +<p><pre> +%define ctrl 0x1F & +%define param(a,b) ((a)+(a)*(b)) + + mov byte [param(2,ebx)], ctrl 'D' +</pre> +<p>which will expand to +<p><pre> + mov byte [(2)+(2)*(ebx)], 0x1F & 'D' +</pre> +<p>When the expansion of a single-line macro contains tokens which invoke +another macro, the expansion is performed at invocation time, not at +definition time. Thus the code +<p><pre> +%define a(x) 1+b(x) +%define b(x) 2*x + + mov ax,a(8) +</pre> +<p>will evaluate in the expected way to +<code><nobr>mov ax,1+2*8</nobr></code>, even though the macro +<code><nobr>b</nobr></code> wasn't defined at the time of definition of +<code><nobr>a</nobr></code>. +<p>Macros defined with <code><nobr>%define</nobr></code> are case +sensitive: after <code><nobr>%define foo bar</nobr></code>, only +<code><nobr>foo</nobr></code> will expand to <code><nobr>bar</nobr></code>: +<code><nobr>Foo</nobr></code> or <code><nobr>FOO</nobr></code> will not. By +using <code><nobr>%idefine</nobr></code> instead of +<code><nobr>%define</nobr></code> (the `i' stands for `insensitive') you +can define all the case variants of a macro at once, so that +<code><nobr>%idefine foo bar</nobr></code> would cause +<code><nobr>foo</nobr></code>, <code><nobr>Foo</nobr></code>, +<code><nobr>FOO</nobr></code>, <code><nobr>fOO</nobr></code> and so on all +to expand to <code><nobr>bar</nobr></code>. +<p>There is a mechanism which detects when a macro call has occurred as a +result of a previous expansion of the same macro, to guard against circular +references and infinite loops. If this happens, the preprocessor will only +expand the first occurrence of the macro. Hence, if you code +<p><pre> +%define a(x) 1+a(x) + + mov ax,a(3) +</pre> +<p>the macro <code><nobr>a(3)</nobr></code> will expand once, becoming +<code><nobr>1+a(3)</nobr></code>, and will then expand no further. This +behaviour can be useful: see <a href="nasmdoc9.html#section-9.1">section +9.1</a> for an example of its use. +<p>You can overload single-line macros: if you write +<p><pre> +%define foo(x) 1+x +%define foo(x,y) 1+x*y +</pre> +<p>the preprocessor will be able to handle both types of macro call, by +counting the parameters you pass; so <code><nobr>foo(3)</nobr></code> will +become <code><nobr>1+3</nobr></code> whereas +<code><nobr>foo(ebx,2)</nobr></code> will become +<code><nobr>1+ebx*2</nobr></code>. However, if you define +<p><pre> +%define foo bar +</pre> +<p>then no other definition of <code><nobr>foo</nobr></code> will be +accepted: a macro with no parameters prohibits the definition of the same +name as a macro <em>with</em> parameters, and vice versa. +<p>This doesn't prevent single-line macros being <em>redefined</em>: you +can perfectly well define a macro with +<p><pre> +%define foo bar +</pre> +<p>and then re-define it later in the same source file with +<p><pre> +%define foo baz +</pre> +<p>Then everywhere the macro <code><nobr>foo</nobr></code> is invoked, it +will be expanded according to the most recent definition. This is +particularly useful when defining single-line macros with +<code><nobr>%assign</nobr></code> (see <a href="#section-4.1.7">section +4.1.7</a>). +<p>You can pre-define single-line macros using the `-d' option on the NASM +command line: see <a href="nasmdoc2.html#section-2.1.18">section +2.1.18</a>. +<h4><a name="section-4.1.2">4.1.2 Resolving <code><nobr>%define</nobr></code>: <code><nobr>%xdefine</nobr></code></a></h4> +<p>To have a reference to an embedded single-line macro resolved at the +time that the embedding macro is <em>defined</em>, as opposed to when the +embedding macro is <em>expanded</em>, you need a different mechanism to the +one offered by <code><nobr>%define</nobr></code>. The solution is to use +<code><nobr>%xdefine</nobr></code>, or it's case-insensitive counterpart +<code><nobr>%ixdefine</nobr></code>. +<p>Suppose you have the following code: +<p><pre> +%define isTrue 1 +%define isFalse isTrue +%define isTrue 0 + +val1: db isFalse + +%define isTrue 1 + +val2: db isFalse +</pre> +<p>In this case, <code><nobr>val1</nobr></code> is equal to 0, and +<code><nobr>val2</nobr></code> is equal to 1. This is because, when a +single-line macro is defined using <code><nobr>%define</nobr></code>, it is +expanded only when it is called. As <code><nobr>isFalse</nobr></code> +expands to <code><nobr>isTrue</nobr></code>, the expansion will be the +current value of <code><nobr>isTrue</nobr></code>. The first time it is +called that is 0, and the second time it is 1. +<p>If you wanted <code><nobr>isFalse</nobr></code> to expand to the value +assigned to the embedded macro <code><nobr>isTrue</nobr></code> at the time +that <code><nobr>isFalse</nobr></code> was defined, you need to change the +above code to use <code><nobr>%xdefine</nobr></code>. +<p><pre> +%xdefine isTrue 1 +%xdefine isFalse isTrue +%xdefine isTrue 0 + +val1: db isFalse + +%xdefine isTrue 1 + +val2: db isFalse +</pre> +<p>Now, each time that <code><nobr>isFalse</nobr></code> is called, it +expands to 1, as that is what the embedded macro +<code><nobr>isTrue</nobr></code> expanded to at the time that +<code><nobr>isFalse</nobr></code> was defined. +<h4><a name="section-4.1.3">4.1.3 Macro Indirection: <code><nobr>%[...]</nobr></code></a></h4> +<p>The <code><nobr>%[...]</nobr></code> construct can be used to expand +macros in contexts where macro expansion would otherwise not occur, +including in the names other macros. For example, if you have a set of +macros named <code><nobr>Foo16</nobr></code>, +<code><nobr>Foo32</nobr></code> and <code><nobr>Foo64</nobr></code>, you +could write: +<p><pre> + mov ax,Foo%[__BITS__] ; The Foo value +</pre> +<p>to use the builtin macro <code><nobr>__BITS__</nobr></code> (see +<a href="#section-4.11.5">section 4.11.5</a>) to automatically select +between them. Similarly, the two statements: +<p><pre> +%xdefine Bar Quux ; Expands due to %xdefine +%define Bar %[Quux] ; Expands due to %[...] +</pre> +<p>have, in fact, exactly the same effect. +<p><code><nobr>%[...]</nobr></code> concatenates to adjacent tokens in the +same way that multi-line macro parameters do, see +<a href="#section-4.3.8">section 4.3.8</a> for details. +<h4><a name="section-4.1.4">4.1.4 Concatenating Single Line Macro Tokens: <code><nobr>%+</nobr></code></a></h4> +<p>Individual tokens in single line macros can be concatenated, to produce +longer tokens for later processing. This can be useful if there are several +similar macros that perform similar functions. +<p>Please note that a space is required after <code><nobr>%+</nobr></code>, +in order to disambiguate it from the syntax <code><nobr>%+1</nobr></code> +used in multiline macros. +<p>As an example, consider the following: +<p><pre> +%define BDASTART 400h ; Start of BIOS data area +</pre> +<p><pre> +struc tBIOSDA ; its structure + .COM1addr RESW 1 + .COM2addr RESW 1 + ; ..and so on +endstruc +</pre> +<p>Now, if we need to access the elements of tBIOSDA in different places, +we can end up with: +<p><pre> + mov ax,BDASTART + tBIOSDA.COM1addr + mov bx,BDASTART + tBIOSDA.COM2addr +</pre> +<p>This will become pretty ugly (and tedious) if used in many places, and +can be reduced in size significantly by using the following macro: +<p><pre> +; Macro to access BIOS variables by their names (from tBDA): +</pre> +<p><pre> +%define BDA(x) BDASTART + tBIOSDA. %+ x +</pre> +<p>Now the above code can be written as: +<p><pre> + mov ax,BDA(COM1addr) + mov bx,BDA(COM2addr) +</pre> +<p>Using this feature, we can simplify references to a lot of macros (and, +in turn, reduce typing errors). +<h4><a name="section-4.1.5">4.1.5 The Macro Name Itself: <code><nobr>%?</nobr></code> and <code><nobr>%??</nobr></code></a></h4> +<p>The special symbols <code><nobr>%?</nobr></code> and +<code><nobr>%??</nobr></code> can be used to reference the macro name +itself inside a macro expansion, this is supported for both single-and +multi-line macros. <code><nobr>%?</nobr></code> refers to the macro name as +<em>invoked</em>, whereas <code><nobr>%??</nobr></code> refers to the macro +name as <em>declared</em>. The two are always the same for case-sensitive +macros, but for case-insensitive macros, they can differ. +<p>For example: +<p><pre> +%idefine Foo mov %?,%?? + + foo + FOO +</pre> +<p>will expand to: +<p><pre> + mov foo,Foo + mov FOO,Foo +</pre> +<p>The sequence: +<p><pre> +%idefine keyword $%? +</pre> +<p>can be used to make a keyword "disappear", for example in case a new +instruction has been used as a label in older code. For example: +<p><pre> +%idefine pause $%? ; Hide the PAUSE instruction +</pre> +<h4><a name="section-4.1.6">4.1.6 Undefining Single-Line Macros: <code><nobr>%undef</nobr></code></a></h4> +<p>Single-line macros can be removed with the +<code><nobr>%undef</nobr></code> directive. For example, the following +sequence: +<p><pre> +%define foo bar +%undef foo + + mov eax, foo +</pre> +<p>will expand to the instruction <code><nobr>mov eax, foo</nobr></code>, +since after <code><nobr>%undef</nobr></code> the macro +<code><nobr>foo</nobr></code> is no longer defined. +<p>Macros that would otherwise be pre-defined can be undefined on the +command-line using the `-u' option on the NASM command line: see +<a href="nasmdoc2.html#section-2.1.19">section 2.1.19</a>. +<h4><a name="section-4.1.7">4.1.7 Preprocessor Variables: <code><nobr>%assign</nobr></code></a></h4> +<p>An alternative way to define single-line macros is by means of the +<code><nobr>%assign</nobr></code> command (and its case-insensitive +counterpart <code><nobr>%iassign</nobr></code>, which differs from +<code><nobr>%assign</nobr></code> in exactly the same way that +<code><nobr>%idefine</nobr></code> differs from +<code><nobr>%define</nobr></code>). +<p><code><nobr>%assign</nobr></code> is used to define single-line macros +which take no parameters and have a numeric value. This value can be +specified in the form of an expression, and it will be evaluated once, when +the <code><nobr>%assign</nobr></code> directive is processed. +<p>Like <code><nobr>%define</nobr></code>, macros defined using +<code><nobr>%assign</nobr></code> can be re-defined later, so you can do +things like +<p><pre> +%assign i i+1 +</pre> +<p>to increment the numeric value of a macro. +<p><code><nobr>%assign</nobr></code> is useful for controlling the +termination of <code><nobr>%rep</nobr></code> preprocessor loops: see +<a href="#section-4.5">section 4.5</a> for an example of this. Another use +for <code><nobr>%assign</nobr></code> is given in +<a href="nasmdoc8.html#section-8.4">section 8.4</a> and +<a href="nasmdoc9.html#section-9.1">section 9.1</a>. +<p>The expression passed to <code><nobr>%assign</nobr></code> is a critical +expression (see <a href="nasmdoc3.html#section-3.8">section 3.8</a>), and +must also evaluate to a pure number (rather than a relocatable reference +such as a code or data address, or anything involving a register). +<h4><a name="section-4.1.8">4.1.8 Defining Strings: <code><nobr>%defstr</nobr></code></a></h4> +<p><code><nobr>%defstr</nobr></code>, and its case-insensitive counterpart +<code><nobr>%idefstr</nobr></code>, define or redefine a single-line macro +without parameters but converts the entire right-hand side, after macro +expansion, to a quoted string before definition. +<p>For example: +<p><pre> +%defstr test TEST +</pre> +<p>is equivalent to +<p><pre> +%define test 'TEST' +</pre> +<p>This can be used, for example, with the <code><nobr>%!</nobr></code> +construct (see <a href="#section-4.10.2">section 4.10.2</a>): +<p><pre> +%defstr PATH %!PATH ; The operating system PATH variable +</pre> +<h4><a name="section-4.1.9">4.1.9 Defining Tokens: <code><nobr>%deftok</nobr></code></a></h4> +<p><code><nobr>%deftok</nobr></code>, and its case-insensitive counterpart +<code><nobr>%ideftok</nobr></code>, define or redefine a single-line macro +without parameters but converts the second parameter, after string +conversion, to a sequence of tokens. +<p>For example: +<p><pre> +%deftok test 'TEST' +</pre> +<p>is equivalent to +<p><pre> +%define test TEST +</pre> +<h3><a name="section-4.2">4.2 String Manipulation in Macros</a></h3> +<p>It's often useful to be able to handle strings in macros. NASM supports +a few simple string handling macro operators from which more complex +operations can be constructed. +<p>All the string operators define or redefine a value (either a string or +a numeric value) to a single-line macro. When producing a string value, it +may change the style of quoting of the input string or strings, and +possibly use <code><nobr>\</nobr></code>-escapes inside +<code><nobr>`</nobr></code>-quoted strings. +<h4><a name="section-4.2.1">4.2.1 Concatenating Strings: <code><nobr>%strcat</nobr></code></a></h4> +<p>The <code><nobr>%strcat</nobr></code> operator concatenates quoted +strings and assign them to a single-line macro. +<p>For example: +<p><pre> +%strcat alpha "Alpha: ", '12" screen' +</pre> +<p>... would assign the value <code><nobr>'Alpha: 12" screen'</nobr></code> +to <code><nobr>alpha</nobr></code>. Similarly: +<p><pre> +%strcat beta '"foo"\', "'bar'" +</pre> +<p>... would assign the value <code><nobr>`"foo"\\'bar'`</nobr></code> to +<code><nobr>beta</nobr></code>. +<p>The use of commas to separate strings is permitted but optional. +<h4><a name="section-4.2.2">4.2.2 String Length: <code><nobr>%strlen</nobr></code></a></h4> +<p>The <code><nobr>%strlen</nobr></code> operator assigns the length of a +string to a macro. For example: +<p><pre> +%strlen charcnt 'my string' +</pre> +<p>In this example, <code><nobr>charcnt</nobr></code> would receive the +value 9, just as if an <code><nobr>%assign</nobr></code> had been used. In +this example, <code><nobr>'my string'</nobr></code> was a literal string +but it could also have been a single-line macro that expands to a string, +as in the following example: +<p><pre> +%define sometext 'my string' +%strlen charcnt sometext +</pre> +<p>As in the first case, this would result in +<code><nobr>charcnt</nobr></code> being assigned the value of 9. +<h4><a name="section-4.2.3">4.2.3 Extracting Substrings: <code><nobr>%substr</nobr></code></a></h4> +<p>Individual letters or substrings in strings can be extracted using the +<code><nobr>%substr</nobr></code> operator. An example of its use is +probably more useful than the description: +<p><pre> +%substr mychar 'xyzw' 1 ; equivalent to %define mychar 'x' +%substr mychar 'xyzw' 2 ; equivalent to %define mychar 'y' +%substr mychar 'xyzw' 3 ; equivalent to %define mychar 'z' +%substr mychar 'xyzw' 2,2 ; equivalent to %define mychar 'yz' +%substr mychar 'xyzw' 2,-1 ; equivalent to %define mychar 'yzw' +%substr mychar 'xyzw' 2,-2 ; equivalent to %define mychar 'yz' +</pre> +<p>As with <code><nobr>%strlen</nobr></code> (see +<a href="#section-4.2.2">section 4.2.2</a>), the first parameter is the +single-line macro to be created and the second is the string. The third +parameter specifies the first character to be selected, and the optional +fourth parameter preceeded by comma) is the length. Note that the first +index is 1, not 0 and the last index is equal to the value that +<code><nobr>%strlen</nobr></code> would assign given the same string. Index +values out of range result in an empty string. A negative length means +"until N-1 characters before the end of string", i.e. +<code><nobr>-1</nobr></code> means until end of string, +<code><nobr>-2</nobr></code> until one character before, etc. +<h3><a name="section-4.3">4.3 Multi-Line Macros: <code><nobr>%macro</nobr></code></a></h3> +<p>Multi-line macros are much more like the type of macro seen in MASM and +TASM: a multi-line macro definition in NASM looks something like this. +<p><pre> +%macro prologue 1 + + push ebp + mov ebp,esp + sub esp,%1 + +%endmacro +</pre> +<p>This defines a C-like function prologue as a macro: so you would invoke +the macro with a call such as +<p><pre> +myfunc: prologue 12 +</pre> +<p>which would expand to the three lines of code +<p><pre> +myfunc: push ebp + mov ebp,esp + sub esp,12 +</pre> +<p>The number <code><nobr>1</nobr></code> after the macro name in the +<code><nobr>%macro</nobr></code> line defines the number of parameters the +macro <code><nobr>prologue</nobr></code> expects to receive. The use of +<code><nobr>%1</nobr></code> inside the macro definition refers to the +first parameter to the macro call. With a macro taking more than one +parameter, subsequent parameters would be referred to as +<code><nobr>%2</nobr></code>, <code><nobr>%3</nobr></code> and so on. +<p>Multi-line macros, like single-line macros, are case-sensitive, unless +you define them using the alternative directive +<code><nobr>%imacro</nobr></code>. +<p>If you need to pass a comma as <em>part</em> of a parameter to a +multi-line macro, you can do that by enclosing the entire parameter in +braces. So you could code things like +<p><pre> +%macro silly 2 + + %2: db %1 + +%endmacro + + silly 'a', letter_a ; letter_a: db 'a' + silly 'ab', string_ab ; string_ab: db 'ab' + silly {13,10}, crlf ; crlf: db 13,10 +</pre> +<h4><a name="section-4.3.1">4.3.1 Recursive Multi-Line Macros: <code><nobr>%rmacro</nobr></code></a></h4> +<p>A multi-line macro cannot be referenced within itself, in order to +prevent accidental infinite recursion. +<p>Recursive multi-line macros allow for self-referencing, with the caveat +that the user is aware of the existence, use and purpose of recursive +multi-line macros. There is also a generous, but sane, upper limit to the +number of recursions, in order to prevent run-away memory consumption in +case of accidental infinite recursion. +<p>As with non-recursive multi-line macros, recursive multi-line macros are +case-sensitive, unless you define them using the alternative directive +<code><nobr>%irmacro</nobr></code>. +<h4><a name="section-4.3.2">4.3.2 Overloading Multi-Line Macros</a></h4> +<p>As with single-line macros, multi-line macros can be overloaded by +defining the same macro name several times with different numbers of +parameters. This time, no exception is made for macros with no parameters +at all. So you could define +<p><pre> +%macro prologue 0 + + push ebp + mov ebp,esp + +%endmacro +</pre> +<p>to define an alternative form of the function prologue which allocates +no local stack space. +<p>Sometimes, however, you might want to `overload' a machine instruction; +for example, you might want to define +<p><pre> +%macro push 2 + + push %1 + push %2 + +%endmacro +</pre> +<p>so that you could code +<p><pre> + push ebx ; this line is not a macro call + push eax,ecx ; but this one is +</pre> +<p>Ordinarily, NASM will give a warning for the first of the above two +lines, since <code><nobr>push</nobr></code> is now defined to be a macro, +and is being invoked with a number of parameters for which no definition +has been given. The correct code will still be generated, but the assembler +will give a warning. This warning can be disabled by the use of the +<code><nobr>-w-macro-params</nobr></code> command-line option (see +<a href="nasmdoc2.html#section-2.1.24">section 2.1.24</a>). +<h4><a name="section-4.3.3">4.3.3 Macro-Local Labels</a></h4> +<p>NASM allows you to define labels within a multi-line macro definition in +such a way as to make them local to the macro call: so calling the same +macro multiple times will use a different label each time. You do this by +prefixing <code><nobr>%%</nobr></code> to the label name. So you can invent +an instruction which executes a <code><nobr>RET</nobr></code> if the +<code><nobr>Z</nobr></code> flag is set by doing this: +<p><pre> +%macro retz 0 + + jnz %%skip + ret + %%skip: + +%endmacro +</pre> +<p>You can call this macro as many times as you want, and every time you +call it NASM will make up a different `real' name to substitute for the +label <code><nobr>%%skip</nobr></code>. The names NASM invents are of the +form <code><nobr>..@2345.skip</nobr></code>, where the number 2345 changes +with every macro call. The <code><nobr>..@</nobr></code> prefix prevents +macro-local labels from interfering with the local label mechanism, as +described in <a href="nasmdoc3.html#section-3.9">section 3.9</a>. You +should avoid defining your own labels in this form (the +<code><nobr>..@</nobr></code> prefix, then a number, then another period) +in case they interfere with macro-local labels. +<h4><a name="section-4.3.4">4.3.4 Greedy Macro Parameters</a></h4> +<p>Occasionally it is useful to define a macro which lumps its entire +command line into one parameter definition, possibly after extracting one +or two smaller parameters from the front. An example might be a macro to +write a text string to a file in MS-DOS, where you might want to be able to +write +<p><pre> + writefile [filehandle],"hello, world",13,10 +</pre> +<p>NASM allows you to define the last parameter of a macro to be +<em>greedy</em>, meaning that if you invoke the macro with more parameters +than it expects, all the spare parameters get lumped into the last defined +one along with the separating commas. So if you code: +<p><pre> +%macro writefile 2+ + + jmp %%endstr + %%str: db %2 + %%endstr: + mov dx,%%str + mov cx,%%endstr-%%str + mov bx,%1 + mov ah,0x40 + int 0x21 + +%endmacro +</pre> +<p>then the example call to <code><nobr>writefile</nobr></code> above will +work as expected: the text before the first comma, +<code><nobr>[filehandle]</nobr></code>, is used as the first macro +parameter and expanded when <code><nobr>%1</nobr></code> is referred to, +and all the subsequent text is lumped into <code><nobr>%2</nobr></code> and +placed after the <code><nobr>db</nobr></code>. +<p>The greedy nature of the macro is indicated to NASM by the use of the +<code><nobr>+</nobr></code> sign after the parameter count on the +<code><nobr>%macro</nobr></code> line. +<p>If you define a greedy macro, you are effectively telling NASM how it +should expand the macro given <em>any</em> number of parameters from the +actual number specified up to infinity; in this case, for example, NASM now +knows what to do when it sees a call to <code><nobr>writefile</nobr></code> +with 2, 3, 4 or more parameters. NASM will take this into account when +overloading macros, and will not allow you to define another form of +<code><nobr>writefile</nobr></code> taking 4 parameters (for example). +<p>Of course, the above macro could have been implemented as a non-greedy +macro, in which case the call to it would have had to look like +<p><pre> + writefile [filehandle], {"hello, world",13,10} +</pre> +<p>NASM provides both mechanisms for putting commas in macro parameters, +and you choose which one you prefer for each macro definition. +<p>See <a href="nasmdoc6.html#section-6.3.1">section 6.3.1</a> for a better +way to write the above macro. +<h4><a name="section-4.3.5">4.3.5 Default Macro Parameters</a></h4> +<p>NASM also allows you to define a multi-line macro with a <em>range</em> +of allowable parameter counts. If you do this, you can specify defaults for +omitted parameters. So, for example: +<p><pre> +%macro die 0-1 "Painful program death has occurred." + + writefile 2,%1 + mov ax,0x4c01 + int 0x21 + +%endmacro +</pre> +<p>This macro (which makes use of the <code><nobr>writefile</nobr></code> +macro defined in <a href="#section-4.3.4">section 4.3.4</a>) can be called +with an explicit error message, which it will display on the error output +stream before exiting, or it can be called with no parameters, in which +case it will use the default error message supplied in the macro +definition. +<p>In general, you supply a minimum and maximum number of parameters for a +macro of this type; the minimum number of parameters are then required in +the macro call, and then you provide defaults for the optional ones. So if +a macro definition began with the line +<p><pre> +%macro foobar 1-3 eax,[ebx+2] +</pre> +<p>then it could be called with between one and three parameters, and +<code><nobr>%1</nobr></code> would always be taken from the macro call. +<code><nobr>%2</nobr></code>, if not specified by the macro call, would +default to <code><nobr>eax</nobr></code>, and <code><nobr>%3</nobr></code> +if not specified would default to <code><nobr>[ebx+2]</nobr></code>. +<p>You can provide extra information to a macro by providing too many +default parameters: +<p><pre> +%macro quux 1 something +</pre> +<p>This will trigger a warning by default; see +<a href="nasmdoc2.html#section-2.1.24">section 2.1.24</a> for more +information. When <code><nobr>quux</nobr></code> is invoked, it receives +not one but two parameters. <code><nobr>something</nobr></code> can be +referred to as <code><nobr>%2</nobr></code>. The difference between passing +<code><nobr>something</nobr></code> this way and writing +<code><nobr>something</nobr></code> in the macro body is that with this way +<code><nobr>something</nobr></code> is evaluated when the macro is defined, +not when it is expanded. +<p>You may omit parameter defaults from the macro definition, in which case +the parameter default is taken to be blank. This can be useful for macros +which can take a variable number of parameters, since the +<code><nobr>%0</nobr></code> token (see <a href="#section-4.3.6">section +4.3.6</a>) allows you to determine how many parameters were really passed +to the macro call. +<p>This defaulting mechanism can be combined with the greedy-parameter +mechanism; so the <code><nobr>die</nobr></code> macro above could be made +more powerful, and more useful, by changing the first line of the +definition to +<p><pre> +%macro die 0-1+ "Painful program death has occurred.",13,10 +</pre> +<p>The maximum parameter count can be infinite, denoted by +<code><nobr>*</nobr></code>. In this case, of course, it is impossible to +provide a <em>full</em> set of default parameters. Examples of this usage +are shown in <a href="#section-4.3.7">section 4.3.7</a>. +<h4><a name="section-4.3.6">4.3.6 <code><nobr>%0</nobr></code>: Macro Parameter Counter</a></h4> +<p>The parameter reference <code><nobr>%0</nobr></code> will return a +numeric constant giving the number of parameters received, that is, if +<code><nobr>%0</nobr></code> is n then <code><nobr>%</nobr></code>n is the +last parameter. <code><nobr>%0</nobr></code> is mostly useful for macros +that can take a variable number of parameters. It can be used as an +argument to <code><nobr>%rep</nobr></code> (see +<a href="#section-4.5">section 4.5</a>) in order to iterate through all the +parameters of a macro. Examples are given in +<a href="#section-4.3.7">section 4.3.7</a>. +<h4><a name="section-4.3.7">4.3.7 <code><nobr>%rotate</nobr></code>: Rotating Macro Parameters</a></h4> +<p>Unix shell programmers will be familiar with the +<code><nobr>shift</nobr></code> shell command, which allows the arguments +passed to a shell script (referenced as <code><nobr>$1</nobr></code>, +<code><nobr>$2</nobr></code> and so on) to be moved left by one place, so +that the argument previously referenced as <code><nobr>$2</nobr></code> +becomes available as <code><nobr>$1</nobr></code>, and the argument +previously referenced as <code><nobr>$1</nobr></code> is no longer +available at all. +<p>NASM provides a similar mechanism, in the form of +<code><nobr>%rotate</nobr></code>. As its name suggests, it differs from +the Unix <code><nobr>shift</nobr></code> in that no parameters are lost: +parameters rotated off the left end of the argument list reappear on the +right, and vice versa. +<p><code><nobr>%rotate</nobr></code> is invoked with a single numeric +argument (which may be an expression). The macro parameters are rotated to +the left by that many places. If the argument to +<code><nobr>%rotate</nobr></code> is negative, the macro parameters are +rotated to the right. +<p>So a pair of macros to save and restore a set of registers might work as +follows: +<p><pre> +%macro multipush 1-* + + %rep %0 + push %1 + %rotate 1 + %endrep + +%endmacro +</pre> +<p>This macro invokes the <code><nobr>PUSH</nobr></code> instruction on +each of its arguments in turn, from left to right. It begins by pushing its +first argument, <code><nobr>%1</nobr></code>, then invokes +<code><nobr>%rotate</nobr></code> to move all the arguments one place to +the left, so that the original second argument is now available as +<code><nobr>%1</nobr></code>. Repeating this procedure as many times as +there were arguments (achieved by supplying <code><nobr>%0</nobr></code> as +the argument to <code><nobr>%rep</nobr></code>) causes each argument in +turn to be pushed. +<p>Note also the use of <code><nobr>*</nobr></code> as the maximum +parameter count, indicating that there is no upper limit on the number of +parameters you may supply to the <code><nobr>multipush</nobr></code> macro. +<p>It would be convenient, when using this macro, to have a +<code><nobr>POP</nobr></code> equivalent, which <em>didn't</em> require the +arguments to be given in reverse order. Ideally, you would write the +<code><nobr>multipush</nobr></code> macro call, then cut-and-paste the line +to where the pop needed to be done, and change the name of the called macro +to <code><nobr>multipop</nobr></code>, and the macro would take care of +popping the registers in the opposite order from the one in which they were +pushed. +<p>This can be done by the following definition: +<p><pre> +%macro multipop 1-* + + %rep %0 + %rotate -1 + pop %1 + %endrep + +%endmacro +</pre> +<p>This macro begins by rotating its arguments one place to the +<em>right</em>, so that the original <em>last</em> argument appears as +<code><nobr>%1</nobr></code>. This is then popped, and the arguments are +rotated right again, so the second-to-last argument becomes +<code><nobr>%1</nobr></code>. Thus the arguments are iterated through in +reverse order. +<h4><a name="section-4.3.8">4.3.8 Concatenating Macro Parameters</a></h4> +<p>NASM can concatenate macro parameters and macro indirection constructs +on to other text surrounding them. This allows you to declare a family of +symbols, for example, in a macro definition. If, for example, you wanted to +generate a table of key codes along with offsets into the table, you could +code something like +<p><pre> +%macro keytab_entry 2 + + keypos%1 equ $-keytab + db %2 + +%endmacro + +keytab: + keytab_entry F1,128+1 + keytab_entry F2,128+2 + keytab_entry Return,13 +</pre> +<p>which would expand to +<p><pre> +keytab: +keyposF1 equ $-keytab + db 128+1 +keyposF2 equ $-keytab + db 128+2 +keyposReturn equ $-keytab + db 13 +</pre> +<p>You can just as easily concatenate text on to the other end of a macro +parameter, by writing <code><nobr>%1foo</nobr></code>. +<p>If you need to append a <em>digit</em> to a macro parameter, for example +defining labels <code><nobr>foo1</nobr></code> and +<code><nobr>foo2</nobr></code> when passed the parameter +<code><nobr>foo</nobr></code>, you can't code <code><nobr>%11</nobr></code> +because that would be taken as the eleventh macro parameter. Instead, you +must code <code><nobr>%{1}1</nobr></code>, which will separate the first +<code><nobr>1</nobr></code> (giving the number of the macro parameter) from +the second (literal text to be concatenated to the parameter). +<p>This concatenation can also be applied to other preprocessor in-line +objects, such as macro-local labels (<a href="#section-4.3.3">section +4.3.3</a>) and context-local labels (<a href="#section-4.7.2">section +4.7.2</a>). In all cases, ambiguities in syntax can be resolved by +enclosing everything after the <code><nobr>%</nobr></code> sign and before +the literal text in braces: so <code><nobr>%{%foo}bar</nobr></code> +concatenates the text <code><nobr>bar</nobr></code> to the end of the real +name of the macro-local label <code><nobr>%%foo</nobr></code>. (This is +unnecessary, since the form NASM uses for the real names of macro-local +labels means that the two usages <code><nobr>%{%foo}bar</nobr></code> and +<code><nobr>%%foobar</nobr></code> would both expand to the same thing +anyway; nevertheless, the capability is there.) +<p>The single-line macro indirection construct, +<code><nobr>%[...]</nobr></code> (<a href="#section-4.1.3">section +4.1.3</a>), behaves the same way as macro parameters for the purpose of +concatenation. +<p>See also the <code><nobr>%+</nobr></code> operator, +<a href="#section-4.1.4">section 4.1.4</a>. +<h4><a name="section-4.3.9">4.3.9 Condition Codes as Macro Parameters</a></h4> +<p>NASM can give special treatment to a macro parameter which contains a +condition code. For a start, you can refer to the macro parameter +<code><nobr>%1</nobr></code> by means of the alternative syntax +<code><nobr>%+1</nobr></code>, which informs NASM that this macro parameter +is supposed to contain a condition code, and will cause the preprocessor to +report an error message if the macro is called with a parameter which is +<em>not</em> a valid condition code. +<p>Far more usefully, though, you can refer to the macro parameter by means +of <code><nobr>%-1</nobr></code>, which NASM will expand as the +<em>inverse</em> condition code. So the <code><nobr>retz</nobr></code> +macro defined in <a href="#section-4.3.3">section 4.3.3</a> can be replaced +by a general conditional-return macro like this: +<p><pre> +%macro retc 1 + + j%-1 %%skip + ret + %%skip: + +%endmacro +</pre> +<p>This macro can now be invoked using calls like +<code><nobr>retc ne</nobr></code>, which will cause the conditional-jump +instruction in the macro expansion to come out as +<code><nobr>JE</nobr></code>, or <code><nobr>retc po</nobr></code> which +will make the jump a <code><nobr>JPE</nobr></code>. +<p>The <code><nobr>%+1</nobr></code> macro-parameter reference is quite +happy to interpret the arguments <code><nobr>CXZ</nobr></code> and +<code><nobr>ECXZ</nobr></code> as valid condition codes; however, +<code><nobr>%-1</nobr></code> will report an error if passed either of +these, because no inverse condition code exists. +<h4><a name="section-4.3.10">4.3.10 Disabling Listing Expansion</a></h4> +<p>When NASM is generating a listing file from your program, it will +generally expand multi-line macros by means of writing the macro call and +then listing each line of the expansion. This allows you to see which +instructions in the macro expansion are generating what code; however, for +some macros this clutters the listing up unnecessarily. +<p>NASM therefore provides the <code><nobr>.nolist</nobr></code> qualifier, +which you can include in a macro definition to inhibit the expansion of the +macro in the listing file. The <code><nobr>.nolist</nobr></code> qualifier +comes directly after the number of parameters, like this: +<p><pre> +%macro foo 1.nolist +</pre> +<p>Or like this: +<p><pre> +%macro bar 1-5+.nolist a,b,c,d,e,f,g,h +</pre> +<h4><a name="section-4.3.11">4.3.11 Undefining Multi-Line Macros: <code><nobr>%unmacro</nobr></code></a></h4> +<p>Multi-line macros can be removed with the +<code><nobr>%unmacro</nobr></code> directive. Unlike the +<code><nobr>%undef</nobr></code> directive, however, +<code><nobr>%unmacro</nobr></code> takes an argument specification, and +will only remove exact matches with that argument specification. +<p>For example: +<p><pre> +%macro foo 1-3 + ; Do something +%endmacro +%unmacro foo 1-3 +</pre> +<p>removes the previously defined macro <code><nobr>foo</nobr></code>, but +<p><pre> +%macro bar 1-3 + ; Do something +%endmacro +%unmacro bar 1 +</pre> +<p>does <em>not</em> remove the macro <code><nobr>bar</nobr></code>, since +the argument specification does not match exactly. +<h4><a name="section-4.3.12">4.3.12 Exiting Multi-Line Macros: <code><nobr>%exitmacro</nobr></code></a></h4> +<p>Multi-line macro expansions can be arbitrarily terminated with the +<code><nobr>%exitmacro</nobr></code> directive. +<p>For example: +<p><pre> +%macro foo 1-3 + ; Do something + %if<condition> + %exitmacro + %endif + ; Do something +%endmacro +</pre> +<h3><a name="section-4.4">4.4 Conditional Assembly</a></h3> +<p>Similarly to the C preprocessor, NASM allows sections of a source file +to be assembled only if certain conditions are met. The general syntax of +this feature looks like this: +<p><pre> +%if<condition> + ; some code which only appears if <condition> is met +%elif<condition2> + ; only appears if <condition> is not met but <condition2> is +%else + ; this appears if neither <condition> nor <condition2> was met +%endif +</pre> +<p>The inverse forms <code><nobr>%ifn</nobr></code> and +<code><nobr>%elifn</nobr></code> are also supported. +<p>The <code><nobr>%else</nobr></code> clause is optional, as is the +<code><nobr>%elif</nobr></code> clause. You can have more than one +<code><nobr>%elif</nobr></code> clause as well. +<p>There are a number of variants of the <code><nobr>%if</nobr></code> +directive. Each has its corresponding <code><nobr>%elif</nobr></code>, +<code><nobr>%ifn</nobr></code>, and <code><nobr>%elifn</nobr></code> +directives; for example, the equivalents to the +<code><nobr>%ifdef</nobr></code> directive are +<code><nobr>%elifdef</nobr></code>, <code><nobr>%ifndef</nobr></code>, and +<code><nobr>%elifndef</nobr></code>. +<h4><a name="section-4.4.1">4.4.1 <code><nobr>%ifdef</nobr></code>: Testing Single-Line Macro Existence</a></h4> +<p>Beginning a conditional-assembly block with the line +<code><nobr>%ifdef MACRO</nobr></code> will assemble the subsequent code +if, and only if, a single-line macro called <code><nobr>MACRO</nobr></code> +is defined. If not, then the <code><nobr>%elif</nobr></code> and +<code><nobr>%else</nobr></code> blocks (if any) will be processed instead. +<p>For example, when debugging a program, you might want to write code such +as +<p><pre> + ; perform some function +%ifdef DEBUG + writefile 2,"Function performed successfully",13,10 +%endif + ; go and do something else +</pre> +<p>Then you could use the command-line option +<code><nobr>-dDEBUG</nobr></code> to create a version of the program which +produced debugging messages, and remove the option to generate the final +release version of the program. +<p>You can test for a macro <em>not</em> being defined by using +<code><nobr>%ifndef</nobr></code> instead of +<code><nobr>%ifdef</nobr></code>. You can also test for macro definitions +in <code><nobr>%elif</nobr></code> blocks by using +<code><nobr>%elifdef</nobr></code> and <code><nobr>%elifndef</nobr></code>. +<h4><a name="section-4.4.2">4.4.2 <code><nobr>%ifmacro</nobr></code>: Testing Multi-Line Macro Existence</a></h4> +<p>The <code><nobr>%ifmacro</nobr></code> directive operates in the same +way as the <code><nobr>%ifdef</nobr></code> directive, except that it +checks for the existence of a multi-line macro. +<p>For example, you may be working with a large project and not have +control over the macros in a library. You may want to create a macro with +one name if it doesn't already exist, and another name if one with that +name does exist. +<p>The <code><nobr>%ifmacro</nobr></code> is considered true if defining a +macro with the given name and number of arguments would cause a definitions +conflict. For example: +<p><pre> +%ifmacro MyMacro 1-3 + + %error "MyMacro 1-3" causes a conflict with an existing macro. + +%else + + %macro MyMacro 1-3 + + ; insert code to define the macro + + %endmacro + +%endif +</pre> +<p>This will create the macro "MyMacro 1-3" if no macro already exists +which would conflict with it, and emits a warning if there would be a +definition conflict. +<p>You can test for the macro not existing by using the +<code><nobr>%ifnmacro</nobr></code> instead of +<code><nobr>%ifmacro</nobr></code>. Additional tests can be performed in +<code><nobr>%elif</nobr></code> blocks by using +<code><nobr>%elifmacro</nobr></code> and +<code><nobr>%elifnmacro</nobr></code>. +<h4><a name="section-4.4.3">4.4.3 <code><nobr>%ifctx</nobr></code>: Testing the Context Stack</a></h4> +<p>The conditional-assembly construct <code><nobr>%ifctx</nobr></code> will +cause the subsequent code to be assembled if and only if the top context on +the preprocessor's context stack has the same name as one of the arguments. +As with <code><nobr>%ifdef</nobr></code>, the inverse and +<code><nobr>%elif</nobr></code> forms <code><nobr>%ifnctx</nobr></code>, +<code><nobr>%elifctx</nobr></code> and <code><nobr>%elifnctx</nobr></code> +are also supported. +<p>For more details of the context stack, see +<a href="#section-4.7">section 4.7</a>. For a sample use of +<code><nobr>%ifctx</nobr></code>, see <a href="#section-4.7.5">section +4.7.5</a>. +<h4><a name="section-4.4.4">4.4.4 <code><nobr>%if</nobr></code>: Testing Arbitrary Numeric Expressions</a></h4> +<p>The conditional-assembly construct <code><nobr>%if expr</nobr></code> +will cause the subsequent code to be assembled if and only if the value of +the numeric expression <code><nobr>expr</nobr></code> is non-zero. An +example of the use of this feature is in deciding when to break out of a +<code><nobr>%rep</nobr></code> preprocessor loop: see +<a href="#section-4.5">section 4.5</a> for a detailed example. +<p>The expression given to <code><nobr>%if</nobr></code>, and its +counterpart <code><nobr>%elif</nobr></code>, is a critical expression (see +<a href="nasmdoc3.html#section-3.8">section 3.8</a>). +<p><code><nobr>%if</nobr></code> extends the normal NASM expression syntax, +by providing a set of relational operators which are not normally available +in expressions. The operators <code><nobr>=</nobr></code>, +<code><nobr><</nobr></code>, <code><nobr>></nobr></code>, +<code><nobr><=</nobr></code>, <code><nobr>>=</nobr></code> and +<code><nobr><></nobr></code> test equality, less-than, greater-than, +less-or-equal, greater-or-equal and not-equal respectively. The C-like +forms <code><nobr>==</nobr></code> and <code><nobr>!=</nobr></code> are +supported as alternative forms of <code><nobr>=</nobr></code> and +<code><nobr><></nobr></code>. In addition, low-priority logical +operators <code><nobr>&&</nobr></code>, +<code><nobr>^^</nobr></code> and <code><nobr>||</nobr></code> are provided, +supplying logical AND, logical XOR and logical OR. These work like the C +logical operators (although C has no logical XOR), in that they always +return either 0 or 1, and treat any non-zero input as 1 (so that +<code><nobr>^^</nobr></code>, for example, returns 1 if exactly one of its +inputs is zero, and 0 otherwise). The relational operators also return 1 +for true and 0 for false. +<p>Like other <code><nobr>%if</nobr></code> constructs, +<code><nobr>%if</nobr></code> has a counterpart +<code><nobr>%elif</nobr></code>, and negative forms +<code><nobr>%ifn</nobr></code> and <code><nobr>%elifn</nobr></code>. +<h4><a name="section-4.4.5">4.4.5 <code><nobr>%ifidn</nobr></code> and <code><nobr>%ifidni</nobr></code>: Testing Exact Text Identity</a></h4> +<p>The construct <code><nobr>%ifidn text1,text2</nobr></code> will cause +the subsequent code to be assembled if and only if +<code><nobr>text1</nobr></code> and <code><nobr>text2</nobr></code>, after +expanding single-line macros, are identical pieces of text. Differences in +white space are not counted. +<p><code><nobr>%ifidni</nobr></code> is similar to +<code><nobr>%ifidn</nobr></code>, but is case-insensitive. +<p>For example, the following macro pushes a register or number on the +stack, and allows you to treat <code><nobr>IP</nobr></code> as a real +register: +<p><pre> +%macro pushparam 1 + + %ifidni %1,ip + call %%label + %%label: + %else + push %1 + %endif + +%endmacro +</pre> +<p>Like other <code><nobr>%if</nobr></code> constructs, +<code><nobr>%ifidn</nobr></code> has a counterpart +<code><nobr>%elifidn</nobr></code>, and negative forms +<code><nobr>%ifnidn</nobr></code> and <code><nobr>%elifnidn</nobr></code>. +Similarly, <code><nobr>%ifidni</nobr></code> has counterparts +<code><nobr>%elifidni</nobr></code>, <code><nobr>%ifnidni</nobr></code> and +<code><nobr>%elifnidni</nobr></code>. +<h4><a name="section-4.4.6">4.4.6 <code><nobr>%ifid</nobr></code>, <code><nobr>%ifnum</nobr></code>, <code><nobr>%ifstr</nobr></code>: Testing Token Types</a></h4> +<p>Some macros will want to perform different tasks depending on whether +they are passed a number, a string, or an identifier. For example, a string +output macro might want to be able to cope with being passed either a +string constant or a pointer to an existing string. +<p>The conditional assembly construct <code><nobr>%ifid</nobr></code>, +taking one parameter (which may be blank), assembles the subsequent code if +and only if the first token in the parameter exists and is an identifier. +<code><nobr>%ifnum</nobr></code> works similarly, but tests for the token +being a numeric constant; <code><nobr>%ifstr</nobr></code> tests for it +being a string. +<p>For example, the <code><nobr>writefile</nobr></code> macro defined in +<a href="#section-4.3.4">section 4.3.4</a> can be extended to take +advantage of <code><nobr>%ifstr</nobr></code> in the following fashion: +<p><pre> +%macro writefile 2-3+ + + %ifstr %2 + jmp %%endstr + %if %0 = 3 + %%str: db %2,%3 + %else + %%str: db %2 + %endif + %%endstr: mov dx,%%str + mov cx,%%endstr-%%str + %else + mov dx,%2 + mov cx,%3 + %endif + mov bx,%1 + mov ah,0x40 + int 0x21 + +%endmacro +</pre> +<p>Then the <code><nobr>writefile</nobr></code> macro can cope with being +called in either of the following two ways: +<p><pre> + writefile [file], strpointer, length + writefile [file], "hello", 13, 10 +</pre> +<p>In the first, <code><nobr>strpointer</nobr></code> is used as the +address of an already-declared string, and <code><nobr>length</nobr></code> +is used as its length; in the second, a string is given to the macro, which +therefore declares it itself and works out the address and length for +itself. +<p>Note the use of <code><nobr>%if</nobr></code> inside the +<code><nobr>%ifstr</nobr></code>: this is to detect whether the macro was +passed two arguments (so the string would be a single string constant, and +<code><nobr>db %2</nobr></code> would be adequate) or more (in which case, +all but the first two would be lumped together into +<code><nobr>%3</nobr></code>, and <code><nobr>db %2,%3</nobr></code> would +be required). +<p>The usual <code><nobr>%elif</nobr></code>..., +<code><nobr>%ifn</nobr></code>..., and <code><nobr>%elifn</nobr></code>... +versions exist for each of <code><nobr>%ifid</nobr></code>, +<code><nobr>%ifnum</nobr></code> and <code><nobr>%ifstr</nobr></code>. +<h4><a name="section-4.4.7">4.4.7 <code><nobr>%iftoken</nobr></code>: Test for a Single Token</a></h4> +<p>Some macros will want to do different things depending on if it is +passed a single token (e.g. paste it to something else using +<code><nobr>%+</nobr></code>) versus a multi-token sequence. +<p>The conditional assembly construct <code><nobr>%iftoken</nobr></code> +assembles the subsequent code if and only if the expanded parameters +consist of exactly one token, possibly surrounded by whitespace. +<p>For example: +<p><pre> +%iftoken 1 +</pre> +<p>will assemble the subsequent code, but +<p><pre> +%iftoken -1 +</pre> +<p>will not, since <code><nobr>-1</nobr></code> contains two tokens: the +unary minus operator <code><nobr>-</nobr></code>, and the number +<code><nobr>1</nobr></code>. +<p>The usual <code><nobr>%eliftoken</nobr></code>, +<code><nobr>%ifntoken</nobr></code>, and +<code><nobr>%elifntoken</nobr></code> variants are also provided. +<h4><a name="section-4.4.8">4.4.8 <code><nobr>%ifempty</nobr></code>: Test for Empty Expansion</a></h4> +<p>The conditional assembly construct <code><nobr>%ifempty</nobr></code> +assembles the subsequent code if and only if the expanded parameters do not +contain any tokens at all, whitespace excepted. +<p>The usual <code><nobr>%elifempty</nobr></code>, +<code><nobr>%ifnempty</nobr></code>, and +<code><nobr>%elifnempty</nobr></code> variants are also provided. +<h3><a name="section-4.5">4.5 Preprocessor Loops: <code><nobr>%rep</nobr></code></a></h3> +<p>NASM's <code><nobr>TIMES</nobr></code> prefix, though useful, cannot be +used to invoke a multi-line macro multiple times, because it is processed +by NASM after macros have already been expanded. Therefore NASM provides +another form of loop, this time at the preprocessor level: +<code><nobr>%rep</nobr></code>. +<p>The directives <code><nobr>%rep</nobr></code> and +<code><nobr>%endrep</nobr></code> (<code><nobr>%rep</nobr></code> takes a +numeric argument, which can be an expression; +<code><nobr>%endrep</nobr></code> takes no arguments) can be used to +enclose a chunk of code, which is then replicated as many times as +specified by the preprocessor: +<p><pre> +%assign i 0 +%rep 64 + inc word [table+2*i] +%assign i i+1 +%endrep +</pre> +<p>This will generate a sequence of 64 <code><nobr>INC</nobr></code> +instructions, incrementing every word of memory from +<code><nobr>[table]</nobr></code> to <code><nobr>[table+126]</nobr></code>. +<p>For more complex termination conditions, or to break out of a repeat +loop part way along, you can use the <code><nobr>%exitrep</nobr></code> +directive to terminate the loop, like this: +<p><pre> +fibonacci: +%assign i 0 +%assign j 1 +%rep 100 +%if j > 65535 + %exitrep +%endif + dw j +%assign k j+i +%assign i j +%assign j k +%endrep + +fib_number equ ($-fibonacci)/2 +</pre> +<p>This produces a list of all the Fibonacci numbers that will fit in 16 +bits. Note that a maximum repeat count must still be given to +<code><nobr>%rep</nobr></code>. This is to prevent the possibility of NASM +getting into an infinite loop in the preprocessor, which (on multitasking +or multi-user systems) would typically cause all the system memory to be +gradually used up and other applications to start crashing. +<h3><a name="section-4.6">4.6 Source Files and Dependencies</a></h3> +<p>These commands allow you to split your sources into multiple files. +<h4><a name="section-4.6.1">4.6.1 <code><nobr>%include</nobr></code>: Including Other Files</a></h4> +<p>Using, once again, a very similar syntax to the C preprocessor, NASM's +preprocessor lets you include other source files into your code. This is +done by the use of the <code><nobr>%include</nobr></code> directive: +<p><pre> +%include "macros.mac" +</pre> +<p>will include the contents of the file +<code><nobr>macros.mac</nobr></code> into the source file containing the +<code><nobr>%include</nobr></code> directive. +<p>Include files are searched for in the current directory (the directory +you're in when you run NASM, as opposed to the location of the NASM +executable or the location of the source file), plus any directories +specified on the NASM command line using the <code><nobr>-i</nobr></code> +option. +<p>The standard C idiom for preventing a file being included more than once +is just as applicable in NASM: if the file +<code><nobr>macros.mac</nobr></code> has the form +<p><pre> +%ifndef MACROS_MAC + %define MACROS_MAC + ; now define some macros +%endif +</pre> +<p>then including the file more than once will not cause errors, because +the second time the file is included nothing will happen because the macro +<code><nobr>MACROS_MAC</nobr></code> will already be defined. +<p>You can force a file to be included even if there is no +<code><nobr>%include</nobr></code> directive that explicitly includes it, +by using the <code><nobr>-p</nobr></code> option on the NASM command line +(see <a href="nasmdoc2.html#section-2.1.17">section 2.1.17</a>). +<h4><a name="section-4.6.2">4.6.2 <code><nobr>%pathsearch</nobr></code>: Search the Include Path</a></h4> +<p>The <code><nobr>%pathsearch</nobr></code> directive takes a single-line +macro name and a filename, and declare or redefines the specified +single-line macro to be the include-path-resolved version of the filename, +if the file exists (otherwise, it is passed unchanged.) +<p>For example, +<p><pre> +%pathsearch MyFoo "foo.bin" +</pre> +<p>... with <code><nobr>-Ibins/</nobr></code> in the include path may end +up defining the macro <code><nobr>MyFoo</nobr></code> to be +<code><nobr>"bins/foo.bin"</nobr></code>. +<h4><a name="section-4.6.3">4.6.3 <code><nobr>%depend</nobr></code>: Add Dependent Files</a></h4> +<p>The <code><nobr>%depend</nobr></code> directive takes a filename and +adds it to the list of files to be emitted as dependency generation when +the <code><nobr>-M</nobr></code> options and its relatives (see +<a href="nasmdoc2.html#section-2.1.4">section 2.1.4</a>) are used. It +produces no output. +<p>This is generally used in conjunction with +<code><nobr>%pathsearch</nobr></code>. For example, a simplified version of +the standard macro wrapper for the <code><nobr>INCBIN</nobr></code> +directive looks like: +<p><pre> +%imacro incbin 1-2+ 0 +%pathsearch dep %1 +%depend dep + incbin dep,%2 +%endmacro +</pre> +<p>This first resolves the location of the file into the macro +<code><nobr>dep</nobr></code>, then adds it to the dependency lists, and +finally issues the assembler-level <code><nobr>INCBIN</nobr></code> +directive. +<h4><a name="section-4.6.4">4.6.4 <code><nobr>%use</nobr></code>: Include Standard Macro Package</a></h4> +<p>The <code><nobr>%use</nobr></code> directive is similar to +<code><nobr>%include</nobr></code>, but rather than including the contents +of a file, it includes a named standard macro package. The standard macro +packages are part of NASM, and are described in +<a href="nasmdoc5.html">chapter 5</a>. +<p>Unlike the <code><nobr>%include</nobr></code> directive, package names +for the <code><nobr>%use</nobr></code> directive do not require quotes, but +quotes are permitted. In NASM 2.04 and 2.05 the unquoted form would be +macro-expanded; this is no longer true. Thus, the following lines are +equivalent: +<p><pre> +%use altreg +%use 'altreg' +</pre> +<p>Standard macro packages are protected from multiple inclusion. When a +standard macro package is used, a testable single-line macro of the form +<code><nobr>__USE_</nobr></code><em>package</em><code><nobr>__</nobr></code> +is also defined, see <a href="#section-4.11.8">section 4.11.8</a>. +<h3><a name="section-4.7">4.7 The Context Stack</a></h3> +<p>Having labels that are local to a macro definition is sometimes not +quite powerful enough: sometimes you want to be able to share labels +between several macro calls. An example might be a +<code><nobr>REPEAT</nobr></code> ... <code><nobr>UNTIL</nobr></code> loop, +in which the expansion of the <code><nobr>REPEAT</nobr></code> macro would +need to be able to refer to a label which the +<code><nobr>UNTIL</nobr></code> macro had defined. However, for such a +macro you would also want to be able to nest these loops. +<p>NASM provides this level of power by means of a <em>context stack</em>. +The preprocessor maintains a stack of <em>contexts</em>, each of which is +characterized by a name. You add a new context to the stack using the +<code><nobr>%push</nobr></code> directive, and remove one using +<code><nobr>%pop</nobr></code>. You can define labels that are local to a +particular context on the stack. +<h4><a name="section-4.7.1">4.7.1 <code><nobr>%push</nobr></code> and <code><nobr>%pop</nobr></code>: Creating and Removing Contexts</a></h4> +<p>The <code><nobr>%push</nobr></code> directive is used to create a new +context and place it on the top of the context stack. +<code><nobr>%push</nobr></code> takes an optional argument, which is the +name of the context. For example: +<p><pre> +%push foobar +</pre> +<p>This pushes a new context called <code><nobr>foobar</nobr></code> on the +stack. You can have several contexts on the stack with the same name: they +can still be distinguished. If no name is given, the context is unnamed +(this is normally used when both the <code><nobr>%push</nobr></code> and +the <code><nobr>%pop</nobr></code> are inside a single macro definition.) +<p>The directive <code><nobr>%pop</nobr></code>, taking one optional +argument, removes the top context from the context stack and destroys it, +along with any labels associated with it. If an argument is given, it must +match the name of the current context, otherwise it will issue an error. +<h4><a name="section-4.7.2">4.7.2 Context-Local Labels</a></h4> +<p>Just as the usage <code><nobr>%%foo</nobr></code> defines a label which +is local to the particular macro call in which it is used, the usage +<code><nobr>%$foo</nobr></code> is used to define a label which is local to +the context on the top of the context stack. So the +<code><nobr>REPEAT</nobr></code> and <code><nobr>UNTIL</nobr></code> +example given above could be implemented by means of: +<p><pre> +%macro repeat 0 + + %push repeat + %$begin: + +%endmacro + +%macro until 1 + + j%-1 %$begin + %pop + +%endmacro +</pre> +<p>and invoked by means of, for example, +<p><pre> + mov cx,string + repeat + add cx,3 + scasb + until e +</pre> +<p>which would scan every fourth byte of a string in search of the byte in +<code><nobr>AL</nobr></code>. +<p>If you need to define, or access, labels local to the context +<em>below</em> the top one on the stack, you can use +<code><nobr>%$$foo</nobr></code>, or <code><nobr>%$$$foo</nobr></code> for +the context below that, and so on. +<h4><a name="section-4.7.3">4.7.3 Context-Local Single-Line Macros</a></h4> +<p>NASM also allows you to define single-line macros which are local to a +particular context, in just the same way: +<p><pre> +%define %$localmac 3 +</pre> +<p>will define the single-line macro <code><nobr>%$localmac</nobr></code> +to be local to the top context on the stack. Of course, after a subsequent +<code><nobr>%push</nobr></code>, it can then still be accessed by the name +<code><nobr>%$$localmac</nobr></code>. +<h4><a name="section-4.7.4">4.7.4 <code><nobr>%repl</nobr></code>: Renaming a Context</a></h4> +<p>If you need to change the name of the top context on the stack (in +order, for example, to have it respond differently to +<code><nobr>%ifctx</nobr></code>), you can execute a +<code><nobr>%pop</nobr></code> followed by a +<code><nobr>%push</nobr></code>; but this will have the side effect of +destroying all context-local labels and macros associated with the context +that was just popped. +<p>NASM provides the directive <code><nobr>%repl</nobr></code>, which +<em>replaces</em> a context with a different name, without touching the +associated macros and labels. So you could replace the destructive code +<p><pre> +%pop +%push newname +</pre> +<p>with the non-destructive version +<code><nobr>%repl newname</nobr></code>. +<h4><a name="section-4.7.5">4.7.5 Example Use of the Context Stack: Block IFs</a></h4> +<p>This example makes use of almost all the context-stack features, +including the conditional-assembly construct +<code><nobr>%ifctx</nobr></code>, to implement a block IF statement as a +set of macros. +<p><pre> +%macro if 1 + + %push if + j%-1 %$ifnot + +%endmacro + +%macro else 0 + + %ifctx if + %repl else + jmp %$ifend + %$ifnot: + %else + %error "expected `if' before `else'" + %endif + +%endmacro + +%macro endif 0 + + %ifctx if + %$ifnot: + %pop + %elifctx else + %$ifend: + %pop + %else + %error "expected `if' or `else' before `endif'" + %endif + +%endmacro +</pre> +<p>This code is more robust than the <code><nobr>REPEAT</nobr></code> and +<code><nobr>UNTIL</nobr></code> macros given in +<a href="#section-4.7.2">section 4.7.2</a>, because it uses conditional +assembly to check that the macros are issued in the right order (for +example, not calling <code><nobr>endif</nobr></code> before +<code><nobr>if</nobr></code>) and issues a <code><nobr>%error</nobr></code> +if they're not. +<p>In addition, the <code><nobr>endif</nobr></code> macro has to be able to +cope with the two distinct cases of either directly following an +<code><nobr>if</nobr></code>, or following an +<code><nobr>else</nobr></code>. It achieves this, again, by using +conditional assembly to do different things depending on whether the +context on top of the stack is <code><nobr>if</nobr></code> or +<code><nobr>else</nobr></code>. +<p>The <code><nobr>else</nobr></code> macro has to preserve the context on +the stack, in order to have the <code><nobr>%$ifnot</nobr></code> referred +to by the <code><nobr>if</nobr></code> macro be the same as the one defined +by the <code><nobr>endif</nobr></code> macro, but has to change the +context's name so that <code><nobr>endif</nobr></code> will know there was +an intervening <code><nobr>else</nobr></code>. It does this by the use of +<code><nobr>%repl</nobr></code>. +<p>A sample usage of these macros might look like: +<p><pre> + cmp ax,bx + + if ae + cmp bx,cx + + if ae + mov ax,cx + else + mov ax,bx + endif + + else + cmp ax,cx + + if ae + mov ax,cx + endif + + endif +</pre> +<p>The block-<code><nobr>IF</nobr></code> macros handle nesting quite +happily, by means of pushing another context, describing the inner +<code><nobr>if</nobr></code>, on top of the one describing the outer +<code><nobr>if</nobr></code>; thus <code><nobr>else</nobr></code> and +<code><nobr>endif</nobr></code> always refer to the last unmatched +<code><nobr>if</nobr></code> or <code><nobr>else</nobr></code>. +<h3><a name="section-4.8">4.8 Stack Relative Preprocessor Directives</a></h3> +<p>The following preprocessor directives provide a way to use labels to +refer to local variables allocated on the stack. +<ul> +<li><code><nobr>%arg</nobr></code> (see <a href="#section-4.8.1">section +4.8.1</a>) +<li><code><nobr>%stacksize</nobr></code> (see +<a href="#section-4.8.2">section 4.8.2</a>) +<li><code><nobr>%local</nobr></code> (see <a href="#section-4.8.3">section +4.8.3</a>) +</ul> +<h4><a name="section-4.8.1">4.8.1 <code><nobr>%arg</nobr></code> Directive</a></h4> +<p>The <code><nobr>%arg</nobr></code> directive is used to simplify the +handling of parameters passed on the stack. Stack based parameter passing +is used by many high level languages, including C, C++ and Pascal. +<p>While NASM has macros which attempt to duplicate this functionality (see +<a href="nasmdoc8.html#section-8.4.5">section 8.4.5</a>), the syntax is not +particularly convenient to use. and is not TASM compatible. Here is an +example which shows the use of <code><nobr>%arg</nobr></code> without any +external macros: +<p><pre> +some_function: + + %push mycontext ; save the current context + %stacksize large ; tell NASM to use bp + %arg i:word, j_ptr:word + + mov ax,[i] + mov bx,[j_ptr] + add ax,[bx] + ret + + %pop ; restore original context +</pre> +<p>This is similar to the procedure defined in +<a href="nasmdoc8.html#section-8.4.5">section 8.4.5</a> and adds the value +in i to the value pointed to by j_ptr and returns the sum in the ax +register. See <a href="#section-4.7.1">section 4.7.1</a> for an explanation +of <code><nobr>push</nobr></code> and <code><nobr>pop</nobr></code> and the +use of context stacks. +<h4><a name="section-4.8.2">4.8.2 <code><nobr>%stacksize</nobr></code> Directive</a></h4> +<p>The <code><nobr>%stacksize</nobr></code> directive is used in +conjunction with the <code><nobr>%arg</nobr></code> (see +<a href="#section-4.8.1">section 4.8.1</a>) and the +<code><nobr>%local</nobr></code> (see <a href="#section-4.8.3">section +4.8.3</a>) directives. It tells NASM the default size to use for subsequent +<code><nobr>%arg</nobr></code> and <code><nobr>%local</nobr></code> +directives. The <code><nobr>%stacksize</nobr></code> directive takes one +required argument which is one of <code><nobr>flat</nobr></code>, +<code><nobr>flat64</nobr></code>, <code><nobr>large</nobr></code> or +<code><nobr>small</nobr></code>. +<p><pre> +%stacksize flat +</pre> +<p>This form causes NASM to use stack-based parameter addressing relative +to <code><nobr>ebp</nobr></code> and it assumes that a near form of call +was used to get to this label (i.e. that <code><nobr>eip</nobr></code> is +on the stack). +<p><pre> +%stacksize flat64 +</pre> +<p>This form causes NASM to use stack-based parameter addressing relative +to <code><nobr>rbp</nobr></code> and it assumes that a near form of call +was used to get to this label (i.e. that <code><nobr>rip</nobr></code> is +on the stack). +<p><pre> +%stacksize large +</pre> +<p>This form uses <code><nobr>bp</nobr></code> to do stack-based parameter +addressing and assumes that a far form of call was used to get to this +address (i.e. that <code><nobr>ip</nobr></code> and +<code><nobr>cs</nobr></code> are on the stack). +<p><pre> +%stacksize small +</pre> +<p>This form also uses <code><nobr>bp</nobr></code> to address stack +parameters, but it is different from <code><nobr>large</nobr></code> +because it also assumes that the old value of bp is pushed onto the stack +(i.e. it expects an <code><nobr>ENTER</nobr></code> instruction). In other +words, it expects that <code><nobr>bp</nobr></code>, +<code><nobr>ip</nobr></code> and <code><nobr>cs</nobr></code> are on the +top of the stack, underneath any local space which may have been allocated +by <code><nobr>ENTER</nobr></code>. This form is probably most useful when +used in combination with the <code><nobr>%local</nobr></code> directive +(see <a href="#section-4.8.3">section 4.8.3</a>). +<h4><a name="section-4.8.3">4.8.3 <code><nobr>%local</nobr></code> Directive</a></h4> +<p>The <code><nobr>%local</nobr></code> directive is used to simplify the +use of local temporary stack variables allocated in a stack frame. +Automatic local variables in C are an example of this kind of variable. The +<code><nobr>%local</nobr></code> directive is most useful when used with +the <code><nobr>%stacksize</nobr></code> (see +<a href="#section-4.8.2">section 4.8.2</a> and is also compatible with the +<code><nobr>%arg</nobr></code> directive (see +<a href="#section-4.8.1">section 4.8.1</a>). It allows simplified reference +to variables on the stack which have been allocated typically by using the +<code><nobr>ENTER</nobr></code> instruction. An example of its use is the +following: +<p><pre> +silly_swap: + + %push mycontext ; save the current context + %stacksize small ; tell NASM to use bp + %assign %$localsize 0 ; see text for explanation + %local old_ax:word, old_dx:word + + enter %$localsize,0 ; see text for explanation + mov [old_ax],ax ; swap ax & bx + mov [old_dx],dx ; and swap dx & cx + mov ax,bx + mov dx,cx + mov bx,[old_ax] + mov cx,[old_dx] + leave ; restore old bp + ret ; + + %pop ; restore original context +</pre> +<p>The <code><nobr>%$localsize</nobr></code> variable is used internally by +the <code><nobr>%local</nobr></code> directive and <em>must</em> be defined +within the current context before the <code><nobr>%local</nobr></code> +directive may be used. Failure to do so will result in one expression +syntax error for each <code><nobr>%local</nobr></code> variable declared. +It then may be used in the construction of an appropriately sized ENTER +instruction as shown in the example. +<h3><a name="section-4.9">4.9 Reporting User-Defined Errors: <code><nobr>%error</nobr></code>, <code><nobr>%warning</nobr></code>, <code><nobr>%fatal</nobr></code></a></h3> +<p>The preprocessor directive <code><nobr>%error</nobr></code> will cause +NASM to report an error if it occurs in assembled code. So if other users +are going to try to assemble your source files, you can ensure that they +define the right macros by means of code like this: +<p><pre> +%ifdef F1 + ; do some setup +%elifdef F2 + ; do some different setup +%else + %error "Neither F1 nor F2 was defined." +%endif +</pre> +<p>Then any user who fails to understand the way your code is supposed to +be assembled will be quickly warned of their mistake, rather than having to +wait until the program crashes on being run and then not knowing what went +wrong. +<p>Similarly, <code><nobr>%warning</nobr></code> issues a warning, but +allows assembly to continue: +<p><pre> +%ifdef F1 + ; do some setup +%elifdef F2 + ; do some different setup +%else + %warning "Neither F1 nor F2 was defined, assuming F1." + %define F1 +%endif +</pre> +<p><code><nobr>%error</nobr></code> and <code><nobr>%warning</nobr></code> +are issued only on the final assembly pass. This makes them safe to use in +conjunction with tests that depend on symbol values. +<p><code><nobr>%fatal</nobr></code> terminates assembly immediately, +regardless of pass. This is useful when there is no point in continuing the +assembly further, and doing so is likely just going to cause a spew of +confusing error messages. +<p>It is optional for the message string after +<code><nobr>%error</nobr></code>, <code><nobr>%warning</nobr></code> or +<code><nobr>%fatal</nobr></code> to be quoted. If it is <em>not</em>, then +single-line macros are expanded in it, which can be used to display more +information to the user. For example: +<p><pre> +%if foo > 64 + %assign foo_over foo-64 + %error foo is foo_over bytes too large +%endif +</pre> +<h3><a name="section-4.10">4.10 Other Preprocessor Directives</a></h3> +<p>NASM also has preprocessor directives which allow access to information +from external sources. Currently they include: +<ul> +<li><code><nobr>%line</nobr></code> enables NASM to correctly handle the +output of another preprocessor (see <a href="#section-4.10.1">section +4.10.1</a>). +<li><code><nobr>%!</nobr></code> enables NASM to read in the value of an +environment variable, which can then be used in your program (see +<a href="#section-4.10.2">section 4.10.2</a>). +</ul> +<h4><a name="section-4.10.1">4.10.1 <code><nobr>%line</nobr></code> Directive</a></h4> +<p>The <code><nobr>%line</nobr></code> directive is used to notify NASM +that the input line corresponds to a specific line number in another file. +Typically this other file would be an original source file, with the +current NASM input being the output of a pre-processor. The +<code><nobr>%line</nobr></code> directive allows NASM to output messages +which indicate the line number of the original source file, instead of the +file that is being read by NASM. +<p>This preprocessor directive is not generally of use to programmers, by +may be of interest to preprocessor authors. The usage of the +<code><nobr>%line</nobr></code> preprocessor directive is as follows: +<p><pre> +%line nnn[+mmm] [filename] +</pre> +<p>In this directive, <code><nobr>nnn</nobr></code> identifies the line of +the original source file which this line corresponds to. +<code><nobr>mmm</nobr></code> is an optional parameter which specifies a +line increment value; each line of the input file read in is considered to +correspond to <code><nobr>mmm</nobr></code> lines of the original source +file. Finally, <code><nobr>filename</nobr></code> is an optional parameter +which specifies the file name of the original source file. +<p>After reading a <code><nobr>%line</nobr></code> preprocessor directive, +NASM will report all file name and line numbers relative to the values +specified therein. +<h4><a name="section-4.10.2">4.10.2 <code><nobr>%!</nobr></code><code><nobr><env></nobr></code>: Read an environment variable.</a></h4> +<p>The <code><nobr>%!<env></nobr></code> directive makes it possible +to read the value of an environment variable at assembly time. This could, +for example, be used to store the contents of an environment variable into +a string, which could be used at some other point in your code. +<p>For example, suppose that you have an environment variable +<code><nobr>FOO</nobr></code>, and you want the contents of +<code><nobr>FOO</nobr></code> to be embedded in your program. You could do +that as follows: +<p><pre> +%defstr FOO %!FOO +</pre> +<p>See <a href="#section-4.1.8">section 4.1.8</a> for notes on the +<code><nobr>%defstr</nobr></code> directive. +<h3><a name="section-4.11">4.11 Standard Macros</a></h3> +<p>NASM defines a set of standard macros, which are already defined when it +starts to process any source file. If you really need a program to be +assembled with no pre-defined macros, you can use the +<code><nobr>%clear</nobr></code> directive to empty the preprocessor of +everything but context-local preprocessor variables and single-line macros. +<p>Most user-level assembler directives (see +<a href="nasmdoc6.html">chapter 6</a>) are implemented as macros which +invoke primitive directives; these are described in +<a href="nasmdoc6.html">chapter 6</a>. The rest of the standard macro set +is described here. +<h4><a name="section-4.11.1">4.11.1 NASM Version Macros</a></h4> +<p>The single-line macros <code><nobr>__NASM_MAJOR__</nobr></code>, +<code><nobr>__NASM_MINOR__</nobr></code>, +<code><nobr>__NASM_SUBMINOR__</nobr></code> and +<code><nobr>___NASM_PATCHLEVEL__</nobr></code> expand to the major, minor, +subminor and patch level parts of the version number of NASM being used. +So, under NASM 0.98.32p1 for example, +<code><nobr>__NASM_MAJOR__</nobr></code> would be defined to be 0, +<code><nobr>__NASM_MINOR__</nobr></code> would be defined as 98, +<code><nobr>__NASM_SUBMINOR__</nobr></code> would be defined to 32, and +<code><nobr>___NASM_PATCHLEVEL__</nobr></code> would be defined as 1. +<p>Additionally, the macro <code><nobr>__NASM_SNAPSHOT__</nobr></code> is +defined for automatically generated snapshot releases <em>only</em>. +<h4><a name="section-4.11.2">4.11.2 <code><nobr>__NASM_VERSION_ID__</nobr></code>: NASM Version ID</a></h4> +<p>The single-line macro <code><nobr>__NASM_VERSION_ID__</nobr></code> +expands to a dword integer representing the full version number of the +version of nasm being used. The value is the equivalent to +<code><nobr>__NASM_MAJOR__</nobr></code>, +<code><nobr>__NASM_MINOR__</nobr></code>, +<code><nobr>__NASM_SUBMINOR__</nobr></code> and +<code><nobr>___NASM_PATCHLEVEL__</nobr></code> concatenated to produce a +single doubleword. Hence, for 0.98.32p1, the returned number would be +equivalent to: +<p><pre> + dd 0x00622001 +</pre> +<p>or +<p><pre> + db 1,32,98,0 +</pre> +<p>Note that the above lines are generate exactly the same code, the second +line is used just to give an indication of the order that the separate +values will be present in memory. +<h4><a name="section-4.11.3">4.11.3 <code><nobr>__NASM_VER__</nobr></code>: NASM Version string</a></h4> +<p>The single-line macro <code><nobr>__NASM_VER__</nobr></code> expands to +a string which defines the version number of nasm being used. So, under +NASM 0.98.32 for example, +<p><pre> + db __NASM_VER__ +</pre> +<p>would expand to +<p><pre> + db "0.98.32" +</pre> +<h4><a name="section-4.11.4">4.11.4 <code><nobr>__FILE__</nobr></code> and <code><nobr>__LINE__</nobr></code>: File Name and Line Number</a></h4> +<p>Like the C preprocessor, NASM allows the user to find out the file name +and line number containing the current instruction. The macro +<code><nobr>__FILE__</nobr></code> expands to a string constant giving the +name of the current input file (which may change through the course of +assembly if <code><nobr>%include</nobr></code> directives are used), and +<code><nobr>__LINE__</nobr></code> expands to a numeric constant giving the +current line number in the input file. +<p>These macros could be used, for example, to communicate debugging +information to a macro, since invoking <code><nobr>__LINE__</nobr></code> +inside a macro definition (either single-line or multi-line) will return +the line number of the macro <em>call</em>, rather than +<em>definition</em>. So to determine where in a piece of code a crash is +occurring, for example, one could write a routine +<code><nobr>stillhere</nobr></code>, which is passed a line number in +<code><nobr>EAX</nobr></code> and outputs something like `line 155: still +here'. You could then write a macro +<p><pre> +%macro notdeadyet 0 + + push eax + mov eax,__LINE__ + call stillhere + pop eax + +%endmacro +</pre> +<p>and then pepper your code with calls to +<code><nobr>notdeadyet</nobr></code> until you find the crash point. +<h4><a name="section-4.11.5">4.11.5 <code><nobr>__BITS__</nobr></code>: Current BITS Mode</a></h4> +<p>The <code><nobr>__BITS__</nobr></code> standard macro is updated every +time that the BITS mode is set using the <code><nobr>BITS XX</nobr></code> +or <code><nobr>[BITS XX]</nobr></code> directive, where XX is a valid mode +number of 16, 32 or 64. <code><nobr>__BITS__</nobr></code> receives the +specified mode number and makes it globally available. This can be very +useful for those who utilize mode-dependent macros. +<h4><a name="section-4.11.6">4.11.6 <code><nobr>__OUTPUT_FORMAT__</nobr></code>: Current Output Format</a></h4> +<p>The <code><nobr>__OUTPUT_FORMAT__</nobr></code> standard macro holds the +current Output Format, as given by the <code><nobr>-f</nobr></code> option +or NASM's default. Type <code><nobr>nasm -hf</nobr></code> for a list. +<p><pre> +%ifidn __OUTPUT_FORMAT__, win32 + %define NEWLINE 13, 10 +%elifidn __OUTPUT_FORMAT__, elf32 + %define NEWLINE 10 +%endif +</pre> +<h4><a name="section-4.11.7">4.11.7 Assembly Date and Time Macros</a></h4> +<p>NASM provides a variety of macros that represent the timestamp of the +assembly session. +<ul> +<li>The <code><nobr>__DATE__</nobr></code> and +<code><nobr>__TIME__</nobr></code> macros give the assembly date and time +as strings, in ISO 8601 format (<code><nobr>"YYYY-MM-DD"</nobr></code> and +<code><nobr>"HH:MM:SS"</nobr></code>, respectively.) +<li>The <code><nobr>__DATE_NUM__</nobr></code> and +<code><nobr>__TIME_NUM__</nobr></code> macros give the assembly date and +time in numeric form; in the format <code><nobr>YYYYMMDD</nobr></code> and +<code><nobr>HHMMSS</nobr></code> respectively. +<li>The <code><nobr>__UTC_DATE__</nobr></code> and +<code><nobr>__UTC_TIME__</nobr></code> macros give the assembly date and +time in universal time (UTC) as strings, in ISO 8601 format +(<code><nobr>"YYYY-MM-DD"</nobr></code> and +<code><nobr>"HH:MM:SS"</nobr></code>, respectively.) If the host platform +doesn't provide UTC time, these macros are undefined. +<li>The <code><nobr>__UTC_DATE_NUM__</nobr></code> and +<code><nobr>__UTC_TIME_NUM__</nobr></code> macros give the assembly date +and time universal time (UTC) in numeric form; in the format +<code><nobr>YYYYMMDD</nobr></code> and <code><nobr>HHMMSS</nobr></code> +respectively. If the host platform doesn't provide UTC time, these macros +are undefined. +<li>The <code><nobr>__POSIX_TIME__</nobr></code> macro is defined as a +number containing the number of seconds since the POSIX epoch, 1 January +1970 00:00:00 UTC; excluding any leap seconds. This is computed using UTC +time if available on the host platform, otherwise it is computed using the +local time as if it was UTC. +</ul> +<p>All instances of time and date macros in the same assembly session +produce consistent output. For example, in an assembly session started at +42 seconds after midnight on January 1, 2010 in Moscow (timezone UTC+3) +these macros would have the following values, assuming, of course, a +properly configured environment with a correct clock: +<p><pre> + __DATE__ "2010-01-01" + __TIME__ "00:00:42" + __DATE_NUM__ 20100101 + __TIME_NUM__ 000042 + __UTC_DATE__ "2009-12-31" + __UTC_TIME__ "21:00:42" + __UTC_DATE_NUM__ 20091231 + __UTC_TIME_NUM__ 210042 + __POSIX_TIME__ 1262293242 +</pre> +<h4><a name="section-4.11.8">4.11.8 <code><nobr>__USE_</nobr></code><em>package</em><code><nobr>__</nobr></code>: Package Include Test</a></h4> +<p>When a standard macro package (see <a href="nasmdoc5.html">chapter +5</a>) is included with the <code><nobr>%use</nobr></code> directive (see +<a href="#section-4.6.4">section 4.6.4</a>), a single-line macro of the +form +<code><nobr>__USE_</nobr></code><em>package</em><code><nobr>__</nobr></code> +is automatically defined. This allows testing if a particular package is +invoked or not. +<p>For example, if the <code><nobr>altreg</nobr></code> package is included +(see <a href="nasmdoc5.html#section-5.1">section 5.1</a>), then the macro +<code><nobr>__USE_ALTREG__</nobr></code> is defined. +<h4><a name="section-4.11.9">4.11.9 <code><nobr>__PASS__</nobr></code>: Assembly Pass</a></h4> +<p>The macro <code><nobr>__PASS__</nobr></code> is defined to be +<code><nobr>1</nobr></code> on preparatory passes, and +<code><nobr>2</nobr></code> on the final pass. In preprocess-only mode, it +is set to <code><nobr>3</nobr></code>, and when running only to generate +dependencies (due to the <code><nobr>-M</nobr></code> or +<code><nobr>-MG</nobr></code> option, see +<a href="nasmdoc2.html#section-2.1.4">section 2.1.4</a>) it is set to +<code><nobr>0</nobr></code>. +<p><em>Avoid using this macro if at all possible. It is tremendously easy +to generate very strange errors by misusing it, and the semantics may +change in future versions of NASM.</em> +<h4><a name="section-4.11.10">4.11.10 <code><nobr>STRUC</nobr></code> and <code><nobr>ENDSTRUC</nobr></code>: Declaring Structure Data Types</a></h4> +<p>The core of NASM contains no intrinsic means of defining data +structures; instead, the preprocessor is sufficiently powerful that data +structures can be implemented as a set of macros. The macros +<code><nobr>STRUC</nobr></code> and <code><nobr>ENDSTRUC</nobr></code> are +used to define a structure data type. +<p><code><nobr>STRUC</nobr></code> takes one or two parameters. The first +parameter is the name of the data type. The second, optional parameter is +the base offset of the structure. The name of the data type is defined as a +symbol with the value of the base offset, and the name of the data type +with the suffix <code><nobr>_size</nobr></code> appended to it is defined +as an <code><nobr>EQU</nobr></code> giving the size of the structure. Once +<code><nobr>STRUC</nobr></code> has been issued, you are defining the +structure, and should define fields using the +<code><nobr>RESB</nobr></code> family of pseudo-instructions, and then +invoke <code><nobr>ENDSTRUC</nobr></code> to finish the definition. +<p>For example, to define a structure called +<code><nobr>mytype</nobr></code> containing a longword, a word, a byte and +a string of bytes, you might code +<p><pre> +struc mytype + + mt_long: resd 1 + mt_word: resw 1 + mt_byte: resb 1 + mt_str: resb 32 + +endstruc +</pre> +<p>The above code defines six symbols: <code><nobr>mt_long</nobr></code> as +0 (the offset from the beginning of a <code><nobr>mytype</nobr></code> +structure to the longword field), <code><nobr>mt_word</nobr></code> as 4, +<code><nobr>mt_byte</nobr></code> as 6, <code><nobr>mt_str</nobr></code> as +7, <code><nobr>mytype_size</nobr></code> as 39, and +<code><nobr>mytype</nobr></code> itself as zero. +<p>The reason why the structure type name is defined at zero by default is +a side effect of allowing structures to work with the local label +mechanism: if your structure members tend to have the same names in more +than one structure, you can define the above structure like this: +<p><pre> +struc mytype + + .long: resd 1 + .word: resw 1 + .byte: resb 1 + .str: resb 32 + +endstruc +</pre> +<p>This defines the offsets to the structure fields as +<code><nobr>mytype.long</nobr></code>, +<code><nobr>mytype.word</nobr></code>, +<code><nobr>mytype.byte</nobr></code> and +<code><nobr>mytype.str</nobr></code>. +<p>NASM, since it has no <em>intrinsic</em> structure support, does not +support any form of period notation to refer to the elements of a structure +once you have one (except the above local-label notation), so code such as +<code><nobr>mov ax,[mystruc.mt_word]</nobr></code> is not valid. +<code><nobr>mt_word</nobr></code> is a constant just like any other +constant, so the correct syntax is +<code><nobr>mov ax,[mystruc+mt_word]</nobr></code> or +<code><nobr>mov ax,[mystruc+mytype.word]</nobr></code>. +<p>Sometimes you only have the address of the structure displaced by an +offset. For example, consider this standard stack frame setup: +<p><pre> +push ebp +mov ebp, esp +sub esp, 40 +</pre> +<p>In this case, you could access an element by subtracting the offset: +<p><pre> +mov [ebp - 40 + mytype.word], ax +</pre> +<p>However, if you do not want to repeat this offset, you can use -40 as a +base offset: +<p><pre> +struc mytype, -40 +</pre> +<p>And access an element this way: +<p><pre> +mov [ebp + mytype.word], ax +</pre> +<h4><a name="section-4.11.11">4.11.11 <code><nobr>ISTRUC</nobr></code>, <code><nobr>AT</nobr></code> and <code><nobr>IEND</nobr></code>: Declaring Instances of Structures</a></h4> +<p>Having defined a structure type, the next thing you typically want to do +is to declare instances of that structure in your data segment. NASM +provides an easy way to do this in the <code><nobr>ISTRUC</nobr></code> +mechanism. To declare a structure of type <code><nobr>mytype</nobr></code> +in a program, you code something like this: +<p><pre> +mystruc: + istruc mytype + + at mt_long, dd 123456 + at mt_word, dw 1024 + at mt_byte, db 'x' + at mt_str, db 'hello, world', 13, 10, 0 + + iend +</pre> +<p>The function of the <code><nobr>AT</nobr></code> macro is to make use of +the <code><nobr>TIMES</nobr></code> prefix to advance the assembly position +to the correct point for the specified structure field, and then to declare +the specified data. Therefore the structure fields must be declared in the +same order as they were specified in the structure definition. +<p>If the data to go in a structure field requires more than one source +line to specify, the remaining source lines can easily come after the +<code><nobr>AT</nobr></code> line. For example: +<p><pre> + at mt_str, db 123,134,145,156,167,178,189 + db 190,100,0 +</pre> +<p>Depending on personal taste, you can also omit the code part of the +<code><nobr>AT</nobr></code> line completely, and start the structure field +on the next line: +<p><pre> + at mt_str + db 'hello, world' + db 13,10,0 +</pre> +<h4><a name="section-4.11.12">4.11.12 <code><nobr>ALIGN</nobr></code> and <code><nobr>ALIGNB</nobr></code>: Data Alignment</a></h4> +<p>The <code><nobr>ALIGN</nobr></code> and <code><nobr>ALIGNB</nobr></code> +macros provides a convenient way to align code or data on a word, longword, +paragraph or other boundary. (Some assemblers call this directive +<code><nobr>EVEN</nobr></code>.) The syntax of the +<code><nobr>ALIGN</nobr></code> and <code><nobr>ALIGNB</nobr></code> macros +is +<p><pre> + align 4 ; align on 4-byte boundary + align 16 ; align on 16-byte boundary + align 8,db 0 ; pad with 0s rather than NOPs + align 4,resb 1 ; align to 4 in the BSS + alignb 4 ; equivalent to previous line +</pre> +<p>Both macros require their first argument to be a power of two; they both +compute the number of additional bytes required to bring the length of the +current section up to a multiple of that power of two, and then apply the +<code><nobr>TIMES</nobr></code> prefix to their second argument to perform +the alignment. +<p>If the second argument is not specified, the default for +<code><nobr>ALIGN</nobr></code> is <code><nobr>NOP</nobr></code>, and the +default for <code><nobr>ALIGNB</nobr></code> is +<code><nobr>RESB 1</nobr></code>. So if the second argument is specified, +the two macros are equivalent. Normally, you can just use +<code><nobr>ALIGN</nobr></code> in code and data sections and +<code><nobr>ALIGNB</nobr></code> in BSS sections, and never need the second +argument except for special purposes. +<p><code><nobr>ALIGN</nobr></code> and <code><nobr>ALIGNB</nobr></code>, +being simple macros, perform no error checking: they cannot warn you if +their first argument fails to be a power of two, or if their second +argument generates more than one byte of code. In each of these cases they +will silently do the wrong thing. +<p><code><nobr>ALIGNB</nobr></code> (or <code><nobr>ALIGN</nobr></code> +with a second argument of <code><nobr>RESB 1</nobr></code>) can be used +within structure definitions: +<p><pre> +struc mytype2 + + mt_byte: + resb 1 + alignb 2 + mt_word: + resw 1 + alignb 4 + mt_long: + resd 1 + mt_str: + resb 32 + +endstruc +</pre> +<p>This will ensure that the structure members are sensibly aligned +relative to the base of the structure. +<p>A final caveat: <code><nobr>ALIGN</nobr></code> and +<code><nobr>ALIGNB</nobr></code> work relative to the beginning of the +<em>section</em>, not the beginning of the address space in the final +executable. Aligning to a 16-byte boundary when the section you're in is +only guaranteed to be aligned to a 4-byte boundary, for example, is a waste +of effort. Again, NASM does not check that the section's alignment +characteristics are sensible for the use of <code><nobr>ALIGN</nobr></code> +or <code><nobr>ALIGNB</nobr></code>. +<p>See also the <code><nobr>smartalign</nobr></code> standard macro +package, <a href="nasmdoc5.html#section-5.2">section 5.2</a>. +<p align=center><a href="nasmdoc5.html">Next Chapter</a> | +<a href="nasmdoc3.html">Previous Chapter</a> | +<a href="nasmdoc0.html">Contents</a> | +<a href="nasmdoci.html">Index</a> +</body></html> |