.dm category begin
.begnote
.note Category:
&*
.endnote
.dm category end

.dm syntax begin
.begnote
.note Syntax:
.us on
.* Screwing with formatting is extremely bad idea for online help!
.if &e'&dohelp eq 0 .do begin
.fo off
.do end
.sk -1 c
.dm syntax end

.dm esyntax begin
.us off
.if &e'&dohelp eq 0 .do begin
.fo on
.do end
.endnote
.dm esyntax end

.dm descrp begin
.begnote
.note Description:
.dm descrp end

.dm edescrp begin
.endnote
.dm edescrp end

.dm notes begin
.begnote
.note Notes:
&*
.endnote
.dm notes end

.*
.chap *refid=wasaxp The &wasname.
.*
.if &e'&dohelp eq 0 .do begin
.section Introduction
.do end
.*
.np
.ix 'assembler'
This chapter describes the &wasname..
It takes as input an assembler source file (a file with extension
"&axt") and produces, as output, an object file.
.np
The &wasname command line syntax is the following.
.ix '&wascmdup' 'command line format'
.ix 'command line format' '&wascmdup'
.if '&target' eq 'QNX' .do begin
.mbigbox
&wascmdup [options] asm_file [options] [@env_var]
.embigbox
.np
The square brackets [ ] denote items which are optional.
.begnote
.mnote &wascmd
is the name of the &wasname..
.mnote asm_file
is the filename specification of the assembler source file to be
assembled.
A default filename extension of ".a" is assumed when no extension is
specified.
A filename extension consists of that portion of a filename containing
the last "." and any characters which follow it.
.exam begin
File Specification              Extension
/home/john.doe/foo              (none)
/home/john.doe/foo.             .
/home/john.doe/foo.bar          .bar
/home/john.doe/foo.goo.bar      .bar
.exam end
.mnote options
is a list of valid &wasname options, each preceded by a dash
("&minus.").
Options may be specified in any order.
.endnote
.do end
.el .do begin
.mbigbox
&wascmdup [options] [d:][path]filename[.ext] [options] [@env_var]
.embigbox
.np
The square brackets [ ] denote items which are optional.
.begnote
.mnote &wascmdup
is the name of the &wasname..
.mnote d:
is an optional drive specification such as "A:", "B:", etc.
If not specified, the default drive is assumed.
.mnote path
is an optional path specification such as "\PROGRAMS\ASM\".
If not specified, the current directory is assumed.
.mnote filename
is the file name of the assembler source file to be assembled.
.mnote ext
is the file extension of the assembler source file to be assembled.
If omitted, a file extension of "&axt" is assumed.
If the period "." is specified but not the extension, the file is
assumed to have no file extension.
.mnote options
is a list of valid options, each preceded by a slash
("/") or a dash ("&minus.").
Options may be specified in any order.
.endnote
.do end
.np
The options supported by the &wasname. are:
.begnote $compact
.note d<name>[=text]
define text macro
.note e<number>
set error limit number
.note fo=<file_name>
set object file name
.note h or ?
display options summary
.note i=<directory>
add directory to list of include directories
.note o{e,c}
object file format (ELF,COFF)
.note q or zq
operate quietly
.note we
treat all warnings as errors
.endnote
.*
.section Using the &wasname
.*
.np
Assume that the following assembler program was stored in
.fi hello.asm.
.tinyexam begin
~.new_section .text, "crx4"
~.globl  main
main:
    lda           $sp,-0x10($sp)
    stq           $ra,($sp)
    ldah          $a0,h^`L$0`($zero)
    lda           $a0,l^`L$0`($a0)
    sextl         $a0,$a0
    bsr           $ra,j^printf
    ldq           $ra,($sp)
    lda           $sp,0x10($sp)
    ret           $zero,($ra),0x00000001

~.new_section .const, "drw4"
`L$0`:
    .asciiz "Hello world\n"

~.new_section .pdata, "dr2"
    //  0000                Procedure descriptor for main
    .long   main                    //  BeginAddress      : 0
    .long   main+36                 //  EndAddress        : 36
    .long   00000000                //  ExceptionHandler  : 0
    .long   00000000                //  HandlerData       : 0
    .long   main+8                  //  PrologEnd         : 8

