NASM-X is a set of macros for the Netwide Assembler, NASM, designed for portability, modularity, ease of use, and speed of development. Portability means that the complete macro-set can be used for both 32 and 64bit assembly with no change in syntax. Modularity implies NASM-X fully supports projects having multiple source files along with external linkage. Ease of use and speed of development are featured benefits of using NASM-X as the macros correctly handle all supported calling conventions, ensure proper stack alignment, and ensure proper structure layout and memory alignment.
NASM-X currently supports both 32 and 64-bit development on the following operating systems:
• Linux • FreeBSD • NetBSD • OpenBSD • Windows
1.2 License Conditions
Please see the file LICENSE, supplied as part of any NASM-X distribution archive, for the license conditions under which you may use NASM-X. NASM-X is now under the so-called 2-clause BSD license, also known as the simplified BSD license.
Copyright 2005-2014 the NASM-X Authors - All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISINGIN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OFSUCH DAMAGE.
1.3 Contact Information
The current version of NASM-X is maintained by a team of developers, accessible through the nasmx-devel mailing list (see below for the link).
NASM-X forums are currently located at http://www.nasm.us/. If it's not there, google for us!
New releases, release candidates, and daily development snapshots of NASM-X are available from http://www.sourceforge.net/.
1.4 Installation
1.4.1 Installing NASM-X under Windows
Once you've obtained the appropriate archive for NASM-X, nasmx-X.X.zip (where X.X denotes the version number of NASM-X contained in the archive), unpack it into its own directory (for example c:\nasmx).
The archive will contain a set of executable files: the NASM executable file nasm.exe, the NDISASM executable file ndisasm.exe, and additional utilities.
The files NASM-X needs to run are located in the nasm-X.X/bin directory. You may either copy these programs to a directory on your PATH, or alternatively, edit autoexec.bat to add the nasmx/bin directory to your PATH (to do that under Windows XP, go to Start > Control Panel > System > Advanced > Environment Variables; these instructions may work under other versions of Windows as well.)
You must also set the NASMENV environment variable to point to the install include directory, eg: NASMENV=-IC:\nasmx\nasmx-X.X\inc\
That's it - NASM-X is installed.
1.4.2 Installing NASM-X under Unix
Once you've obtained the Unix source archive for NASM-X, nasmx-X.X.tar.gz (where X.X denotes the version number of NASM-X contained in the archive), unpack it into a directory such as /usr/local/src. The archive, when unpacked, will create its own subdirectory nasmx-X.X.
NASM-X is not an auto-configuring package: once you've unpacked it, cd to the directory it's been unpackedinto and type ./setpaths.sh. This shell script will set up your environment so that you can use NASM-X. So that you don't have to source this file each time you open a new terminal you can simply add the NASMENV environment variable to your login profile. For example, when using the bash shell, add the line export NASMENV=-I/usr/local/src/nasmx-X.X/inc/ to your .bashrc file located in your home directory.
The NASM-X package for Linux does not come with any binaries. The demo programs require that the following programs already exist on your computer: nasm, gcc, make.
2.12: IMPORT: Importing Symbols from Other Modules
Description
This macro causes the external procedure name provided to be made available to your program to call.
Syntax
IMPORT [callconv,] proc_name [,param[,param,...]] where: callconv is the calling convention used if not the default. supported conventions: CDECL, FASTCALL, NAKED, PASCAL, STDCALL proc_name is the name of the procedure to import. param is the type and parameter name(s) of the procedure.
INVOKE [callconv,] proc_name [,param[,param,...]] where: callconv is the calling convention used if not the default. supported conventions: CDECL, FASTCALL, NAKED, PASCAL, STDCALL proc_name is the name of the procedure to call. param is the parameter type and value of the called procedure.
Notes
Fox Windows x64 programming:INVOKE will not normally spill register arguments to the stack prior to the call. If this behavior is desired due to calling a non-conformant function then you may use NASMX_PRAGMA INVOKE_FASTCALL_STACK_PRELOAD, ENABLE prior to INVOKE to enable this behavior and then disable the pragma after INVOKE.
This macro creates variable space for the procedure on the stack.
Syntax
LOCAL varname, type, qty where: varname is the name of the local variable. type is the type of the local variable being created. qty is the number of types needed ( default: 1 ).
This macro marks the beginning of procedure local variables. It must be the next immediate macro after PROC.
Syntax
LOCALS [NONE] where: NONE is an optional value indicating the procedure does not use local stack variables. Note that the macro ENDLOCALS is not required when LOCALS NONE is specified.
This macro allows the developer to specify certain options that affect how NASMX generates code.
Syntax
NASMX_PRAGMA directive,option [,options] where: directive provides instruction to NASMX options are optional values specified for the directive. directives: CALLSTACK, size ; Win64 minimum callstack size is 32 PACK, PUSH, align_val ; default is natural structure member alignment PACK, POP PROC_FASTCALL_STACK_PRELOAD, [ ENABLE | DISABLE ] ; default is enable
INVOKE_FASTCALL_STACK_PRELOAD, [ ENABLE | DISABLE ] ; default is disable
Note: The pragma INVOKE_FASTCALL_STACK_PRELOAD is applicable only for Windows 64-bit.
Example
Please see demos
See also:
Section 2.15: LOCALSSection 2.27: PROC
2.22: NASMX_RESERVE: Defining structure/union members
Description
This macro allows the developer to specify the structure member variable names and types.
Syntax
NASMX_RESERVE name, type, qty where: name provides the name of the structure member. type specifies the data type of the member. qty specifies how many types to reserve ( Default: 1 ).
This macro causes the named procedure to be defined.
Syntax
PROC [callconv,] proc_name [,param[,param,...]] where: callconv is the calling convention used if not the default. supported conventions: CDECL, FASTCALL, NAKED, PASCAL, STDCALL proc_name is the name of the procedure. param is the type and parameter name(s) of the procedure.
Notes
The stack frame is automatically created whenever you have defined either procedure parameters or local stack variables. Arguments are always located on the stack above the return address for both 32-bit and 64-bit. The 32-bit register EBP ( RBP in 64-bit ) is used as the frame pointer. Procedures that define parameter arguments will have the parameter names equated to offsets from the frame. Use the macro argv() to access the procedure arguments.
For the 64-bit fastcall calling convention:By default, during the procedure prologue, NASM-X will automatically save the registers used for the procedure parameters you define to the stack. To prevent NASM-X from saving register parameters to the stack you can place a NASMX_PRAGMA PROC_FASTCALL_STACK_PRELOAD, DISABLE at the beginning of your source file after including nasmx.incYou may enable or disable stack pre-loading at any time by using multiple NASMX_PRAGMA directives in your source file.
For Linux 64-bit mode:NASM-X will create a register argument spill area below the return address in a manner similar to local variables. Automatic register argument saving is enabled or disabled as indicated previously. The macro argv() will correctly provide the parameter offsets in this area.
Finally, if your procedure does not require automatic register saves or you will not access the register spill area then you may simply define a PROC without parameters. Doing so may eliminate the need to use register EBP/RBP to create the stack frame depending on whether local variable stack space is required or not thus freeing up that register for use. The exceptions are 1.) the program main entry point which, if defined, must establish the initial frame; and 2.) procedures that expect floating point arguments must be prototyped in order for INVOKE to assign the appropriate floating point registers.
Known Issues
• There is currently no support for passing parameter values larger than 64-bits. • For Linux 64-bit mode NASM-X currently does not support defining a PROC with more parameters
than the maximum registers defined for the x64 fastcall calling convention. The INVOKE macro, however, fully supports the calling convention.
This macro generates a global procedure name that can be imported by additional source modules.
Syntax
PROTO [callconv,] proc_name [,param[,param,...]] where: callconv is the calling convention used if not the default. supported conventions: CDECL, FASTCALL, NAKED, PASCAL, STDCALL proc_name is the name of the procedure. param is the type and parameter name(s) of the procedure.
This macro creates a procedure specific label to implement a looping block.
Syntax
REPEAT
Examples
Section E.3
See also:
Section 2.1: BREAKSection 2.31: UNTIL
2.30: RETURN: returning from a procedure
Description
This macro causes a jump to the procedure epilogue.
Syntax
RETURN [ val ] where val is the optional procedure return value
Examples
See demos/win32/demo2 for example usage.
Notes
At the end of your procedure you may simply mov eax, val as the last statement to be executed in order to optimize out the jump to the procedure epilogue.
See also:
Section 2.8: ENDPROCSection 2.27: PROC
2.31: UNTIL: loop condition
Description
Specifying a REPEAT block terminating condition.
Syntax
UNTIL reg,cc,val where:
reg is the register used for comparison cc is the condition to check val is the value to compare the register against
Examples
Section E.1Section E.2
See also:
Section 2.1: BREAKSection 2.29: REPEAT
2.32: USES: Saving registers to the stack
Description
This macro enables the developer to specific registers that must be saved during the procedure prologue. Saved registers are restored automatically by NASMX during ENDPROC. This macro, if used, must appear immediately following a PROC statement and immediate before the LOCALS statement
Syntax
USES reg [,reg [,reg...]]
Examples
Section E.3
See also:
Section 2.8: ENDPROCSection 2.27: PROC
2.33: WHILE: looping
Description
This macro creates a procedure specific label to implement a looping block.
Syntax
WHILE reg,cc,val where: reg is the register used for comparison cc is the condition to check val is the value to compare the register against
• Fixed INVOKE stack alignment bug • Enhanced INVOKE to save and restore register eax/rax when used in parameter arguments if
necessary • Optimized USES macro • Corrected x64 register parameter spill behavior • Corrected various Windows structure definitions • Added pragmas PROC_FASTCALL_STACK_PRELOAD and
INVOKE_FASTCALL_STACK_PRELOAD • Deprecated previous FASTCALL_STACK_PRELOAD pragma • Nasm v2.11 or greater now required due to preprocessor fixes • Updated Windows distribution "bin" directory with NASM v2.11.02 • Updated html docs and Windows Compiled Help Modules
A.1.2 NASM-X v1.3: 14 Feb 2014
• Refresh Win32 distribution "bin" directory with latest release version of Nasm: NASM v2.11, NDISASM v2.11
• New docs directory added. • Added NASM-X html document files • Windows Compiled Help Modules:
• Created NASM-X.CHM • Updated NASMDOC.CHM to Nasm 2.11
• Corrected structure alignment issue • Added defines to all win32 include files based on value of UNICODE • Added FASTCALL_STACK_PRELOAD pragma
When disabled the fastcall register arguments will no longer automatically spill into the register shadow space on the stack. It is enabled by default only on Win64 to remain backward compatible.
• Fixed issue when user specifies structure member name with _type appended.
A.1.3 NASM-X v1.2: 12 Jan 2013
• Added BSD x86 & x64 syscall support • Added BSD Demos 1-5 • Refresh Win32 distribution "bin" directory with latest release version of Nasm: NASM v2.10.07,
NDISASM v2.10.07 • Updated NASMDOC.CHM to Nasm 2.10.07 • Added Win32 Demo 15 - OpenGL Torus example • Added Win32 Demo 16 - GTK example program • Added Win32 Demo 17 - GDI floor program
• Added Win64 Demo 6 - GDI floor program • Added Linux64 Demo 5 - Xlib example • Added REPEAT, UNTIL, CONTINUE macros • Fixed BREAK macro bug • Fixed INVOKE macro bug for x64 Linux procs with more than 6 arguments
A.1.4 NASM-X v1.1: 29 Sep 2012
• Refresh Win32 distribution "bin" directory with latest release version of tool chain: NASM v2.10.05, NDISASM v2.10.05 GoLink v0.27.00
• Update NASMDOC.CHM Windows help file to include latest Nasm documentation changes. • Fixed SOCKET definition in winsock.inc
A.1.5 NASM-X v1.0: 20 Aug 2011
• Official release • Updated Win32 "bin" directory with latest release versions of nasm tools: NASM v2.09.10,
NDISASM v2.09.10 • Added convenience scripts for setting NASMENV • Added Linux x64 syscall support
A.1.6 Archived releases
• See CHANGES.TXT for more history
Appendix E: NASM-X Examples
These examples show how to use the NASMX macro system to create assembly programs. It is recommended that you read the examples in order starting with the first example. Each subsequent example builds upon the previous example.
Please note that, being examples, they are not optimized nor are errors checked for. They are, however, working examples that you can build from.Simply create a new working directory for each example and copy/paste the code into a new file within each directory.
Once you understand how these examples work you are ready to begin building the DEMOS for your system.The DEMOS directories contain additional working examples that show some of the more advanced features of NASMX.
For convenience we've provided a Makefile that you can use to build each example. Simply save the Makefile to your working directory then edit the first line containing NAME=MYDEMO substituting MYDEMO with the name of the file you saved the example as (without the filename extension).These Makefiles assume you're building 32-bit programs considering that the example code provided is also 32-bit.
message: declare(NASMX_TCHAR) NASMX_TEXT('The power of 2 to %u = %u'),13,10,0 errmsg: declare(NASMX_TCHAR) NASMX_TEXT('an error occurred!'),13,10,0
EX. 5 : Using structures
Description
This example shows how to define, create, and access structures. It makes use of two structures, POINT and RECT, which define a rectangle in a coordinate system where (0,0 ) represents the top-left most point. This type of coordinate system is used in many computer graphics systems. It defines a procedure to calculate the area of a rectangle.
Code:
%include 'nasmx.inc' NASMX_STRUC POINT NASMX_RESERVE x, uint32_t, 1 NASMX_RESERVE y, uint32_t, 1 NASMX_ENDSTRUC
NASMX_STRUC RECT NASMX_STRUC top_left, POINT NASMX_RESERVE x, uint32_t, 1 NASMX_RESERVE y, uint32_t, 1 NASMX_ENDSTRUC NASMX_STRUC bottom_right, POINT NASMX_RESERVE x, uint32_t, 1 NASMX_RESERVE y, uint32_t, 1 NASMX_ENDSTRUC NASMX_ENDSTRUC
PROC calc_area, ptrdiff_t rect USES ebx LOCALS LOCAL height, uint32_t, 1 LOCAL width, uint32_t, 1 ENDLOCALS ; get the pointer to the RECT structure mov ebx, ptrdiff_t [argv(.rect)]
