From 5f9f4007ff01fe9faf0fd86db02cc243f77a0529 Mon Sep 17 00:00:00 2001 From: "H. Peter Anvin" Date: Thu, 19 Jun 2008 16:58:05 -0700 Subject: [PATCH] doc: framework for documenting standard macro packages Add a framework for documenting the standard macro packages. Also move the standard macros to the end of the preprocessor section, instead of having them in the middle of the directives list. --- doc/nasmdoc.src | 389 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 218 insertions(+), 171 deletions(-) diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src index 7a0c5a5..05b62ca 100644 --- a/doc/nasmdoc.src +++ b/doc/nasmdoc.src @@ -3048,6 +3048,22 @@ This first resolves the location of the file into the macro \c{dep}, then adds it to the dependency lists, and finally issues the assembler-level \c{INCBIN} directive. + +\S{use} \i\c{%use}: Include Standard Macro Package + +The \c{%use} directive is similar to \c{%include}, 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 \k{macropkg}. + +Unlike the \c{%include} directive, package names for the \c{%use} +directive do not require quotes, but quotes are permitted; using +quotes will prevent unwanted macro expansion. Thus, the following +lines are equivalent, unless \c{altreg} is defined as a macro: + +\c %use altreg +\c %use 'altreg' + \H{ctxstack} The \i{Context Stack} Having labels that are local to a macro definition is sometimes not @@ -3236,6 +3252,184 @@ one describing the outer \c{if}; thus \c{else} and \c{endif} always refer to the last unmatched \c{if} or \c{else}. +\H{stackrel} \i{Stack Relative Preprocessor Directives} + +The following preprocessor directives provide a way to use +labels to refer to local variables allocated on the stack. + +\b\c{%arg} (see \k{arg}) + +\b\c{%stacksize} (see \k{stacksize}) + +\b\c{%local} (see \k{local}) + + +\S{arg} \i\c{%arg} Directive + +The \c{%arg} 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. + +While NASM has macros which attempt to duplicate this +functionality (see \k{16cmacro}), the syntax is not particularly +convenient to use. and is not TASM compatible. Here is an example +which shows the use of \c{%arg} without any external macros: + +\c some_function: +\c +\c %push mycontext ; save the current context +\c %stacksize large ; tell NASM to use bp +\c %arg i:word, j_ptr:word +\c +\c mov ax,[i] +\c mov bx,[j_ptr] +\c add ax,[bx] +\c ret +\c +\c %pop ; restore original context + +This is similar to the procedure defined in \k{16cmacro} and adds +the value in i to the value pointed to by j_ptr and returns the +sum in the ax register. See \k{pushpop} for an explanation of +\c{push} and \c{pop} and the use of context stacks. + + +\S{stacksize} \i\c{%stacksize} Directive + +The \c{%stacksize} directive is used in conjunction with the +\c{%arg} (see \k{arg}) and the \c{%local} (see \k{local}) directives. +It tells NASM the default size to use for subsequent \c{%arg} and +\c{%local} directives. The \c{%stacksize} directive takes one +required argument which is one of \c{flat}, \c{flat64}, \c{large} or \c{small}. + +\c %stacksize flat + +This form causes NASM to use stack-based parameter addressing +relative to \c{ebp} and it assumes that a near form of call was used +to get to this label (i.e. that \c{eip} is on the stack). + +\c %stacksize flat64 + +This form causes NASM to use stack-based parameter addressing +relative to \c{rbp} and it assumes that a near form of call was used +to get to this label (i.e. that \c{rip} is on the stack). + +\c %stacksize large + +This form uses \c{bp} to do stack-based parameter addressing and +assumes that a far form of call was used to get to this address +(i.e. that \c{ip} and \c{cs} are on the stack). + +\c %stacksize small + +This form also uses \c{bp} to address stack parameters, but it is +different from \c{large} because it also assumes that the old value +of bp is pushed onto the stack (i.e. it expects an \c{ENTER} +instruction). In other words, it expects that \c{bp}, \c{ip} and +\c{cs} are on the top of the stack, underneath any local space which +may have been allocated by \c{ENTER}. This form is probably most +useful when used in combination with the \c{%local} directive +(see \k{local}). + + +\S{local} \i\c{%local} Directive + +The \c{%local} 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 +\c{%local} directive is most useful when used with the \c{%stacksize} +(see \k{stacksize} and is also compatible with the \c{%arg} directive +(see \k{arg}). It allows simplified reference to variables on the +stack which have been allocated typically by using the \c{ENTER} +instruction. +\# (see \k{insENTER} for a description of that instruction). +An example of its use is the following: + +\c silly_swap: +\c +\c %push mycontext ; save the current context +\c %stacksize small ; tell NASM to use bp +\c %assign %$localsize 0 ; see text for explanation +\c %local old_ax:word, old_dx:word +\c +\c enter %$localsize,0 ; see text for explanation +\c mov [old_ax],ax ; swap ax & bx +\c mov [old_dx],dx ; and swap dx & cx +\c mov ax,bx +\c mov dx,cx +\c mov bx,[old_ax] +\c mov cx,[old_dx] +\c leave ; restore old bp +\c ret ; +\c +\c %pop ; restore original context + +The \c{%$localsize} variable is used internally by the +\c{%local} directive and \e{must} be defined within the +current context before the \c{%local} directive may be used. +Failure to do so will result in one expression syntax error for +each \c{%local} variable declared. It then may be used in +the construction of an appropriately sized ENTER instruction +as shown in the example. + +\H{otherpreproc} \i{Other Preprocessor Directives} + +NASM also has preprocessor directives which allow access to +information from external sources. Currently they include: + +The following preprocessor directive is supported to allow NASM to +correctly handle output of the cpp C language preprocessor. + +\b\c{%line} enables NAsM to correctly handle the output of the cpp +C language preprocessor (see \k{line}). + +\b\c{%!} enables NASM to read in the value of an environment variable, +which can then be used in your program (see \k{getenv}). + +\S{line} \i\c{%line} Directive + +The \c{%line} 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 \c{%line} +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. + +This preprocessor directive is not generally of use to programmers, +by may be of interest to preprocessor authors. The usage of the +\c{%line} preprocessor directive is as follows: + +\c %line nnn[+mmm] [filename] + +In this directive, \c{nnn} identifies the line of the original source +file which this line corresponds to. \c{mmm} is an optional parameter +which specifies a line increment value; each line of the input file +read in is considered to correspond to \c{mmm} lines of the original +source file. Finally, \c{filename} is an optional parameter which +specifies the file name of the original source file. + +After reading a \c{%line} preprocessor directive, NASM will report +all file name and line numbers relative to the values specified +therein. + + +\S{getenv} \i\c{%!}\c{}: Read an environment variable. + +The \c{%!} 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. + +For example, suppose that you have an environment variable \c{FOO}, and +you want the contents of \c{FOO} to be embedded in your program. You +could do that as follows: + +\c %defstr FOO %!FOO + +See \k{defstr} for notes on the \c{%defstr} directive. + + \H{stdmac} \i{Standard Macros} NASM defines a set of standard macros, which are already defined @@ -3554,182 +3748,35 @@ check that the section's alignment characteristics are sensible for the use of \c{ALIGN} or \c{ALIGNB}. -\H{stackrel} \i{Stack Relative Preprocessor Directives} - -The following preprocessor directives provide a way to use -labels to refer to local variables allocated on the stack. - -\b\c{%arg} (see \k{arg}) +\C{macropkg} \i{Standard Macro Packages} -\b\c{%stacksize} (see \k{stacksize}) +The \i\c{%use} directive (see \k{use}) includes one of the standard +macro packages included with the NASM distribution and compiled into +the NASM binary. It operates like the \c{%include} directive (see +\k{include}), but the included contents is provided by NASM itself. -\b\c{%local} (see \k{local}) +The names of standard macro packages are case insensitive, and can be +quoted or not. -\S{arg} \i\c{%arg} Directive +\H{pkg_altreg} \i\c{altreg}: \i{Alternate Register Names} -The \c{%arg} 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. +The \c{altreg} standard macro package provides alternate register +names. It provides numeric register names for all registers (not just +\c{R8}-\c{R15}), the Intel-defined aliases \c{R8L}-\c{R15L} for the +low bytes of register (as opposed to the NASM/AMD standard names +\c{R8B}-\c{R15B}), and the names \c{R0H}-\c{R3H} (by analogy with +\c{R0L}-\c{R3L}) for \c{AH}, \c{CH}, \c{DH}, and \c{BH}. -While NASM has macros which attempt to duplicate this -functionality (see \k{16cmacro}), the syntax is not particularly -convenient to use. and is not TASM compatible. Here is an example -which shows the use of \c{%arg} without any external macros: +Example use: -\c some_function: -\c -\c %push mycontext ; save the current context -\c %stacksize large ; tell NASM to use bp -\c %arg i:word, j_ptr:word -\c -\c mov ax,[i] -\c mov bx,[j_ptr] -\c add ax,[bx] -\c ret +\c %use altreg \c -\c %pop ; restore original context - -This is similar to the procedure defined in \k{16cmacro} and adds -the value in i to the value pointed to by j_ptr and returns the -sum in the ax register. See \k{pushpop} for an explanation of -\c{push} and \c{pop} and the use of context stacks. - - -\S{stacksize} \i\c{%stacksize} Directive - -The \c{%stacksize} directive is used in conjunction with the -\c{%arg} (see \k{arg}) and the \c{%local} (see \k{local}) directives. -It tells NASM the default size to use for subsequent \c{%arg} and -\c{%local} directives. The \c{%stacksize} directive takes one -required argument which is one of \c{flat}, \c{flat64}, \c{large} or \c{small}. - -\c %stacksize flat - -This form causes NASM to use stack-based parameter addressing -relative to \c{ebp} and it assumes that a near form of call was used -to get to this label (i.e. that \c{eip} is on the stack). - -\c %stacksize flat64 - -This form causes NASM to use stack-based parameter addressing -relative to \c{rbp} and it assumes that a near form of call was used -to get to this label (i.e. that \c{rip} is on the stack). - -\c %stacksize large - -This form uses \c{bp} to do stack-based parameter addressing and -assumes that a far form of call was used to get to this address -(i.e. that \c{ip} and \c{cs} are on the stack). - -\c %stacksize small - -This form also uses \c{bp} to address stack parameters, but it is -different from \c{large} because it also assumes that the old value -of bp is pushed onto the stack (i.e. it expects an \c{ENTER} -instruction). In other words, it expects that \c{bp}, \c{ip} and -\c{cs} are on the top of the stack, underneath any local space which -may have been allocated by \c{ENTER}. This form is probably most -useful when used in combination with the \c{%local} directive -(see \k{local}). - - -\S{local} \i\c{%local} Directive +\c proc: +\c mov r0l,r3h ; mov al,bh +\c ret -The \c{%local} 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 -\c{%local} directive is most useful when used with the \c{%stacksize} -(see \k{stacksize} and is also compatible with the \c{%arg} directive -(see \k{arg}). It allows simplified reference to variables on the -stack which have been allocated typically by using the \c{ENTER} -instruction. -\# (see \k{insENTER} for a description of that instruction). -An example of its use is the following: - -\c silly_swap: -\c -\c %push mycontext ; save the current context -\c %stacksize small ; tell NASM to use bp -\c %assign %$localsize 0 ; see text for explanation -\c %local old_ax:word, old_dx:word -\c -\c enter %$localsize,0 ; see text for explanation -\c mov [old_ax],ax ; swap ax & bx -\c mov [old_dx],dx ; and swap dx & cx -\c mov ax,bx -\c mov dx,cx -\c mov bx,[old_ax] -\c mov cx,[old_dx] -\c leave ; restore old bp -\c ret ; -\c -\c %pop ; restore original context - -The \c{%$localsize} variable is used internally by the -\c{%local} directive and \e{must} be defined within the -current context before the \c{%local} directive may be used. -Failure to do so will result in one expression syntax error for -each \c{%local} variable declared. It then may be used in -the construction of an appropriately sized ENTER instruction -as shown in the example. - -\H{otherpreproc} \i{Other Preprocessor Directives} - -NASM also has preprocessor directives which allow access to -information from external sources. Currently they include: - -The following preprocessor directive is supported to allow NASM to -correctly handle output of the cpp C language preprocessor. - -\b\c{%line} enables NAsM to correctly handle the output of the cpp -C language preprocessor (see \k{line}). - -\b\c{%!} enables NASM to read in the value of an environment variable, -which can then be used in your program (see \k{getenv}). - -\S{line} \i\c{%line} Directive - -The \c{%line} 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 \c{%line} -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. - -This preprocessor directive is not generally of use to programmers, -by may be of interest to preprocessor authors. The usage of the -\c{%line} preprocessor directive is as follows: - -\c %line nnn[+mmm] [filename] - -In this directive, \c{nnn} identifies the line of the original source -file which this line corresponds to. \c{mmm} is an optional parameter -which specifies a line increment value; each line of the input file -read in is considered to correspond to \c{mmm} lines of the original -source file. Finally, \c{filename} is an optional parameter which -specifies the file name of the original source file. - -After reading a \c{%line} preprocessor directive, NASM will report -all file name and line numbers relative to the values specified -therein. - - -\S{getenv} \i\c{%!}\c{}: Read an environment variable. - -The \c{%!} 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. - -For example, suppose that you have an environment variable \c{FOO}, and -you want the contents of \c{FOO} to be embedded in your program. You -could do that as follows: - -\c %defstr FOO %!FOO - -See \k{defstr} for notes on the \c{%defstr} directive. +See also \k{reg64}. \C{directive} \i{Assembler Directives} @@ -6980,7 +7027,7 @@ loading a value into a 32-bit register (but not an 8- or 16-bit register), the upper 32 bits of the corresponding 64-bit register are set to zero. -\H{reg64} Register names in 64-bit mode +\H{reg64} Register Names in 64-bit Mode NASM uses the following names for general-purpose registers in 64-bit mode, for 8-, 16-, 32- and 64-bit references, respecitively: @@ -6995,10 +7042,10 @@ assemblers. The Intel documentation, however, uses the names \c{R8L-R15L} for 8-bit references to the higher registers. It is possible to use those names by definiting them as macros; similarly, if one wants to use numeric names for the low 8 registers, define them -as macros. See the file \i\c{altreg.inc} in the \c{misc} directory of -the NASM source distribution. +as macros. The standard macro package \c{altreg} (see \k{pkg_altreg}) +can be used for this purpose. -\H{id64} Immediates and displacements in 64-bit mode +\H{id64} Immediates and Displacements in 64-bit Mode In 64-bit mode, immediates and displacements are generally only 32 bits wide. NASM will therefore truncate most displacements and -- 2.7.4