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.
64-bit Register
Usage
%rip
Instruction Pointer points to
the current instruction
%rsp
Stack Pointer
%rbp
Frame Pointer (saved stack pointer pointing to parameters on stack)
%rdi
Function Parameter 1
%rsi
Function Parameter 2
%rdx
Function Parameter 3
%rcx
Function Parameter 4
%r8
Function Parameter 5
%r9
Function Parameter 6
%rax
Function return value
%r10, %r11
Temporary registers (need not be saved before used)
%rbx, %r12, %r13, %r14, %r15
Temporary registers, but must be saved before use and
restored before returning from
the current function
(usually with
the push and pop instructions).
32-, 16-, and 8-bit registers
To access
the lower 32-, 16-, or 8-bits
of a 64-bit register use
the following:
64-bit register
Least significant 32-bits
Least significant 16-bits
Least significant 8-bits
%rax%eax%ax%al
%rbx%ebx%bx%bl
%rcx%ecx%cx%cl
%rdx%edx%dx%dl
%rsi%esi%si%sil
%rdi%edi%di%axl
%rbp%ebp%bp%bp
%rsp%esp%sp%spl
%r9%r9d%r9w%r9b
%r10%r10d%r10w%r10b
%r11%r11d%r11w%r11b
%r12%r12d%r12w%r12b
%r13%r13d%r13w%r13b
%r14%r14d%r14w%r14b
%r15%r15d%r15w%r15b
%r16%r16d%r16w%r16b
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.
