`nasm -f elf myfile.asm`: Basic use. Generates a elf file called `myfile.o`
-Common formats:
+Common `-f` formats:
- `bin` (default)
- `elf32` (for x86)
- `elf64` (for x86-64)
- `-l myfile.lst`: Generate a listing. Example listing line below
14 00000000 B801000000 mov rax, 1 ; 1 = 'write' syscall`
- A B C D E
- \ address machine code Assembly Comment in .asm
- ---Line number
+ L# address machine code assembly comment in .asm
- `-w+float`, `-w-float`: disable or enable a class of warning
- `-i/usr/share/include`: Add a search path for the `%include` directive
+`
### Chapter 3: The NASM language
The basic format of a NASM line is
-`label: instruction operands ; comment`
+
+ label: instruction operands ; comment
+
NASM lines are designed to be assembled pretty much independently. For example, the exact type of variables declared elsewhere does not influence the generated code. Obviously, references to labels are filled in, but for example the type of jump (local vs long jump) must be supplied by the programmer.
-pseudo-instruction:
- d[bwdqtoyz]: Declare initialized data
- db (define byte) 8
- dw (define word) 16
- dd (define double) 32
- dq (define quad) 64
- dt, do, dy, dz: ? (float only?)
- db 0x55 ; Just one byte
- db 0x55,0x56,0x57 ; Three bytes
- db 'hello',0 ; String constant made of bytes
- db 64 dup 0 ; 64 zero bytes
-
- times <x> <instr>: Assemble an instruction the given number of times
- times 64 db 0 ; 64 zero bytes
-
- res[bwdqtoyz]: Reserve space
- resb 64 ; Reserve 64 uninitialized bytes
- db ? ; Another syntax for uninitialized data
- db 64 dup ? ; Reserve 64 uninitialized bytes
-
- incbin: Transclude a binary file
- incbin "file.dat" ; directly copy the given binary file to the output
- incbin "file.dat",100,200 ; copy bytes starting at 100, but only up to 200 bytes total.
-
- equ: Define a compile-time constant
- ```
- message db "Hello, world",0 ; A c-style string
- msglen equ $-message ; Length of the string. See $ immediately below.```
+d[bwdqtoyz]: (pseudo-instruction) Declare initialized data
+ - db (define byte) 8
+ - dw (define word) 16
+ - dd (define double) 32
+ - dq (define quad) 64
+ - dt, do, dy, dz: ? (float only?)
+
+ db 0x55 ; Just one byte
+ db 0x55,0x56,0x57 ; Three bytes
+ db 'hello',0 ; String constant made of bytes
+ db 64 dup 0 ; 64 zero bytes
+
+times <x> <instr>: (meta-instruction) Assemble an instruction the given number of times
+
+ times 64 db 0 ; 64 zero bytes
+
+res[bwdqtoyz]: (pseudo-instruction) Reserve space
+
+ resb 64 ; Reserve 64 uninitialized bytes
+ db ? ; Another syntax for uninitialized data
+ db 64 dup ? ; Reserve 64 uninitialized bytes
+
+incbin: (pseudo-instruction) Transclude a binary file
+
+ incbin "file.dat" ; directly copy the given binary file to the output
+ incbin "file.dat",100,200 ; copy bytes starting at 100, but only up to 200 bytes total.
+
+equ: (pseudo-instruction) Define a compile-time constant
+
+ message db "Hello, world",0 ; A c-style string
+ msglen equ $-message ; Length of the string. See $ immediately below.```
Constants and expressions:
- $: the address of the current instruction output
- $$: the address of start-of-section
- [x]: the address given by expression <x>
-
-
- memory references
- ```
- wordvar: dw 123
- mov ax, [wordvar] ; move the value at memory location 123 to ax
- mov ax, [wordvar+1]
- mov eax, [dbx*2+ecx+offset]```
-
- constants:
- 200, 0200, 200d, 0d200: decimal
- 0xc8, $0xc8, 0hc8, 0x8h: hex
- 310o, 0o310, 0q310: octal
- 11001000b, 0b1100_1000: binary
- `hi`, 'hi', "hi": string (up to 8 bytes can be considered an integer too)
- -0.2, 1.2e10: floating point. see docs for more, i don't care about floats.
-
- seg/wrt: memory segmentation, used for 16-bit programs.
-
- local .labels are labels which can be repeated. references are to the "nearest" local label.
- .loop
- ; code
- jne .loop
- ret
+
+- $: the address of the current instruction output
+- $$: the address of start-of-section
+- [x]: the address given by expression <x>
+
+memory references
+
+ wordvar: dw 123
+ mov ax, [wordvar] ; move the value at memory address 123 to ax
+ mov ax, [wordvar+1]
+ mov eax, [dbx*2+ecx+offset]
+
+constants:
+
+- decimal: 200, 0200, 200d, 0d200
+- hex: 0xc8, $0xc8, 0hc8, 0x8h: hex
+- octal: 310o, 0o310, 0q310: octal
+- binary: 11001000b, 0b1100_1000: binary
+- string: `hi`, 'hi', "hi". 1-8 byte strings can be considered integers.
+- float: -0.2, 1.2e10. see docs for more about floats, i don't care about floats.
+
+seg/wrt: memory segmentation, used for 16-bit programs.
+
+local labels: .labels are labels which can be repeated. references are to the "nearest" local label.
+
+ .loop
+ ; code
+ jne .loop
+ ret
+
### Chapter 4: The NASM Preprocessor
-%include MACROS_MAC ; Recommend using C-style include guards
+Single-line macros work similarly to the C preprocessor.
-%define ctrl 0x1F &
-%define a(x) 1+b(x)
-%define b(x) 2*x
-Similar to C preprocessor.
+ %include MACROS_MAC ; Recommend using C-style include guards
+
+ %define ctrl 0x1F &
+ %define a(x) 1+b(x)
+ %define b(x) 2*x
+ %undef ctrl ; Un-define a macro
+ %ifdef DEBUG
+ writefile 2, "Function performed successfully",13,10
+ %endif
%xdefine is similar to %define, but if referenced by another macro it's expanded at definition time.
+
%+ prevents tokenizing in a macro:
-```
-mov ax,BDASTART + tBIOSDA.COM1addr
-%define BDA(x) BDASTART + tBIOSDA. %+ x
-mov ax,BDA(COM1addr)```
-%undef un-defines a macro
-
-%assign i i+1 ; Defines numeric macros only, which take no variables
-%defalias OLD NEW ; two-way symlink for macros
-
-multi-line macros:
-```
-%macro prologue 1
- push ebp
- mov dbp,esp
- sub esp,%1
-%endmacro```
-Here `1` is the number of parameters, and `%1` is a reference to the first parameter.
-
-macro-local labels:
-```%macro retz 0
- jnz %%skip
- ret
- %%skip:
-%endmacro```
-When evaluated, becomes `..@1.skip`, `..@2.skip` etc.
-```
-%ifdef DEBUG
- writefile 2, "Function performed successfully",13,10
-%endif```
-`%ifidni TARGET x64` - test exact text equality.
+ mov ax,BDASTART + tBIOSDA.COM1addr
+ %define BDA(x) BDASTART + tBIOSDA. %+ x
+ mov ax,BDA(COM1addr)
+
+Some additional commands, not found in C:
+
+ %assign i i+1 ; Defines numeric macros only, which take no variables
+ %defalias OLD NEW ; two-way symlink for macros
+ %ifidni TARGET x64 ; test exact text equality.
+ %ref 64 ; like times, but works for multi-line expressions. needed for multi-line macros below
-%ref 64 -- like times, but works for multi-line expressions. needed for multi-line macros.
+Multi-line macros take a number of parameters:
-many more macro features omitted: optional arguments, varargs in macros, very weird quoting and self-reference, condition codes, listing behavior, additianal %if-variants, dependencies, context-local labels, user-defined errors and warnings, %pragma
+ %macro prologue 1
+ push ebp
+ mov dbp,esp
+ sub esp,%1
+ %endmacro
+
+Here `1` is the number of parameters, and `%1` is a reference to the first parameter. You can also have optional parameters, greedy parameters, varargs-style parameters, etc. See the docs for more.
+
+Macro-local labels can help with multi-line macros:
+
+ %macro retz 0
+ jnz %%skip
+ ret
+ %%skip:
+ %endmacro
+When evaluated, becomes `..@1.skip`, `..@2.skip` etc.
+
+Many more macro features omitted:
+- For multi-line macros. Varargs, greedy args, optional args, condition code args (see below)
+- more %if variants
+- Obscure quoting and self-reference
+- Condition codes arguments (E->JE, NZ->JNZ, etc in macro)
+- Modifying generation of a listing
+- Dependencies
+- Contexts and context-local labels
+- User-defined errors and warnings
+- %pragma
### Chapter 5: Standard Macros
struc/endstruc/istruc+at: define a C-style structure
align: aligns code or data
+
### Chapter 6: Standard Macro Packages
%use altreg ; Import a standard macro package
altreg: alternate register names
fp: floating point macros
ifunc: integer functions
masm: masm compatiblity
+
### Chapter 7: Assembler Directives
`BITS 16` / `BITS 32` / `BITS 64`: Explicitly declare a bit mode. Discouraged since it can be done automatically by output format.
`DEFAULT REL` / `DEFAULT ABS` / `DEFAULT [NO]BND`: Change assembler defaults
`CPU`: Restrict instruction set
`FLOAT`: Set various floating point options
`WARNING`: Enable or disable warnings
+
### Chapter 8: Output Formats
- `bin`: Generate only machine code. Useful for bootloaders, operating systems, etc.
- ORG 0x100 ; tell NASM the absolute address where the program will be loaded
- `obj,win32,win64`: dos/windows object format
- `aout,aoutb(?),as85,rdf`: Obsolete
- `dbg`: Debugging. Don't use.
+
### Chapter 9: Writing 16-bit code (DOS, Windows 3/3.1)
16-bit EXEs can be made by linking `.obj` files, or directly with a DOS .exe macro header
16-bit COMs can be made by adding an extra line or two at the start of `bin`.
.sys (DOS driver) is similar to .com with a different offset.
Interfacing with external libraries: see docs
+
### Chapter 10: Writing 32-bit code (Unix, Win32, DJGPP)
No memory segmentation--"flat" memory model where you just have a 32-bit, 4GB address space.
C call interface [very helpful, copy from https://www.nasm.us/xdoc/2.15.05/html/nasmdo10.html]
See later section for syscall to Linux kernel
+
### Chapter 11: Mixing 16- and 32-bit Code [ obsolete ]
+
### Chapter 12: Writing 64-bit Code (Unix, Win64)
C ABI for Unix:
The first six arguments are passed in RDI, RSI, RDX, RCX, R8, and R9.
Return value is in RAX (only)
Floating point, memory, etc work differently and you'll have to read a spec.
See later section for syscall to Linux kernel
+
### Chapter 13: Troubleshoting [useless]
+
### Appendix A: Ndisasm (Netwide Disassembler)
There's a disassembler. It can only read binary (not elf, etc)
+
### Appendix B: Instruction List [useless]
+
### Appendix C: Version History [useless]
+
### Appendix D: Building NASM from Source [useless]
+
### Appendix E: Contact Information [useless]
## System calls
projects / za3k.git / commitdiff