~.new_section .drectve, "iRr0"
    .asciiz "-defaultlib:clib -defaultlib:math "
.tinyexam end
.np
We can assemble this file using the following command:
.millust begin
&wascmd hello
.millust end
.*
.section Assembly Directives and Opcodes
.*
.np
It is not the intention of this chapter to describe assembly-language
programming in any detail.
You should consult a book that deals with this topic.
However, we present an alphabetically ordered list of the directives
that are recognized by the assembler.
.*
.beglevel
.*
.section .aent (not supported)
.*
.section .align
.*
.syntax
    .align expression
.esyntax
.*
.descrp
The .align directive sets low-order bits in the location counter to
zero. The value of expression establishes the number of bits to be
zeroed. The maximum value for expression is 6 (64 byte alignment).
Windows NT default alignment is .align 4 (octaword alignment).
.np
If the .align directive advances the location counter, the assembler
fills the skipped bytes with zeros in data sections or nop instructions
in text sections.
.np
Normally, the
.kw .word,
.kw .long,
.kw .quad,
.kw .float,
.kw .double,
.kw .d_floating,
.kw .f_floating,
.kw .g_floating,
.kw .s_floating,
and
.kw .t_floating
directives
automatically align their data appropriately. For example,
.mono .word
does an implicit
.mono .align 1,
and
.mono .double
does an implicit
.mono .align 3.
.np
The automatic alignment feature can be disabled with
.mono .align 0.
The assembler reinstates automatic alignment at the next
.kw .text,
.kw .data,
.kw .rdata,
or
.kw .sdata
directive that it encounters.
.np
Labels immediately preceding an automatic or explicit alignment are
also realigned. For example:
.millust begin
foo: .align 3
~.word 0
.millust end
.pc
is the same as
.millust begin
~.align 3
foo: .word 0
.millust end
.edescrp
.category location control directive
.*
.section .ascii
.*
.syntax
    .ascii string[, string ...]
