1. Introduction

   GNU-AS is a family of assembly for different platforms. For example, there is a gnu-as for intel x86 and a gnu-as (avr-as) for avr microcontrollers. They may have a few different command-line arguments. For example, avr-as has the -mmcu argument to select the target device type. However, they have a lot of common directives and same syntax.

2. Concepts

   Terms

   • Directives [pseudo-ops]: (e.g. .text) are commands that are part of the assembler syntax but are not related to the any instruction set. All assembler directives begin with a period (.) But different assemblers may have different directives. e.g. both avrasm and avr-as are used to compile the assmebly code for avr devices, but they have a few different directives. GNU-AS directives reference.

   • Labels: (e.g. main:) locates the address of a piece of code.

             1).symbolic label: A symbolic label e.g. L2 or .L2 
                                 It can only defined only once. 
                                 Symbolic labels without prefix . are in global scope and appear in the object file's symbol table.
                                 Symbolic labels with . are in local scope and do not appear in the object file's symbol table.
             2). numeric label: a number from 0 to 9, inclusive. They are in local scope and do not appear in the object file's symbol table.
                 e.g. 
             
     
                 
         1: 				;define a numeric label 1
             mov r1, r2
             brne 1b		;1b (before) jump to the nearest label 1 define before here. The first
             jmp 1f		;1f (forward) jump to the nearest label 1 define after here. The second
         1:				;define the numeric label 1 again
             mov
                 
             
                 
         

3. NASM

   TO DO

4. Directives

   1. .text (name code section): define the start of a section of code.

      A executable can have several code sections that goes to different locations in the executable. For example, the cortex-m3 requires isr_handler section and main program section. The code under .text belongs to the same .text section. Using ".text" by itself tells the assembler that the following code goes in the default section.

   2. .section name: assemble the following code into a section named name

      .text is same as .section .text

   3. .global [.globl] symbol (declare a symbol as global): This make the symbol as global, it means that other .s files and the linker can see the file. A symbol can either a label or Because the linker takes the main function as entry point, it is necessary to declare the main as global.

   4. .equ symbol, expression (declare a symbol as the value of expression) like a macro

      .set symbol, expression : same as equ

      .equiv symbol, expression : same as equ, but when define twice, the assembler will report an error.

   5. .include "file.inc"

      This directive includes a supporting file (which is also a assembly file but may end with .inc) at the point when reaching it. It is same as copy and paste the entire included file at the include directive point.

      The search path can be set use -I (a command-line argument)

          ; the three instructions in one file
          mov r18, 12
          mov r19, r18
          mov r17, r19
          

          ; the three instructions are put in 2 files
          mov r18, 12
          .include "./external.inc"
          mov r17, r19
          

          ; filename is external.inc
          mov r19, r18
          

   6. .file (for debugging)

   7. .def (for debugging)

5. Macro

   A set of instruction represented by a single statement. A macro can be seen as a new instruction created by the programmer for the microcontroller.

       .MACRO        LSP	init=0x0020
           LDI    r17, lo8(\init)
           OUT    SPL, r17
           LDI    r17, hi8(\init)
           OUT    SPH, r17
       .ENDM
       

6. Reference

   1. GAS syntax
   2. x86 assembly guide