"Fossies" - the Fresh Open Source Software Archive

Member "nasm-2.15.05/doc/html/nasmdoc5.html" (28 Aug 2020, 18937 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="nasmdoc4.html">Chapter 4</a></li>
   12 <li><a class="next" href="nasmdoc6.html">Chapter 6</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-5">Chapter 5: Standard Macros</h2>
   23 <p>NASM defines a set of standard macros, which are already defined when it
   24 starts to process any source file. If you really need a program to be
   25 assembled with no pre-defined macros, you can use the <code>%clear</code>
   26 directive to empty the preprocessor of everything but context-local
   27 preprocessor variables and single-line macros, see
   28 <a href="nasmdoc4.html#section-4.11.3">section 4.11.3</a>.</p>
   29 <p>Most user-level directives (see <a href="nasmdoc7.html">chapter 7</a>)
   30 are implemented as macros which invoke primitive directives; these are
   31 described in <a href="nasmdoc7.html">chapter 7</a>. The rest of the
   32 standard macro set is described here.</p>
   33 <p>For compability with NASM versions before NASM 2.15, most standard
   34 macros of the form <code>__?foo?__</code> have aliases of form
   35 <code>__foo__</code> (see <a href="nasmdoc4.html#section-4.1.11">section
   36 4.1.11</a>). These can be removed with the directive
   37 <code>%clear defalias</code>.</p>
   38 <h3 id="section-5.1">5.1 NASM Version Macros</h3>
   39 <p>The single-line macros <code>__?NASM_MAJOR?__</code>,
   40 <code>__?NASM_MINOR?__</code>, <code>__?NASM_SUBMINOR?__</code> and
   41 <code>__?NASM_PATCHLEVEL?__</code> expand to the major, minor, subminor and
   42 patch level parts of the version number of NASM being used. So, under NASM
   43 0.98.32p1 for example, <code>__?NASM_MAJOR?__</code> would be defined to be
   44 0, <code>__?NASM_MINOR?__</code> would be defined as 98,
   45 <code>__?NASM_SUBMINOR?__</code> would be defined to 32, and
   46 <code>__?NASM_PATCHLEVEL?__</code> would be defined as 1.</p>
   47 <p>Additionally, the macro <code>__?NASM_SNAPSHOT?__</code> is defined for
   48 automatically generated snapshot releases <em>only</em>.</p>
   49 <h4 id="section-5.1.1">5.1.1 <code>__?NASM_VERSION_ID?__</code>: NASM Version ID</h4>
   50 <p>The single-line macro <code>__?NASM_VERSION_ID?__</code> expands to a
   51 dword integer representing the full version number of the version of nasm
   52 being used. The value is the equivalent to <code>__?NASM_MAJOR?__</code>,
   53 <code>__?NASM_MINOR?__</code>, <code>__?NASM_SUBMINOR?__</code> and
   54 <code>__?NASM_PATCHLEVEL?__</code> concatenated to produce a single
   55 doubleword. Hence, for 0.98.32p1, the returned number would be equivalent
   56 to:</p>
   57 <pre>
   58         dd      0x00622001
   59 </pre>
   60 <p>or</p>
   61 <pre>
   62         db      1,32,98,0
   63 </pre>
   64 <p>Note that the above lines are generate exactly the same code, the second
   65 line is used just to give an indication of the order that the separate
   66 values will be present in memory.</p>
   67 <h4 id="section-5.1.2">5.1.2 <code>__?NASM_VER?__</code>: NASM Version String</h4>
   68 <p>The single-line macro <code>__?NASM_VER?__</code> expands to a string
   69 which defines the version number of nasm being used. So, under NASM 0.98.32
   70 for example,</p>
   71 <pre>
   72         db      __?NASM_VER?__
   73 </pre>
   74 <p>would expand to</p>
   75 <pre>
   76         db      "0.98.32"
   77 </pre>
   78 <h3 id="section-5.2">5.2 <code>__?FILE?__</code> and <code>__?LINE?__</code>: File Name and Line Number</h3>
   79 <p>Like the C preprocessor, NASM allows the user to find out the file name
   80 and line number containing the current instruction. The macro
   81 <code>__?FILE?__</code> expands to a string constant giving the name of the
   82 current input file (which may change through the course of assembly if
   83 <code>%include</code> directives are used), and <code>__?LINE?__</code>
   84 expands to a numeric constant giving the current line number in the input
   85 file.</p>
   86 <p>These macros could be used, for example, to communicate debugging
   87 information to a macro, since invoking <code>__?LINE?__</code> inside a
   88 macro definition (either single-line or multi-line) will return the line
   89 number of the macro <em>call</em>, rather than <em>definition</em>. So to
   90 determine where in a piece of code a crash is occurring, for example, one
   91 could write a routine <code>stillhere</code>, which is passed a line number
   92 in <code>EAX</code> and outputs something like
   93 <code>line 155: still here</code>. You could then write a macro:</p>
   94 <pre>
   95 %macro  notdeadyet 0 
   97         push    eax 
   98         mov     eax,__?LINE?__ 
   99         call    stillhere 
  100         pop     eax 
  102 %endmacro
  103 </pre>
  104 <p>and then pepper your code with calls to <code>notdeadyet</code> until
  105 you find the crash point.</p>
  106 <h3 id="section-5.3">5.3 <code>__?BITS?__</code>: Current Code Generation Mode</h3>
  107 <p>The <code>__?BITS?__</code> standard macro is updated every time that
  108 the BITS mode is set using the <code>BITS XX</code> or
  109 <code>[BITS XX]</code> directive, where XX is a valid mode number of 16, 32
  110 or 64. <code>__?BITS?__</code> receives the specified mode number and makes
  111 it globally available. This can be very useful for those who utilize
  112 mode-dependent macros.</p>
  113 <h3 id="section-5.4">5.4 <code>__?OUTPUT_FORMAT?__</code>: Current Output Format</h3>
  114 <p>The <code>__?OUTPUT_FORMAT?__</code> standard macro holds the current
  115 output format name, as given by the <code>-f</code> option or NASM's
  116 default. Type <code>nasm -h</code> for a list.</p>
  117 <pre>
  118 %ifidn __?OUTPUT_FORMAT?__, win32 
  119  %define NEWLINE 13, 10 
  120 %elifidn __?OUTPUT_FORMAT?__, elf32 
  121  %define NEWLINE 10 
  122 %endif
  123 </pre>
  124 <h3 id="section-5.5">5.5 <code>__?DEBUG_FORMAT?__</code>: Current Debug Format</h3>
  125 <p>If debugging information generation is enabled, The
  126 <code>__?DEBUG_FORMAT?__</code> standard macro holds the current debug
  127 format name as specified by the <code>-F</code> or <code>-g</code> option
  128 or the output format default. Type <code>nasm -f</code> <em>output</em>
  129 <code>y</code> for a list.</p>
  130 <p><code>__?DEBUG_FORMAT?__</code> is not defined if debugging is not
  131 enabled, or if the debug format specified is <code>null</code>.</p>
  132 <h3 id="section-5.6">5.6 Assembly Date and Time Macros</h3>
  133 <p>NASM provides a variety of macros that represent the timestamp of the
  134 assembly session.</p>
  135 <ul>
  136 <li>
  137 <p>The <code>__?DATE?__</code> and <code>__?TIME?__</code> macros give the
  138 assembly date and time as strings, in ISO 8601 format
  139 (<code>"YYYY-MM-DD"</code> and <code>"HH:MM:SS"</code>, respectively.)</p>
  140 </li>
  141 <li>
  142 <p>The <code>__?DATE_NUM?__</code> and <code>__?TIME_NUM?__</code> macros
  143 give the assembly date and time in numeric form; in the format
  144 <code>YYYYMMDD</code> and <code>HHMMSS</code> respectively.</p>
  145 </li>
  146 <li>
  147 <p>The <code>__?UTC_DATE?__</code> and <code>__?UTC_TIME?__</code> macros
  148 give the assembly date and time in universal time (UTC) as strings, in ISO
  149 8601 format (<code>"YYYY-MM-DD"</code> and <code>"HH:MM:SS"</code>,
  150 respectively.) If the host platform doesn't provide UTC time, these macros
  151 are undefined.</p>
  152 </li>
  153 <li>
  154 <p>The <code>__?UTC_DATE_NUM?__</code> and <code>__?UTC_TIME_NUM?__</code>
  155 macros give the assembly date and time universal time (UTC) in numeric
  156 form; in the format <code>YYYYMMDD</code> and <code>HHMMSS</code>
  157 respectively. If the host platform doesn't provide UTC time, these macros
  158 are undefined.</p>
  159 </li>
  160 <li>
  161 <p>The <code>__?POSIX_TIME?__</code> macro is defined as a number
  162 containing the number of seconds since the POSIX epoch, 1 January 1970
  163 00:00:00 UTC; excluding any leap seconds. This is computed using UTC time
  164 if available on the host platform, otherwise it is computed using the local
  165 time as if it was UTC.</p>
  166 </li>
  167 </ul>
  168 <p>All instances of time and date macros in the same assembly session
  169 produce consistent output. For example, in an assembly session started at
  170 42 seconds after midnight on January 1, 2010 in Moscow (timezone UTC+3)
  171 these macros would have the following values, assuming, of course, a
  172 properly configured environment with a correct clock:</p>
  173 <pre>
  174       __?DATE?__             "2010-01-01" 
  175       __?TIME?__             "00:00:42" 
  176       __?DATE_NUM?__         20100101 
  177       __?TIME_NUM?__         000042 
  178       __?UTC_DATE?__         "2009-12-31" 
  179       __?UTC_TIME?__         "21:00:42" 
  180       __?UTC_DATE_NUM?__     20091231 
  181       __?UTC_TIME_NUM?__     210042 
  182       __?POSIX_TIME?__       1262293242
  183 </pre>
  184 <h3 id="section-5.7">5.7 <code>__?USE_</code><em>package</em><code>?__</code>: Package Include Test</h3>
  185 <p>When a standard macro package (see <a href="nasmdoc6.html">chapter
  186 6</a>) is included with the <code>%use</code> directive (see
  187 <a href="nasmdoc4.html#section-4.6.4">section 4.6.4</a>), a single-line
  188 macro of the form <code>__USE_</code><em>package</em><code>__</code> is
  189 automatically defined. This allows testing if a particular package is
  190 invoked or not.</p>
  191 <p>For example, if the <code>altreg</code> package is included (see
  192 <a href="nasmdoc6.html#section-6.1">section 6.1</a>), then the macro
  193 <code>__?USE_ALTREG?__</code> is defined.</p>
  194 <h3 id="section-5.8">5.8 <code>__?PASS?__</code>: Assembly Pass</h3>
  195 <p>The macro <code>__?PASS?__</code> is defined to be <code>1</code> on
  196 preparatory passes, and <code>2</code> on the final pass. In
  197 preprocess-only mode, it is set to <code>3</code>, and when running only to
  198 generate dependencies (due to the <code>-M</code> or <code>-MG</code>
  199 option, see <a href="nasmdoc2.html#section-2.1.5">section 2.1.5</a>) it is
  200 set to <code>0</code>.</p>
  201 <p><em>Avoid using this macro if at all possible. It is tremendously easy
  202 to generate very strange errors by misusing it, and the semantics may
  203 change in future versions of NASM.</em></p>
  204 <h3 id="section-5.9">5.9 Structure Data Types</h3>
  205 <h4 id="section-5.9.1">5.9.1 <code>STRUC</code> and <code>ENDSTRUC</code>: Declaring Structure Data Types</h4>
  206 <p>The core of NASM contains no intrinsic means of defining data
  207 structures; instead, the preprocessor is sufficiently powerful that data
  208 structures can be implemented as a set of macros. The macros
  209 <code>STRUC</code> and <code>ENDSTRUC</code> are used to define a structure
  210 data type.</p>
  211 <p><code>STRUC</code> takes one or two parameters. The first parameter is
  212 the name of the data type. The second, optional parameter is the base
  213 offset of the structure. The name of the data type is defined as a symbol
  214 with the value of the base offset, and the name of the data type with the
  215 suffix <code>_size</code> appended to it is defined as an <code>EQU</code>
  216 giving the size of the structure. Once <code>STRUC</code> has been issued,
  217 you are defining the structure, and should define fields using the
  218 <code>RESB</code> family of pseudo-instructions, and then invoke
  219 <code>ENDSTRUC</code> to finish the definition.</p>
  220 <p>For example, to define a structure called <code>mytype</code> containing
  221 a longword, a word, a byte and a string of bytes, you might code</p>
  222 <pre>
  223 struc   mytype 
  225   mt_long:      resd    1 
  226   mt_word:      resw    1 
  227   mt_byte:      resb    1 
  228   mt_str:       resb    32 
  230 endstruc
  231 </pre>
  232 <p>The above code defines six symbols: <code>mt_long</code> as 0 (the
  233 offset from the beginning of a <code>mytype</code> structure to the
  234 longword field), <code>mt_word</code> as 4, <code>mt_byte</code> as 6,
  235 <code>mt_str</code> as 7, <code>mytype_size</code> as 39, and
  236 <code>mytype</code> itself as zero.</p>
  237 <p>The reason why the structure type name is defined at zero by default is
  238 a side effect of allowing structures to work with the local label
  239 mechanism: if your structure members tend to have the same names in more
  240 than one structure, you can define the above structure like this:</p>
  241 <pre>
  242 struc mytype 
  244   .long:        resd    1 
  245   .word:        resw    1 
  246   .byte:        resb    1 
  247   .str:         resb    32 
  249 endstruc
  250 </pre>
  251 <p>This defines the offsets to the structure fields as
  252 <code>mytype.long</code>, <code>mytype.word</code>,
  253 <code>mytype.byte</code> and <code>mytype.str</code>.</p>
  254 <p>NASM, since it has no <em>intrinsic</em> structure support, does not
  255 support any form of period notation to refer to the elements of a structure
  256 once you have one (except the above local-label notation), so code such as
  257 <code>mov ax,[mystruc.mt_word]</code> is not valid. <code>mt_word</code> is
  258 a constant just like any other constant, so the correct syntax is
  259 <code>mov ax,[mystruc+mt_word]</code> or
  260 <code>mov ax,[mystruc+mytype.word]</code>.</p>
  261 <p>Sometimes you only have the address of the structure displaced by an
  262 offset. For example, consider this standard stack frame setup:</p>
  263 <pre>
  264 push ebp 
  265 mov ebp, esp 
  266 sub esp, 40
  267 </pre>
  268 <p>In this case, you could access an element by subtracting the offset:</p>
  269 <pre>
  270 mov [ebp - 40 + mytype.word], ax
  271 </pre>
  272 <p>However, if you do not want to repeat this offset, you can use &ndash;40
  273 as a base offset:</p>
  274 <pre>
  275 struc mytype, -40
  276 </pre>
  277 <p>And access an element this way:</p>
  278 <pre>
  279 mov [ebp + mytype.word], ax
  280 </pre>
  281 <h4 id="section-5.9.2">5.9.2 <code>ISTRUC</code>, <code>AT</code> and <code>IEND</code>: Declaring Instances of Structures</h4>
  282 <p>Having defined a structure type, the next thing you typically want to do
  283 is to declare instances of that structure in your data segment. NASM
  284 provides an easy way to do this in the <code>ISTRUC</code> mechanism. To
  285 declare a structure of type <code>mytype</code> in a program, you code
  286 something like this:</p>
  287 <pre>
  288 mystruc: 
  289     istruc mytype 
  291         at mt_long, dd      123456 
  292         at mt_word, dw      1024 
  293         at mt_byte, db      'x' 
  294         at mt_str,  db      'hello, world', 13, 10, 0 
  296     iend
  297 </pre>
  298 <p>The function of the <code>AT</code> macro is to make use of the
  299 <code>TIMES</code> prefix to advance the assembly position to the correct
  300 point for the specified structure field, and then to declare the specified
  301 data. Therefore the structure fields must be declared in the same order as
  302 they were specified in the structure definition.</p>
  303 <p>If the data to go in a structure field requires more than one source
  304 line to specify, the remaining source lines can easily come after the
  305 <code>AT</code> line. For example:</p>
  306 <pre>
  307         at mt_str,  db      123,134,145,156,167,178,189 
  308                     db      190,100,0
  309 </pre>
  310 <p>Depending on personal taste, you can also omit the code part of the
  311 <code>AT</code> line completely, and start the structure field on the next
  312 line:</p>
  313 <pre>
  314         at mt_str 
  315                 db      'hello, world' 
  316                 db      13,10,0
  317 </pre>
  318 <h3 id="section-5.10">5.10 Alignment Control</h3>
  319 <h4 id="section-5.10.1">5.10.1 <code>ALIGN</code> and <code>ALIGNB</code>: Code and Data Alignment</h4>
  320 <p>The <code>ALIGN</code> and <code>ALIGNB</code> macros provides a
  321 convenient way to align code or data on a word, longword, paragraph or
  322 other boundary. (Some assemblers call this directive <code>EVEN</code>.)
  323 The syntax of the <code>ALIGN</code> and <code>ALIGNB</code> macros is</p>
  324 <pre>
  325         align   4               ; align on 4-byte boundary 
  326         align   16              ; align on 16-byte boundary 
  327         align   8,db 0          ; pad with 0s rather than NOPs 
  328         align   4,resb 1        ; align to 4 in the BSS 
  329         alignb  4               ; equivalent to previous line
  330 </pre>
  331 <p>Both macros require their first argument to be a power of two; they both
  332 compute the number of additional bytes required to bring the length of the
  333 current section up to a multiple of that power of two, and then apply the
  334 <code>TIMES</code> prefix to their second argument to perform the
  335 alignment.</p>
  336 <p>If the second argument is not specified, the default for
  337 <code>ALIGN</code> is <code>NOP</code>, and the default for
  338 <code>ALIGNB</code> is <code>RESB 1</code>. So if the second argument is
  339 specified, the two macros are equivalent. Normally, you can just use
  340 <code>ALIGN</code> in code and data sections and <code>ALIGNB</code> in BSS
  341 sections, and never need the second argument except for special purposes.</p>
  342 <p><code>ALIGN</code> and <code>ALIGNB</code>, being simple macros, perform
  343 no error checking: they cannot warn you if their first argument fails to be
  344 a power of two, or if their second argument generates more than one byte of
  345 code. In each of these cases they will silently do the wrong thing.</p>
  346 <p><code>ALIGNB</code> (or <code>ALIGN</code> with a second argument of
  347 <code>RESB 1</code>) can be used within structure definitions:</p>
  348 <pre>
  349 struc mytype2 
  351   mt_byte: 
  352         resb 1 
  353         alignb 2 
  354   mt_word: 
  355         resw 1 
  356         alignb 4 
  357   mt_long: 
  358         resd 1 
  359   mt_str: 
  360         resb 32 
  362 endstruc
  363 </pre>
  364 <p>This will ensure that the structure members are sensibly aligned
  365 relative to the base of the structure.</p>
  366 <p>A final caveat: <code>ALIGN</code> and <code>ALIGNB</code> work relative
  367 to the beginning of the <em>section</em>, not the beginning of the address
  368 space in the final executable. Aligning to a 16-byte boundary when the
  369 section you're in is only guaranteed to be aligned to a 4-byte boundary,
  370 for example, is a waste of effort. Again, NASM does not check that the
  371 section's alignment characteristics are sensible for the use of
  372 <code>ALIGN</code> or <code>ALIGNB</code>.</p>
  373 <p>Both <code>ALIGN</code> and <code>ALIGNB</code> do call
  374 <code>SECTALIGN</code> macro implicitly. See
  375 <a href="#section-5.10.2">section 5.10.2</a> for details.</p>
  376 <p>See also the <code>smartalign</code> standard macro package,
  377 <a href="nasmdoc6.html#section-6.2">section 6.2</a>.</p>
  378 <h4 id="section-5.10.2">5.10.2 <code>SECTALIGN</code>: Section Alignment</h4>
  379 <p>The <code>SECTALIGN</code> macros provides a way to modify alignment
  380 attribute of output file section. Unlike the <code>align=</code> attribute
  381 (which is allowed at section definition only) the <code>SECTALIGN</code>
  382 macro may be used at any time.</p>
  383 <p>For example the directive</p>
  384 <pre>
  385 SECTALIGN 16
  386 </pre>
  387 <p>sets the section alignment requirements to 16 bytes. Once increased it
  388 can not be decreased, the magnitude may grow only.</p>
  389 <p>Note that <code>ALIGN</code> (see <a href="#section-5.10.1">section
  390 5.10.1</a>) calls the <code>SECTALIGN</code> macro implicitly so the active
  391 section alignment requirements may be updated. This is by default
  392 behaviour, if for some reason you want the <code>ALIGN</code> do not call
  393 <code>SECTALIGN</code> at all use the directive</p>
  394 <pre>
  396 </pre>
  397 <p>It is still possible to turn in on again by</p>
  398 <pre>
  400 </pre>
  401 <p>Note that <code>SECTALIGN &lt;ON|OFF&gt;</code> affects only the
  402 <code>ALIGN</code>/<code>ALIGNB</code> directives, not an explicit
  403 <code>SECTALIGN</code> directive.</p>
  404 </div>
  405 </body>
  406 </html>