.esyntax
.*
.descrp
The
.kw .ascii
directive assembles each string from the list into
successive locations. The
.kw .ascii
directive does not pad the string with null characters. You must put
quotation marks (") around each string. You can optionally use the
backslash escape characters.
.edescrp
.category data storage
.*
.section .asciz
.*
.syntax
    .asciz string[, string ...]
.esyntax
.*
.descrp
The .asciz directive assembles each string in the list into successive
locations and adds a null character. You can optionally use the
backslash escape characters.
.edescrp
.category data storage
.notes non-Microsoft
.*
.section .asciiz
.*
.syntax
    .asciiz string[, string ...]
.esyntax
.*
.descrp
The .asciiz directive assembles each string in the list into successive
locations and adds a null character. You can optionally use the
backslash escape characters.
.edescrp
.category data storage
.*
.section .bss
.*
.syntax
    .bss
.esyntax
.*
.descrp
The .bss directive instructs the assembler to add subsequent code to
the .bss section.
.edescrp
.category location control directive
.*
.notes non-Microsoft
.*
.section .byte
.*
.syntax
    .byte expression1 [ , expression2 ] ... [ , expressionN ]
.esyntax
.*
.descrp
The .byte directive truncates the values of the expressions specified
in the comma-separated list to 8-bit values and assembles the values in
successive locations. The values of the expressions must be absolute.
The operands in a .byte directive can optionally have the form:
.illust begin
expressionVal [ :expressionRep]
.illust end
.np
The expressionVal is an 8-bit value. The optional expressionRep is a
non-negative expression that specifies how many times to replicate the
value of expressionVal. The expression value (expressionVal) and
repetition count (expressionRep) must be absolute.
.edescrp
.category data storage
.*
.section .comm
.*
.syntax
    .comm name, expression
.esyntax
.*
.descrp
The .comm directive causes name (unless defined elsewhere) to become a
global common symbol at the head of a block of at least expression
 bytes of storage. The linker overlays like-named common blocks, using
the expression value of the largest block as the byte size of the
overlay.
.edescrp
.category data storage
.*
.section .data
.*
.syntax
    .data
.esyntax
.*
.descrp
The .data directive directs the assembler to add all subsequent data to
the .data section.
.edescrp
.category location control directive
.*
.section .debug$P
.*
.notes non-Microsoft
.*
.section .debug$S
.*
.notes non-Microsoft
.*
.section .debug$T
.*
.notes non-Microsoft
.*
.section .d_floating (not supported)
.*
.section .double
.*
.syntax
    .double expression1 [, expression2] ... [, expressionN]
.esyntax
.*
.descrp
The .double directive is a synonym for .t_floating.
.edescrp
.category data storage
.*
.section .edata (not supported)
.*
.section .eflag (not supported)
.*
.section .end (not supported)
.*
.section .endr (not supported)
.*
.section .ent (not supported)
.*
.section .err
.*
.notes non-Microsoft
.*
.section .even
.*
.notes non-Microsoft
.*
.section .extern
.*
.syntax
    .extern         name
    .extern(thread) name
.esyntax
.*
.descrp
The .extern directive indicates that the specified symbol is global and
external; that is, the symbol is defined in another object module and
cannot be defined until link time. The name operand is a global
undefined symbol. Symbols declared as (thread) are declared to reside
in the .tls$ (thread local storage) section. Please refer to the .tls$
directive  description for an example of how to use symbols in thread
local storage.
.np
NOTE: This directive must be used prior to the first reference of name.
.edescrp
.category symbol declaration directive
.*
.section .f_floating (not supported)
.*
.section .file (not supported)
.*
.section .float
.*
.syntax
    .float expression1 [, expression2] ... [, expressionN]
.esyntax
.*
.descrp
The .float directive is a synonym for .s_floating.
.edescrp
.category data storage
.*
.section .fmask (not supported)
.*
.section fnop
.*
.syntax
    fnop
.esyntax
.*
.descrp
No Operation has no effect on the machine state.
.edescrp
.category instruction
.*
.section .frame (not supported)
.*
.section .g_floating (not supported)
.*
.section .globl
.*
.syntax
    .globl name
.esyntax
.*
.descrp
The .globl directive identifies name as an external symbol. If the name
is otherwise defined (for example, by its appearance as a label), the
assembler exports the symbol; otherwise, it imports the symbol. In
general, the assembler imports undefined symbols; that is, it gives
them the storage class "global undefined" and requires the linker to
resolve them.
.np
NOTE: This directive must be used prior to the first reference of name.
.edescrp
.category symbol declaration directives
.*
.section .half
.*
.notes non-Microsoft
.*
.section .ident
.*
.notes non-Microsoft
.*
.section .lcomm
.*
.syntax
    .lcomm name, expression
.esyntax
.*
.descrp
The .lcomm directive gives the named symbol (name) a data type of bss.
The assembler allocates the named symbol to the bss area, and the
expression defines the named symbol's length. If a .globl directive
also specifies name, the assembler allocates the named symbol to
external bss.
.edescrp
.category data storage
.*
.section .livereg (compiler-use only -- not supported)
.*
.section .loc (compiler-use only -- not supported)
.*
.section .long
.*
.syntax
    .long expression1 [, expression2] ... [, expressionN]
.esyntax
.*
.descrp
The .long directive truncates the values of the expressions specified
in the comma-separated list to 32-bit values and assembles the values
in successive locations. The values of the expression can be
relocatable.
.np
The operands can optionally have the form:
.illust begin
expressionVal [ :expressionRep]
.illust end
.np
The expressionVal is a 32-bit value. The optional expressionRep is a
non-negative expression that specifies how many times to replicate the
value of expressionVal. The expression value (expressionVal) and
repetition count (expressionRep) must be absolute.
.np
This directive automatically aligns its data and preceding labels to a
longword boundary. You can disable this feature with the .align 0
directive.
.edescrp
.category data storage
.*
.section .new_section
.*
.notes non-Microsoft
.*
.section nop
.*
.syntax
    nop
.esyntax
.*
.descrp
No Operation has no effect on the machine state.
.edescrp
.category instruction
.*
.section .pdata
.*
.notes non-Microsoft
.*
.section .prologue (not supported)
.*
.section .quad (not supported)
.*
.section .rdata
.*
.syntax
    .rdata
.esyntax
.*
.descrp
The .rdata directive instructs the assembler to add subsequent data
into the .rdata section.
.edescrp
.category location control directive
.*
.section .repeat (not supported)
.*
.section .save_ra (not supported)
.*
.section .sdata (not supported)
.*
.section .section
.*
.notes non-Microsoft
.*