Asmutils Source Guide

Contents

1. Introduction
2. Program structure
3. Include files description

3.1 system.inc
3.2 config.inc
3.3 kernel.inc
3.4 types.inc

4. Size/speed optimization
5. Tips and tricks

1. Introduction

First of all please note that this is not nasm guide. I assume that you know nasm syntax; I will not explain any nasm-related things here.

Second, I expect that you will examine source code of asmutils. This document is not intended to replace the source, its goal is only to accompany asmutils source and explain some unclear moments. Again, examine ALL source code. Look how command line parsing is done, how conditional assembly for different kernel versions is done and so on -- I am not going to explain everything here.

Mostly this guide describes a set of macros I've developed to write fast and readable; they are hiding from you unneeded details, and also take care of optimization.

You may also want to read Startup state of Linux/i386 ELF binary and Linux/i386 system calls documents to get better general (not asmutils specific) understanding of asmutils source code.

2. Program structure

There are three macros that make section definition as simple as possible: CODESEG, DATASEG and UDATASEG (similar to TASM ideal mode syntax).

Program must have at least CODESEG (.text) section, other sections optional. CODESEG is read-only, DATASEG and UDATASEG are read-write; i.e. you can place data in CODESEG as long as you will not change it. You can also define your own sections if you want, but there's very rare need of doing so. Each section (even if it is empty) will enlarge your file.

START macro tells linker entry point. If you will not mark entry point -- linker will use start of CODESEG section.

So, typical code will look like:

%include "system.inc"

CODESEG

START:			;entry point

    your_code_here

DATASEG

    your_data_here

UDATASEG

    your_bss_here

3. Include files description

3.1 system.inc

system.inc file MUST be included into program code to do anything else; all vital constants and system call macros are here, as well as CODESEG, DATASEG and UDATASEG macros. Without this file you will have to write in usual boring way.

It also contains optimizing macro __setreg32, that does register assignment. You can use this macro instead of movs if you take care of size, it produces quiet good results (do not try to understand how it works :).

A lot of people asked me for some description of syscall macros, so here are general things to know about sys_xxx macros:

• there can be up to 5 parameters (depends on syscall)
• parameters to sys_xxx are always optional
• registers corresponding to parameters are: ebx [1], ecx [2], edx [3], esi [4], edi [5]
• eax is used as syscall (function) number and is always destroyed; after call it contains return value
• ecx and edx also can be destroyed by several system calls
• if there are no parameters, macro thinks that all registers (except eax) are already set before syscall
• number of registers used is equal to parameters passed + 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; f.e. sys_write EMPTY,EMPTY,1 will expand to:

  __setreg32 edx,1
  __syscall __NR_write
  

• registers are set in this order: edi,esi,edx,ecx,ebx,eax; i.e. it is possible to write: sys_write eax,ebx,ecx -- it will expand to:

  	mov	edx,ecx
  	mov	ecx,ebx
  	mov	ebx,eax
  	__syscall __NR_write
  

• all macros can generate code optimized for size (default) or speed

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.2 config.inc

This file stores configuration parameters. It is included from system.inc, so you have no need to include directly. Here you can set target kernel version (KERNEL) and optimization (__OPTIMIZE). Further other configuration parameters will be added.

3.3 kernel.inc

Kernel structures reside and should be added into kernel.inc file. So, if you work with kernel structures -- this file must be included.

3.4 types.inc

This file contains common types definitions (INT, LONG, etc.). This file is included internally from kernel.inc, but you can also use it without kernel.inc if you wish.

4. Size/speed optimization

In fact this must be done by assembler.. but.. optimizing assembler is a dream. So, I've took care of it. By default code is optimized for size, and you can get up to 20% smaller executable; speed optimization in fact is a fake, it is just absence of size optimization :), though theoretically you can gain something on pentium processors.. To enable speed optimization set __OPTIMIZE to __O_SPEED in config.inc. Optimization touches register assignment mechanism (__setreg32 macro) and section alignment (CODESEG, DATASEG macros). Optimization is a work in progress, so results may be better in future versions.

5. Tips and tricks

Section is not written yet, go examine source code :) Until you've got better algorithms use existing ones. Also, read Startup state of Linux/i386 ELF binary document, you can find some tricks there.