mirror of
https://github.com/netwide-assembler/nasm.git
synced 2025-04-12 18:40:23 +08:00
man: Generate manpages from asciidoc format
The asciidoc format is a way more easier to read by a human. Signed-off-by: Cyrill Gorcunov <gorcunov@gmail.com>
This commit is contained in:
Cyrill Gorcunov
parent
a709e767f6
commit
1a63699ce5
10
Makefile.in
10
Makefile.in
@ -31,6 +31,8 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
|
||||
INSTALL_DATA = @INSTALL_DATA@
|
||||
|
||||
NROFF = @NROFF@
|
||||
ASCIIDOC = @ASCIIDOC@
|
||||
XMLTO = @XMLTO@
|
||||
|
||||
MKDIR = mkdir
|
||||
RM = rm
|
||||
@ -47,7 +49,7 @@ ifeq ($(TRACE),1)
|
||||
CFLAGS += -DNASM_TRACE
|
||||
endif
|
||||
|
||||
.SUFFIXES: .c .i .s .$(O) .1 .man
|
||||
.SUFFIXES: .c .i .s .$(O) .1 .txt
|
||||
|
||||
.PHONY: all doc rdf install clean distclean cleaner spotless install_rdf test
|
||||
.PHONY: install_doc everything install_everything strip perlreq dist tags TAGS
|
||||
@ -61,8 +63,10 @@ endif
|
||||
.c.i:
|
||||
$(CC) -E $(ALL_CFLAGS) -o $@ $<
|
||||
|
||||
.1.man:
|
||||
$(NROFF) -man $< > $@
|
||||
.txt.1:
|
||||
$(ASCIIDOC) -b docbook -d manpage -o $(patsubst %.1,%.xml,$@) $<
|
||||
$(XMLTO) man --skip-validation $(patsubst %.1,%.xml,$@) 2>/dev/null
|
||||
|
||||
|
||||
#-- Begin File Lists --#
|
||||
NASM = nasm.$(O) nasmlib.$(O) ver.$(O) \
|
||||
|
||||
@ -68,6 +68,8 @@ PA_ADD_CFLAGS([-pedantic])
|
||||
|
||||
dnl Look for programs...
|
||||
AC_CHECK_PROGS(NROFF, nroff, echo)
|
||||
AC_CHECK_PROGS(ASCIIDOC, asciidoc, echo)
|
||||
AC_CHECK_PROGS(XMLTO, xmlto, echo)
|
||||
AC_CHECK_PROGS(ACRODIST, acrodist, false)
|
||||
AC_CHECK_PROGS(PS2PDF, ps2pdf, false)
|
||||
AC_CHECK_PROGS(PSTOPDF, pstopdf, false)
|
||||
|
||||
535
nasm.1
535
nasm.1
@ -1,535 +0,0 @@
|
||||
.TH NASM 1 "The Netwide Assembler Project"
|
||||
.SH NAME
|
||||
nasm \- the Netwide Assembler, a portable 80x86 assembler
|
||||
.SH SYNOPSIS
|
||||
.B nasm
|
||||
[
|
||||
.B \-@
|
||||
response file
|
||||
] [
|
||||
.B \-f
|
||||
format
|
||||
] [
|
||||
.B \-o
|
||||
outfile
|
||||
] [
|
||||
.B \-l
|
||||
listfile
|
||||
] [
|
||||
.IR options ...
|
||||
] filename
|
||||
.br
|
||||
.B nasm \-h
|
||||
.br
|
||||
.B nasm \-v
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B nasm
|
||||
command assembles the file
|
||||
.I filename
|
||||
and directs output to the file
|
||||
.I outfile
|
||||
if specified. If
|
||||
.I outfile
|
||||
is not specified,
|
||||
.B nasm
|
||||
will derive a default output file name from the name of its input
|
||||
file, usually by appending `.o' or `.obj', or by removing all
|
||||
extensions for a raw binary file. Failing that, the output file name
|
||||
will be `nasm.out'.
|
||||
.SS OPTIONS
|
||||
.TP
|
||||
.BI \-@ " filename"
|
||||
Causes
|
||||
.B nasm
|
||||
to process options from
|
||||
.I filename
|
||||
as if they were included on the command line.
|
||||
.TP
|
||||
.B \-a
|
||||
Causes
|
||||
.B nasm
|
||||
to assemble the given input file without first applying the macro
|
||||
preprocessor.
|
||||
.TP
|
||||
.BI \-D " macro[=value]"
|
||||
Pre-defines a single-line macro.
|
||||
.TP
|
||||
.BI \-d " macro[=value]"
|
||||
Same as the
|
||||
.B \-D
|
||||
option.
|
||||
.TP
|
||||
.B \-e
|
||||
Causes
|
||||
.B nasm
|
||||
to preprocess the given input file, and write the output to
|
||||
.I stdout
|
||||
(or the specified output file name), and not actually assemble
|
||||
anything.
|
||||
.TP
|
||||
.BI \-f " format"
|
||||
Specifies the output file format. To see a list of valid output
|
||||
formats, use the
|
||||
.B -hf
|
||||
option.
|
||||
.TP
|
||||
.B \-g
|
||||
Causes
|
||||
.B nasm
|
||||
to generate debug information in selected format
|
||||
.TP
|
||||
.B \-h
|
||||
Causes
|
||||
.B nasm
|
||||
to exit immediately, after giving a summary of its invocation
|
||||
options.
|
||||
.TP
|
||||
.B \-hf
|
||||
Same as
|
||||
.B -h
|
||||
, but also lists all valid output formats.
|
||||
.TP
|
||||
.BI \-I " directory"
|
||||
Adds a directory to the search path for include files. The directory
|
||||
specification must include the trailing slash, as it will be
|
||||
directly prepended to the name of the include file.
|
||||
.TP
|
||||
.BI \-i " directory"
|
||||
Same as the
|
||||
.B \-I
|
||||
option.
|
||||
.TP
|
||||
.BI \-l " listfile"
|
||||
Causes an assembly listing to be directed to the given file, in
|
||||
which the original source is displayed on the right hand side (plus
|
||||
the source for included files and the expansions of multi-line
|
||||
macros) and the generated code is shown in hex on the left.
|
||||
.TP
|
||||
.B \-M
|
||||
Causes
|
||||
.B nasm
|
||||
to output Makefile-style dependencies to stdout; normal output is
|
||||
suppressed.
|
||||
.TP
|
||||
.BI \-MG " file"
|
||||
Same as
|
||||
.B \-M
|
||||
but assumes that missing Makefile dependecies are generated and added
|
||||
to dependency list without a prefix.
|
||||
.TP
|
||||
.BI \-MF " file"
|
||||
Output Makefile-style dependencies to the specified file.
|
||||
.TP
|
||||
.BI \-MD " file"
|
||||
Same as a combination of
|
||||
.B \-M
|
||||
and
|
||||
.B \-MF
|
||||
options.
|
||||
.TP
|
||||
.BI \-MT " file"
|
||||
Override the default name of the dependency target
|
||||
dependency target name. This is normally the same
|
||||
as the output filename, specified by the
|
||||
.B \-o
|
||||
option.
|
||||
.TP
|
||||
.BI \-MQ " file"
|
||||
The same as
|
||||
.B \-MT
|
||||
except it tries to quote characters that have special
|
||||
meaning in Makefile syntax. This is not foolproof,
|
||||
as not all characters with special meaning are quotable
|
||||
in Make.
|
||||
.TP
|
||||
.BI \-MP
|
||||
Emit phony target
|
||||
.TP
|
||||
.BI \-O " number"
|
||||
Optimize branch offsets.
|
||||
.ti
|
||||
.B \-O0
|
||||
:No optimization
|
||||
.ti
|
||||
.B \-O1
|
||||
:Minimal optimization
|
||||
.ti
|
||||
.B \-Ox
|
||||
:Multipass optimization (default)
|
||||
.TP
|
||||
.BI \-o " outfile"
|
||||
Specifies a precise name for the output file, overriding
|
||||
.BR nasm 's
|
||||
default means of determining it.
|
||||
.TP
|
||||
.BI \-P " file"
|
||||
Specifies a file to be pre-included, before the main source file
|
||||
starts to be processed.
|
||||
.TP
|
||||
.BI \-p " file"
|
||||
Same as the
|
||||
.B \-P
|
||||
option.
|
||||
.TP
|
||||
.BI \-r
|
||||
Causes
|
||||
.B nasm
|
||||
to exit immediately, after displaying its version number.
|
||||
.I (obsolete)
|
||||
.TP
|
||||
.B \-s
|
||||
Causes
|
||||
.B nasm
|
||||
to send its error messages and/or help text to
|
||||
.I stdout
|
||||
instead of
|
||||
.IR stderr .
|
||||
.TP
|
||||
.B \-t
|
||||
Causes
|
||||
.B nasm
|
||||
to assemble in SciTech TASM compatible mode
|
||||
.TP
|
||||
.BI \-U " macro"
|
||||
Undefines a single-line macro.
|
||||
.TP
|
||||
.BI \-u " macro"
|
||||
Same as the
|
||||
.B \-U
|
||||
option.
|
||||
.TP
|
||||
.BI \-v
|
||||
Causes
|
||||
.B nasm
|
||||
to exit immediately, after displaying its version number.
|
||||
.TP
|
||||
.BI \-w [+-]foo
|
||||
Causes
|
||||
.B nasm
|
||||
to enable or disable certain classes of warning messages, for
|
||||
example
|
||||
.B \-w+orphan-labels
|
||||
or
|
||||
.B \-w-macro-params
|
||||
.TP
|
||||
.BI \-X " format"
|
||||
specifies error reporting format (gnu or vc).
|
||||
.TP
|
||||
.BI \-Z " filename"
|
||||
Causes
|
||||
.B nasm
|
||||
to redirect error messages to
|
||||
.IR filename .
|
||||
This option exists to support operating systems on which stderr is not
|
||||
easily redirected.
|
||||
.TP
|
||||
.BI \-\-prefix
|
||||
.TP
|
||||
.BI \-\-postfix
|
||||
Prepend or append (respectively) the given argument to all
|
||||
global or extern variables.
|
||||
.PP
|
||||
.RE
|
||||
.SS SYNTAX
|
||||
This man page does not fully describe the syntax of
|
||||
.BR nasm 's
|
||||
assembly language, but does give a summary of the differences from
|
||||
other assemblers.
|
||||
.PP
|
||||
.I Registers
|
||||
have no leading `%' sign, unlike
|
||||
.BR gas ,
|
||||
and floating-point stack registers are referred to as
|
||||
.IR st0 ,
|
||||
.IR st1 ,
|
||||
and so on.
|
||||
.PP
|
||||
.I Floating-point instructions
|
||||
may use either the single-operand form or the double. A
|
||||
.I TO
|
||||
keyword is provided; thus, one could either write
|
||||
.PP
|
||||
.ti +15n
|
||||
fadd st0,st1
|
||||
.br
|
||||
.ti +15n
|
||||
fadd st1,st0
|
||||
.PP
|
||||
or one could use the alternative single-operand forms
|
||||
.PP
|
||||
.ti +15n
|
||||
fadd st1
|
||||
.br
|
||||
.ti +15n
|
||||
fadd to st1
|
||||
.PP
|
||||
.I Uninitialised storage
|
||||
is reserved using the
|
||||
.IR RESB ,
|
||||
.IR RESW ,
|
||||
.IR RESD ,
|
||||
.IR RESQ ,
|
||||
.I REST
|
||||
and
|
||||
.I RESO
|
||||
pseudo-opcodes, each taking one parameter which gives the number of
|
||||
bytes, words, doublewords, quadwords or ten-byte words to reserve.
|
||||
.PP
|
||||
.I Repetition
|
||||
of data items is not done by the
|
||||
.I DUP
|
||||
keyword as seen in DOS assemblers, but by the use of the
|
||||
.I TIMES
|
||||
prefix, like this:
|
||||
.PP
|
||||
.ti +6n
|
||||
.ta 9n
|
||||
message: times 3 db 'abc'
|
||||
.br
|
||||
.ti +15n
|
||||
times 64-$+message db 0
|
||||
.PP
|
||||
which defines the string `abcabcabc', followed by the right number
|
||||
of zero bytes to make the total length up to 64 bytes.
|
||||
.PP
|
||||
.I Symbol references
|
||||
are always understood to be immediate (i.e. the address of the
|
||||
symbol), unless square brackets are used, in which case the contents
|
||||
of the memory location are used. Thus:
|
||||
.PP
|
||||
.ti +15n
|
||||
mov ax,wordvar
|
||||
.PP
|
||||
loads AX with the address of the variable `wordvar', whereas
|
||||
.PP
|
||||
.ti +15n
|
||||
mov ax,[wordvar]
|
||||
.br
|
||||
.ti +15n
|
||||
mov ax,[wordvar+1]
|
||||
.br
|
||||
.ti +15n
|
||||
mov ax,[es:wordvar+bx]
|
||||
.PP
|
||||
all refer to the
|
||||
.I contents
|
||||
of memory locations. The syntaxes
|
||||
.PP
|
||||
.ti +15n
|
||||
mov ax,es:wordvar[bx]
|
||||
.br
|
||||
.ti +15n
|
||||
es mov ax,wordvar[1]
|
||||
.PP
|
||||
are not legal at all, although the use of a segment register name as
|
||||
an instruction prefix is valid, and can be used with instructions
|
||||
such as
|
||||
.I LODSB
|
||||
which can't be overridden any other way.
|
||||
.PP
|
||||
.I Constants
|
||||
may be expressed numerically in most formats: a trailing H, Q or B
|
||||
denotes hex, octal or binary respectively, and a leading `0x' or `$'
|
||||
denotes hex as well. Leading zeros are not treated specially at all.
|
||||
Character constants may be enclosed in single or double quotes;
|
||||
there is no escape character. The ordering is little-endian
|
||||
(reversed), so that the character constant
|
||||
.I 'abcd'
|
||||
denotes 0x64636261 and not 0x61626364.
|
||||
.PP
|
||||
.I Local labels
|
||||
begin with a period, and their `locality' is granted by the
|
||||
assembler prepending the name of the previous non-local symbol. Thus
|
||||
declaring a label `.loop' after a label `label' has actually defined
|
||||
a symbol called `label.loop'.
|
||||
.SS DIRECTIVES
|
||||
.I SECTION name
|
||||
or
|
||||
.I SEGMENT name
|
||||
causes
|
||||
.B nasm
|
||||
to direct all following code to the named section. Section names
|
||||
vary with output file format, although most formats support the
|
||||
names
|
||||
.IR .text ,
|
||||
.I .data
|
||||
and
|
||||
.IR .bss .
|
||||
(The exception is the
|
||||
.I obj
|
||||
format, in which all segments are user-definable.)
|
||||
.PP
|
||||
.I ABSOLUTE address
|
||||
causes
|
||||
.B nasm
|
||||
to position its notional assembly point at an absolute address: so
|
||||
no code or data may be generated, but you can use
|
||||
.IR RESB ,
|
||||
.I RESW
|
||||
and
|
||||
.I RESD
|
||||
to move the assembly point further on, and you can define labels. So
|
||||
this directive may be used to define data structures. When you have
|
||||
finished doing absolute assembly, you must issue another
|
||||
.I SECTION
|
||||
directive to return to normal assembly.
|
||||
.PP
|
||||
.I BITS 16,
|
||||
.I BITS 32
|
||||
or
|
||||
.I BITS 64
|
||||
switches the default processor mode for which
|
||||
.B nasm
|
||||
is generating code: it is equivalent to
|
||||
.I USE16
|
||||
or
|
||||
.I USE32
|
||||
in DOS assemblers.
|
||||
.PP
|
||||
.I EXTERN symbol
|
||||
and
|
||||
.I GLOBAL symbol
|
||||
import and export symbol definitions, respectively, from and to
|
||||
other modules. Note that the
|
||||
.I GLOBAL
|
||||
directive must appear before the definition of the symbol it refers
|
||||
to.
|
||||
.PP
|
||||
.I STRUC strucname
|
||||
and
|
||||
.IR ENDSTRUC ,
|
||||
when used to bracket a number of
|
||||
.IR RESB ,
|
||||
.I RESW
|
||||
or similar instructions, define a data structure. In addition to
|
||||
defining the offsets of the structure members, the construct also
|
||||
defines a symbol for the size of the structure, which is simply the
|
||||
structure name with
|
||||
.I _size
|
||||
tacked on to the end.
|
||||
.SS FORMAT-SPECIFIC DIRECTIVES
|
||||
.I ORG address
|
||||
is used by the
|
||||
.I bin
|
||||
flat-form binary output format, and specifies the address at which
|
||||
the output code will eventually be loaded.
|
||||
.PP
|
||||
.I GROUP grpname seg1 seg2...
|
||||
is used by the
|
||||
.I obj
|
||||
(Microsoft 16-bit) output format, and defines segment groups. This
|
||||
format also uses
|
||||
.IR UPPERCASE ,
|
||||
which directs that all segment, group and symbol names output to the
|
||||
object file should be in uppercase. Note that the actual assembly is
|
||||
still case sensitive.
|
||||
.PP
|
||||
.I LIBRARY libname
|
||||
is used by the
|
||||
.I rdf
|
||||
output format, and causes a dependency record to be written to the
|
||||
output file which indicates that the program requires a certain
|
||||
library in order to run.
|
||||
.SS MACRO PREPROCESSOR
|
||||
Single-line macros are defined using the
|
||||
.I %define
|
||||
or
|
||||
.I %idefine
|
||||
commands, in a similar fashion to the C preprocessor. They can be
|
||||
overloaded with respect to number of parameters, although defining a
|
||||
macro with no parameters prevents the definition of any macro with
|
||||
the same name taking parameters, and vice versa.
|
||||
.I %define
|
||||
defines macros whose names match case-sensitively, whereas
|
||||
.I %idefine
|
||||
defines case-insensitive macros.
|
||||
.PP
|
||||
Multi-line macros are defined using
|
||||
.I %macro
|
||||
and
|
||||
.I %imacro
|
||||
(the distinction is the same as that between
|
||||
.I %define
|
||||
and
|
||||
.IR %idefine ),
|
||||
whose syntax is as follows:
|
||||
.PP
|
||||
.ti +6n
|
||||
%macro
|
||||
.I name
|
||||
.IR minprm [- maxprm "][+][.nolist] [" defaults ]
|
||||
.br
|
||||
.ti +15n
|
||||
<some lines of macro expansion text>
|
||||
.br
|
||||
.ti +6n
|
||||
%endmacro
|
||||
.PP
|
||||
Again, these macros may be overloaded. The trailing plus sign
|
||||
indicates that any parameters after the last one get subsumed, with
|
||||
their separating commas, into the last parameter. The
|
||||
.I defaults
|
||||
part can be used to specify defaults for unspecified macro
|
||||
parameters after
|
||||
.IR minparam .
|
||||
.I %endm
|
||||
is a valid synonym for
|
||||
.IR %endmacro .
|
||||
.PP
|
||||
To refer to the macro parameters within a macro expansion, you use
|
||||
.IR %1 ,
|
||||
.I %2
|
||||
and so on. You can also enforce that a macro parameter should
|
||||
contain a condition code by using
|
||||
.IR %+1 ,
|
||||
and you can invert the condition code by using
|
||||
.IR %-1 .
|
||||
You can also define a label specific to a macro invocation by
|
||||
prefixing it with a double % sign.
|
||||
.PP
|
||||
Files can be included using the
|
||||
.I %include
|
||||
directive, which works like C.
|
||||
.PP
|
||||
The preprocessor has a `context stack', which may be used by one
|
||||
macro to store information that a later one will retrieve. You can
|
||||
push a context on the stack using
|
||||
.IR %push ,
|
||||
remove one using
|
||||
.IR %pop ,
|
||||
and change the name of the top context (without disturbing any
|
||||
associated definitions) using
|
||||
.IR %repl .
|
||||
Labels and
|
||||
.I %define
|
||||
macros specific to the top context may be defined by prefixing their
|
||||
names with %$, and things specific to the next context down with
|
||||
%$$, and so on.
|
||||
.PP
|
||||
Conditional assembly is done by means of
|
||||
.IR %ifdef ,
|
||||
.IR %ifndef ,
|
||||
.I %else
|
||||
and
|
||||
.I %endif
|
||||
as in C. (Except that
|
||||
.I %ifdef
|
||||
can accept several putative macro names, and will evaluate TRUE if
|
||||
any of them is defined.) In addition, the directives
|
||||
.I %ifctx
|
||||
and
|
||||
.I %ifnctx
|
||||
can be used to condition on the name of the top context on the
|
||||
context stack. The obvious set of `else-if' directives,
|
||||
.IR %elifdef ,
|
||||
.IR %elifndef ,
|
||||
.IR %elifctx
|
||||
and
|
||||
.IR %elifnctx
|
||||
are also supported.
|
||||
.SH BUGS
|
||||
Please report bugs through the bug tracker function at http://nasm.sourceforge.org.
|
||||
.SH SEE ALSO
|
||||
.BR as "(" 1 "),"
|
||||
.BR ld "(" 1 ")."
|
||||
292
nasm.txt
Normal file
292
nasm.txt
Normal file
@ -0,0 +1,292 @@
|
||||
nasm(1)
|
||||
=======
|
||||
:doctype: manpage
|
||||
:man source: NASM
|
||||
:man manual: The Netwide Assembler Project
|
||||
|
||||
NAME
|
||||
----
|
||||
nasm - the Netwide Assembler, a portable 80x86 assembler
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
*nasm* [*-@* response file] [*-f* format] [*-o* outfile] [*-l* listfile] ['options'...] filename
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
The *nasm* command assembles the file 'filename' and directs output to the file
|
||||
'outfile' if specified. If 'outfile' is not specified, *nasm* will derive a default
|
||||
output file name from the name of its input file, usually by appending `.o' or
|
||||
`.obj', or by removing all extensions for a raw binary file. Failing that, the
|
||||
output file name will be `nasm.out'.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
*-@* 'filename'::
|
||||
Causes *nasm* to process options from filename as if they were included on
|
||||
the command line.
|
||||
|
||||
*-a*::
|
||||
Causes *nasm* to assemble the given input file without first applying the
|
||||
macro preprocessor.
|
||||
|
||||
*-D*|*-d* 'macro[=value]'::
|
||||
Pre-defines a single-line macro.
|
||||
|
||||
*-e*::
|
||||
Causes *nasm* to preprocess the given input file, and write the output to
|
||||
'stdout' (or the specified output file name), and not actually assemble
|
||||
anything.
|
||||
|
||||
*-f* 'format'::
|
||||
Specifies the output file format. To see a list of valid output formats,
|
||||
use the *-hf* option.
|
||||
|
||||
*-g*::
|
||||
Causes *nasm* to generate debug information in selected format
|
||||
|
||||
*-h*::
|
||||
Causes *nasm* to exit immediately, after giving a summary of its
|
||||
invocation options.
|
||||
|
||||
*-hf*::
|
||||
Same as *-h* , but also lists all valid output formats.
|
||||
|
||||
*-I*|*-i* 'directory'::
|
||||
Adds a directory to the search path for include files. The directory
|
||||
specification must include the trailing slash, as it will be directly
|
||||
prepended to the name of the include file.
|
||||
|
||||
*-l* 'listfile'::
|
||||
Causes an assembly listing to be directed to the given file, in which
|
||||
the original source is displayed on the right hand side (plus the source
|
||||
for included files and the expansions of multi-line macros) and the
|
||||
generated code is shown in hex on the left.
|
||||
|
||||
*-M*::
|
||||
Causes *nasm* to output Makefile-style dependencies to stdout; normal
|
||||
output is suppressed.
|
||||
|
||||
*-MG* 'file'::
|
||||
Same as *-M* but assumes that missing Makefile dependecies are generated
|
||||
and added to dependency list without a prefix.
|
||||
|
||||
*-MF* 'file'::
|
||||
Output Makefile-style dependencies to the specified file.
|
||||
|
||||
*-MD* 'file'::
|
||||
Same as a combination of *-M* and *-MF* options.
|
||||
|
||||
*-MT* 'file'::
|
||||
Override the default name of the dependency target dependency target name.
|
||||
This is normally the same as the output filename, specified by
|
||||
the *-o* option.
|
||||
|
||||
*-MQ* 'file'::
|
||||
The same as *-MT* except it tries to quote characters that have special
|
||||
meaning in Makefile syntax. This is not foolproof, as not all characters
|
||||
with special meaning are quotable in Make.
|
||||
|
||||
*-MP*::
|
||||
Emit phony target.
|
||||
|
||||
*-O* 'number'::
|
||||
Optimize branch offsets.
|
||||
* *-O0*: No optimization
|
||||
* *-O1*: Minimal optimization
|
||||
* *-Ox*: Multipass optimization (default)
|
||||
|
||||
*-o* 'outfile'::
|
||||
Specifies a precise name for the output file, overriding *nasm*'s default
|
||||
means of determining it.
|
||||
|
||||
*-P*|*-p* 'file'::
|
||||
Specifies a file to be pre-included, before the main source file
|
||||
starts to be processed.
|
||||
|
||||
*-s*::
|
||||
Causes *nasm* to send its error messages and/or help text to stdout
|
||||
instead of stderr.
|
||||
|
||||
*-t*::
|
||||
Causes *nasm* to assemble in SciTech TASM compatible mode.
|
||||
|
||||
*-U*|*-u* 'macro'::
|
||||
Undefines a single-line macro.
|
||||
|
||||
*-v*::
|
||||
Causes *nasm* to exit immediately, after displaying its version number.
|
||||
|
||||
*-w*'[+-]foo'::
|
||||
Causes *nasm* to enable or disable certain classes of warning messages,
|
||||
for example *-w+orphan-labels* or *-w-macro-params*.
|
||||
|
||||
*-X* 'format'::
|
||||
Specifies error reporting format (gnu or vc).
|
||||
|
||||
*-Z* 'filename'::
|
||||
Causes *nasm* to redirect error messages to 'filename'. This option exists
|
||||
to support operating systems on which stderr is not easily redirected.
|
||||
|
||||
--prefix::
|
||||
--postfix::
|
||||
Prepend or append (respectively) the given argument to all global or
|
||||
extern variables.
|
||||
|
||||
SYNTAX
|
||||
------
|
||||
This man page does not fully describe the syntax of *nasm*'s assembly language,
|
||||
but does give a summary of the differences from other assemblers.
|
||||
|
||||
'Registers' have no leading `%' sign, unlike *gas*, and floating-point stack
|
||||
registers are referred to as 'st0', 'st1', and so on.
|
||||
|
||||
'Floating-point instructions' may use either the single-operand form or the
|
||||
double. A 'TO' keyword is provided; thus, one could either write
|
||||
|
||||
fadd st0,st1
|
||||
fadd st1,st0
|
||||
|
||||
or one could use the alternative single-operand forms
|
||||
|
||||
fadd st1
|
||||
fadd to st1
|
||||
|
||||
'Uninitialised storage' is reserved using the 'RESB', 'RESW', 'RESD', 'RESQ',
|
||||
'REST' and 'RESO' pseudo-opcodes, each taking one parameter which gives the
|
||||
number of bytes, words, doublewords, quadwords or ten-byte words to reserve.
|
||||
|
||||
'Repetition' of data items is not done by the 'DUP' keyword as seen in DOS
|
||||
assemblers, but by the use of the 'TIMES' prefix, like this:
|
||||
|
||||
message: times 3 db 'abc'
|
||||
times 64-$+message db 0
|
||||
|
||||
which defines the string `abcabcabc`, followed by the right number of zero
|
||||
bytes to make the total length up to 64 bytes.
|
||||
|
||||
'Symbol references' are always understood to be immediate (i.e. the address
|
||||
of the symbol), unless square brackets are used, in which case the contents
|
||||
of the memory location are used. Thus:
|
||||
|
||||
mov ax,wordvar
|
||||
|
||||
loads AX with the address of the variable `wordvar`, whereas
|
||||
|
||||
mov ax,[wordvar]
|
||||
mov ax,[wordvar+1]
|
||||
mov ax,[es:wordvar+bx]
|
||||
|
||||
all refer to the 'contents' of memory locations. The syntaxes
|
||||
|
||||
mov ax,es:wordvar[bx]
|
||||
es mov ax,wordvar[1]
|
||||
|
||||
are not legal at all, although the use of a segment register name as an instruction
|
||||
prefix is valid, and can be used with instructions such as 'LODSB' which can't
|
||||
be overridden any other way.
|
||||
|
||||
'Constants' may be expressed numerically in most formats: a trailing H, Q or
|
||||
B denotes hex, octal or binary respectively, and a leading `0x' or `$' denotes
|
||||
hex as well. Leading zeros are not treated specially at all. Character constants
|
||||
may be enclosed in single or double quotes; there is no escape character. The
|
||||
ordering is little-endian (reversed), so that the character constant ''abcd''
|
||||
denotes 0x64636261 and not 0x61626364.
|
||||
|
||||
Local labels begin with a period, and their `locality' is granted by the assembler
|
||||
prepending the name of the previous non-local symbol. Thus declaring a label
|
||||
`.loop' after a label `label' has actually defined a symbol called `label.loop'.
|
||||
|
||||
DIRECTIVES
|
||||
----------
|
||||
'SECTION' 'name' or 'SEGMENT' 'name' causes *nasm* to direct all following code
|
||||
to the named section. Section names vary with output file format, although most
|
||||
formats support the names '.text', '.data' and '.bss'. (The exception is the
|
||||
'obj' format, in which all segments are user-definable.)
|
||||
|
||||
'ABSOLUTE' 'address' causes *nasm* to position its notional assembly point at
|
||||
an absolute address: so no code or data may be generated, but you can use 'RESB',
|
||||
'RESW' and 'RESD' to move the assembly point further on, and you can define labels.
|
||||
So this directive may be used to define data structures. When you have finished
|
||||
doing absolute assembly, you must issue another 'SECTION' directive to return to
|
||||
normal assembly.
|
||||
|
||||
'BITS' '16', 'BITS' '32' or 'BITS' '64' switches the default processor mode for
|
||||
which *nasm* is generating code: it is equivalent to 'USE16' or 'USE32' in DOS
|
||||
assemblers.
|
||||
|
||||
'EXTERN' 'symbol' and 'GLOBAL' 'symbol' import and export symbol definitions,
|
||||
respectively, from and to other modules. Note that the 'GLOBAL' directive must
|
||||
appear before the definition of the symbol it refers to.
|
||||
|
||||
'STRUC' 'strucname' and 'ENDSTRUC', when used to bracket a number of 'RESB',
|
||||
'RESW' or similar instructions, define a data structure. In addition to
|
||||
defining the offsets of the structure members, the construct also defines a symbol
|
||||
for the size of the structure, which is simply the structure name with 'size'
|
||||
tacked on to the end.
|
||||
|
||||
FORMAT-SPECIFIC DIRECTIVES
|
||||
--------------------------
|
||||
'ORG' 'address' is used by the 'bin' flat-form binary output format, and
|
||||
specifies the address at which the output code will eventually be loaded.
|
||||
|
||||
'GROUP' 'grpname' 'seg1' 'seg2'... is used by the obj (Microsoft 16-bit)
|
||||
output format, and defines segment groups. This format also uses 'UPPERCASE',
|
||||
which directs that all segment, group and symbol names output to the object
|
||||
file should be in uppercase. Note that the actual assembly is still case
|
||||
sensitive.
|
||||
|
||||
'LIBRARY' 'libname' is used by the 'rdf' output format, and causes a
|
||||
dependency record to be written to the output file which indicates that
|
||||
the program requires a certain library in order to run.
|
||||
|
||||
MACRO PREPROCESSOR
|
||||
------------------
|
||||
Single-line macros are defined using the '%define' or '%idefine' commands, in
|
||||
a similar fashion to the C preprocessor. They can be overloaded with respect
|
||||
to number of parameters, although defining a macro with no parameters prevents
|
||||
the definition of any macro with the same name taking parameters, and vice versa.
|
||||
'%define' defines macros whose names match case-sensitively, whereas '%idefine'
|
||||
defines case-insensitive macros.
|
||||
|
||||
Multi-line macros are defined using '%macro' and '%imacro' (the distinction is the
|
||||
same as that between '%define' and '%idefine'), whose syntax is as follows
|
||||
|
||||
%macro name minprm[-maxprm][+][.nolist] [defaults]
|
||||
<some lines of macro expansion text>
|
||||
%endmacro
|
||||
|
||||
Again, these macros may be overloaded. The trailing plus sign indicates that
|
||||
any parameters after the last one get subsumed, with their separating commas,
|
||||
into the last parameter. The 'defaults' part can be used to specify defaults for
|
||||
unspecified macro parameters after 'minparam'. '%endm' is a valid synonym for
|
||||
'%endmacro'.
|
||||
|
||||
To refer to the macro parameters within a macro expansion, you use '%1', '%2' and
|
||||
so on. You can also enforce that a macro parameter should contain a condition
|
||||
code by using '%+1', and you can invert the condition code by using '%-1'. You can also
|
||||
define a label specific to a macro invocation by prefixing it with a double `%' sign.
|
||||
|
||||
Files can be included using the '%include' directive, which works like C.
|
||||
|
||||
The preprocessor has a `context stack', which may be used by one macro to store
|
||||
information that a later one will retrieve. You can push a context on the stack
|
||||
using '%push', remove one using '%pop', and change the name of the top context (without
|
||||
disturbing any associated definitions) using '%repl'. Labels and '%define' macros
|
||||
specific to the top context may be defined by prefixing their names with %$,
|
||||
and things specific to the next context down with %$$, and so on.
|
||||
|
||||
Conditional assembly is done by means of '%ifdef', '%ifndef', '%else' and '%endif'
|
||||
as in C. (Except that '%ifdef' can accept several putative macro names, and
|
||||
will evaluate TRUE if any of them is defined.) In addition, the directives
|
||||
'%ifctx' and '%ifnctx' can be used to condition on the name of the top context
|
||||
on the context stack. The obvious set of `else-if' directives, '%elifdef',
|
||||
'%elifndef', '%elifctx' and '%elifnctx' are also supported.
|
||||
|
||||
BUGS
|
||||
----
|
||||
Please report bugs through the bug tracker function at http://nasm.us.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
*as*(1), *ld*(1).
|
||||
129
ndisasm.1
129
ndisasm.1
@ -1,129 +0,0 @@
|
||||
.\"
|
||||
.\" This file is part of NASM and is released under the NASM License.
|
||||
.\"
|
||||
.TH NDISASM 1 "The Netwide Assembler Project"
|
||||
.SH NAME
|
||||
ndisasm \- the Netwide Disassembler, an 80x86 binary file disassembler
|
||||
.SH SYNOPSIS
|
||||
.B ndisasm
|
||||
[
|
||||
.B \-o
|
||||
origin
|
||||
] [
|
||||
.B \-s
|
||||
sync-point [...]]
|
||||
[
|
||||
.B \-a
|
||||
|
|
||||
.B \-i
|
||||
] [
|
||||
.B \-b
|
||||
bits
|
||||
] [
|
||||
.B -u
|
||||
] [
|
||||
.B \-e
|
||||
hdrlen
|
||||
] [
|
||||
.B \-k
|
||||
offset,length [...]]
|
||||
infile
|
||||
.br
|
||||
.B ndisasm \-h
|
||||
.br
|
||||
.B ndisasm \-r
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B ndisasm
|
||||
command generates a disassembly listing of the binary file
|
||||
.I infile
|
||||
and directs it to stdout.
|
||||
.SS OPTIONS
|
||||
.TP
|
||||
.B \-h
|
||||
Causes
|
||||
.B ndisasm
|
||||
to exit immediately, after giving a summary of its invocation
|
||||
options.
|
||||
.TP
|
||||
.BI \-r
|
||||
Causes
|
||||
.B ndisasm
|
||||
to exit immediately, after displaying its version number.
|
||||
.TP
|
||||
.BI \-o " origin"
|
||||
Specifies the notional load address for the file. This option causes
|
||||
.B ndisasm
|
||||
to get the addresses it lists down the left hand margin, and the
|
||||
target addresses of PC-relative jumps and calls, right.
|
||||
.TP
|
||||
.BI \-s " sync-point"
|
||||
Manually specifies a synchronisation address, such that
|
||||
.B ndisasm
|
||||
will not output any machine instruction which encompasses bytes on
|
||||
both sides of the address. Hence the instruction which
|
||||
.I starts
|
||||
at that address will be correctly disassembled.
|
||||
.TP
|
||||
.BI \-e " hdrlen"
|
||||
Specifies a number of bytes to discard from the beginning of the
|
||||
file before starting disassembly. This does not count towards the
|
||||
calculation of the disassembly offset: the first
|
||||
.I disassembled
|
||||
instruction will be shown starting at the given load address.
|
||||
.TP
|
||||
.BI \-k " offset,length"
|
||||
Specifies that
|
||||
.I length
|
||||
bytes, starting from disassembly offset
|
||||
.IR offset ,
|
||||
should be skipped over without generating any output. The skipped
|
||||
bytes still count towards the calculation of the disassembly offset.
|
||||
.TP
|
||||
.BR \-a " or " \-i
|
||||
Enables automatic (or intelligent) sync mode, in which
|
||||
.B ndisasm
|
||||
will attempt to guess where synchronisation should be performed, by
|
||||
means of examining the target addresses of the relative jumps and
|
||||
calls it disassembles.
|
||||
.TP
|
||||
.BI \-b " bits"
|
||||
Specifies 16-, 32- or 64-bit mode. The default is 16-bit mode.
|
||||
.TP
|
||||
.B \-u
|
||||
Specifies 32-bit mode, more compactly than using `-b 32'.
|
||||
.TP
|
||||
.BI \-p " vendor"
|
||||
Prefers instructions as defined by
|
||||
.I vendor
|
||||
in case of a conflict. Known
|
||||
.I vendor
|
||||
names include
|
||||
.BR intel ,
|
||||
.BR amd ,
|
||||
.BR cyrix ,
|
||||
and
|
||||
.BR idt .
|
||||
The default is
|
||||
.BR intel .
|
||||
.PP
|
||||
.RE
|
||||
.SH RESTRICTIONS
|
||||
.B ndisasm
|
||||
only disassembles binary files: it has no understanding of the
|
||||
header information present in object or executable files. If you
|
||||
want to disassemble an object file, you should probably be using
|
||||
.BR objdump "(" 1 ")."
|
||||
.PP
|
||||
Auto-sync mode won't necessarily cure all your synchronisation
|
||||
problems: a sync marker can only be placed automatically if a jump
|
||||
or call instruction is found to refer to it
|
||||
.I before
|
||||
.B ndisasm
|
||||
actually disassembles that part of the code. Also, if spurious jumps
|
||||
or calls result from disassembling non-machine-code data, sync
|
||||
markers may get placed in strange places. Feel free to turn
|
||||
auto-sync off and go back to doing it manually if necessary.
|
||||
.PP
|
||||
.SH SEE ALSO
|
||||
.BR objdump "(" 1 ")."
|
||||
94
ndisasm.txt
Normal file
94
ndisasm.txt
Normal file
@ -0,0 +1,94 @@
|
||||
ndisasm(1)
|
||||
==========
|
||||
:doctype: manpage
|
||||
:man source: NASM
|
||||
:man manual: The Netwide Assembler Project
|
||||
|
||||
NAME
|
||||
----
|
||||
ndisasm - the Netwide Disassembler, an 80x86 binary file disassembler
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
*ndisasm* [ *-o* origin ] [ *-s* sync-point [...]] [ *-a* | *-i* ]
|
||||
[ *-b* bits ] [ *-u* ] [ *-e* hdrlen ]
|
||||
[ *-k* offset,length [...]] infile
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
The *ndisasm* command generates a disassembly listing of the binary file
|
||||
infile and directs it to stdout.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
-h::
|
||||
Causes *ndisasm* to exit immediately, after giving a summary
|
||||
of its invocation options.
|
||||
|
||||
-r::
|
||||
Causes *ndisasm* to exit immediately, after displaying its
|
||||
version number.
|
||||
|
||||
-o 'origin'::
|
||||
Specifies the notional load address for the file. This
|
||||
option causes *ndisasm* to get the addresses it lists
|
||||
down the left hand margin, and the target addresses
|
||||
of PC-relative jumps and calls, right.
|
||||
|
||||
-s 'sync-point'::
|
||||
Manually specifies a synchronisation address, such that
|
||||
*ndisasm* will not output any machine instruction which
|
||||
encompasses bytes on both sides of the address. Hence
|
||||
the instruction which starts at that address will be
|
||||
correctly disassembled.
|
||||
|
||||
-e 'hdrlen'::
|
||||
Specifies a number of bytes to discard from the beginning
|
||||
of the file before starting disassembly. This does not
|
||||
count towards the calculation of the disassembly offset:
|
||||
the first 'disassembled' instruction will be shown starting
|
||||
at the given load address.
|
||||
|
||||
-k 'offset,length'::
|
||||
Specifies that 'length' bytes, starting from disassembly
|
||||
offset 'offset', should be skipped over without generating
|
||||
any output. The skipped bytes still count towards the
|
||||
calculation of the disassembly offset.
|
||||
|
||||
-a|-i::
|
||||
Enables automatic (or intelligent) sync mode, in which
|
||||
*ndisasm* will attempt to guess where synchronisation should
|
||||
be performed, by means of examining the target addresses
|
||||
of the relative jumps and calls it disassembles.
|
||||
|
||||
-b 'bits'::
|
||||
Specifies 16-, 32- or 64-bit mode. The default is 16-bit
|
||||
mode.
|
||||
|
||||
-u::
|
||||
Specifies 32-bit mode, more compactly than using `-b 32'.
|
||||
|
||||
-p 'vendor'::
|
||||
Prefers instructions as defined by 'vendor' in case of
|
||||
a conflict. Known 'vendor' names include *intel*, *amd*,
|
||||
*cyrix*, and *idt*. The default is *intel*.
|
||||
|
||||
RESTRICTIONS
|
||||
------------
|
||||
*ndisasm* only disassembles binary files: it has no understanding of
|
||||
the header information present in object or executable files.
|
||||
If you want to disassemble an object file, you should probably
|
||||
be using *objdump*(1).
|
||||
|
||||
Auto-sync mode won't necessarily cure all your synchronisation
|
||||
problems: a sync marker can only be placed automatically if a
|
||||
jump or call instruction is found to refer to it 'before'
|
||||
*ndisasm* actually disassembles that part of the code. Also,
|
||||
if spurious jumps or calls result from disassembling
|
||||
non-machine-code data, sync markers may get placed in strange
|
||||
places. Feel free to turn auto-sync off and go back to doing
|
||||
it manually if necessary.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
*objdump*(1)
|
||||
Loading…
x
Reference in New Issue
Block a user