Solaris X86 64-bit Assembly Programming

This is a simple example on writing, compiling, and debugging Solaris 64-bit x86 assembly language with a C program. This is also referred to as "AMD64" assembly. The term "AMD64" is used in an inclusive sense to refer to all X86 64-bit processors, whether AMD Opteron family or Intel 64 processor family. Both run Solaris x86. I'm keeping this example simple mainly to illustrate how everything comes together—compiler, assembler, linker, and debugger when using assembly language. The example I'm using here is a C program that calls an assembly language program passing a C string. The assembly language program takes the C string and calls printf() with it to print the string.

AMD64 Register Usage But first let's review the use of AMD64 registers. AMD64 has several 64-bit registers, some special purpose (such as the stack pointer) and others general purpose. By convention, Solaris follows the AMD64 ABI in register usage, which is the same used by Linux, but different from Microsoft Windows in usage (such as which registers are used to pass parameters). This blog will only discuss conventions for Linux and Solaris. The following chart shows how AMD64 registers are used. The first six parameters to a function are passed through registers. If there's more than six parameters, parameter 7 and above are pushed on the stack before calling the function. The stack is also used to save temporary "stack" variables for use by a function.

32-, 16-, and 8-bit registers To access the lower 32-, 16-, or 8-bits of a 64-bit register use the following:

There's other registers present, such as the 64-bit %mm registers, 128-bit %xmm registers, 256-bit %ymm registers, and 512-bit %zmm registers. Except for %mm registers, these registers may not present on older AMD64 processors.

Assembly Source

The following is the source for a C program, helloas1.c, that calls an assembly function, hello_asm().

$ cat helloas1.c
extern void hello_asm(char *s);
int
main(void)
{
	hello_asm("Hello, World!");
}

The assembly function called above, hello_asm(), is defined below.

$ cat helloas2.s
/*
 * helloas2.s
 * To build:
 *	cc -m64 -o helloas2-cpp.s -D_ASM -E helloas2.s 
 *	cc -m64 -c -o helloas2.o helloas2-cpp.s
 */
#if defined(lint) || defined(__lint)
/* ARGSUSED */
void
hello_asm(char *s)
{
}

#else	/* lint */
#include <sys/asm_linkage.h>
.extern	printf
ENTRY_NP(hello_asm)
	// Setup printf parameters on stack
	mov	%rdi, %rsi		// P2 (%rsi) is string variable
	lea	.printf_string, %rdi	// P1 (%rdi) is printf format string
	call	printf
	ret    
	SET_SIZE(hello_asm)

// Read-only data
.text
.align	16
.type	.printf_string, @object
.printf_string:
	.ascii	"The string is: %s.\n\0"
#endif	/* lint || __lint */

In the assembly source above, the C skeleton code under "#if defined(lint)" is optionally used for lint to check the interfaces with your C program--very useful to catch nasty interface bugs. The "asm_linkage.h" file includes some handy macros useful for assembly, such as ENTRY_NP(), used to define a program entry point, and SET_SIZE(), used to set the function size in the symbol table.

The function hello_asm calls C function printf() by passing two parameters, Parameter 1 (P1) is a printf format string, and P2 is a string variable. The function begins by moving %rdi, which contains Parameter 1 (P1) passed hello_asm, to printf()'s P2, %rsi. Then it sets printf's P1, the format string, by loading the address the address of the format string in %rdi, P1. Finally it calls printf. After returning from printf, the hello_asm function returns itself.

Larger, more complex assembly functions usually do more setup than the example above. If a function is returning a value, it would set %rax to the return value. Also, it's typical for a function to save the %rbp and %rsp registers of the calling function and to restore these registers before returning. %rsp contains the stack pointer and %rbp contains the frame pointer. Here is the typical function setup and return sequence for a function:

ENTRY_NP(sample_assembly_function)
	push	%rbp		// save frame pointer on stack
	mov	%rsp, %rbp	// save stack pointer in frame pointer

	xor	%rax, %r4ax	// set function return value to 0.
	mov	%rbp, %rsp	// restore stack pointer
	pop	%rbp		// restore frame pointer
	ret    			// return to calling function
	SET_SIZE(sample_assembly_function)

Compiling and Running Assembly

Use the Solaris cc command to compile both C and assembly source, and to pre-process assembly source. You can also use GNU gcc instead of cc to compile, if you prefer. The "-m64" option tells the compiler to compile in 64-bit address mode (instead of 32-bit).

$ cc -m64 -o helloas2-cpp.s -D_ASM -E helloas2.s
$ cc -m64 -c -o helloas2.o helloas2-cpp.s
$ cc -m64 -c helloas1.c
$ cc -m64 -o hello-asm helloas1.o helloas2.o
$ file hello-asm helloas1.o helloas2.o
hello-asm:	ELF 64-bit LSB executable AMD64 Version 1 [SSE FXSR FPU], dynamically linked, not stripped
helloas1.o:	ELF 64-bit LSB relocatable AMD64 Version 1
helloas2.o:	ELF 64-bit LSB relocatable AMD64 Version 1

$ hello-asm
The string is: Hello, World!.

Debugging Assembly with MDB

MDB is the Solaris system debugger. It can also be used to debug user programs, including assembly and C. The following example runs the above program, hello-asm, under control of the debugger. In the example below I load the program, set a breakpoint at the assembly function hello_asm, display the registers and the first parameter, step through the assembly function, and continue execution.

