From: Jordan Justen 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 --- 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 index 0000000..35c92f6 --- /dev/null +++ b/nasm.man @@ -0,0 +1,271 @@ +NASM(1) NASM(1) + + + +NNAAMMEE + nasm - the Netwide Assembler - portable 80x86 assembler + +SSYYNNOOPPSSIISS + nnaassmm [ --ff format ] [ --oo outfile ] [ _o_p_t_i_o_n_s... ] infile + nnaassmm --hh + nnaassmm --rr + +DDEESSCCRRIIPPTTIIOONN + 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’. + + OOPPTTIIOONNSS + --hh Causes nnaassmm to exit immediately, after giving a summary of its + invocation options, and listing all its supported output file + formats. + + --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 + number. + + --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. + + --ww_[_+_‐_]_f_o_o + 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 + calls. + + --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. + + + SSYYNNTTAAXX + 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‐ + blers. + + _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[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 + _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 + 0x61626364. + + _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’. + + DDIIRREECCTTIIVVEESS + _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‐ + blers. + + _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 + loaded. + + _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 + macros. + + 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 + follows: + + %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] + + %endmacro + + 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‐ + ported. + +BBUUGGSS + 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... + +RREESSTTRRIICCTTIIOONNSS + 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. + +SSEEEE AALLSSOO + aass(11), lldd(11). + + + + The Netwide Assembler Project NASM(1)