Include files description

Asmutils HOWTO
Prev |  | Next

# 3. Include files description

## 3.1. system.inc

This file is vital and MUST be included into program code to do anything else; it provides the framework and macros described here, without it you have to write in usual boring way.

`CODESEG`, `DATASEG`, `UDATASEG`, `END`, `I_STRUC`, `I_END`, `B_STRUC` macros are here, some other will be added.

Also it contains optimizing macros `_mov`, `_add`, `_sub`, that perform register assignment, addition and subtraction. You can use these macros instead of mov, add, sub instructions -- if you take care of size, this will produce quite good results (do not try to understand how they work :).

> Note: when passing negative number in -0x80..0x00 range to `_mov`, pass it as hex, i.e. 0xffffffff instead of -1, if you want size optimization. This is a "feature" of nasm, not `_mov` bug.

This file includes two others: includes.inc and syscall.inc, you do need to include them manually.

## 3.2. includes.inc

This file stores generic constant definitions and structures (from libc headers) that are (as a rule) OS independent. If you add some defined constant, please do not forget to mention header file it was taken from.

## 3.3. syscall.inc

File holds system call macros, here are general things to know about them:

- all parameters are always optional

- there can be up to 6 parameters (depends on syscall) on Linux, more on *BSD

  > Note: Passing sixth parameter in `ebp` is valid only for Linux 2.4, previous Linux versions understand only 5 parameters in registers. This means that sixth parameter will be passed in `ebp` only if you have `KERNEL=24` (or higher) in `MCONFIG`. This applies to Linux only.

- registers corresponding to parameters are: `ebx` (1), `ecx` (2), `edx` (3), `esi` (4), `edi` (5), `ebp` (6).

- `eax` register is used as syscall (function) number and is always destroyed; after call it contains return value. Other registers are not touched.

- flags can be touched, you should not assume that flags are the same after call

- if there are no parameters, macro assumes that all registers (except `eax`) are already set before syscall

- number of used registers is equal to number of passed parameters + 1 (`eax`)

- parameter can be register, memory address, reference, constant or reserved word

- reserved words are (currently only one): `EMPTY` (indicates that register is already set before macro and must be skipped). It is useful when you need to pass only say third parameter and not touch others; e.g. `sys_write EMPTY,EMPTY,1` will expand to:

      	_mov	edx,1
      	__syscall write...

- registers are set in this order: `ebp`, `edi`, `esi`, `edx`, `ecx`, `ebx`, `eax`; therefore it is possible to write `sys_write eax, ebx, ecx`; it will expand to:

      	mov	edx,ecx
      	mov	ecx,ebx
      	mov	ebx,eax
      	__syscall write...

- generated code can be optimized for size (default) or speed

Warning
NEVER use `__syscall` macro in your program directly (of course the same applies to `int 0x80` !!). This is a VERY BAD thing to do. This will MAKE YOUR CODE UNPORTABLE! Therefore please use only `sys_xxx` macros! See also this section .

If some system call is missing, you can add it to this file; it's simple, just look how others are done there; use sys_syscallname as macro name.

## 3.4. elf.inc

