File: stdmac.src

package info (click to toggle)
chromium 139.0.7258.127-2
  • links: PTS, VCS
  • area: main
  • in suites: forky
  • size: 6,122,156 kB
  • sloc: cpp: 35,100,771; ansic: 7,163,530; javascript: 4,103,002; python: 1,436,920; asm: 946,517; xml: 746,709; pascal: 187,653; perl: 88,691; sh: 88,436; objc: 79,953; sql: 51,488; cs: 44,583; fortran: 24,137; makefile: 22,147; tcl: 15,277; php: 13,980; yacc: 8,984; ruby: 7,485; awk: 3,720; lisp: 3,096; lex: 1,327; ada: 727; jsp: 228; sed: 36
file content (416 lines) | stat: -rw-r--r-- 15,630 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
\C{stdmac} \i{Standard Macros}

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 \i\c{%clear}
directive to empty the preprocessor of everything but context-local
preprocessor variables and single-line macros, see \k{clear}.

Most \i{user-level directives} (see \k{directive}) are implemented as
macros which invoke primitive directives; these are described in
\k{directive}. The rest of the standard macro set is described here.

For compatibility with NASM versions before NASM 2.15, most standard
macros of the form \c{__?foo?__} have aliases of form \c{__foo__} (see
\k{defalias}). These can be removed with the directive \c{%clear
defalias}.


\H{stdmacver} \i{NASM Version Macros}

The single-line macros \i\c{__?NASM_MAJOR?__}, \i\c{__?NASM_MINOR?__},
\i\c{__?NASM_SUBMINOR?__} and \i\c{__?NASM_PATCHLEVEL?__} expand to the
major, minor, subminor and patch level parts of the \i{version
number of NASM} being used. So, under NASM 0.98.32p1 for
example, \c{__?NASM_MAJOR?__} would be defined to be 0, \c{__?NASM_MINOR?__}
would be defined as 98, \c{__?NASM_SUBMINOR?__} would be defined to 32,
and \c{__?NASM_PATCHLEVEL?__} would be defined as 1.

Additionally, the macro \i\c{__?NASM_SNAPSHOT?__} is defined for
automatically generated snapshot releases \e{only}.


\S{stdmacverid} \i\c{__?NASM_VERSION_ID?__}: \i{NASM Version ID}

The single-line macro \c{__?NASM_VERSION_ID?__} expands to a dword integer
representing the full version number of the version of nasm being used.
The value is the equivalent to \c{__?NASM_MAJOR?__}, \c{__?NASM_MINOR?__},
\c{__?NASM_SUBMINOR?__} and \c{__?NASM_PATCHLEVEL?__} concatenated to
produce a single doubleword. Hence, for 0.98.32p1, the returned number
would be equivalent to:

\c         dd      0x00622001

or

\c         db      1,32,98,0

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.


\S{stdmacverstr} \i\c{__?NASM_VER?__}: \i{NASM Version String}

The single-line macro \c{__?NASM_VER?__} expands to a string which defines
the version number of nasm being used. So, under NASM 0.98.32 for example,

\c         db      __?NASM_VER?__

would expand to

\c         db      "0.98.32"


\H{fileline} \i\c{__?FILE?__} and \i\c{__?LINE?__}: File Name and Line Number

Like the C preprocessor, NASM allows the user to find out the file
name and line number containing the current instruction. The macro
\c{__?FILE?__} expands to a string constant giving the name of the
current input file (which may change through the course of assembly
if \c{%include} directives are used), and \c{__?LINE?__} expands to a
numeric constant giving the current line number in the input file.

These macros could be used, for example, to communicate debugging
information to a macro, since invoking \c{__?LINE?__} inside a macro
definition (either single-line or multi-line) will return the line
number of the macro \e{call}, rather than \e{definition}. So to
determine where in a piece of code a crash is occurring, for
example, one could write a routine \c{stillhere}, which is passed a
line number in \c{EAX} and outputs something like \c{line 155: still
here}. You could then write a macro:

\c %macro  notdeadyet 0
\c
\c         push    eax
\c         mov     eax,__?LINE?__
\c         call    stillhere
\c         pop     eax
\c
\c %endmacro

and then pepper your code with calls to \c{notdeadyet} until you
find the crash point.


\H{bitsm} \i\c{__?BITS?__}: Current Code Generation Mode

The \c{__?BITS?__} standard macro is updated every time that the BITS mode is
set using the \c{BITS XX} or \c{[BITS XX]} directive, where XX is a valid mode
number of 16, 32 or 64. \c{__?BITS?__} receives the specified mode number and
makes it globally available. This can be very useful for those who utilize
mode-dependent macros.

\H{ofmtm} \i\c{__?OUTPUT_FORMAT?__}: Current Output Format

