"Fossies" - the Fresh Open Source Software Archive

Member "nasm-2.15.05/doc/html/nasmdoc3.html" (28 Aug 2020, 46336 Bytes) of package /linux/misc/nasm-2.15.05-xdoc.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    3 <html xmlns="http://www.w3.org/1999/xhtml">
    4 <head>
    5 <title>NASM - The Netwide Assembler</title>
    6 <link href="nasmdoc.css" rel="stylesheet" type="text/css" />
    7 <link href="local.css" rel="stylesheet" type="text/css" />
    8 </head>
    9 <body>
   10 <ul class="navbar">
   11 <li class="first"><a class="prev" href="nasmdoc2.html">Chapter 2</a></li>
   12 <li><a class="next" href="nasmdoc4.html">Chapter 4</a></li>
   13 <li><a class="toc" href="nasmdoc0.html">Contents</a></li>
   14 <li class="last"><a class="index" href="nasmdoci.html">Index</a></li>
   15 </ul>
   16 <div class="title">
   17 <h1>NASM - The Netwide Assembler</h1>
   18 <span class="subtitle">version 2.15.05</span>
   19 </div>
   20 <div class="contents"
   21 >
   22 <h2 id="chapter-3">Chapter 3: The NASM Language</h2>
   23 <h3 id="section-3.1">3.1 Layout of a NASM Source Line</h3>
   24 <p>Like most assemblers, each NASM source line contains (unless it is a
   25 macro, a preprocessor directive or an assembler directive: see
   26 <a href="nasmdoc4.html">chapter 4</a> and <a href="nasmdoc7.html">chapter
   27 7</a>) some combination of the four fields</p>
   28 <pre>
   29 label:    instruction operands        ; comment
   30 </pre>
   31 <p>As usual, most of these fields are optional; the presence or absence of
   32 any combination of a label, an instruction and a comment is allowed. Of
   33 course, the operand field is either required or forbidden by the presence
   34 and nature of the instruction field.</p>
   35 <p>NASM uses backslash (\) as the line continuation character; if a line
   36 ends with backslash, the next line is considered to be a part of the
   37 backslash-ended line.</p>
   38 <p>NASM places no restrictions on white space within a line: labels may
   39 have white space before them, or instructions may have no space before
   40 them, or anything. The colon after a label is also optional. (Note that
   41 this means that if you intend to code <code>lodsb</code> alone on a line,
   42 and type <code>lodab</code> by accident, then that's still a valid source
   43 line which does nothing but define a label. Running NASM with the
   44 command-line option <code>-w+orphan-labels</code> will cause it to warn you
   45 if you define a label alone on a line without a trailing colon.)</p>
   46 <p>Valid characters in labels are letters, numbers, <code>_</code>,
   47 <code>$</code>, <code>#</code>, <code>@</code>, <code>~</code>,
   48 <code>.</code>, and <code>?</code>. The only characters which may be used
   49 as the <em>first</em> character of an identifier are letters,
   50 <code>.</code> (with special meaning: see <a href="#section-3.9">section
   51 3.9</a>), <code>_</code> and <code>?</code>. An identifier may also be
   52 prefixed with a <code>$</code> to indicate that it is intended to be read
   53 as an identifier and not a reserved word; thus, if some other module you
   54 are linking with defines a symbol called <code>eax</code>, you can refer to
   55 <code>$eax</code> in NASM code to distinguish the symbol from the register.
   56 Maximum length of an identifier is 4095 characters.</p>
   57 <p>The instruction field may contain any machine instruction: Pentium and
   58 P6 instructions, FPU instructions, MMX instructions and even undocumented
   59 instructions are all supported. The instruction may be prefixed by
   60 <code>LOCK</code>, <code>REP</code>, <code>REPE</code>/<code>REPZ</code>,
   61 <code>REPNE</code>/<code>REPNZ</code>,
   62 <code>XACQUIRE</code>/<code>XRELEASE</code> or
   63 <code>BND</code>/<code>NOBND</code>, in the usual way. Explicit
   64 address-size and operand-size prefixes <code>A16</code>, <code>A32</code>,
   65 <code>A64</code>, <code>O16</code> and <code>O32</code>, <code>O64</code>
   66 are provided &ndash; one example of their use is given in
   67 <a href="nasmdo11.html">chapter 11</a>. You can also use the name of a
   68 segment register as an instruction prefix: coding
   69 <code>es mov [bx],ax</code> is equivalent to coding
   70 <code>mov [es:bx],ax</code>. We recommend the latter syntax, since it is
   71 consistent with other syntactic features of the language, but for
   72 instructions such as <code>LODSB</code>, which has no operands and yet can
   73 require a segment override, there is no clean syntactic way to proceed
   74 apart from <code>es lodsb</code>.</p>
   75 <p>An instruction is not required to use a prefix: prefixes such as
   76 <code>CS</code>, <code>A32</code>, <code>LOCK</code> or <code>REPE</code>
   77 can appear on a line by themselves, and NASM will just generate the prefix
   78 bytes.</p>
   79 <p>In addition to actual machine instructions, NASM also supports a number
   80 of pseudo-instructions, described in <a href="#section-3.2">section
   81 3.2</a>.</p>
   82 <p>Instruction operands may take a number of forms: they can be registers,
   83 described simply by the register name (e.g. <code>ax</code>,
   84 <code>bp</code>, <code>ebx</code>, <code>cr0</code>: NASM does not use the
   85 <code>gas</code>&ndash;style syntax in which register names must be
   86 prefixed by a <code>%</code> sign), or they can be effective addresses (see
   87 <a href="#section-3.3">section 3.3</a>), constants
   88 (<a href="#section-3.4">section 3.4</a>) or expressions
   89 (<a href="#section-3.5">section 3.5</a>).</p>
   90 <p>For x87 floating-point instructions, NASM accepts a wide range of
   91 syntaxes: you can use two-operand forms like MASM supports, or you can use
   92 NASM's native single-operand forms in most cases. For example, you can
   93 code:</p>
   94 <pre>
   95         fadd    st1             ; this sets st0 := st0 + st1 
   96         fadd    st0,st1         ; so does this 
   97 
   98         fadd    st1,st0         ; this sets st1 := st1 + st0 
   99         fadd    to st1          ; so does this
  100 </pre>
  101 <p>Almost any x87 floating-point instruction that references memory must
  102 use one of the prefixes <code>DWORD</code>, <code>QWORD</code> or
  103 <code>TWORD</code> to indicate what size of memory operand it refers to.</p>
  104 <h3 id="section-3.2">3.2 Pseudo-Instructions</h3>
  105 <p>Pseudo-instructions are things which, though not real x86 machine
  106 instructions, are used in the instruction field anyway because that's the
  107 most convenient place to put them. The current pseudo-instructions are
  108 <code>DB</code>, <code>DW</code>, <code>DD</code>, <code>DQ</code>,
  109 <code>DT</code>, <code>DO</code>, <code>DY</code> and <code>DZ</code>;
  110 their uninitialized counterparts <code>RESB</code>, <code>RESW</code>,
  111 <code>RESD</code>, <code>RESQ</code>, <code>REST</code>, <code>RESO</code>,
  112 <code>RESY</code> and <code>RESZ</code>; the <code>INCBIN</code> command,
  113 the <code>EQU</code> command, and the <code>TIMES</code> prefix.</p>
  114 <p>In this documentation, the notation "<code>Dx</code>" and
  115 "<code>RESx</code>" is used to indicate all the <code>DB</code> and
  116 <code>RESB</code> type directives, respectively.</p>
  117 <h4 id="section-3.2.1">3.2.1 <code>Dx</code>: Declaring Initialized Data</h4>
  118 <p><code>DB</code>, <code>DW</code>, <code>DD</code>, <code>DQ</code>,
  119 <code>DT</code>, <code>DO</code>, <code>DY</code> and <code>DZ</code>
  120 (collectively "<code>Dx</code>" in this documentation) are used, much as in
  121 MASM, to declare initialized data in the output file. They can be invoked
  122 in a wide range of ways:</p>
  123 <pre>
  124       db    0x55                ; just the byte 0x55 
  125       db    0x55,0x56,0x57      ; three bytes in succession 
  126       db    'a',0x55            ; character constants are OK 
  127       db    'hello',13,10,'$'   ; so are string constants 
  128       dw    0x1234              ; 0x34 0x12 
  129       dw    'a'                 ; 0x61 0x00 (it's just a number) 
  130       dw    'ab'                ; 0x61 0x62 (character constant) 
  131       dw    'abc'               ; 0x61 0x62 0x63 0x00 (string) 
  132       dd    0x12345678          ; 0x78 0x56 0x34 0x12 
  133       dd    1.234567e20         ; floating-point constant 
  134       dq    0x123456789abcdef0  ; eight byte constant 
  135       dq    1.234567e20         ; double-precision float 
  136       dt    1.234567e20         ; extended-precision float
  137 </pre>
  138 <p><code>DT</code>, <code>DO</code>, <code>DY</code> and <code>DZ</code> do
  139 not accept integer numeric constants as operands.</p>
  140 <p> Starting in NASM 2.15, a the following MASM&ndash;like features have
  141 been implemented:</p>
  142 <ul>
  143 <li>
  144 <p>A <code>?</code> argument to declare uninitialized storage:</p>
  145 <pre>
  146       db    ?                   ; uninitialized
  147 </pre>
  148 </li>
  149 <li>
  150 <p>A superset of the <code>DUP</code> syntax. The NASM version of this has
  151 the following syntax specification; capital letters indicate literal
  152 keywords:</p>
  153 <pre>
  154      dx      := DB | DW | DD | DQ | DT | DO | DY | DZ 
  155      type    := BYTE | WORD | DWORD | QWORD | TWORD | OWORD | YWORD | ZWORD 
  156      atom    := expression | string | float | '?' 
  157      parlist := '(' value [, value ...] ')' 
  158      duplist := expression DUP [type] ['%'] parlist 
  159      list    := duplist | '%' parlist | type ['%'] parlist 
  160      value   := atom | type value | list 
  161 
  162      stmt    := dx value [, value...]
  163 </pre>
  164 <p>Note that a <em>list</em> needs to be prefixed with a <code>%</code>
  165 sign unless prefixed by either <code>DUP</code> or a <em>type</em> in order
  166 to avoid confusing it with a parentesis starting an expression. The
  167 following expressions are all valid:</p>
  168 <pre>
  169        db 33 
  170        db (44)               ; Integer expression 
  171      ; db (44,55)            ; Invalid - error 
  172        db %(44,55) 
  173        db %('XX','YY') 
  174        db ('AA')             ; Integer expression - outputs single byte 
  175        db %('BB')            ; List, containing a string 
  176        db ? 
  177        db 6 dup (33) 
  178        db 6 dup (33, 34) 
  179        db 6 dup (33, 34), 35 
  180        db 7 dup (99) 
  181        db 7 dup dword (?, word ?, ?) 
  182        dw byte (?,44) 
  183        dw 3 dup (0xcc, 4 dup byte ('PQR'), ?), 0xabcd 
  184        dd 16 dup (0xaaaa, ?, 0xbbbbbb) 
  185        dd 64 dup (?)
  186 </pre>
  187 </li>
  188 </ul>
  189 <p> The use of <code>$</code> (current address) in a <code>Dx</code>
  190 statement is undefined in the current version of NASM, <em>except in the
  191 following cases</em>:</p>
  192 <ul>
  193 <li>
  194 <p>For the first expression in the statement, either a <code>DUP</code> or
  195 a data item.</p>
  196 </li>
  197 <li>
  198 <p>An expression of the form "<em>value</em><code> - $</code>", which is
  199 converted to a self-relative relocation.</p>
  200 </li>
  201 </ul>
  202 <p>Future versions of NASM is likely to produce a different result or issue
  203 an error this case.</p>
  204 <p>There is no such restriction on using <code>$$</code> or
  205 section-relative symbols.</p>
  206 <h4 id="section-3.2.2">3.2.2 <code>RESB</code> and Friends: Declaring Uninitialized Data</h4>
  207 <p><code>RESB</code>, <code>RESW</code>, <code>RESD</code>,
  208 <code>RESQ</code>, <code>REST</code>, <code>RESO</code>, <code>RESY</code>
  209 and <code>RESZ</code> are designed to be used in the BSS section of a
  210 module: they declare <em>uninitialized</em> storage space. Each takes a
  211 single operand, which is the number of bytes, words, doublewords or
  212 whatever to reserve. The operand to a <code>RESB</code>&ndash;type
  213 pseudo-instruction is a <em>critical expression</em>: see
  214 <a href="#section-3.8">section 3.8</a>.</p>
  215 <p>For example:</p>
  216 <pre>
  217 buffer:         resb    64              ; reserve 64 bytes 
  218 wordvar:        resw    1               ; reserve a word 
  219 realarray       resq    10              ; array of ten reals 
  220 ymmval:         resy    1               ; one YMM register 
  221 zmmvals:        resz    32              ; 32 ZMM registers
  222 </pre>
  223 <p> Since NASM 2.15, the MASM syntax of using <code>?</code> and
  224 <code>DUP</code> in the <code>D</code><em>x</em> directives is also
  225 supported. Thus, the above example could also be written:</p>
  226 <pre>
  227 buffer:         db      64 dup (?)      ; reserve 64 bytes 
  228 wordvar:        dw      ?               ; reserve a word 
  229 realarray       dq      10 dup (?)      ; array of ten reals 
  230 ymmval:         dy      ?               ; one YMM register 
  231 zmmvals:        dz      32 dup (?)      ; 32 ZMM registers
  232 </pre>
  233 <h4 id="section-3.2.3">3.2.3 <code>INCBIN</code>: Including External Binary Files</h4>
  234 <p><code>INCBIN</code> includes binary file data verbatim into the output
  235 file. This can be handy for (for example) including graphics and sound data
  236 directly into a game executable file. It can be called in one of these
  237 three ways:</p>
  238 <pre>
  239     incbin  "file.dat"             ; include the whole file 
  240     incbin  "file.dat",1024        ; skip the first 1024 bytes 
  241     incbin  "file.dat",1024,512    ; skip the first 1024, and 
  242                                    ; actually include at most 512
  243 </pre>
  244 <p><code>INCBIN</code> is both a directive and a standard macro; the
  245 standard macro version searches for the file in the include file search
  246 path and adds the file to the dependency lists. This macro can be
  247 overridden if desired.</p>
  248 <h4 id="section-3.2.4">3.2.4 <code>EQU</code>: Defining Constants</h4>
  249 <p><code>EQU</code> defines a symbol to a given constant value: when
  250 <code>EQU</code> is used, the source line must contain a label. The action
  251 of <code>EQU</code> is to define the given label name to the value of its
  252 (only) operand. This definition is absolute, and cannot change later. So,
  253 for example,</p>
  254 <pre>
  255 message         db      'hello, world' 
  256 msglen          equ     $-message
  257 </pre>
  258 <p>defines <code>msglen</code> to be the constant 12. <code>msglen</code>
  259 may not then be redefined later. This is not a preprocessor definition
  260 either: the value of <code>msglen</code> is evaluated <em>once</em>, using
  261 the value of <code>$</code> (see <a href="#section-3.5">section 3.5</a> for
  262 an explanation of <code>$</code>) at the point of definition, rather than
  263 being evaluated wherever it is referenced and using the value of
  264 <code>$</code> at the point of reference.</p>
  265 <h4 id="section-3.2.5">3.2.5 <code>TIMES</code>: Repeating Instructions or Data</h4>
  266 <p>The <code>TIMES</code> prefix causes the instruction to be assembled
  267 multiple times. This is partly present as NASM's equivalent of the
  268 <code>DUP</code> syntax supported by MASM&ndash;compatible assemblers, in
  269 that you can code</p>
  270 <pre>
  271 zerobuf:        times 64 db 0
  272 </pre>
  273 <p>or similar things; but <code>TIMES</code> is more versatile than that.
  274 The argument to <code>TIMES</code> is not just a numeric constant, but a
  275 numeric <em>expression</em>, so you can do things like</p>
  276 <pre>
  277 buffer: db      'hello, world' 
  278         times 64-$+buffer db ' '
  279 </pre>
  280 <p>which will store exactly enough spaces to make the total length of
  281 <code>buffer</code> up to 64. Finally, <code>TIMES</code> can be applied to
  282 ordinary instructions, so you can code trivial unrolled loops in it:</p>
  283 <pre>
  284         times 100 movsb
  285 </pre>
  286 <p>Note that there is no effective difference between
  287 <code>times 100 resb 1</code> and <code>resb 100</code>, except that the
  288 latter will be assembled about 100 times faster due to the internal
  289 structure of the assembler.</p>
  290 <p>The operand to <code>TIMES</code> is a critical expression
  291 (<a href="#section-3.8">section 3.8</a>).</p>
  292 <p>Note also that <code>TIMES</code> can't be applied to macros: the reason
  293 for this is that <code>TIMES</code> is processed after the macro phase,
  294 which allows the argument to <code>TIMES</code> to contain expressions such
  295 as <code>64-$+buffer</code> as above. To repeat more than one line of code,
  296 or a complex macro, use the preprocessor <code>%rep</code> directive.</p>
  297 <h3 id="section-3.3">3.3 Effective Addresses</h3>
  298 <p>An effective address is any operand to an instruction which references
  299 memory. Effective addresses, in NASM, have a very simple syntax: they
  300 consist of an expression evaluating to the desired address, enclosed in
  301 square brackets. For example:</p>
  302 <pre>
  303 wordvar dw      123 
  304         mov     ax,[wordvar] 
  305         mov     ax,[wordvar+1] 
  306         mov     ax,[es:wordvar+bx]
  307 </pre>
  308 <p>Anything not conforming to this simple system is not a valid memory
  309 reference in NASM, for example <code>es:wordvar[bx]</code>.</p>
  310 <p>More complicated effective addresses, such as those involving more than
  311 one register, work in exactly the same way:</p>
  312 <pre>
  313         mov     eax,[ebx*2+ecx+offset] 
  314         mov     ax,[bp+di+8]
  315 </pre>
  316 <p>NASM is capable of doing algebra on these effective addresses, so that
  317 things which don't necessarily <em>look</em> legal are perfectly all right:</p>
  318 <pre>
  319     mov     eax,[ebx*5]             ; assembles as [ebx*4+ebx] 
  320     mov     eax,[label1*2-label2]   ; ie [label1+(label1-label2)]
  321 </pre>
  322 <p>Some forms of effective address have more than one assembled form; in
  323 most such cases NASM will generate the smallest form it can. For example,
  324 there are distinct assembled forms for the 32-bit effective addresses
  325 <code>[eax*2+0]</code> and <code>[eax+eax]</code>, and NASM will generally
  326 generate the latter on the grounds that the former requires four bytes to
  327 store a zero offset.</p>
  328 <p>NASM has a hinting mechanism which will cause <code>[eax+ebx]</code> and
  329 <code>[ebx+eax]</code> to generate different opcodes; this is occasionally
  330 useful because <code>[esi+ebp]</code> and <code>[ebp+esi]</code> have
  331 different default segment registers.</p>
  332 <p>However, you can force NASM to generate an effective address in a
  333 particular form by the use of the keywords <code>BYTE</code>,
  334 <code>WORD</code>, <code>DWORD</code> and <code>NOSPLIT</code>. If you need
  335 <code>[eax+3]</code> to be assembled using a double-word offset field
  336 instead of the one byte NASM will normally generate, you can code
  337 <code>[dword eax+3]</code>. Similarly, you can force NASM to use a byte
  338 offset for a small value which it hasn't seen on the first pass (see
  339 <a href="#section-3.8">section 3.8</a> for an example of such a code
  340 fragment) by using <code>[byte eax+offset]</code>. As special cases,
  341 <code>[byte eax]</code> will code <code>[eax+0]</code> with a byte offset
  342 of zero, and <code>[dword eax]</code> will code it with a double-word
  343 offset of zero. The normal form, <code>[eax]</code>, will be coded with no
  344 offset field.</p>
  345 <p>The form described in the previous paragraph is also useful if you are
  346 trying to access data in a 32-bit segment from within 16 bit code. For more
  347 information on this see the section on mixed-size addressing
  348 (<a href="nasmdo11.html#section-11.2">section 11.2</a>). In particular, if
  349 you need to access data with a known offset that is larger than will fit in
  350 a 16-bit value, if you don't specify that it is a dword offset, nasm will
  351 cause the high word of the offset to be lost.</p>
  352 <p>Similarly, NASM will split <code>[eax*2]</code> into
  353 <code>[eax+eax]</code> because that allows the offset field to be absent
  354 and space to be saved; in fact, it will also split
  355 <code>[eax*2+offset]</code> into <code>[eax+eax+offset]</code>. You can
  356 combat this behaviour by the use of the <code>NOSPLIT</code> keyword:
  357 <code>[nosplit eax*2]</code> will force <code>[eax*2+0]</code> to be
  358 generated literally. <code>[nosplit eax*1]</code> also has the same effect.
  359 In another way, a split EA form <code>[0, eax*2]</code> can be used, too.
  360 However, <code>NOSPLIT</code> in <code>[nosplit eax+eax]</code> will be
  361 ignored because user's intention here is considered as
  362 <code>[eax+eax]</code>.</p>
  363 <p>In 64-bit mode, NASM will by default generate absolute addresses. The
  364 <code>REL</code> keyword makes it produce <code>RIP</code>&ndash;relative
  365 addresses. Since this is frequently the normally desired behaviour, see the
  366 <code>DEFAULT</code> directive (<a href="nasmdoc7.html#section-7.2">section
  367 7.2</a>). The keyword <code>ABS</code> overrides <code>REL</code>.</p>
  368 <p>A new form of split effective addres syntax is also supported. This is
  369 mainly intended for mib operands as used by MPX instructions, but can be
  370 used for any memory reference. The basic concept of this form is splitting
  371 base and index.</p>
  372 <pre>
  373      mov eax,[ebx+8,ecx*4]   ; ebx=base, ecx=index, 4=scale, 8=disp
  374 </pre>
  375 <p>For mib operands, there are several ways of writing effective address
  376 depending on the tools. NASM supports all currently possible ways of mib
  377 syntax:</p>
  378 <pre>
  379      ; bndstx 
  380      ; next 5 lines are parsed same 
  381      ; base=rax, index=rbx, scale=1, displacement=3 
  382      bndstx [rax+0x3,rbx], bnd0      ; NASM - split EA 
  383      bndstx [rbx*1+rax+0x3], bnd0    ; GAS - '*1' indecates an index reg 
  384      bndstx [rax+rbx+3], bnd0        ; GAS - without hints 
  385      bndstx [rax+0x3], bnd0, rbx     ; ICC-1 
  386      bndstx [rax+0x3], rbx, bnd0     ; ICC-2
  387 </pre>
  388 <p>When broadcasting decorator is used, the opsize keyword should match the
  389 size of each element.</p>
  390 <pre>
  391      VDIVPS zmm4, zmm5, dword [rbx]{1to16}   ; single-precision float 
  392      VDIVPS zmm4, zmm5, zword [rbx]          ; packed 512 bit memory
  393 </pre>
  394 <h3 id="section-3.4">3.4 Constants</h3>
  395 <p>NASM understands four different types of constant: numeric, character,
  396 string and floating-point.</p>
  397 <h4 id="section-3.4.1">3.4.1 Numeric Constants</h4>
  398 <p>A numeric constant is simply a number. NASM allows you to specify
  399 numbers in a variety of number bases, in a variety of ways: you can suffix
  400 <code>H</code> or <code>X</code>, <code>D</code> or <code>T</code>,
  401 <code>Q</code> or <code>O</code>, and <code>B</code> or <code>Y</code> for
  402 hexadecimal, decimal, octal and binary respectively, or you can prefix
  403 <code>0x</code>, for hexadecimal in the style of C, or you can prefix
  404 <code>$</code> for hexadecimal in the style of Borland Pascal or Motorola
  405 Assemblers. Note, though, that the <code>$</code> prefix does double duty
  406 as a prefix on identifiers (see <a href="#section-3.1">section 3.1</a>), so
  407 a hex number prefixed with a <code>$</code> sign must have a digit after
  408 the <code>$</code> rather than a letter. In addition, current versions of
  409 NASM accept the prefix <code>0h</code> for hexadecimal, <code>0d</code> or
  410 <code>0t</code> for decimal, <code>0o</code> or <code>0q</code> for octal,
  411 and <code>0b</code> or <code>0y</code> for binary. Please note that unlike
  412 C, a <code>0</code> prefix by itself does <em>not</em> imply an octal
  413 constant!</p>
  414 <p>Numeric constants can have underscores (<code>_</code>) interspersed to
  415 break up long strings.</p>
  416 <p>Some examples (all producing exactly the same code):</p>
  417 <pre>
  418         mov     ax,200          ; decimal 
  419         mov     ax,0200         ; still decimal 
  420         mov     ax,0200d        ; explicitly decimal 
  421         mov     ax,0d200        ; also decimal 
  422         mov     ax,0c8h         ; hex 
  423         mov     ax,$0c8         ; hex again: the 0 is required 
  424         mov     ax,0xc8         ; hex yet again 
  425         mov     ax,0hc8         ; still hex 
  426         mov     ax,310q         ; octal 
  427         mov     ax,310o         ; octal again 
  428         mov     ax,0o310        ; octal yet again 
  429         mov     ax,0q310        ; octal yet again 
  430         mov     ax,11001000b    ; binary 
  431         mov     ax,1100_1000b   ; same binary constant 
  432         mov     ax,1100_1000y   ; same binary constant once more 
  433         mov     ax,0b1100_1000  ; same binary constant yet again 
  434         mov     ax,0y1100_1000  ; same binary constant yet again
  435 </pre>
  436 <h4 id="section-3.4.2">3.4.2 Character Strings</h4>
  437 <p>A character string consists of up to eight characters enclosed in either
  438 single quotes (<code>'...'</code>), double quotes (<code>"..."</code>) or
  439 backquotes (<code>`...`</code>). Single or double quotes are equivalent to
  440 NASM (except of course that surrounding the constant with single quotes
  441 allows double quotes to appear within it and vice versa); the contents of
  442 those are represented verbatim. Strings enclosed in backquotes support
  443 C-style <code>\</code>&ndash;escapes for special characters.</p>
  444 <p>The following escape sequences are recognized by backquoted strings:</p>
  445 <pre>
  446       \'          single quote (') 
  447       \"          double quote (") 
  448       \`          backquote (`) 
  449       \\          backslash (\) 
  450       \?          question mark (?) 
  451       \a          BEL (ASCII 7) 
  452       \b          BS  (ASCII 8) 
  453       \t          TAB (ASCII 9) 
  454       \n          LF  (ASCII 10) 
  455       \v          VT  (ASCII 11) 
  456       \f          FF  (ASCII 12) 
  457       \r          CR  (ASCII 13) 
  458       \e          ESC (ASCII 27) 
  459       \377        Up to 3 octal digits - literal byte 
  460       \xFF        Up to 2 hexadecimal digits - literal byte 
  461       \u1234      4 hexadecimal digits - Unicode character 
  462       \U12345678  8 hexadecimal digits - Unicode character
  463 </pre>
  464 <p>All other escape sequences are reserved. Note that <code>\0</code>,
  465 meaning a <code>NUL</code> character (ASCII 0), is a special case of the
  466 octal escape sequence.</p>
  467 <p>Unicode characters specified with <code>\u</code> or <code>\U</code> are
  468 converted to UTF-8. For example, the following lines are all equivalent:</p>
  469 <pre>
  470       db `\u263a`            ; UTF-8 smiley face 
  471       db `\xe2\x98\xba`      ; UTF-8 smiley face 
  472       db 0E2h, 098h, 0BAh    ; UTF-8 smiley face
  473 </pre>
  474 <h4 id="section-3.4.3">3.4.3 Character Constants</h4>
  475 <p>A character constant consists of a string up to eight bytes long, used
  476 in an expression context. It is treated as if it was an integer.</p>
  477 <p>A character constant with more than one byte will be arranged with
  478 little-endian order in mind: if you code</p>
  479 <pre>
  480           mov eax,'abcd'
  481 </pre>
  482 <p>then the constant generated is not <code>0x61626364</code>, but
  483 <code>0x64636261</code>, so that if you were then to store the value into
  484 memory, it would read <code>abcd</code> rather than <code>dcba</code>. This
  485 is also the sense of character constants understood by the Pentium's
  486 <code>CPUID</code> instruction.</p>
  487 <h4 id="section-3.4.4">3.4.4 String Constants</h4>
  488 <p>String constants are character strings used in the context of some
  489 pseudo-instructions, namely the <code>DB</code> family and
  490 <code>INCBIN</code> (where it represents a filename.) They are also used in
  491 certain preprocessor directives.</p>
  492 <p>A string constant looks like a character constant, only longer. It is
  493 treated as a concatenation of maximum-size character constants for the
  494 conditions. So the following are equivalent:</p>
  495 <pre>
  496       db    'hello'               ; string constant 
  497       db    'h','e','l','l','o'   ; equivalent character constants
  498 </pre>
  499 <p>And the following are also equivalent:</p>
  500 <pre>
  501       dd    'ninechars'           ; doubleword string constant 
  502       dd    'nine','char','s'     ; becomes three doublewords 
  503       db    'ninechars',0,0,0     ; and really looks like this
  504 </pre>
  505 <p>Note that when used in a string-supporting context, quoted strings are
  506 treated as a string constants even if they are short enough to be a
  507 character constant, because otherwise <code>db 'ab'</code> would have the
  508 same effect as <code>db 'a'</code>, which would be silly. Similarly,
  509 three-character or four-character constants are treated as strings when
  510 they are operands to <code>DW</code>, and so forth.</p>
  511 <h4 id="section-3.4.5">3.4.5 Unicode Strings</h4>
  512 <p>The special operators <code>__?utf16?__</code>,
  513 <code>__?utf16le?__</code>, <code>__?utf16be?__</code>,
  514 <code>__?utf32?__</code>, <code>__?utf32le?__</code> and
  515 <code>__?utf32be?__</code> allows definition of Unicode strings. They take
  516 a string in UTF-8 format and converts it to UTF-16 or UTF-32, respectively.
  517 Unless the <code>be</code> forms are specified, the output is littleendian.</p>
  518 <p>For example:</p>
  519 <pre>
  520 %define u(x) __?utf16?__(x) 
  521 %define w(x) __?utf32?__(x) 
  522 
  523       dw u('C:\WINDOWS'), 0       ; Pathname in UTF-16 
  524       dd w(`A + B = \u206a`), 0   ; String in UTF-32
  525 </pre>
  526 <p>The UTF operators can be applied either to strings passed to the
  527 <code>DB</code> family instructions, or to character constants in an
  528 expression context.</p>
  529 <h4 id="section-3.4.6">3.4.6 Floating-Point Constants</h4>
  530 <p>Floating-point constants are acceptable only as arguments to
  531 <code>DB</code>, <code>DW</code>, <code>DD</code>, <code>DQ</code>,
  532 <code>DT</code>, and <code>DO</code>, or as arguments to the special
  533 operators <code>__?float8?__</code>, <code>__?float16?__</code>,
  534 <code>__?bfloat16?__</code>, <code>__?float32?__</code>,
  535 <code>__?float64?__</code>, <code>__?float80m?__</code>,
  536 <code>__?float80e?__</code>, <code>__?float128l?__</code>, and
  537 <code>__?float128h?__</code>. See also
  538 <a href="nasmdoc6.html#section-6.3">section 6.3</a>.</p>
  539 <p>Floating-point constants are expressed in the traditional form: digits,
  540 then a period, then optionally more digits, then optionally an
  541 <code>E</code> followed by an exponent. The period is mandatory, so that
  542 NASM can distinguish between <code>dd 1</code>, which declares an integer
  543 constant, and <code>dd 1.0</code> which declares a floating-point constant.</p>
  544 <p>NASM also support C99-style hexadecimal floating-point: <code>0x</code>,
  545 hexadecimal digits, period, optionally more hexadeximal digits, then
  546 optionally a <code>P</code> followed by a <em>binary</em> (not hexadecimal)
  547 exponent in decimal notation. As an extension, NASM additionally supports
  548 the <code>0h</code> and <code>$</code> prefixes for hexadecimal, as well
  549 binary and octal floating-point, using the <code>0b</code> or
  550 <code>0y</code> and <code>0o</code> or <code>0q</code> prefixes,
  551 respectively.</p>
  552 <p>Underscores to break up groups of digits are permitted in floating-point
  553 constants as well.</p>
  554 <p>Some examples:</p>
  555 <pre>
  556       db    -0.2                    ; "Quarter precision" 
  557       dw    -0.5                    ; IEEE 754r/SSE5 half precision 
  558       dd    1.2                     ; an easy one 
  559       dd    1.222_222_222           ; underscores are permitted 
  560       dd    0x1p+2                  ; 1.0x2^2 = 4.0 
  561       dq    0x1p+32                 ; 1.0x2^32 = 4 294 967 296.0 
  562       dq    1.e10                   ; 10 000 000 000.0 
  563       dq    1.e+10                  ; synonymous with 1.e10 
  564       dq    1.e-10                  ; 0.000 000 000 1 
  565       dt    3.141592653589793238462 ; pi 
  566       do    1.e+4000                ; IEEE 754r quad precision
  567 </pre>
  568 <p>The 8-bit "quarter-precision" floating-point format is
  569 sign:exponent:mantissa = 1:4:3 with an exponent bias of 7. This appears to
  570 be the most frequently used 8-bit floating-point format, although it is not
  571 covered by any formal standard. This is sometimes called a "minifloat."</p>
  572 <p>The <code>bfloat16</code> format is effectively a compressed version of
  573 the 32-bit single precision format, with a reduced mantissa. It is
  574 effectively the same as truncating the 32-bit format to the upper 16 bits,
  575 except for rounding. There is no <code>D</code><em>x</em> directive that
  576 corresponds to <code>bfloat16</code> as it obviously has the same size as
  577 the IEEE standard 16-bit half precision format, see however
  578 <a href="nasmdoc6.html#section-6.3">section 6.3</a>.</p>
  579 <p>The special operators are used to produce floating-point numbers in
  580 other contexts. They produce the binary representation of a specific
  581 floating-point number as an integer, and can use anywhere integer constants
  582 are used in an expression. <code>__?float80m?__</code> and
  583 <code>__?float80e?__</code> produce the 64-bit mantissa and 16-bit exponent
  584 of an 80-bit floating-point number, and <code>__?float128l?__</code> and
  585 <code>__?float128h?__</code> produce the lower and upper 64-bit halves of a
  586 128-bit floating-point number, respectively.</p>
  587 <p>For example:</p>
  588 <pre>
  589       mov    rax,__?float64?__(3.141592653589793238462)
  590 </pre>
  591 <p>... would assign the binary representation of pi as a 64-bit floating
  592 point number into <code>RAX</code>. This is exactly equivalent to:</p>
  593 <pre>
  594       mov    rax,0x400921fb54442d18
  595 </pre>
  596 <p>NASM cannot do compile-time arithmetic on floating-point constants. This
  597 is because NASM is designed to be portable &ndash; although it always
  598 generates code to run on x86 processors, the assembler itself can run on
  599 any system with an ANSI C compiler. Therefore, the assembler cannot
  600 guarantee the presence of a floating-point unit capable of handling the
  601 Intel number formats, and so for NASM to be able to do floating arithmetic
  602 it would have to include its own complete set of floating-point routines,
  603 which would significantly increase the size of the assembler for very
  604 little benefit.</p>
  605 <p>The special tokens <code>__?Infinity?__</code>, <code>__?QNaN?__</code>
  606 (or <code>__?NaN?__</code>) and <code>__?SNaN?__</code> can be used to
  607 generate infinities, quiet NaNs, and signalling NaNs, respectively. These
  608 are normally used as macros:</p>
  609 <pre>
  610 %define Inf __?Infinity?__ 
  611 %define NaN __?QNaN?__ 
  612 
  613       dq    +1.5, -Inf, NaN         ; Double-precision constants
  614 </pre>
  615 <p>The <code>%use fp</code> standard macro package contains a set of
  616 convenience macros. See <a href="nasmdoc6.html#section-6.3">section
  617 6.3</a>.</p>
  618 <h4 id="section-3.4.7">3.4.7 Packed BCD Constants</h4>
  619 <p>x87-style packed BCD constants can be used in the same contexts as
  620 80-bit floating-point numbers. They are suffixed with <code>p</code> or
  621 prefixed with <code>0p</code>, and can include up to 18 decimal digits.</p>
  622 <p>As with other numeric constants, underscores can be used to separate
  623 digits.</p>
  624 <p>For example:</p>
  625 <pre>
  626       dt 12_345_678_901_245_678p 
  627       dt -12_345_678_901_245_678p 
  628       dt +0p33 
  629       dt 33p
  630 </pre>
  631 <h3 id="section-3.5">3.5 Expressions</h3>
  632 <p>Expressions in NASM are similar in syntax to those in C. Expressions are
  633 evaluated as 64-bit integers which are then adjusted to the appropriate
  634 size.</p>
  635 <p>NASM supports two special tokens in expressions, allowing calculations
  636 to involve the current assembly position: the <code>$</code> and
  637 <code>$$</code> tokens. <code>$</code> evaluates to the assembly position
  638 at the beginning of the line containing the expression; so you can code an
  639 infinite loop using <code>JMP $</code>. <code>$$</code> evaluates to the
  640 beginning of the current section; so you can tell how far into the section
  641 you are by using <code>($-$$)</code>.</p>
  642 <p>The arithmetic operators provided by NASM are listed here, in increasing
  643 order of precedence.</p>
  644 <p>A <em>boolean</em> value is true if nonzero and false if zero. The
  645 operators which return a boolean value always return 1 for true and 0 for
  646 false.</p>
  647 <h4 id="section-3.5.1">3.5.1 <code>?</code> ... <code>:</code>: Conditional Operator</h4>
  648 <p>The syntax of this operator, similar to the C conditional operator, is:</p>
  649 <p><em>boolean</em> <code>?</code> <em>trueval</em> <code>:</code>
  650 <em>falseval</em></p>
  651 <p>This operator evaluates to <em>trueval</em> if <em>boolean</em> is true,
  652 otherwise to <em>falseval</em>.</p>
  653 <p>Note that NASM allows <code>?</code> characters in symbol names.
  654 Therefore, it is highly advisable to always put spaces around the
  655 <code>?</code> and <code>:</code> characters.</p>
  656 <h4 id="section-3.5.2">3.5.2 : <code>||</code>: Boolean OR Operator</h4>
  657 <p>The <code>||</code> operator gives a boolean OR: it evaluates to 1 if
  658 both sides of the expression are nonzero, otherwise 0.</p>
  659 <h4 id="section-3.5.3">3.5.3 : <code>^^</code>: Boolean XOR Operator</h4>
  660 <p>The <code>^^</code> operator gives a boolean XOR: it evaluates to 1 if
  661 any one side of the expression is nonzero, otherwise 0.</p>
  662 <h4 id="section-3.5.4">3.5.4 : <code>&amp;&amp;</code>: Boolean AND Operator</h4>
  663 <p>The <code>&amp;&amp;</code> operator gives a boolean AND: it evaluates
  664 to 1 if both sides of the expression is nonzero, otherwise 0.</p>
  665 <h4 id="section-3.5.5">3.5.5 : Comparison Operators</h4>
  666 <p>NASM supports the following comparison operators:</p>
  667 <ul>
  668 <li>
  669 <p><code>=</code> or <code>==</code> compare for equality.</p>
  670 </li>
  671 <li>
  672 <p><code>!=</code> or <code>&lt;&gt;</code> compare for inequality.</p>
  673 </li>
  674 <li>
  675 <p><code>&lt;</code> compares signed less than.</p>
  676 </li>
  677 <li>
  678 <p><code>&lt;=</code> compares signed less than or equal.</p>
  679 </li>
  680 <li>
  681 <p><code>&gt;</code> compares signed greater than.</p>
  682 </li>
  683 <li>
  684 <p><code>&gt;=</code> compares signed greather than or equal.</p>
  685 </li>
  686 </ul>
  687 <p>These operators evaluate to 0 for false or 1 for true.</p>
  688 <ul>
  689 <li>
  690 <p>&lt;=&gt; does a signed comparison, and evaluates to &ndash;1 for less
  691 than, 0 for equal, and 1 for greater than.</p>
  692 </li>
  693 </ul>
  694 <p>At this time, NASM does not provide unsigned comparison operators.</p>
  695 <h4 id="section-3.5.6">3.5.6 <code>|</code>: Bitwise OR Operator</h4>
  696 <p>The <code>|</code> operator gives a bitwise OR, exactly as performed by
  697 the <code>OR</code> machine instruction.</p>
  698 <h4 id="section-3.5.7">3.5.7 <code>^</code>: Bitwise XOR Operator</h4>
  699 <p><code>^</code> provides the bitwise XOR operation.</p>
  700 <h4 id="section-3.5.8">3.5.8 <code>&amp;</code>: Bitwise AND Operator</h4>
  701 <p><code>&amp;</code> provides the bitwise AND operation.</p>
  702 <h4 id="section-3.5.9">3.5.9 Bit Shift Operators</h4>
  703 <p><code>&lt;&lt;</code> gives a bit-shift to the left, just as it does in
  704 C. So <code>5&lt;&lt;3</code> evaluates to 5 times 8, or 40.
  705 <code>&gt;&gt;</code> gives an <em>unsigned</em> (logical) bit-shift to the
  706 right; the bits shifted in from the left are set to zero.</p>
  707 <p><code>&lt;&lt;&lt;</code> gives a bit-shift to the left, exactly
  708 equivalent to the <code>&lt;&lt;</code> operator; it is included for
  709 completeness. <code>&gt;&gt;&gt;</code> gives an <em>signed</em>
  710 (arithmetic) bit-shift to the right; the bits shifted in from the left are
  711 filled with copies of the most significant (sign) bit.</p>
  712 <h4 id="section-3.5.10">3.5.10 <code>+</code> and <code>-</code>: Addition and Subtraction Operators</h4>
  713 <p>The <code>+</code> and <code>-</code> operators do perfectly ordinary
  714 addition and subtraction.</p>
  715 <h4 id="section-3.5.11">3.5.11 Multiplication, Division and Modulo</h4>
  716 <p><code>*</code> is the multiplication operator.</p>
  717 <p><code>/</code> and <code>//</code> are both division operators:
  718 <code>/</code> is unsigned division and <code>//</code> is signed division.</p>
  719 <p>Similarly, <code>%</code> and <code>%%</code> provide unsigned and
  720 signed modulo operators respectively.</p>
  721 <p>Since the <code>%</code> character is used extensively by the macro
  722 preprocessor, you should ensure that both the signed and unsigned modulo
  723 operators are followed by white space wherever they appear.</p>
  724 <p>NASM, like ANSI C, provides no guarantees about the sensible operation
  725 of the signed modulo operator. On most systems it will match the signed
  726 division operator, such that:</p>
  727 <pre>
  728      b * (a // b) + (a %% b) = a       (b != 0)
  729 </pre>
  730 <h4 id="section-3.5.12">3.5.12 Unary Operators</h4>
  731 <p>The highest-priority operators in NASM's expression grammar are those
  732 which only apply to one argument. These are:</p>
  733 <ul>
  734 <li>
  735 <p><code>-</code> negates (2's complement) its operand.</p>
  736 </li>
  737 <li>
  738 <p><code>+</code> does nothing; it's provided for symmetry with
  739 <code>-</code>.</p>
  740 </li>
  741 <li>
  742 <p><code>~</code> computes the bitwise negation (1's complement) of its
  743 operand.</p>
  744 </li>
  745 <li>
  746 <p><code>!</code> is the boolean negation operator. It evaluates to 1 if
  747 the argument is 0, otherwise 0.</p>
  748 </li>
  749 <li>
  750 <p><code>SEG</code> provides the segment address of its operand (explained
  751 in more detail in <a href="#section-3.6">section 3.6</a>).</p>
  752 </li>
  753 <li>
  754 <p>A set of additional operators with leading and trailing double
  755 underscores are used to implement the <code>integer functions</code> of the
  756 <code>ifunc</code> macro package, see
  757 <a href="nasmdoc6.html#section-6.4">section 6.4</a>.</p>
  758 </li>
  759 </ul>
  760 <h3 id="section-3.6">3.6 <code>SEG</code> and <code>WRT</code></h3>
  761 <p>When writing large 16-bit programs, which must be split into multiple
  762 segments, it is often necessary to be able to refer to the segment part of
  763 the address of a symbol. NASM supports the <code>SEG</code> operator to
  764 perform this function.</p>
  765 <p>The <code>SEG</code> operator evaluates to the <em>preferred</em>
  766 segment base of a symbol, defined as the segment base relative to which the
  767 offset of the symbol makes sense. So the code</p>
  768 <pre>
  769         mov     ax,seg symbol 
  770         mov     es,ax 
  771         mov     bx,symbol
  772 </pre>
  773 <p>will load <code>ES:BX</code> with a valid pointer to the symbol
  774 <code>symbol</code>.</p>
  775 <p>Things can be more complex than this: since 16-bit segments and groups
  776 may overlap, you might occasionally want to refer to some symbol using a
  777 different segment base from the preferred one. NASM lets you do this, by
  778 the use of the <code>WRT</code> (With Reference To) keyword. So you can do
  779 things like</p>
  780 <pre>
  781         mov     ax,weird_seg        ; weird_seg is a segment base 
  782         mov     es,ax 
  783         mov     bx,symbol wrt weird_seg
  784 </pre>
  785 <p>to load <code>ES:BX</code> with a different, but functionally
  786 equivalent, pointer to the symbol <code>symbol</code>.</p>
  787 <p>NASM supports far (inter-segment) calls and jumps by means of the syntax
  788 <code>call segment:offset</code>, where <code>segment</code> and
  789 <code>offset</code> both represent immediate values. So to call a far
  790 procedure, you could code either of</p>
  791 <pre>
  792         call    (seg procedure):procedure 
  793         call    weird_seg:(procedure wrt weird_seg)
  794 </pre>
  795 <p>(The parentheses are included for clarity, to show the intended parsing
  796 of the above instructions. They are not necessary in practice.)</p>
  797 <p>NASM supports the syntax <code>call far procedure</code> as a synonym
  798 for the first of the above usages. <code>JMP</code> works identically to
  799 <code>CALL</code> in these examples.</p>
  800 <p>To declare a far pointer to a data item in a data segment, you must code</p>
  801 <pre>
  802         dw      symbol, seg symbol
  803 </pre>
  804 <p>NASM supports no convenient synonym for this, though you can always
  805 invent one using the macro processor.</p>
  806 <h3 id="section-3.7">3.7 <code>STRICT</code>: Inhibiting Optimization</h3>
  807 <p>When assembling with the optimizer set to level 2 or higher (see
  808 <a href="nasmdoc2.html#section-2.1.24">section 2.1.24</a>), NASM will use
  809 size specifiers (<code>BYTE</code>, <code>WORD</code>, <code>DWORD</code>,
  810 <code>QWORD</code>, <code>TWORD</code>, <code>OWORD</code>,
  811 <code>YWORD</code> or <code>ZWORD</code>), but will give them the smallest
  812 possible size. The keyword <code>STRICT</code> can be used to inhibit
  813 optimization and force a particular operand to be emitted in the specified
  814 size. For example, with the optimizer on, and in <code>BITS 16</code> mode,</p>
  815 <pre>
  816         push dword 33
  817 </pre>
  818 <p>is encoded in three bytes <code>66 6A 21</code>, whereas</p>
  819 <pre>
  820         push strict dword 33
  821 </pre>
  822 <p>is encoded in six bytes, with a full dword immediate operand
  823 <code>66 68 21 00 00 00</code>.</p>
  824 <p>With the optimizer off, the same code (six bytes) is generated whether
  825 the <code>STRICT</code> keyword was used or not.</p>
  826 <h3 id="section-3.8">3.8 Critical Expressions</h3>
  827 <p>Although NASM has an optional multi-pass optimizer, there are some
  828 expressions which must be resolvable on the first pass. These are called
  829 <em>Critical Expressions</em>.</p>
  830 <p>The first pass is used to determine the size of all the assembled code
  831 and data, so that the second pass, when generating all the code, knows all
  832 the symbol addresses the code refers to. So one thing NASM can't handle is
  833 code whose size depends on the value of a symbol declared after the code in
  834 question. For example,</p>
  835 <pre>
  836         times (label-$) db 0 
  837 label:  db      'Where am I?'
  838 </pre>
  839 <p>The argument to <code>TIMES</code> in this case could equally legally
  840 evaluate to anything at all; NASM will reject this example because it
  841 cannot tell the size of the <code>TIMES</code> line when it first sees it.
  842 It will just as firmly reject the slightly paradoxical code</p>
  843 <pre>
  844         times (label-$+1) db 0 
  845 label:  db      'NOW where am I?'
  846 </pre>
  847 <p>in which <em>any</em> value for the <code>TIMES</code> argument is by
  848 definition wrong!</p>
  849 <p>NASM rejects these examples by means of a concept called a <em>critical
  850 expression</em>, which is defined to be an expression whose value is
  851 required to be computable in the first pass, and which must therefore
  852 depend only on symbols defined before it. The argument to the
  853 <code>TIMES</code> prefix is a critical expression.</p>
  854 <h3 id="section-3.9">3.9 Local Labels</h3>
  855 <p>NASM gives special treatment to symbols beginning with a period. A label
  856 beginning with a single period is treated as a <em>local</em> label, which
  857 means that it is associated with the previous non-local label. So, for
  858 example:</p>
  859 <pre>
  860 label1  ; some code 
  861 
  862 .loop 
  863         ; some more code 
  864 
  865         jne     .loop 
  866         ret 
  867 
  868 label2  ; some code 
  869 
  870 .loop 
  871         ; some more code 
  872 
  873         jne     .loop 
  874         ret
  875 </pre>
  876 <p>In the above code fragment, each <code>JNE</code> instruction jumps to
  877 the line immediately before it, because the two definitions of
  878 <code>.loop</code> are kept separate by virtue of each being associated
  879 with the previous non-local label.</p>
  880 <p>This form of local label handling is borrowed from the old Amiga
  881 assembler DevPac; however, NASM goes one step further, in allowing access
  882 to local labels from other parts of the code. This is achieved by means of
  883 <em>defining</em> a local label in terms of the previous non-local label:
  884 the first definition of <code>.loop</code> above is really defining a
  885 symbol called <code>label1.loop</code>, and the second defines a symbol
  886 called <code>label2.loop</code>. So, if you really needed to, you could
  887 write</p>
  888 <pre>
  889 label3  ; some more code 
  890         ; and some more 
  891 
  892         jmp label1.loop
  893 </pre>
  894 <p>Sometimes it is useful &ndash; in a macro, for instance &ndash; to be
  895 able to define a label which can be referenced from anywhere but which
  896 doesn't interfere with the normal local-label mechanism. Such a label can't
  897 be non-local because it would interfere with subsequent definitions of, and
  898 references to, local labels; and it can't be local because the macro that
  899 defined it wouldn't know the label's full name. NASM therefore introduces a
  900 third type of label, which is probably only useful in macro definitions: if
  901 a label begins with the special prefix <code>..@</code>, then it does
  902 nothing to the local label mechanism. So you could code</p>
  903 <pre>
  904 label1:                         ; a non-local label 
  905 .local:                         ; this is really label1.local 
  906 ..@foo:                         ; this is a special symbol 
  907 label2:                         ; another non-local label 
  908 .local:                         ; this is really label2.local 
  909 
  910         jmp     ..@foo          ; this will jump three lines up
  911 </pre>
  912 <p>NASM has the capacity to define other special symbols beginning with a
  913 double period: for example, <code>..start</code> is used to specify the
  914 entry point in the <code>obj</code> output format (see
  915 <a href="nasmdoc8.html#section-8.4.6">section 8.4.6</a>),
  916 <code>..imagebase</code> is used to find out the offset from a base address
  917 of the current image in the <code>win64</code> output format (see
  918 <a href="nasmdoc8.html#section-8.6.1">section 8.6.1</a>). So just keep in
  919 mind that symbols beginning with a double period are special.</p>
  920 </div>
  921 </body>
  922 </html>