From: Jordan Justen <email@example.com>
Date: Sun, 29 Jan 2017 17:39:54 -0800
Subject: [PATCH] debian: debian/patches/02-nasm.man.patch
Note: I (Jordan) did not author this patch. I'm just adding it to git.
Signed-off-by: Jordan Justen <firstname.lastname@example.org>
nasm.man | 271 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 271 insertions(+)
create mode 100644 nasm.man
diff --git a/nasm.man b/nasm.man
new file mode 100644
@@ -0,0 +1,271 @@
+ nasm - the Netwide Assembler - portable 80x86 assembler
+ nnaassmm [ --ff format ] [ --oo outfile ] [ _o_p_t_i_o_n_s... ] infile
+ nnaassmm --hh
+ nnaassmm --rr
+ The nnaassmm command assembles the file _i_n_f_i_l_e and directs output to the
+ file _o_u_t_f_i_l_e if specified. If _o_u_t_f_i_l_e is not specified, nnaassmm will
+ derive a default output file name from the name of its input file, usu‐
+ ally 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’.
+ --hh Causes nnaassmm to exit immediately, after giving a summary of its
+ invocation options, and listing all its supported output file
+ --aa Causes nnaassmm to assemble the given input file without first
+ applying the macro preprocessor.
+ --ee Causes nnaassmm to preprocess the given input file, and write the
+ output to _s_t_d_o_u_t (or the specified output file name), and not
+ actually assemble anything.
+ --MM Causes nnaassmm to output Makefile‐style dependencies to stdout;
+ normal output is suppressed.
+ --EE _f_i_l_e_n_a_m_e
+ Causes nnaassmm to redirect error messages to _f_i_l_e_n_a_m_e. This option
+ exists to support operating systems on which stderr is not eas‐
+ ily redirected.
+ --rr Causes nnaassmm to exit immediately, after displaying its version
+ number. _(_o_b_s_o_l_e_t_e_)
+ --vv Causes nnaassmm to exit immediately, after displaying its version
+ --ff _f_o_r_m_a_t
+ Specifies the output file format. Formats include _b_i_n, to pro‐
+ duce flat‐form binary files, and _a_o_u_t and _e_l_f to produce Linux
+ a.out and ELF object files, respectively.
+ --oo _o_u_t_f_i_l_e
+ Specifies a precise name for the output file, overriding nnaassmm’s
+ default means of determining it.
+ --ll _l_i_s_t_f_i_l_e
+ 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.
+ --ss Causes nnaassmm to send its error messages and/or help text to _s_t_d_‐
+ _o_u_t instead of _s_t_d_e_r_r.
+ Causes nnaassmm to enable or disable certain classes of warning mes‐
+ sages, for example --ww++oorrpphhaann‐‐llaabbeellss or --ww‐‐mmaaccrroo‐‐ppaarraammss to,
+ respectively, enable warnings about labels alone on lines or
+ disable warnings about incorrect numbers of parameters in macro
+ --II _d_i_r_e_c_t_o_r_y
+ 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.
+ --ii _d_i_r_e_c_t_o_r_y
+ Same as the --II option.
+ --PP _f_i_l_e
+ Specifies a file to be pre‐included, before the main source file
+ starts to be processed.
+ --pp _f_i_l_e
+ Same as the --PP option.
+ --DD _m_a_c_r_o_[_=_v_a_l_u_e_]
+ Pre‐defines a single‐line macro.
+ --dd _m_a_c_r_o_[_=_v_a_l_u_e_]
+ Same as the --DD option.
+ --UU _m_a_c_r_o
+ Undefines a single‐line macro.
+ --uu _m_a_c_r_o
+ Same as the --UU option.
+ This man page does not fully describe the syntax of nnaassmm’s assembly
+ language, but does give a summary of the differences from other assem‐
+ _R_e_g_i_s_t_e_r_s have no leading ‘%’ sign, unlike ggaass, and floating‐point
+ stack registers are referred to as _s_t_0, _s_t_1, and so on.
+ _F_l_o_a_t_i_n_g_‐_p_o_i_n_t _i_n_s_t_r_u_c_t_i_o_n_s may use either the single‐operand form or
+ the double. A _T_O 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
+ _U_n_i_n_i_t_i_a_l_i_s_e_d _s_t_o_r_a_g_e is reserved using the _R_E_S_B, _R_E_S_W, _R_E_S_D, _R_E_S_Q and
+ _R_E_S_T pseudo‐opcodes, each taking one parameter which gives the number
+ of bytes, words, doublewords, quadwords or ten‐byte words to reserve.
+ _R_e_p_e_t_i_t_i_o_n of data items is not done by the _D_U_P keyword as seen in DOS
+ assemblers, but by the use of the _T_I_M_E_S 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.
+ _S_y_m_b_o_l _r_e_f_e_r_e_n_c_e_s 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 _c_o_n_t_e_n_t_s of memory locations. The syntaxes
+ mov ax,es:wordvar[bx]
+ es mov ax,wordvar
+ 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
+ _L_O_D_S_B which can’t be overridden any other way.
+ _C_o_n_s_t_a_n_t_s 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 _’_a_b_c_d_’ denotes 0x64636261 and not
+ _L_o_c_a_l _l_a_b_e_l_s 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’.
+ _S_E_C_T_I_O_N _n_a_m_e or _S_E_G_M_E_N_T _n_a_m_e causes nnaassmm to direct all following code
+ to the named section. Section names vary with output file format,
+ although most formats support the names _._t_e_x_t, _._d_a_t_a and _._b_s_s. (The
+ exception is the _o_b_j format, in which all segments are user‐definable.)
+ _A_B_S_O_L_U_T_E _a_d_d_r_e_s_s causes nnaassmm to position its notional assembly point at
+ an absolute address: so no code or data may be generated, but you can
+ use _R_E_S_B, _R_E_S_W and _R_E_S_D to move the assembly point further on, and you
+ can define labels. So this directive may be used to define data struc‐
+ tures. When you have finished doing absolute assembly, you must issue
+ another _S_E_C_T_I_O_N directive to return to normal assembly.
+ _B_I_T_S _1_6 or _B_I_T_S _3_2 switches the default processor mode for which nnaassmm
+ is generating code: it is equivalent to _U_S_E_1_6 or _U_S_E_3_2 in DOS assem‐
+ _E_X_T_E_R_N _s_y_m_b_o_l and _G_L_O_B_A_L _s_y_m_b_o_l import and export symbol definitions,
+ respectively, from and to other modules. Note that the _G_L_O_B_A_L directive
+ must appear before the definition of the symbol it refers to.
+ _S_T_R_U_C _s_t_r_u_c_n_a_m_e and _E_N_D_S_T_R_U_C, when used to bracket a number of _R_E_S_B,
+ _R_E_S_W 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 ___s_i_z_e tacked on to the end.
+ FFOORRMMAATT‐‐SSPPEECCIIFFIICC DDIIRREECCTTIIVVEESS
+ _O_R_G _a_d_d_r_e_s_s is used by the _b_i_n flat‐form binary output format, and
+ specifies the address at which the output code will eventually be
+ _G_R_O_U_P _g_r_p_n_a_m_e _s_e_g_1 _s_e_g_2_._._. is used by the _o_b_j (Microsoft 16‐bit) out‐
+ put format, and defines segment groups. This format also uses
+ _U_P_P_E_R_C_A_S_E, which directs that all segment, group and symbol names out‐
+ put to the object file should be in uppercase. Note that the actual
+ assembly is still case sensitive.
+ _L_I_B_R_A_R_Y _l_i_b_n_a_m_e is used by the _r_d_f output format, and causes a depen‐
+ dency record to be written to the output file which indicates that the
+ program requires a certain library in order to run.
+ MMAACCRROO PPRREEPPRROOCCEESSSSOORR
+ Single‐line macros are defined using the _%_d_e_f_i_n_e or _%_i_d_e_f_i_n_e 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 tak‐
+ ing parameters, and vice versa. _%_d_e_f_i_n_e defines macros whose names
+ match case‐sensitively, whereas _%_i_d_e_f_i_n_e defines case‐insensitive
+ Multi‐line macros are defined using _%_m_a_c_r_o and _%_i_m_a_c_r_o (the distinction
+ is the same as that between _%_d_e_f_i_n_e and _%_i_d_e_f_i_n_e), whose syntax is as
+ %macro _n_a_m_e _m_i_n_p_r_m[‐_m_a_x_p_r_m][+][.nolist] [_d_e_f_a_u_l_t_s]
+ <some lines of macro expansion text>
+ Again, these macros may be overloaded. The trailing plus sign indicates
+ that any parameters after the last one get subsumed, with their sepa‐
+ rating commas, into the last parameter. The _d_e_f_a_u_l_t_s part can be used
+ to specify defaults for unspecified macro parameters after _m_i_n_p_a_r_a_m.
+ _%_e_n_d_m is a valid synonym for _%_e_n_d_m_a_c_r_o.
+ 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 con‐
+ tain 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 _%_i_n_c_l_u_d_e 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 _%_p_u_s_h, remove one using _%_p_o_p, and change the
+ name of the top context (without disturbing any associated definitions)
+ using _%_r_e_p_l. Labels and _%_d_e_f_i_n_e 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 _%_i_f_d_e_f, _%_i_f_n_d_e_f, _%_e_l_s_e and
+ _%_e_n_d_i_f as in C. (Except that _%_i_f_d_e_f can accept several putative macro
+ names, and will evaluate TRUE if any of them is defined.) In addition,
+ the directives _%_i_f_c_t_x and _%_i_f_n_c_t_x can be used to condition on the name
+ of the top context on the context stack. The obvious set of ‘else‐if’
+ directives, _%_e_l_i_f_d_e_f, _%_e_l_i_f_n_d_e_f, _%_e_l_i_f_c_t_x and _%_e_l_i_f_n_c_t_x are also sup‐
+ There is a reported seg‐fault on some (Linux) systems with some large
+ source files. This appears to be very hard to reproduce. All other
+ _k_n_o_w_n bugs have been fixed...
+ There is no support for listing files, symbol maps, or debugging
+ object‐file records. The advanced features of the ELF and Win32 object
+ file formats are not supported, and there is no means for warning the
+ programmer against using an instruction beyond the capability of the
+ target processor.
+ aass(11), lldd(11).
+ The Netwide Assembler Project NASM(1)