This file applies only to ELF systems. ELF macros are defined here. These macros can be (and are, by default) used to reduce the final size of an executable. Almost all of them (except `ELF_AT`) are integrated into existing program structure. To enable them you just need to have `ELF_MACROS = y` line in `MCONFIG` (enabled by default), this turns on automatic usage of these macros (and you do not have to include `elf.inc`). And if you will follow simple rules when writing a program, then you do not have to carry out two different definitions for sections and structures; so, you can compile the same source with and without usage of these macros, getting correct code in both cases. Rules are simple: use following section order: `CODESEG`, `DATASEG`, `UDATASEG`, `END`, and use `I_STRUC` and `I_END` to define structures in `UDATASEG`, or even better, `B_STRUC` macro, instead of `istruc` and `iend` (take any asmutils source as an example), Alternatively, you can use macros from elf.inc directly if you want, but then you can't compile your source using usual nasm/ld procedure. If you want to go this way, take the time and read carefully description by Brian Raiter below and comments in the `elf.inc` (also do read it if you want to understand how they work). Personally I think that first way is simpler.

    	elf.inc macros description (by Brian Raiter)
    	--------------------------------------------

    ELF executable files can contain a great deal of overhead information.
    This overhead is used to define things such as the program's memory
    layout, dynamic libraries which it needs in order to run, and so on.
    The programs in asmutils, however, require almost none of this
    overhead (e.g., by making direct system calls). This permits the
    programs to be much smaller than they would be otherwise. In fact,
    they require less ELF overhead than Nasm and ld expect of any program.
    As a result, these tools create executables with unnecessary overhead.
    Some of this overhead can be removed afterwards using strip and/or
    sstrip, but not all of it.

    Therefore, as of version 0.05, the asmutils programs avoid using
    object files entirely, and instead define the ELF executable file
    images directly, byte for byte, using Nasm's "bin" output file format
    and the macros defined in elf.inc. These macros are defined here.

    BEGIN_ELF
    END_ELF

    These are the two main macros in elf.inc. They mark the beginning and
    the end of the program, and must be used together. All assembler
    instructions (and pseudo-instructions such as "DB") should appear
    between these two macros.

    Within these two macros, the START label should be defined, which will
    mark the entry point of the program.

    BEGIN_ELF uses the ORG pseudo-instruction to indicate where the file
    is to be loaded in memory, and then defines a minimal ELF header and
    program header table. BEGIN_ELF also defines the label _text to point
    to the area immediately following its usage (which is typically the
    beginning of the program).

    Note that if instructions do appear after the END_ELF macro, they will
    still be added to the executable file. However, nothing after END_ELF
    will be loaded into memory when the program is executed.

    If the program requires no writable data storage outside of the
    stack, then nothing else from elf.inc will be needed.

    ELF_DATA

    This macro is used to reserve writable memory. ELF_DATA should appear
    after the program proper, and before END_ELF. Between these two
    macros, the programmer can define "uninitialized" data using the
    RESB family of pseudo-instructions.

    Memory defined in the ELF_DATA section will not take up space in the
    executable file, but will instead be automatically allocated at
    runtime. The data will be initialized to all zeros. The builtin macro
    ALIGNB may also be used here.

    ELF_DATA also defines the label _data to point to the area immediately
    following its usage.

    Note: do not use the DB family of pseudo-instructions within the
    ELF_DATA section; those should appear before ELF_DATA, within the
    program proper.

    ELF_BSTRUC strucname [, fieldname ...]

    This macro declares an instance of a structure (previously defined
    with the builtin STRUC macro) within an ELF_DATA segment. The
    structure, in order to work with ELF_BSTRUC, must have been defined
    using local labels (i.e., prefixed with a dot) for the field names.

    The first argument to ELF_BSTRUC is the name of the structure to use.
    The remaining arguments (if any) list the field names to declare. Only
    those field names specified will be declared as labels within the
    program.

    Thus, for example, if the following structure has been defined:

              struc mytype
    .long:    resd 1
    .word:    resw 1
    .byte:    resb 1
    .str:     resb 32
              endstruc

    then a program that included the following after ELF_DATA:

    mine:     elf_bstruc mytype .long, .word, .str

    would have 39 bytes added to its memory image, and could use the
    labels mine.long, mine.word, and mine.str. (mine.byte would not be
    created.)

    ELF_ISTRUC strucname
    ELF_IAT fieldname [, inst ...]
    ELF_IEND

    These macros correspond directly to the builtin macros ISTRUCT, AT,
    and IEND; they differ only in that they declare "uninitialized"
    memory, and thus can be used within an ELF_DATA section.

Prev | Home | Next
Program layout |  | Debugging your code