The \c{__?OUTPUT_FORMAT?__} standard macro holds the current output
format name, as given by the \c{-f} option or NASM's default. Type
\c{nasm -h} for a list.

\c %ifidn __?OUTPUT_FORMAT?__, win32
\c  %define NEWLINE 13, 10
\c %elifidn __?OUTPUT_FORMAT?__, elf32
\c  %define NEWLINE 10
\c %endif

\H{dfmtm} \i\c{__?DEBUG_FORMAT?__}: Current Debug Format

If debugging information generation is enabled, The
\c{__?DEBUG_FORMAT?__} standard macro holds the current debug format
name as specified by the \c{-F} or \c{-g} option or the output format
default. Type \c{nasm -f} \e{output} \c{y} for a list.

\c{__?DEBUG_FORMAT?__} is not defined if debugging is not enabled, or if
the debug format specified is \c{null}.

\H{datetime} Assembly Date and Time Macros

NASM provides a variety of macros that represent the timestamp of the
assembly session.

\b The \i\c{__?DATE?__} and \i\c{__?TIME?__} macros give the assembly date and
time as strings, in ISO 8601 format (\c{"YYYY-MM-DD"} and \c{"HH:MM:SS"},
respectively.)

\b The \i\c{__?DATE_NUM?__} and \i\c{__?TIME_NUM?__} macros give the assembly
date and time in numeric form; in the format \c{YYYYMMDD} and
\c{HHMMSS} respectively.

\b The \i\c{__?UTC_DATE?__} and \i\c{__?UTC_TIME?__} macros give the assembly
date and time in universal time (UTC) as strings, in ISO 8601 format
(\c{"YYYY-MM-DD"} and \c{"HH:MM:SS"}, respectively.)  If the host
platform doesn't provide UTC time, these macros are undefined.

\b The \i\c{__?UTC_DATE_NUM?__} and \i\c{__?UTC_TIME_NUM?__} macros give the
assembly date and time universal time (UTC) in numeric form; in the
format \c{YYYYMMDD} and \c{HHMMSS} respectively.  If the
host platform doesn't provide UTC time, these macros are
undefined.

\b The \c{__?POSIX_TIME?__} 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.

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:

\c       __?DATE?__             "2010-01-01"
\c       __?TIME?__             "00:00:42"
\c       __?DATE_NUM?__         20100101
\c       __?TIME_NUM?__         000042
\c       __?UTC_DATE?__         "2009-12-31"
\c       __?UTC_TIME?__         "21:00:42"
\c       __?UTC_DATE_NUM?__     20091231
\c       __?UTC_TIME_NUM?__     210042
\c       __?POSIX_TIME?__       1262293242


\H{use_def} \I\c{__?USE_*?__}\c{__?USE_}\e{package}\c{?__}: Package
Include Test

When a standard macro package (see \k{macropkg}) is included with the
\c{%use} directive (see \k{use}), a single-line macro of the form
\c{__?USE_}\e{package}\c{?__} is automatically defined.  This allows
testing if a particular package is invoked or not.

For example, if the \c{altreg} package is included (see
\k{pkg_altreg}), then the macro \c{__?USE_ALTREG?__} is defined.


\H{pass_macro} \i\c{__?PASS?__}: Assembly Pass

The macro \c{__?PASS?__} is defined to be \c{1} on preparatory passes,
and \c{2} on the final pass.  In preprocess-only mode, it is set to
\c{3}, and when running only to generate dependencies (due to the
\c{-M} or \c{-MG} option, see \k{opt-M}) it is set to \c{0}.

\e{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.}


\H{strucs} \i{Structure Data Types}

\S{struc} \i\c{STRUC} and \i\c{ENDSTRUC}: \i{Declaring Structure} Data Types

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
\c{STRUC} and \c{ENDSTRUC} are used to define a structure data type.

\c{STRUC} 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 \c{_size} appended to it is defined as an \c{EQU} giving the
size of the structure. Once \c{STRUC} has been issued, you are
defining the structure, and should define fields using the \c{RESB}
family of pseudo-instructions, and then invoke \c{ENDSTRUC} to finish
the definition.

For example, to define a structure called \c{mytype} containing a
longword, a word, a byte and a string of bytes, you might code

\c struc   mytype
\c
\c   mt_long:      resd    1
\c   mt_word:      resw    1
\c   mt_byte:      resb    1
\c   mt_str:       resb    32
\c
\c endstruc

The above code defines six symbols: \c{mt_long} as 0 (the offset
from the beginning of a \c{mytype} structure to the longword field),
\c{mt_word} as 4, \c{mt_byte} as 6, \c{mt_str} as 7, \c{mytype_size}
as 39, and \c{mytype} itself as zero.

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:

\c struc mytype
\c
\c   .long:        resd    1
\c   .word:        resw    1
\c   .byte:        resb    1
\c   .str:         resb    32
\c
\c endstruc

