14.2: Example, Sum and Average

The following is a simple example of a main that calls an assembly language function, stats(), to compute the integer sum and integer average for a list of signed integers. The main and the function are in different source files and are presented as an example of how multiple source files are used. The example itself is really too small to actually require multiple source files.

Assembly Main

The main is as follows:

;  Simple example to call an external function.

; ----------------------------------------------------------
;  Data section

section     .data

; -----
;  Define standard constants

LF            equ    10            ; line feed
NULL          equ    0             ; end of string

TRUE          equ    1
FALSE         equ    0

EXIT_SUCCESS  equ    0             ; success code
SYS_exit      equ    60            ; terminate 

; -----
; Declare the data

1st1          dd    1, -2, 3, -4, 5
              dd    7, 9, 11
1en1          dd    8

1st2          dd    2, -3, 4, -5, 6
              dd    -7, 10, 12, 14, 16
len2          dd    10

section     .bss
sum1          resd     1 
ave1          resd     1

sum2          resd     1 
ave2          resd     1    

; ---------------------------------------------------------- 

extern stats

section     .text 
global _start 
_start:

; ----
;  Call the function
;       HLL Call:   stats (1st, len, &sum, &ave);

    mov    rdi, lst1            ; data set 1
    mov    esi, dword [len1]    
    mov    rdx, sum1
    mov    rcx, ave1
    call   stats
    
    mov    rdi, lst2            ; data set 2
    mov    esi, dword [len2]
    mov    rdx, sum2
    mov    rcx, ave2
    call   stats
    
; -----
;  Example program done

exampleDone:
    mov     rax, SYS_exit 
    mov     rdi, EXIT_SUCCESS 
    syscall                              

The above main can be assembled with the same assemble command as described in Chapter 5, Tool chain. The extern statement will ensure that the assembler does not generate errors.

14.2.2 Function Source

The function, in a different source file is as follows:

;  Simple example void function.

; **********************************************************
;  Data declarations
;  Note, none needed for this example.
;  If needed, they would be declared here as always.

section     .data

; ********************************************************** 

section .text 

; --------------------------------------------------
;  Function to find integer sum and integer average
;  for a passed list of signed integers.

; Call:
; stats(lst, len, &sum, &ave); 

;  Arguments Passed:

;      1) rdi - address of array 
;      2) rsi - length of passed array
;      3) rdx - address of variable for sum
;      4) rcx - address of variable for average
; Returns:
;      sum of integers (via reference)
;      average of integers (via reference)

global stats 
stats:
    push     r12 

; -----
;  Find and return sum.

    mov     r11, 0                     ; i=0
    mov     r12d, 0                    ; sum=0
    
sumLoop:
    mov     eax, dword [rdi+r11*4]     ; get lst[i]
    add     r12d, eax                  ; update sum
    inc     r11                        ; i++
    cmp     r11, rsi
    jb      sumLoop

    mov dword [rdx], r12d              ; return sum

; -----
;  Find and return average.

    mov     eax, r12d
    cdq
    idiv    esi
    
    mov     dword [rcx], eax            ; return average

; -----
;  Done, return to calling function.

    pop     r12 
    ret  

The above source file can be assembled with the same assemble command as described in Chapter 5, Tool chain. No extern statement is required since no external functions are called.

Assemble and Link

Assuming the main source file is named main.asm and the functions source file is named stats.asm, the following command will perform the assemble and link.

       yasm -g dwarf2 -f elf64 main.asm -l main.lst
       yasm -g dwarf2 -f elf64 stats.asm -l stats.lst
       ld -g -o main main.o stats.o

The files names can be changed as desired.

As usual, the debugger is started with the ddd <executable> command. It would be appropriate to note that using the debugger step command will step into the function, including showing the function source code (even if the source is in a different file). The debugger next command will execute the entire function and not show the source. If the function is working, the next command would be most useful. In order to debug the function, the step command would be most useful.

If the “-g” option is omitted, the debugger will not be able to display the source code.