From owner-freebsd-doc Mon Mar 20 23:30: 7 2000 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.ORG [204.216.27.21]) by hub.freebsd.org (Postfix) with ESMTP id 218C337BAED for ; Mon, 20 Mar 2000 23:30:01 -0800 (PST) (envelope-from gnats@FreeBSD.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.9.3/8.9.2) id XAA92562; Mon, 20 Mar 2000 23:30:01 -0800 (PST) (envelope-from gnats@FreeBSD.org) Received: from mail.ptd.net (mail2.ha-net.ptd.net [207.44.96.66]) by hub.freebsd.org (Postfix) with SMTP id DB4F437B63E for ; Mon, 20 Mar 2000 23:21:07 -0800 (PST) (envelope-from tms@mail.ptd.net) Received: (qmail 8761 invoked from network); 21 Mar 2000 07:21:05 -0000 Received: from du29.cli.ptd.net (HELO beowulf.bsd.home) (204.186.33.29) by mail.ptd.net with SMTP; 21 Mar 2000 07:21:05 -0000 Received: (from tms@localhost) by beowulf.bsd.home (8.9.3/8.9.3) id CAA01053; Tue, 21 Mar 2000 02:20:10 -0500 (EST) (envelope-from tms) Message-Id: <200003210720.CAA01053@beowulf.bsd.home> Date: Tue, 21 Mar 2000 02:20:10 -0500 (EST) From: tms2@mail.ptd.net Reply-To: tms2@mail.ptd.net To: FreeBSD-gnats-submit@freebsd.org X-Send-Pr-Version: 3.2 Subject: docs/17521: Proposed FAQ on assembly programming Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org >Number: 17521 >Category: docs >Synopsis: Proposed FAQ on assembly programming >Confidential: no >Severity: non-critical >Priority: medium >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Mon Mar 20 23:30:00 PST 2000 >Closed-Date: >Last-Modified: >Originator: Thomas M. Sommers >Release: FreeBSD 3.2-RELEASE i386 >Organization: >Environment: The FAQ applies only to i386 machines. >Description: Information on assembly programming is not readily available. In particular, the correct way to make syscalls is not at all obvious. The proposed FAQ shows how to write a "Hello, world." program in assembly. >How-To-Repeat: >Fix: Hello, World in FreeBSD Assembler

How do I write "Hello, world" in FreeBSD assembler?

This program prints "Hello, world." on the standard output, and then exits with an exit status of 0. It is written for Intel machines, to be assembled by the GNU assembler, as. The syntax used by as is different from Intel's, but is common in the Unix world. See man as or info as for details. This syntax is known as AT&T syntax. The most important difference for present purposes is that the order of operands is reversed: the source operand comes first, then the destination.

The program works by first calling write(2) to write the message, and then calling exit(2) to exit.

 1:         .data                       # Data section
 2: 
 3: msg:    .string "Hello, world.\n"   # The string to print.
 4:         len = . - msg - 1           # The length of the string.
 5:     
 5:         .text                       # Code section.
 6:         .global _start
 7:
 8: _start:                             # Entry point.
10:         pushl   $len                # Arg 3 to write: length of string.
11:         pushl   $msg                # Arg 2: pointer to string.
12:         pushl   $1                  # Arg 1: file descriptor.
13:         movl    $4, %eax            # Write.
14:         call    do_syscall
15:         addl    $12, %esp           # Clean stack.
16:
17:         pushl   $0                  # Exit status.
18:         movl    $1, %eax            # Exit.
19:         call    do_syscall
20:
21: do_syscall:   
22:         int     $0x80               # Call kernel.
23:         ret

_start (line 8) is the default name for a program's entry point.

Arguments to system calls are placed on the stack from right to left, just as in C. Lines 10 through 12 push the arguments for write(2) on the stack, and line 17 pushes the argument for exit(2). Note that the caller is responsible for cleaning up the stack after control has returned from the call.

System calls are made by putting the call's index in EAX (lines 13 and 18), and then invoking int $0x80 (line 22). Important: A call must be made after the arguments are placed on the stack and before the int $0x80. If you replace call do_syscall (lines 14 and 19) with int $0x80, the program will not work.

The kernel puts the system call's return value in EAX. This program ignores the value returned by write(2).

Assemble the program with (assuming you saved it as hello.s)

    as -o hello.o hello.s

and link it with

    ld -o hello hello.o

It is also possible to invoke system calls using libc instead of doing it directly through int $0x80.

 1:         .data
 2:
 3: msg:    .string "Hello, world.\n"
 4:         len = . - msg - 1       
 5:
 6:         .text
 7:         .extern write
 8:         .extern exit
 9:         .global main
10:
11: main:
12:         pushl   $len
13:         pushl   $msg
14:         pushl   $1
15:         call    write
16:         addl    $12, %esp
17:
18:         pushl   $0
19:         call    exit

Since we are linking with libc, we must also use the C startup code, which means that the entry point to our program is now main (line 11) instead of _start.

The easiest way to assemble and link this program is through cc, which will take care of linking in the proper startup modules in the correct order:

    cc -o hello hello.s

Resources

There is a lot of information available about assembly programming on Intel machines, but little if any of it applies to FreeBSD specifically (hence this FAQ). All of the books I have seen, and most of the Web sites, are about programming in an MS-DOS environment. These books can be useful for a FreeBSD programmer to the extent that they discuss general principles or the Intel instruction set, but of course nothing specific to MS-DOS or the PC BIOS will work under FreeBSD. There is also some material on the Web concerning assembly programming under Linux, but the same caveat applies.

Here are some Web links that you might find useful:

Intel Manuals: Reference manuals for Intel processors can be found here.
Art of Assembly Language: A well-regarded and very long (~1500 page) online textbook for assembly programming in MS-DOS.
Linux Assembly: Assembly programming under Linux. Some useful information for FreeBSD programmers, but be wary of the differences between FreeBSD and Linux.
NASM: If you prefer Intel syntax in your assembler, try NASM. It is in the FreeBSD ports system.
comp.lang.asm.x86 Host page: Contains links to other Intel assembly resources on the Web.
Alpha Assembly Language Programmer's Guide: Probably useful if you are running FreeBSD on an Alpha.

>Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message