$ mdb hello-asm			# Start the debugger
> hello_asm:b			# Set a breakpoint
> ::run				# Run the program under the debugger
mdb: stop at hello_asm
mdb: target stopped at:
hello_asm:      movq   %rdi,%rsi
> $C				# display function stack
ffff80ffbffff6e0 hello_asm()
ffff80ffbffff6f0 0x400adc()
> $r				# display registers
%rax = 0x0000000000000000       %r8  = 0x0000000000000000
%rbx = 0xffff80ffbf7f8e70       %r9  = 0x0000000000000000
%rcx = 0x0000000000000000       %r10 = 0x0000000000000000
%rdx = 0xffff80ffbffff718       %r11 = 0xffff80ffbf537db8
%rsi = 0xffff80ffbffff708       %r12 = 0x0000000000000000
%rdi = 0x0000000000400cf8       %r13 = 0x0000000000000000
                                %r14 = 0x0000000000000000
                                %r15 = 0x0000000000000000
%cs = 0x0053    %fs = 0x0000    %gs = 0x0000
%ds = 0x0000    %es = 0x0000    %ss = 0x004b
%rip = 0x0000000000400c70 hello_asm
%rbp = 0xffff80ffbffff6e0
%rsp = 0xffff80ffbffff6c8
%rflags = 0x00000282
  id=0 vip=0 vif=0 ac=0 vm=0 rf=0 nt=0 iopl=0x0
  status=<of,df,IF,tf,SF,zf,af,pf,cf>
%gsbase = 0x0000000000000000
%fsbase = 0xffff80ffbf782a40
%trapno = 0x3
   %err = 0x0
> ::dis			# disassemble the current instructions
hello_asm:                      movq   %rdi,%rsi
hello_asm+3:                    leaq   0x400c90,%rdi
hello_asm+0xb:                  call   -0x220   <PLT:printf>
hello_asm+0x10:                 ret    
0x400c81:                       nop    
0x400c85:                       nop    
0x400c88:                       nop    
0x400c8c:                       nop    
0x400c90:                       pushq  %rsp
0x400c91:                       pushq  $0x74732065
0x400c96:                       jb     +0x69    <0x400d01>
> 0x0000000000400cf8/S		# %rdi contains Parameter 1
0x400cf8:       Hello, World!
> [				# Step and execute 1 instruction
mdb: target stopped at:
hello_asm+3:    leaq   0x400c90,%rdi
> [
mdb: target stopped at:
hello_asm+0xb:  call   -0x220   <PLT:printf>
> [
The string is: Hello, World!.
mdb: target stopped at:
hello_asm+0x10: ret    
> [
mdb: target stopped at:
main+0x19:      movl   $0x0,-0x4(%rbp)
> :c				# continue program execution
mdb: target has terminated
> $q				# quit the MDB debugger
$

In the example above, at the start of function hello_asm(), I display the stack contents with "$C", display the registers contents with "$r", then disassemble the current function with "::dis".

The first function parameter, which is a C string, is passed by reference with the string address in %rdi (see the register usage chart above). The address is 0x400cf8, so I print the value of the string with the "/S" MDB command: "0x0000000000400cf8/S".

I can also print the contents at an address in several other formats. Here's a few popular formats. For more, see the mdb(1) man page for details.

• address/S C string
• address/C ASCII character (1 byte)
• address/E unsigned decimal (8 bytes)
• address/U unsigned decimal (4 bytes)
• address/D signed decimal (4 bytes)
• address/J hexadecimal (8 bytes)
• address/X hexadecimal (4 bytes)
• address/B hexadecimal (1 bytes)
• address/K pointer in hexadecimal (4 or 8 bytes)
• address/I disassembled instruction

Finally, I step through each machine instruction with the "[" command, which steps over functions. If I wanted to enter a function, I would use the "]" command. Then I continue program execution with ":c", which continues until the program terminates.

MDB Basic Cheat Sheet

Here's a brief cheat sheet of some of the more common MDB commands useful for assembly debugging. There's an entire set of macros and more powerful commands, especially some for debugging the Solaris kernel, but that's beyond the scope of this example.

• $C Display function stack with pointers
• $c Display function stack
• $e Display external function names
• $v Display non-zero variables and registers
• $r Display registers
• ::fpregs Display floating point (or "media" registers). Includes %st, %xmm, and %ymm registers.
• ::status Display program status
• ::run Run the program (followed by optional command line parameters)
• $q Quit the debugger
• address:b Set a breakpoint
• address:d Delete a breakpoint
• $b Display breakpoints
• :c Continue program execution after a breakpoint
• [ Step 1 instruction, but step over function calls
• ] Step 1 instruction
• address::dis Disassemble instructions at an address
• ::events Display events

Further Information

• "Assembly Language Techniques for Oracle Solaris on x86 Platforms" by Paul Lowik (2004). Good tutorial on Solaris x86 optimization with assembly.
• The Solaris Operating System on x86 Platforms An excellent, detailed tutorial on X86 architecture, with Solaris specifics. By an ex-Sun employee, Frank Hofmann (2005).
• "AMD64 ABI Features", Solaris 64-bit Developer's Guide contains rules on data types and register usage for Intel 64/AMD64-class processors. (available at docs.oracle.com)
• Solaris X86 Assembly Language Reference Manual (available at docs.oracle.com)
• SPARC Assembly Language Reference Manual (available at docs.oracle.com)
• System V Application Binary Interface (2003) defines the AMD64 ABI for UNIX-class operating systems, including Solaris, Linux, and BSD. Google for it—the original website is gone.
• cc(1), gcc(1), and mdb(1) man pages.