This defines the offsets to the structure fields as \c{mytype.long},
\c{mytype.word}, \c{mytype.byte} and \c{mytype.str}.

NASM, since it has no \e{intrinsic} 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 \c{mov ax,[mystruc.mt_word]} is not valid.
\c{mt_word} is a constant just like any other constant, so the
correct syntax is \c{mov ax,[mystruc+mt_word]} or \c{mov
ax,[mystruc+mytype.word]}.

Sometimes you only have the address of the structure displaced by an
offset. For example, consider this standard stack frame setup:

\c push ebp
\c mov ebp, esp
\c sub esp, 40

In this case, you could access an element by subtracting the offset:

\c mov [ebp - 40 + mytype.word], ax

However, if you do not want to repeat this offset, you can use -40 as
a base offset:

\c struc mytype, -40

And access an element this way:

\c mov [ebp + mytype.word], ax


\S{istruc} \i\c{ISTRUC}, \i\c{AT} and \i\c{IEND}: Declaring
\i{Instances of Structures}

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 \c{ISTRUC}
mechanism. To declare a structure of type \c{mytype} in a program,
you code something like this:

\c mystruc:
\c     istruc mytype
\c
\c         at mt_long, dd      123456
\c         at mt_word, dw      1024
\c         at mt_byte, db      'x'
\c         at mt_str,  db      'hello, world', 13, 10, 0
\c
\c     iend

The function of the \c{AT} macro is to make use of the \c{TIMES}
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.

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 \c{AT} line. For example:

\c         at mt_str,  db      123,134,145,156,167,178,189
\c                     db      190,100,0

Depending on personal taste, you can also omit the code part of the
\c{AT} line completely, and start the structure field on the next
line:

\c         at mt_str
\c                 db      'hello, world'
\c                 db      13,10,0

\H{alignment} \i{Alignment} Control

\S{align} \i\c{ALIGN} and \i\c{ALIGNB}: Code and Data Alignment

The \c{ALIGN} and \c{ALIGNB} macros provides a convenient way to
align code or data on a word, longword, paragraph or other boundary.
(Some assemblers call this directive \i\c{EVEN}.) The syntax of the
\c{ALIGN} and \c{ALIGNB} macros is

\c         align   4               ; align on 4-byte boundary
\c         align   16              ; align on 16-byte boundary
\c         align   8,db 0          ; pad with 0s rather than NOPs
\c         align   4,resb 1        ; align to 4 in the BSS
\c         alignb  4               ; equivalent to previous line

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 \c{TIMES} prefix to their second argument to
perform the alignment.

If the second argument is not specified, the default for \c{ALIGN}
is \c{NOP}, and the default for \c{ALIGNB} is \c{RESB 1}. So if the
second argument is specified, the two macros are equivalent.
Normally, you can just use \c{ALIGN} in code and data sections and
\c{ALIGNB} in BSS sections, and never need the second argument
except for special purposes.

\c{ALIGN} and \c{ALIGNB}, 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.

\c{ALIGNB} (or \c{ALIGN} with a second argument of \c{RESB 1}) can
be used within structure definitions:

\c struc mytype2
\c
\c   mt_byte:
\c         resb 1
\c         alignb 2
\c   mt_word:
\c         resw 1
\c         alignb 4
\c   mt_long:
\c         resd 1
\c   mt_str:
\c         resb 32
\c
\c endstruc

This will ensure that the structure members are sensibly aligned
relative to the base of the structure.

A final caveat: \c{ALIGN} and \c{ALIGNB} work relative to the
beginning of the \e{section}, 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 \c{ALIGN} or \c{ALIGNB}.

Both \c{ALIGN} and \c{ALIGNB} do call \c{SECTALIGN} macro implicitly.
See \k{sectalign} for details.

See also the \c{smartalign} standard macro package, \k{pkg_smartalign}.


\S{sectalign} \i\c{SECTALIGN}: Section Alignment

The \c{SECTALIGN} macros provides a way to modify alignment attribute
of output file section. Unlike the \c{align=} attribute (which is allowed
at section definition only) the \c{SECTALIGN} macro may be used at any time.

For example the directive

\c SECTALIGN 16

sets the section alignment requirements to 16 bytes. Once increased it can
not be decreased, the magnitude may grow only.

Note that \c{ALIGN} (see \k{align}) calls the \c{SECTALIGN} macro implicitly
so the active section alignment requirements may be updated. This is by default
behaviour, if for some reason you want the \c{ALIGN} do not call \c{SECTALIGN}
at all use the directive

\c SECTALIGN OFF

It is still possible to turn in on again by

\c SECTALIGN ON

Note that \c{SECTALIGN <ON|OFF>} affects only the \c{ALIGN}/\c{ALIGNB} directives,
not an explicit \c{SECTALIGN} directive.