From tms@mail.ptd.net Mon Mar 20 23:21:09 2000 Return-Path: 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 Sender: tms@mail.ptd.net Reply-To: tms2@mail.ptd.net To: FreeBSD-gnats-submit@freebsd.org Subject: Proposed FAQ on assembly programming X-Send-Pr-Version: 3.2 >Number: 17521 >Category: docs >Synopsis: Proposed FAQ on assembly programming >Confidential: no >Severity: non-critical >Priority: medium >Responsible: murray >State: closed >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Mon Mar 20 23:30:00 PST 2000 >Closed-Date: Tue Jun 12 22:23:53 PDT 2001 >Last-Modified: Tue Jun 12 22:24:32 PDT 2001 >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: State-Changed-From-To: open->feedback State-Changed-By: alex State-Changed-When: Mon Jun 12 03:56:25 PDT 2000 State-Changed-Why: Where would you like this entry to appear? In the FAQ? However, please resubmit it as DocBook SGML, the HTML files are generated automatically. Please see the other .sgml-files for the FAQ to learn how. It's easy :) Thanks! http://www.freebsd.org/cgi/query-pr.cgi?pr=17521 From: "Thomas M. Sommers" To: freebsd-gnats-submit@FreeBSD.org Cc: alex@big.endian.de Subject: Re: docs/17521: Proposed FAQ on assembly programming Date: Wed, 21 Jun 2000 20:17:29 -0400 Here is an SGML version. It requires the entities in docs/19425. 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.1; 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. In addition, a size suffix is appended to the opcodes. The program works by first calling &man.write.2; to write the message, and then calling &man.exit.2; to exit. 1: .data # Data section 2: 3: msg: .asciz "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 an ELF 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 &man.write.2; on the stack, and line 17 pushes the argument for &man.exit.2;. 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 invoking int $0x80 (line 22). The kernel expects to find the first argument 4 bytes below the top of the stack, as it would be if the system call were made using the C library. Therefore, the invocation of int $0x80 is placed in its own function. The kernel puts the system call's return value in %eax. If there is an error, the carry flag is set, and %eax contains the error code. This program ignores the value returned by &man.write.2;. Assuming you saved the program as hello.s, assemble and link it with: &prompt.user; as -o hello.o hello.s &prompt.user; ld -o hello hello.o It is also possible to invoke system calls using the C library instead of using 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 the C library, 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 _start label is in the C startup code, which does some initialization and then calls main.) 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: &prompt.user; cc -o hello hello.s There is a lot of information available about assembly programming on Intel machines, but little if any of it applies to FreeBSD specifically. Most or all Intel assembly books and 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 some material on the Web concerning assembly programming under Linux, but even this does not always apply to FreeBSD, because Linux uses a different protocol for making system calls. 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. Responsible-Changed-From-To: freebsd-doc->murray Responsible-Changed-By: murray Responsible-Changed-When: Tue Jun 12 21:03:25 PDT 2001 Responsible-Changed-Why: We now have an assembly language chapter of the Developer's Handbook. I'investigating whether any of this can be added to our existing chapter. http://www.FreeBSD.org/cgi/query-pr.cgi?pr=17521 State-Changed-From-To: feedback->closed State-Changed-By: murray State-Changed-When: Tue Jun 12 22:23:53 PDT 2001 State-Changed-Why: This information is now in the developer's handbook x86 assembly language chapter. http://www.FreeBSD.org/cgi/query-pr.cgi?pr=17521 >Unformatted: